快速上手

快速上手#

本教程介绍了使用 Trinity-RFT 运行 RFT 的快速入门指南。

第 0 步：环境准备#

请按照安装指南中的说明进行环境设置。

第 1 步：模型和数据准备#

模型准备

将 Qwen2.5-1.5B-Instruct 模型下载到本地目录 $MODEL_PATH/Qwen2.5-1.5B-Instruct：

# 使用 Modelscope
modelscope download Qwen/Qwen2.5-1.5B-Instruct --local_dir $MODEL_PATH/Qwen2.5-1.5B-Instruct

# 使用 Huggingface
huggingface-cli download Qwen/Qwen2.5-1.5B-Instruct --local-dir $MODEL_PATH/Qwen2.5-1.5B-Instruct

更多关于模型下载的细节请参考 ModelScope 或 Huggingface。

数据准备

将 GSM8K 数据集下载到本地目录 $DATASET_PATH/gsm8k：

# 使用 Modelscope
modelscope download --dataset AI-ModelScope/gsm8k --local_dir $DATASET_PATH/gsm8k

# 使用 Huggingface
huggingface-cli download openai/gsm8k --repo-type dataset --local-dir $DATASET_PATH/gsm8k

更多关于数据集下载的细节请参考 ModelScope 或 Huggingface。 从 ModelScope 下载的数据集可能缺少 dtype 字段，导致加载数据集时出错。要解决这个问题，请删除 dataset_infos.json 文件并重新运行实验。

第 2 步：配置实验并运行#

Trinity-RFT 的同步模式#

我们在同步模式下运行实验，其中 Explorer 和 Trainer 轮流执行。要启用此模式，需将 mode 设置为 both（默认）并合理设置 sync_interval。较小的 sync_interval 值使训练更接近 on-policy 设置。例如，我们将 sync_interval 设为 1 来模拟 on-policy 场景。

使用 GRPO 算法#

本实验使用 gsm8k.yaml 中的配置。以下是 gsm8k.yaml 中一些重要配置项：

project: <project_name>
name: <experiment_name>
checkpoint_root_dir: ${oc.env:TRINITY_CHECKPOINT_ROOT_DIR,./checkpoints}
algorithm:
  algorithm_type: grpo
  repeat_times: 8
  optimizer:
    lr: 1e-5
model:
  model_path: ${oc.env:TRINITY_MODEL_PATH,Qwen/Qwen2.5-1.5B-Instruct}
  max_response_tokens: 1024
  max_model_len: 2048
cluster:
  node_num: 1
  gpu_per_node: 2
buffer:
  total_epochs: 1
  batch_size: 128
  explorer_input:
    taskset:
      name: gsm8k
      storage_type: file
      path: ${oc.env:TRINITY_TASKSET_PATH,openai/gsm8k}
      subset_name: 'main'
      split: 'train'
      format:
        prompt_key: 'question'
        response_key: 'answer'
      rollout_args:
        temperature: 1.0
      default_workflow_type: 'math_workflow'
    eval_tasksets:
    - name: gsm8k-eval
      storage_type: file
      path: ${oc.env:TRINITY_TASKSET_PATH,openai/gsm8k}
      subset_name: 'main'
      split: 'test'
      format:
        prompt_key: 'question'
        response_key: 'answer'
      default_workflow_type: 'math_workflow'
  trainer_input:
    experience_buffer:
      name: gsm8k_buffer
      storage_type: queue
      path: 'sqlite:///gsm8k.db'
explorer:
  eval_interval: 50
  runner_per_model: 16
  rollout_model:
    engine_num: 1
synchronizer:
  sync_method: 'nccl'
  sync_interval: 1
trainer:
  save_interval: 100

运行实验#

使用以下命令启动 RFT 流程：

trinity run --config examples/grpo_gsm8k/gsm8k.yaml

进阶选项：将检查点转换为 Hugging Face 格式#

在运行 Trinity-RFT 进行实验后，系统会自动将训练过程中的检查点（checkpoint）保存到以下路径：

${checkpoint_root_dir}/${project}/${name}

该目录的结构如下：

