Trinity-RFT配置完全指南:YAML配置项逐项精讲,Trinity Studio图形化低代码配置

原创2026-10-31 11:46:342,159 阅读
文章标签:人工智能大模型强化学习RLHF微调分布式训练深度学习模型评测AI Agent本地部署

Trinity-RFT配置完全指南:YAML配置项逐项精讲,Trinity Studio图形化低代码配置

Trinity-RFT 是一个面向大语言模型(LLM)强化微调(Reinforcement Fine-Tuning, RFT)的通用开源框架。它把强化微调拆成三个协同工作的模块:Explorer(探索器)、Buffer(缓冲区)和 Trainer(训练器)。本文以新手视角,逐项精讲 Trinity-RFT 的 YAML 配置项,并手把手教你使用 Trinity Studio 图形化低代码配置工具,帮你快速跑通第一个强化微调实验。

1️⃣ 先搞懂:Trinity-RFT 的三大模块

理解配置项之前,先看一眼整体架构。Trinity-RFT 将 RFT 流程解耦为三个组件,而一份 YAML 配置正是围绕这三个组件展开的:

Trinity-RFT系统架构图:Explorer、Buffer、Trainer三大模块如何协同完成强化微调

  • Explorer:通过"智能体-环境"交互生成经验数据(rollout 模型推理、奖励计算都在这里发生);
  • Trainer:消费经验数据,最小化损失来更新模型权重;
  • Buffer:贯穿 RFT 全生命周期的数据流水线(任务集、经验缓冲区、数据加工)。

每个模块对应的配置段落,下文逐一精讲。

2️⃣ 一份典型 YAML 配置文件长什么样

Trinity-RFT 的所有配置都集中在一个 YAML 文件中,基于 OmegaConf 加载,支持变量插值和环境变量替换(例如 ${oc.env:TRINITY_MODEL_PATH}),这让同一份配置可以在不同机器间复用。

以仓库中经典的 GSM8K + GRPO 示例 examples/grpo_gsm8k/gsm8k.yaml 为例,它的结构是:

project: "Trinity-RFT-gsm8k"      # 全局配置
name: "qwen2.5-1.5B-gsm8k"
algorithm:                        # 算法配置
  algorithm_type: grpo
model:                           # 模型配置
  model_path: ${oc.env:TRINITY_MODEL_PATH,Qwen/Qwen2.5-1.5B-Instruct}
cluster:                          # 集群资源
  node_num: 1
  gpu_per_node: 2
buffer:                           # 数据配置
  batch_size: 96
explorer: {}                      # 探索器
synchronizer: {}                  # 权重同步
trainer: {}                       # 训练器

全局参数定义详见 trinity/common/config.py,完整中文参数文档见 docs/sphinx_doc/source_zh/tutorial/trinity_configs.md。

3️⃣ 全局配置:一个实验的"身份证"

project: Trinity-RFT
name: example
mode: both
checkpoint_root_dir: ${oc.env:TRINITY_CHECKPOINT_ROOT_DIR,./checkpoints}
continue_from_checkpoint: true
配置项 作用
project / name 项目名与实验名,决定检查点目录 <checkpoint_root_dir>/<project>/<name>/
group(可选) 实验分组,插入到检查点路径中,方便归类管理
mode 运行模式,见下表
checkpoint_root_dir 所有检查点和日志的根目录,可用环境变量替换
continue_from_checkpoint 为 true 时从最新检查点恢复训练;否则自动加时间戳开启新实验

mode 是新手最容易困惑的一项,它有 5 种取值:

取值 含义 适用场景
both(默认) 同时启动 trainer 和 explorer 单机一体化训练
train 仅启动 trainer 异步模式下占用训练卡的角色
explore 仅启动 explorer 异步模式下占用推理卡的角色
bench 基准测试模式 benchmark 评测
colocate 单 GPU 上同时运行两者 显存紧张的单机场景

