Chapter 02

安装与依赖

📌 commit 8221a9f把 transformers / accelerate / peft 装对

TRL 是纯 Python 包，但和 transformers / accelerate / peft / trl-vllm 几个生态包深度耦合。本章给出推荐的版本组合、安装方式、验证脚本。

2.1三条安装路径

场景	命令	说明
稳定版	`pip install trl`	大多数项目用这个
跟最新算法	`pip install git+https://github.com/huggingface/trl`	main 分支
开发 / 改源码	`git clone … && pip install -e ".[dev]"`	本仓 commit `8221a9f`

2.2依赖矩阵

包	版本	角色
transformers	>= 4.46	底座模型与 Trainer
accelerate	>= 1.0	多 GPU / FSDP / DeepSpeed
peft	>= 0.13	LoRA / QLoRA
datasets	>= 3.0	数据加载
torch	>= 2.1	底座
bitsandbytes	>= 0.43	QLoRA 用
vllm	>= 0.6	GRPO / online sampling 用
deepspeed	>= 0.14	多机大模型用

2.3验证

python -c "import trl; print(trl.__version__)"
python -c "from trl import SFTTrainer, DPOTrainer, GRPOTrainer, PPOTrainer, RewardTrainer; print('ok')"
accelerate config       # 一次性配好 multi-gpu / mixed precision

2.4accelerate 配置怎么选

accelerate config 会问一系列问题，常见选择：

问题	SFT/单卡	多卡 SFT	大模型 DPO
compute environment	local	local	local
distributed_type	NO	MULTI_GPU	DEEPSPEED
mixed_precision	bf16	bf16	bf16
num_processes	1	8	8
zero_stage	—	—	3

2.5仓库结构

trl/                              https://github.com/huggingface/trl
├── trl/                          ★ 核心库
│   ├── trainer/                  ★ 13+ Trainer 实现
│   │   ├── sft_trainer.py
│   │   ├── dpo_trainer.py
│   │   ├── grpo_trainer.py        ★ R1 同款
│   │   ├── ppo_trainer.py
│   │   ├── reward_trainer.py
│   │   ├── kto_trainer.py
│   │   ├── orpo_trainer.py
│   │   ├── cpo_trainer.py
│   │   └── ...
│   ├── models/                   AutoModelForCausalLMWithValueHead 等
│   ├── extras/                   ProfilerCallback 等
│   └── data_utils.py
├── examples/                     30+ 跑得通的样例
│   ├── scripts/                  ★ CLI 风格脚本
│   └── notebooks/
├── tests/
└── docs/source/

2.6常见装机问题

现象	处理
`ImportError: cannot import name 'SFTTrainer'`	trl < 0.7，升 trl
transformers 版本冲突	用 `pip install -U trl transformers` 一起升
bnb 在 Mac 装不上	QLoRA 不能在 Mac 跑；Mac 上只能跑 LoRA + fp16
vllm 装不上	需要 CUDA >= 11.8 + Linux；先 `pip install vllm --extra-index-url https://wheels.vllm.ai/nightly`

2.7`trl` CLI 子命令全表

装好 trl 包后 PATH 里就多了一个 trl 命令。来源：trl/cli/commands/__init__.py:22–34。

子命令	对应 script	用途
`trl sft`	`trl/scripts/sft.py`	启动 SFTTrainer
`trl dpo`	`trl/scripts/dpo.py`	启动 DPOTrainer
`trl grpo`	`trl/scripts/grpo.py`	启动 GRPOTrainer，自带 reward function 注册表
`trl rloo`	`trl/scripts/rloo.py`	启动 RLOOTrainer
`trl kto`	`trl/scripts/kto.py`	启动 KTOTrainer（experimental wrapper）
`trl reward`	`trl/scripts/reward.py`	训练 reward model
`trl vllm-serve`	`trl/scripts/vllm_serve.py`	起 vLLM rollout server，给 GRPO/RLOO "server 模式"用
`trl env`	`trl/scripts/env.py`	打印系统环境（CUDA、accelerate、vLLM 版本）—— 报 issue 必贴

典型用法：

# 5 分钟跑通一个 SFT，不写代码
trl sft \
    --model_name_or_path Qwen/Qwen2.5-0.5B \
    --dataset_name trl-lib/Capybara \
    --output_dir Qwen-Capybara

# 多卡，配 accelerate
trl sft --config configs/sft.yaml --num_processes 4

# GRPO 启服务模式
trl vllm-serve --model Qwen/Qwen2.5-7B --tensor-parallel-size 4 &
trl grpo --model_name_or_path Qwen/Qwen2.5-7B \
         --reward_funcs accuracy_reward \
         --use_vllm true --vllm_mode server

2.8关键环境变量

变量	用途
`TRL_EXPERIMENTAL_SILENCE=1`	关闭 `trl.experimental.*` 的 "API 不稳定" 警告 banner
`WANDB_DISABLED=true`	跑测试 / debug 时关掉 W&B 同步
`HF_HUB_OFFLINE=1`	纯离线训练，避免被网络阻塞
`CUDA_VISIBLE_DEVICES=...`	colocate 模式下分配给 vLLM 的卡和训练分开
`ACCELERATE_USE_DEEPSPEED=true`	不写 accelerate 配置直接强行走 DeepSpeed

2.9仓库新增目录速读

2.5 给的目录树是简化版，下面这些子目录在 v1 出现后变得很重要：

目录	含义
`trl/experimental/`	21 个实验性 trainer（OnlineDPO / GFPO / PRM / Nash-MD / XPO / SDFT 等），ch13 详细列
`trl/rewards/`	4 个内置 reward function（ch07.3）
`trl/generation/`	VLLMClient / VLLMGeneration（ch10）
`trl/accelerate_configs/`	7 份开箱 yaml（zero1/2/3、fsdp1/2、single_gpu、multi_gpu）
`trl/chat_templates/`	38 个 jinja 模板（Llama3 / Qwen3 / Gemma3 / DeepSeek-V3 / GLM-4-MoE 等）
`trl/skills/`	给 Claude / Codex / OpenCode 等 AI agent 用的 skill bundle
`trl/templates/`	model card 模板（lm / rm / completions 三套）