${checkpoint_root_dir}/${project}/${name}
├── buffer
│   ├── experience_buffer.jsonl          # 存储训练过程中生成的经验数据
│   └── explorer_output.db               # Explorer 模块输出的数据库文件
├── log                                  # 包含多个 Ray Actor 的日志
│   ├── checkpoint_monitor.log
│   ├── explorer.log
│   ├── explorer_experience_pipeline.log
│   ├── explorer_runner_0.log  ...  explorer_runner_31.log
│   ├── queue_experience_buffer.log
│   └── synchronizer.log
├── monitor                              # 监控相关文件（可能为空）
├── global_step_58                       # 示例：第 58 步的完整检查点
│   └── actor
│       ├── huggingface                  # （可选）Hugging Face 格式的模型文件
│       │   ├── added_tokens.json
│       │   ├── chat_template.jinja
│       │   ├── config.json
│       │   ├── generation_config.json
│       │   ├── merges.txt
│       │   ├── model.safetensors        # ← 关键模型权重文件
│       │   ├── special_tokens_map.json
│       │   ├── tokenizer.json
│       │   ├── tokenizer_config.json
│       │   └── vocab.json
│       ├── extra_state_world_size_4_rank_0.pt  # 额外状态（如随机数种子等）
│       ├── ...
│       ├── fsdp_config.json             # FSDP 配置文件
│       ├── model_world_size_4_rank_0.pt ... model_world_size_4_rank_3.pt  # 分片模型参数
│       ├── optim_world_size_4_rank_0.pt ... optim_world_size_4_rank_3.pt  # 分片优化器状态
│       └── ...
├── explorer_meta.json                   # Explorer 模块的元数据
├── trainer_meta.json                    # Trainer 模块的元数据
├── latest_checkpointed_iteration.txt    # 最近一次完整检查点的训练步数
└── latest_state_dict_iteration.txt      # 最近一次保存模型参数的训练步数（用于 checkpoint 同步）

何时需要转换？#

如果你希望使用 Hugging Face 格式 的模型（例如用于推理或部署），但发现 global_step_*/actor/huggingface/ 目录中 缺少 model.safetensors 文件，就需要手动执行转换。

转换工具：trinity convert#

trinity convert 命令提供了灵活的模型转换功能，支持以下几种使用方式：

✅ 批量转换（推荐）#

将 --checkpoint-dir 指向项目根目录（即包含多个 global_step_* 子目录的路径），工具会自动递归查找所有 global_step_* 目录，并对每个检查点执行转换。

trinity convert --checkpoint-dir ${checkpoint_root_dir}/${project}/${name}

该命令会：

  • 自动识别所有形如 global_step_数字 的子目录；

  • 对每个子目录中的 actor 模型进行转换；

  • 将生成的 Hugging Face 格式文件（包括 model.safetensors 等）保存到对应的 actor/huggingface/ 目录中。

✅ 单步转换#

如果只想转换某一个特定训练步的模型，可直接将 --checkpoint-dir 指向对应的 global_step_XXX 文件夹：

trinity convert --checkpoint-dir ${checkpoint_root_dir}/${project}/${name}/global_step_120

✅ 路径容错#

即使你指定了 global_step_XXX 内部的子路径（例如 .../global_step_120/actor），工具也能智能识别并正确完成转换，无需严格对齐到 global_step_XXX 层级。

特殊情况：缺少基础模型配置#

如果某个 global_step_*/actor/huggingface/ 目录中 缺少 config.json（通常是因为训练时未完整保存配置），转换过程需要原始基础模型的配置文件。此时，请通过 --base-model-dir 指定基础模型路径：

trinity convert \
  --checkpoint-dir ${checkpoint_root_dir}/${project}/${name} \
  --base-model-dir /path/to/your/base/model

💡 此参数适用于所有被扫描到的检查点。只要任意一个检查点缺少 config.json，就需要提供该参数。

注意事项#

  • 仅转换 Actor 模型：当前 trinity convert 仅处理 actor 文件夹中的模型参数，不会处理 critic（即使存在）。若需转换 Critic 模型，需另行操作。

  • 自动识别训练格式：trinity convert 原生支持 FSDP 和 Megatron 两种分布式训练格式的检查点，无需额外指定参数，工具会自动检测并正确合并分片权重。

  • 幂等性：如果某个 global_step_* 的 huggingface/ 目录已包含完整的 Hugging Face 文件（特别是 model.safetensors），该检查点将被跳过，避免重复转换。

  • 性能提示：转换过程可能较耗时，尤其是当检查点数量多或模型较大时。建议在空闲时段运行。

进阶选项：带 SFT warmup 的 RFT#

在进行 RFT 之前，我们可以先使用 SFT 作为预热步骤。Trinity-RFT 支持通过在配置文件中设置 stages 来添加 SFT 预热阶段。experience_buffer 指定用于 SFT warmup 的数据集，total_steps 指定 SFT warmup 的训练步数。

# 在 gsm8k.yaml 中正确添加以下配置
stages:
  - stage_name: sft_warmup
    mode: train
    algorithm:
      algorithm_type: sft
    buffer:
      train_batch_size: 128
      total_steps: 10
      trainer_input:
        experience_buffer:
          name: sft_warmup_dataset
          path: /PATH/TO/YOUR/SFT/DATASET
  - stage_name: rft  # 留空则使用原有的 RFT 配置

以下命令将按顺序运行 SFT 和 RFT：

trinity run --config examples/grpo_gsm8k/gsm8k.yaml
目录