异步模式下,trainer 与 explorer 会分别读取两份只差 mode 字段的配置,可参考 examples/async_gsm8k/explorer.yaml 和 examples/async_gsm8k/trainer.yaml。Trinity-RFT 支持同步、单步 Off-Policy、全异步、多 Explorer 异步四种 RFT 模式:

Trinity-RFT四种RFT模式对比:同步、单步Off-Policy、全异步、多Explorer异步的时间线图

4️⃣ algorithm 段:选算法、定超参

algorithm:
  algorithm_type: grpo
  repeat_times: 8
  optimizer:
    lr: 1e-6
    lr_scheduler_type: constant
  • algorithm_type:核心开关。支持 ppo、grpo、dapo、opmd、dpo、sft、mix 等,还有 GiGPO、GSPO、TOPR、AsymRE、CHORD 等多种算法,各算法实现位于 trinity/algorithm/ 目录;
  • repeat_times:每个任务的重复 rollout 次数。注意 buffer.batch_size 不需要手动乘以它;GRPO 等组相对算法要求 repeat_times > 1,DPO 会自动设为 2;
  • optimizer.lr:Actor 学习率;lr_scheduler_type 可选 constant 或 cosine;
  • 可选的高级旋钮:sample_strategy(经验采样策略)、advantage_fn(优势函数)、kl_penalty_fn / kl_loss_fn(KL 惩罚与损失)、entropy_loss_fn(熵正则)。不指定时会按算法类型自动设置,新手可先忽略。

5️⃣ model 段:告诉框架"用哪个模型"

model:
  model_path: ${oc.env:TRINITY_MODEL_PATH,Qwen/Qwen2.5-1.5B-Instruct}
  max_model_len: 2048
  max_response_tokens: 1024

常用配置项:

  • model_path:被训练模型的本地路径或 HuggingFace 名称;
  • max_model_len:单条序列的最大 token 数。若不填,会尝试用 max_prompt_tokens + max_response_tokens 推算;
  • max_prompt_tokens / max_response_tokens / min_response_tokens:控制推理时 prompt 与回复的长度上限;
  • enable_prompt_truncation(默认 true):超长 prompt 是否截断;
  • lora_configs:可选的 LoRA 配置(rank、alpha、target_modules 等),显存不够时的好帮手;
  • tinker:无 GPU 用户可启用 Tinker 后端进行云训练,rank 默认 32;
  • external_model:接入 OpenAI 兼容的外部 API 模型,通过环境变量读取 base url 和 api key;
  • custom_chat_template / chat_template_path:自定义 chat template,后者(jinja2 文件)优先级更高。

6️⃣ buffer 段:数据从哪来、往哪去

Buffer 段是配置里"最像数据工程"的一部分,分三个子块:

6.1 顶层:批大小与训练规模

buffer:
  batch_size: 96        # 每步使用的任务数(不要再乘以 repeat_times)
  train_batch_size: 256 # 每步训练使用的经验数,默认 = batch_size × repeat_times
  total_epochs: 100     # 总训练轮数(与 total_steps 二选一)

6.2 explorer_input:任务数据集

buffer:
  explorer_input:
    taskset:
      name: gsm8k
      storage_type: file
      path: ${oc.env:TRINITY_TASKSET_PATH,openai/gsm8k}
      split: train
      format:
        prompt_key: 'question'
        response_key: 'answer'
      rollout_args:
        temperature: 1.0
    eval_tasksets:
    - name: gsm8k-eval
      path: ${oc.env:TRINITY_TASKSET_PATH,openai/gsm8k}
      split: test
    default_workflow_type: 'math_workflow'
  • taskset:训练任务集。storage_type 可选 file(推荐,jsonl/parquet,符合 HuggingFace 规范)、queue、sql;
  • eval_tasksets:评测任务集列表,通常指向 test 分片;
  • format.prompt_key / response_key:指定数据集里问题列和答案列的字段名,换成自己的数据集时这两行必改;
  • rollout_args.temperature:采样温度,训练通常 1.0、评测可设 0.1;
  • default_workflow_type / default_reward_fn_type:数据集未单独指定时,全局默认的工作流与奖励函数。

