Trinity-RFT配置完全指南:YAML配置项逐项精讲,Trinity Studio图形化低代码配置
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 配置正是围绕这三个组件展开的:
- 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 模式:
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 两侧的状态机,帮助理解各同步风格的触发条件:
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 以上:
1️⃣2️⃣ Trinity Studio:图形化低代码配置,小白友好度拉满
不想手写 YAML?Trinity-RFT 自带基于 Streamlit 的配置生成器(低代码图形界面),只需一条命令:
trinity studio --port 8080
浏览器打开后就是下图这样的界面,分为两种模式(实现见 trinity/manager/config_manager.py):
- 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 亲手生成你的第一份配置吧!




