前言¶

用大模型做 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