6.3 trainer_input:经验缓冲区

buffer:
  trainer_input:
    experience_buffer:
      name: gsm8k_buffer
      storage_type: queue
      path: 'sqlite:///gsm8k.db'
      replay_buffer:
        enable: false
        reuse_cooldown_time: 60
        priority_fn: linear_decay
  • storage_type: queue(推荐):经验在队列中流转,path 可选配 SQLite 做备份;
  • replay_buffer:经验回放。enable: true 后旧经验可被重复利用,priority_fn 控制复用顺序,reuse_cooldown_time 是冷却时间。想体验"经验回放提升样本效率",可参考 examples/ppo_countdown_exp_replay/;
  • auxiliary_buffers:SFT、DPO 等算法的额外数据集入口。

7️⃣ explorer 段:调优 rollout 吞吐的关键

explorer:
  runner_per_model: 8
  concurrent_mode: sequential
  eval_interval: 50
  rollout_model:
    engine_type: vllm
    engine_num: 1
    tensor_parallel_size: 1
  • concurrent_mode:任务执行并发模式。sequential(顺序,默认,兼容性最好)、asynchronous(异步,吞吐更高,要求 workflow 无共享状态)、multi-threading(多线程);
  • rollout_model.engine_type:推理引擎,可选 vllm、tinker、external;engine_num 是引擎实例数,tensor_parallel_size 是单实例张量并行度——多卡机器上调大这两项是最直接的加速手段;
  • runner_per_model:每个推理引擎实例服务的 WorkflowRunner 数量;
  • eval_interval:每隔多少 step 在评测集上跑一次;eval_on_startup(默认 true)在启动时先用原始模型评一次;
  • max_inflight_batches:全异步模式下允许同时存在的未完成批次数(默认 2),防止任务积压。

8️⃣ synchronizer 段:权重如何从 Trainer 流到 Explorer

Trainer 更新完权重后,Explorer 必须拿到新权重才能生成"更新鲜"的经验。synchronizer 段控制这件事:

synchronizer:
  sync_method: 'nccl'     # nccl 或 checkpoint
  sync_interval: 10       # 每多少步同步一次
  sync_style: 'fixed'     # fixed / explorer_driven / trainer_driven / fully_async
  • sync_method: nccl:走 NCCL 高速通信,仅限 both 模式;checkpoint:从磁盘加载最新模型,train/explore/bench 模式都支持(异步部署必选);
  • sync_style 决定"谁来发起同步":fixed 定时同步、explorer_driven 由 explorer 发起、trainer_driven 由 trainer 发起、fully_async 通知后立即同步不等同步点。

下图展示了 Trainer 与 Explorer 两侧的状态机,帮助理解各同步风格的触发条件:

Trinity-RFT权重同步机制:Trainer与Explorer的状态机流转图(Fixed、Explorer Driven、Trainer Driven)

9️⃣ trainer 段:训练后端与显存管理

trainer:
  trainer_type: 'verl'
  trainer_strategy: fsdp
  save_interval: 100
  save_hf_checkpoint: last
  grad_clip: 1.0
  use_dynamic_bsz: true
  max_token_len_per_gpu: 16384
  • trainer_strategy:fsdp(默认)、fsdp2、megatron(大模型首选);
  • save_interval / max_checkpoints_to_keep:保存频率与保留个数,磁盘不够时记得调小;
  • save_hf_checkpoint:last(默认,仅最后一个存 HF 格式)、always、never。HF 格式方便直接推理,但会额外消耗时间和显存;
  • use_dynamic_bsz: true + max_token_len_per_gpu:按 token 总量动态拼 batch,是长序列训练的省显存利器;
  • ulysses_sequence_parallel_size:序列并行度,超长上下文时可大于 1。

完整的 veRL 后端细粒度参数(actor/critic micro batch、offload 等)见 docs/sphinx_doc/source_zh/tutorial/trinity_configs.md 的"veRL Trainer 配置"章节。

