前言¶

用大模型做 SFT、DPO 或带奖励函数的在线 RL 时，难点往往不在「有没有库」，而在 API 怎么配、数据集列名和格式对不对、生成批次和 num_generations 能否整除、chat template 该不该自己套。TRL（Transformers Reinforcement Learning）把多种后训练方法收进统一的 Trainer + Config 模式，但文档分散、实验性 API 又多，写训练脚本或排错时容易来回翻。Hugging Face 在官方 Skills 仓库里提供了 trl-training：把 TRL Python API 与 trl CLI 的约定写进 Agent 可遵循的 SKILL.md，适合在 Cursor、Codex、Claude Code 等环境里让编码助手按同一套事实写代码或查配置。

这是什么¶

trl-training 是 Hugging Face Skills 仓库中的一个工作流 Skill，遵循 Agent Skills 标准：目录内包含带 YAML 前言的 SKILL.md，激活后指导 Agent 使用 TRL 做语言模型后训练。

• 维护方：Hugging Face（metadata.author: huggingface）
• 许可：Apache-2.0
• 官方文档入口：https://huggingface.co/docs/trl
• Skill 源码路径：skills/trl-training

Skill 自述用途：在编写或调试基于 TRL Python API 或 trl CLI 的训练代码时使用；覆盖 SFT、DPO、GRPO、KTO 以及奖励模型训练等后训练路径。

与同仓库里的 huggingface-llm-trainer（侧重 TRL/Unsloth 与 Hugging Face Jobs 基础设施）不同，trl-training 更贴近本地脚本与 CLI 层面的 TRL 用法与排错。

核心功能¶

TRL 的设计是：每种方法对应一个 *Trainer 类和一个 *Config 数据类；Config 继承 transformers.TrainingArguments，因此 Transformers 训练参数在任意 Trainer 配置里均可使用。

更多 Trainer（如 OnlineDPO、ORPO、CPO、GKD 等）位于 trl.experimental，API 不稳定，见 experimental 概览。

Skill 内还强调的数据与训练要点包括：

• 模型加载：model 可传 Hub ID 字符串，加载参数经 model_init_kwargs 传入；tokenizer/processor 默认从模型推断；LoRA 使用 peft_config=LoraConfig(...)。
• 数据集格式：对话式 messages 或 prompt/completion；chat template 由 TRL 自动应用，不应手动套模板。额外列可保留；GRPO 会把额外列传给奖励函数。详见 dataset formats。
• SFT 常用配置项：max_length、packing、padding_free（需 FlashAttention）、use_liger_kernel、assistant_only_loss 等。
• GRPO：自定义 reward_funcs，需接受 **kwargs；对话数据下 completions 为消息列表而非纯字符串；生成批次与 num_generations 的整除关系、以及通过 use_vllm 加速生成等。
• CLI：子命令与配置字段对应，支持 YAML --config 与 --accelerate_config zero3 等分布式预设。

安装与启用¶

Skills 仓库说明：除市场/bootstrap 的 hf-cli 外，其它工作流 Skill 可通过 hf skills add <skill-name> 按需安装；支持 Skill 的客户端也可通过 CLI/MCP 发现。

在已具备 Hugging Face CLI 的前提下，安装本 Skill：

hf skills add trl-training

Cursor：仓库提供 .cursor-plugin/plugin.json 与 MCP 配置；市场入口以 hf-cli 为主，额外 Skill 仍建议用 hf skills add trl-training。

Claude Code：先注册 marketplace 并安装 hf-cli，再用 hf skills add trl-training。

Codex：将 skills/trl-training 复制或符号链接到 Codex 约定的 .agents/skills 路径，由客户端按 Agent Skills 标准加载 SKILL.md。

若运行环境不支持 Skills，仓库提供 agentsmd/AGENTS.md 作为后备说明 bundle。

训练本身仍需在本机或作业环境安装 TRL 与依赖（Skill 指导的是如何用 API，不替代 pip install trl 等环境准备）。

典型用法¶

监督微调（SFT）¶

下面用 Hub 上的小模型与 trl-lib/Capybara 数据集做最小可运行示例：

from datasets import load_dataset
from trl import SFTConfig, SFTTrainer

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",  # model ID 或 PreTrainedModel 实例
    args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT"),
    train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()

需要控制截断、打包与显存时，可在 SFTConfig 中设置例如：

SFTConfig(
    max_length=1024,        # 截断长度；None 表示不截断
    packing=True,           # 将序列打包进 max_length 块，减少 pad、提高吞吐
    padding_free=True,      # 展平 batch、无 padding；需 FlashAttention；packing 时会隐含
    use_liger_kernel=True,  # 融合 Liger kernel，降低峰值显存
    assistant_only_loss=True,  # 仅对 assistant 轮次计算 loss（对话数据集）
)

在线 RL：GRPO 与自定义奖励¶

奖励函数对每个 completion 返回一个 float；可忽略的参数用 **kwargs 接住：

def reward_len(completions, **kwargs):
    return [-abs(20 - len(c[0]["content"])) for c in completions]

trainer = GRPOTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    reward_funcs=reward_len,  # 或列表；多奖励相加
    args=GRPOConfig(output_dir="Qwen2.5-0.5B-GRPO", max_completion_length=512),
    train_dataset=load_dataset("trl-lib/DeepMath-103K", split="train"),
)

生成阶段通常是瓶颈。可设 use_vllm=True：vllm_mode="colocate" 与训练共享 GPU（用 vllm_gpu_memory_utilization 控显存）；vllm_mode="server" 则需单独起 trl vllm-serve --model <model_id>。实验性的 AsyncGRPOTrainer（trl.experimental.async_grpo）可把 vLLM 生成与训练循环解耦并行。

CLI¶

配置项与命令行 flag 对应，例如：

trl sft --model_name_or_path Qwen/Qwen2.5-0.5B --dataset_name trl-lib/Capybara

也可用 --config 指定 YAML；分布式可用 --accelerate_config zero3（Python 脚本侧常用 accelerate launch train.py）。

适用场景与注意¶

适合谁

• 要在本地或自有集群上用 TRL 写 SFT、DPO、GRPO、KTO 或奖励模型训练脚本，并希望 Agent 按 HF 文档约定生成代码、少犯格式与配置类错误。
• 正在调试 TRL 训练（批次与生成、reward_funcs 签名、vLLM 模式等），需要一份可引用的 Skill 上下文。

限制与注意

• trl.experimental 下 Trainer API 不稳定，生产路径应优先用稳定表中的类。
• 对话数据不要自行应用 chat template；格式不符会导致 Trainer 行为异常。
• GRPO 的 generation_batch_size（或由 per_device_train_batch_size × num_processes × steps_per_generation 推导）必须能被 num_generations（默认 8）整除。
• Skill 提供的是工作流与 API 约定，不保证替你选好算力或 Hub 配额；与 huggingface-llm-trainer 的 Jobs 流程是互补关系，按你是「本地 TRL」还是「HF Jobs 托管训练」选 Skill。

结尾¶

trl-training 把 TRL 后训练的主线 Trainer、数据集格式、SFT/GRPO 关键配置和 trl CLI 用法收敛成 Agent 可执行的说明，适合作为对齐与微调话题下的官方教程型 Skill。安装与更新以仓库说明为准；细节以 TRL 文档为准。

• Skill 目录：https://github.com/huggingface/skills/tree/main/skills/trl-training
• TRL 文档：https://huggingface.co/docs/trl