🔟 monitor / service / data_processor / stages:进阶四件套

monitor:
  monitor_type: tensorboard    # wandb / tensorboard / mlflow
service:
  data_juicer:
    auto_start: true
data_processor:
  experience_pipeline:
    operators:
      - name: reward_shaping_mapper
  • monitor:选 tensorboard 最省心,日志直接落在检查点目录下;选 wandb 需提前 wandb login;
  • service.data_juicer:一键启用 Data-Juicer 数据加工服务;
  • data_processor:定义 task_pipeline(任务筛选,如 LLM 难度打分)和 experience_pipeline(经验清洗、奖励整形),适合数据工程师深度定制;
  • stages:多阶段训练。比如先 SFT 预热再切 RFT,每个阶段可覆写 algorithm、buffer、trainer,未指定的参数自动继承全局配置——examples/grpo_gsm8k/gsm8k.yaml 末尾就附了一份被注释掉的 SFT 预热阶段模板,取消注释即可使用。

1️⃣1️⃣ 用 trinity run 启动你的第一个实验

配置写好后,先起 Ray 集群再一键运行:

ray start --head            # 单机即可
trinity run --config examples/grpo_gsm8k/gsm8k.yaml

想验证异步配置是否生效,可对照 examples/async_gsm8k/run.sh。下图是异步模式下 GRPO 在 GSM8K 上的奖励曲线,可以看到 critic/rewards/mean 稳步爬升到 0.7 以上:

Trinity-RFT异步模式GRPO训练GSM8K的奖励曲线:critic/rewards/mean随Step上升

1️⃣2️⃣ Trinity Studio:图形化低代码配置,小白友好度拉满

不想手写 YAML?Trinity-RFT 自带基于 Streamlit 的配置生成器(低代码图形界面),只需一条命令:

trinity studio --port 8080

浏览器打开后就是下图这样的界面,分为两种模式(实现见 trinity/manager/config_manager.py):

Trinity-RFT Config Generator图形化配置界面:左侧Beginner Mode基础模式,右侧Expert Mode专家模式

  • Beginner Mode(初学者模式):只暴露"必选项"——项目名、模型路径、检查点路径、任务集路径、算法类型、学习率、节点/卡数、同步参数。填完自动校验(缺失字段会黄条提示),右侧实时生成 YAML,点 Save 即可下载配置文件;
  • Expert Mode(专家模式):按 Model / Buffer / Explorer and Synchronizer / Trainer 四个页签展开全部参数,对应本文第 4~9 节讲到的所有配置项,每个参数的录入逻辑注册在 trinity/manager/config_registry/ 目录下;
  • 生成配置后可直接 trinity run --config 运行,也可继续手动编辑 YAML。

💡 新手建议路径:先用 Studio 生成一份配置 → 对照本文理解每个字段 → 需要微调时再回到 YAML 精调。图形化负责"跑起来",YAML 负责"调精细"。

总结:一张表回顾配置速查

段落 一句话总结
全局 实验名字、mode 运行模式、检查点目录
algorithm 选算法(grpo/ppo/dpo...)+ 学习率 + 重复次数
model 模型路径 + 长度上限 + LoRA/Tinker 选项
cluster 几台机器 × 几块卡
buffer 任务集(换数据集改 prompt_key/response_key)+ 经验队列
explorer 推理引擎规模 + 并发模式 + 评测间隔
synchronizer nccl/checkpoint 两种同步方式 + 同步节奏
trainer FSDP/Megatron 策略 + 保存策略 + 动态 batch
monitor 等 指标看板、数据服务、多阶段训练

至此,你已经掌握了 Trinity-RFT 从"跑通一个实验"到"精细调参"的全部配置知识。下一步可以阅读 docs/sphinx_doc/source_zh/tutorial/trinity_gpu_configs.md 学习 GPU 资源分配进阶技巧,或者打开 Studio 亲手生成你的第一份配置吧!

登录后查看全文
Trinity-RFT