TRL documentation
异步蒸馏
异步蒸馏
此训练器需要
vllm、transformers>=5.2.0和kernels(训练时通过它从 Hub 加载 FlashAttention)。对于分布式训练,仅支持 FSDP2(不支持 DeepSpeed ZeRO)。目前,
vllm和transformers的依赖约束存在冲突。为解决此问题,请先安装 vLLM,然后强制安装 transformers,再通过 TRL 的 extra 添加kernels,该操作会固定 transformers 所接受的版本:pip install vllm pip install 'transformers>=5.2.0' --no-deps pip install 'trl[kernels]'
概述
experimental.async_distillation.AsyncDistillationTrainer 是 DistillationTrainer 的异步对应版本,其架构类似于 AsyncGRPOTrainer:一个后台 rollout 工作进程生成学生模型自身的 on-policy 补全,并针对教师模型对其进行评分,同时训练并行进行,而非在生成和梯度更新之间交替进行。与同步训练器不同,教师模型永远不会在本地加载——只需要一个 vLLM 服务器 URL,因此教师模型可以运行在与学生模型和训练器完全独立的硬件上,甚至可以是比学生模型大得多、否则无法与学生模型同时容纳的模型。
compute_loss 最小化学生模型与教师模型在每个位置的 token 分布之间的广义 Jensen-Shannon 散度(beta=0.0 为前向 KL,beta=1.0 为反向 KL,介于两者之间的值进行插值),这与 DistillationTrainer 和 ServerDistillationTrainer 使用的目标函数相同。训练始终采用 on-policy 方式:学生模型生成其用于训练的所有补全内容。
多教师在线策略蒸馏(MOPD)
MOPD 并非 2306.13649 论文的一部分,该论文是此训练器核心目标的基础(描述了一种同步、单教师设置);MOPD 是一种独立的方法,在 MOPD: Multi-Teacher On-Policy Distillation for Capability Integration in LLM Post-Training 中进行了描述。在那里,MOPD 是三个阶段中的第三个——先是通用 SFT,然后是每个领域独立进行 RL 训练以训练一个专家,最后通过 MOPD 将这些冻结的专家融合为一个单一的学生模型。AsyncDistillationTrainer 仅实现了第三个融合阶段:各领域的专家教师必须已经存在(例如,使用 GRPOTrainer/RLOOTrainer 单独训练),并在你通过 teacher_server_urls 指向它们之前,通过 HTTP 提供服务。该论文自身的第三阶段使用反向 KL(beta=1.0),而不是此训练器的默认值 beta=0.0(正向 KL)。
teacher_server_urls 可以接受多个条目。如果只有一个条目,所有样本都由该单一教师进行评分(即标准的 on-policy 蒸馏)。如果有多个条目,每个训练样本的 teacher_id 列将决定由哪个教师对其进行评分——例如,将数学提示路由给数学专家教师,将代码提示路由给代码专家教师,每个教师独立提供服务。每个样本仅被分发给其匹配的一个教师,绝不会在多个教师之间进行平均或集成。如果样本的 teacher_id 缺失或未映射,系统将抛出异常,而不是静默地回退到错误的教师。请参阅 examples/async_distillation_mopd/async_distillation_mopd.py 获取一个可运行的示例,该示例将随 Open-MOPD 发布的数学、代码和指令遵循专家融合到它们共享的 SFT 检查点中,并参考 examples/async_distillation_mopd/launcher.py 了解如何使用单条 Hugging Face Jobs 命令在 4 个 GPU 上运行它。
每位教师必须与学生共享同一个分词器。补全内容以原始 token id 的形式发送给教师,而教师返回的候选 id 在
compute_loss中直接索引学生自身的词表。与学生属于同一模型系列的教师(例如在 MOPD 示例中,SmolLM3 学生由从同一检查点训练出的 SmolLM3 专家融合而成)满足此条件;若教师的词表不同,则会让学生针对错误的 token 进行训练,除非其词表比学生的更大,否则这种错误是静默发生的。
检查点与恢复:ignore_data_skip 的默认值为 True;基础 Trainer 的跳过并重放循环不适用于实时 rollout 队列。相反,尚未训练的起始 prompt 的索引会随每个检查点一同保存到 rollout_state.json 中,并在恢复时还原,因此 worker 会快速前进到该 prompt,而无需重放样本。这是 已训练 的位置,而非生成器的位置:worker 会超前于训练 rollout 队列的深度,这些缓冲的样本在运行结束时会被丢弃,因此从生成器的位置恢复会跳过那些已生成但从未参与训练的 prompt。流式数据集(IterableDataset)无法重新定位;其 worker 在恢复时会从 prompt 0 重新开始。在 FSDP 下,若 bf16=True(默认值)或 fp16=True,尽管主权重为 fp32,model.safetensors 仍会以该 dtype 写入,因此推送的检查点大小与部署模型相同,而非其两倍;fp32 主权重和优化器状态仍会写入恢复文件(pytorch_model_fsdp.bin、optimizer.bin),恢复时读取的正是这些文件,因此恢复过程不受影响。若未使用 FSDP,检查点同时也是恢复文件,因此会保留主权重的 dtype。
它与 DistillationTrainer 的区别
在 DistillationTrainer 中,教师模型是一个在本地加载的模型:生成、教师前向传播以及梯度更新都在同一进程中按顺序执行。experimental.async_distillation.AsyncDistillationTrainer 以与 AsyncGRPOTrainer 将 GRPO 的 rollout 与其更新分离相同的方式,将这些关注点分离开来:
- Rollout worker(后台进程)—— 从学生的 vLLM 服务器生成补全,将完整序列连同
prompt_logprobs一起发送到已解析教师的/v1/completions以进行教师强制评分(教师不生成新 token),并将可训练的样本推入队列。 - 训练循环(主进程)—— 从队列中拉取样本,计算广义 JSD 损失,并更新学生模型的权重。
由于教师模型通过 HTTP 而非本地前向传播进行评分,因此仅传输其分布的稀疏 top-k 切片(teacher_top_k),而非完整的词表——有关在每种 beta 机制下,线协议保证为哪些候选项提供教师对数概率,请参阅 experimental.async_distillation.AsyncDistillationConfig 的 beta 和 teacher_top_k 文档。
每经过 weight_sync_steps 个训练步骤,更新后的学生模型权重会通过 NCCL 传输到其 vLLM 服务器。与 AsyncGRPOTrainer 一样,生成过程会领先于训练过程,因此样本可能反映的是略微滞后的策略;max_staleness 控制样本在权重更新中最多可以落后多少步,超过该值后样本将被丢弃。
快速入门
# train_async_distillation.py
from datasets import load_dataset
from trl.experimental.async_distillation import AsyncDistillationTrainer
if __name__ == "__main__": # the rollout worker is a spawned process that re-imports this script
dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
trainer = AsyncDistillationTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
train_dataset=dataset,
)
trainer.train()教师服务器、学生的 vLLM 服务器和训练器必须运行在不同的 GPU 上。两者都是普通的 vllm serve 实例,但需要不同的标志:教师仅用于评分(--logprobs-mode processed_logprobs 以便 teacher_temperature 作用于其返回的 logprobs,--max-logprobs -1 以便 teacher_top_k 可以超过 vLLM 默认的 20 上限),而学生仅用于生成,并且需要启用 NCCL 权重传输,以便训练器将更新后的权重推送到其中。评分会发送学生的完整序列并要求教师再生成一个 token,因此教师的 --max-model-len(或其默认值)必须大于学生的:
# Terminal 1: teacher server on GPU 0 (static, never updated)
CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen2.5-1.5B-Instruct \
--port 8001 \
--logprobs-mode processed_logprobs \
--max-logprobs -1# Terminal 2: student's vLLM server on GPU 1 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
--port 8000 \
--weight-transfer-config '{"backend":"nccl"}'# Terminal 3: training on GPU 2
CUDA_VISIBLE_DEVICES=2 python train_async_distillation.pyLoRA
传入 peft_config 以在 student 上训练 LoRA 适配器,而不是整个模型:
from peft import LoraConfig
trainer = AsyncDistillationTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
train_dataset=dataset,
peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)每次权重同步都需要将更新后的学生模型传输到其服务器。默认情况下,训练器会将适配器合并到基础模型中,并发送完整的合并权重,对于 7B 模型,每次同步大约需要 15 GB。使用 --enable-lora 启动学生模型的 vLLM 服务器后,它只会发送适配器,在 r=32 时约为 160 MB:
CUDA_VISIBLE_DEVICES=1 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen2.5-0.5B-Instruct \
--port 8000 \
--weight-transfer-config '{"backend":"nccl"}' \
--enable-lora \
--max-lora-rank 32 \
--max-loras 6VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 会暴露训练器用于提交每个新适配器的端点。如果您提供张量并行服务,请添加 VLLM_WORKER_MULTIPROC_METHOD=spawn,并且无论如何都要保留 --weight-transfer-config:训练器仅在启动时选择同步模式,此时服务器已经启动,而合并同步是回退方案。教师服务器不受影响:它永远不会被更新。
--max-lora-rank 必须是 1, 8, 16, 32, 64, 128, 256, 320, 512 之一。它设置的是服务器能够支持的最高秩,而非实际服务的秩,因此 r=4 的适配器在 8 下可以正常工作。--max-loras 必须至少为 max_staleness + 2:训练器会注册 max_staleness + 1 个适配器版本,以便在旧策略下开始的 rollout 能够在该策略下完成,而不是在生成中途切换策略;并且每次同步都会在卸载最旧版本之前加载下一个版本。训练器在启动时会检查这两个值,并告知你应使用什么参数重启服务器。
vLLM 从磁盘而非网络加载适配器,因此训练器会将每个版本写入 <output_dir>/.vllm_lora/ 下,并将该路径提供给服务器。如果服务器运行在另一台机器上,该目录必须位于两台机器都能访问的文件系统上。
<output_dir>/.vllm_lora/是一个服务缓存,并非存放训练后适配器的位置。它仅保留最近版本的适配器,且每个版本在超出过期窗口后不久即被删除。检查点才是保存训练适配器的关键,因此请勿将其关闭:若设置save_strategy="no",数小时的训练任务结束后将不会留下任何产物。output_dir必须可被服务器读取,且其生命周期需长于任务本身,因此节点本地临时存储不可行,尽管它能避免在缓慢的共享文件系统上进行同步。
Adapter 同步并不总是更快。与提供合并后的权重相比,vLLM 在提供 LoRA adapter 时,每个 token 的生成速度大约慢 1.33–1.39 倍,而生成过程通常占据实际耗时的主要部分。作为回报,每次同步时的暂停时间会大幅缩短,且同步带宽占用约为 1%。如果生成吞吐量是您的瓶颈,合并同步通常仍是更好的选择。
记录的指标
在生成梯度之前,一次 rollout 会经历多个阶段。让我们首先从提示词到最终的批次组成,看看这些不同的阶段:
Dataset row = PROMPT (message list + optional `teacher_id`)
└─ ROLLOUT (1 prompt -> 1 student completion -> 1 teacher scoring call)
├─ generate (student's vLLM /v1/completions, sampled)
└─ score (the routed teacher's /v1/completions with `prompt_logprobs`, teacher-forced)
└─ SAMPLE (prompt + completion + the teacher's sparse per-position distribution)
════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════
└─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
└─ ROW (Planner assigns it to one of `dp` rows, Σ Lᵢ²-balanced)
└─ MICRO-BATCH (`dp` rows, one per rank)
└─ PACKED ROW (1 concat sequence, `position_ids` reset per sample)
└─ FORWARD (`compute_loss`, bs=1, inter-rank padding stripped)
└─ OPTIMIZER STEP (from `grad_accum` micro-batches)从上到下阅读:
- 一次 rollout 是指一个提示词仅生成一次并仅评分一次。这里没有组的概念:蒸馏没有跨代计算的基线优势,因此提示词不会被重复,一次 rollout 恰好产生一个训练样本。
- 一个样本是补全内容加上教师模型在每个补全位置上的前
teacher_top_k个候选项。这就是跨进程边界传输的内容。 - 超出边界后,训练器将样本规划为行(每个 DP rank 一行),将每一行打包为一个拼接序列,并将
grad_accum个微批次累积为单个优化器步骤。
因此,我们根据指标所涉及的阶段(或 实体)对其进行拆分:
| 命名空间 | 它计数的实体 |
|---|---|
rollout/ | 一次生成与评分往返:耗时多久,进展如何 |
completions/ | 学生模型(vLLM)针对单个提示词生成的内容 |
sample/ | 表示队列中到达的一个训练样本 |
batch/ | 一个微批次或一个优化器步骤(由一个或多个样本构建) |
perf/ | 实测秒数和 FLOPs |
损失函数本身所度量的所有内容都会以无前缀的形式记录(jsd、entropy、teacher_entropy),在 MOPD 下会提供 teacher/<teacher_id>/* 的细分——详见下文中的散度。
让我们也定义一些术语,以消除令牌指标的歧义:
- generated 令牌是学生模型生成的内容(
completions/*)。 - forwarded 令牌是指 forward 前向传播所处理的所有令牌:即提示词和生成的令牌。
- trained tokens 是计算损失时所使用的子集,其中
completion_mask == 1。Trained ≠ generated:如果教师模型未对某个 completion 位置的任何候选项进行评分,该位置会从散度计算中屏蔽,但仍会参与前向传播。
指标在每个日志窗口记录一次:记录自上次日志以来的所有内容,涵盖最近logging_steps个优化器步骤。在该窗口内:
- 像
rollout/duration_s和rollout/score_s这样按 rollout、样本或调用测量的平均值,会对窗口内所有 rollout、样本或调用进行平均。像rollout/generated_tokens_per_s这样的速率则是总 token 数除以总秒数。 - 否则,名称最后一部分包含单词
count的指标会被求和:sample/dropped_stale_count表示自上次日志以来被丢弃的样本数量,而非自训练开始以来的数量。 - 名称的最后一部分包含单词
max或min(例如sample/staleness_max或completions/max_length)时,将保留最大值或最小值。 - 其他任何指标均为窗口内记录值的平均值。
单位:
_s:秒。tokens_per_s:每秒生成的 token 数。_frac:0 到 1 之间的分数。_per_step:单个优化器步长中的数量,在窗口内的步长上取平均值。
GRPOTrainer 同时记录的其他指标仍保留其 GRPO 名称(completions/mean_length、completions/clipped_ratio)。
批次数量的构成方式
行是 单个 DP 秩在一个 micro-batch 中前向传播的内容:将多个样本拼接成单个序列,并在每个样本边界处重置 position_ids。规划器决定哪些样本落入哪一行(通过平衡 Σ Lᵢ² 确保没有秩成为拖后腿的慢节点),而数据整理器负责执行拼接。
在我们所有的指标中,“step”(步)始终指一次完整的优化器更新,而非微批次。gradient_accumulation_steps 个微批次构成一个 step,所有以 _per_step 命名的指标均按优化器步计算,与 global_step、logging_steps 以及 Trainer 词汇表中的其他术语保持一致。若某指标是按微批次计算的,会明确说明(batch/microbatches_per_step);或者它是按行计算的量(batch/row_*、batch/samples_per_row)。
因此,一个步骤包含固定数量的row-slots:
row-slots per step = gradient_accumulation_steps x world_size这使得批量指标可以组合成一个阶梯,你可以将它们相互对照检查:
sample sample/forwarded_tokens_mean
└─ packed into a ROW batch/samples_per_row, batch/row_tokens_mean
└─ one row per DP rank = one micro-batch
└─ gradient_accumulation_steps micro-batches = one STEP
batch/samples_per_step, batch/forwarded_tokens_per_step因此 batch/samples_per_step ≈ row-slots x batch/samples_per_row,token 同理。等式两侧仅在步内各 micro-batch 之间的差异范围内一致——每步指标是求和,每行指标是均值——因此预期会有零点几个百分点的偏差,而非完全相等。
当样本较长时,需要重点关注 batch/row_fill_frac:一个 10k token 的样本在 32k 预算下填充效果很差(三个能放下,四个永远放不下,因此打包器通常只能放入两个,该行填充率约为 77%),而 1k token 的样本则几乎能完美填充。这是量化现象,并非 bug,token_budget 是调节参数——但需注意,每条序列的注意力机制复杂度为 O(L²),因此由长序列组成的更满的行,其内存开销并不会线性增加。
Rollout 队列
Worker 将已评分的样本推入队列,Trainer 从中拉取。四个指标描述了该队列,并回答了不同的问题:
| metric | question |
|---|---|
rollout/queue_size | 当前有多少个样本正在等待 |
sample/time_in_queue_s | 单个样本在训练前被放置了多久——其偏离策略性的后半部分 |
perf/rollout_wait_s | 训练因队列为空而阻塞了多长时间 |
rollout/backpressure_s | 生成(工作进程)因领先训练 max_staleness 步而等待了多长时间 |
最后两个指标(perf/rollout_wait_s 和 rollout/backpressure_s)互为镜像。将它们与队列大小结合阅读,可以判断哪一侧是瓶颈:
- 队列接近空,
perf/rollout_wait_s较高 → 生成受限。训练器处于饥饿状态;请查看rollout/generated_tokens_per_s、rollout/concurrency和rollout/score_s。 - 队列中大约持有
max_staleness个步骤的 token,rollout/backpressure_s较高 → 受训练器限制。生成过程被阻塞,且sample/staleness_mean接近其上限。 - 两者均较高 →
max_staleness限制本身过于严格:正在进行的 rollout 在其样本到达队列之前就已填满该限制,导致训练器等待,而生成过程被阻塞。请提高max_staleness。 - 两者均接近零 → 平衡!
补全
completion 是学生 vLLM 服务器针对单个提示词生成的内容。
| metric | 含义 |
|---|---|
completions/mean_length | 每次 rollout 生成的 token 数 |
completions/min_length, completions/max_length | 窗口内最短和最长补全 |
completions/clipped_ratio | 未以 EOS 结束、即被 max_completion_length 截断的补全比例 |
completions/mean_terminated_length, completions/min_terminated_length, completions/max_terminated_length | 在以 EOS 结尾的补全上,长度相同 |
Rollouts
rollout 指一次完整的提示处理流程:由学生模型生成,随后通过教师模型进行教师强制解码。由于教师调用位于每个 rollout 的关键路径上(与 GRPO 不同,在 GRPO 中评分是对已完成组进行的独立循环),教师模型的延迟会直接体现在 rollout/duration_s 中。
| metric | 含义 |
|---|---|
rollout/duration_s | 单次 rollout 的墙钟时间,从分发到获得带分数的样本:生成 以及 教师调用 |
rollout/score_s | 其中,教师模型的/v1/completions调用所花费的时间 |
teacher/<id>/score_s | MOPD 专用:同上,按教师分别计算。单个缓慢的专家只会限制路由到它的 rollout,而混合平均值会掩盖这一点 |
rollout/generated_tokens_per_s | 上一个区间(窗口化)内的生成吞吐量,因此停滞会显现出来 |
rollout/concurrency | 正在进行的 rollout,即正在生成或正在评分 |
rollout/vllm_retry_count | 重试的 vLLM 请求,指向学生服务器或教师服务器。否则,性能下降的服务器看起来就像无法解释的延迟。它位于此处而非 completions/,因为它统计的是发往服务器的请求数,而非生成的文本 |
rollout/backpressure_s | 生成因超前 max_staleness 步而等待了多长时间。参见 rollout 队列 |
rollout/queue_size | 在训练器拉取样本的位置,测量等待在 rollout 队列中的已评分样本。参见 rollout 队列 |
来自队列的样本
每个样本都是一个 RolloutSample:包含提示词、学生的补全内容,以及教师对其进行的稀疏评分。工作进程将它们推入 rollout_buffer;以下所有内容均在训练器侧进行测量,因为训练器会拉取这些样本用于训练。
| metric | 含义 |
|---|---|
sample/forwarded_tokens_mean, sample/forwarded_tokens_max | 一个样本中的 tokens:提示 + 生成内容。打包是行级问题,参见batch/row_* |
sample/trained_tokens_mean | 其中,损失函数是在多少个样本上计算的 |
sample/time_in_queue_s | 该样本在被训练之前在该队列中等待了多长时间。这与 perf/rollout_wait_s 不同 — 参见 rollout 队列 |
sample/staleness_mean, sample/staleness_max | 数据落后于多少策略版本。jsd 展示了 效果 对损失的影响;这揭示了原因 |
sample/dropped_stale_count | 因超过 max_staleness 而被丢弃的样本 |
批次
一个 micro-batch 包含 world_size 行(请记住,packing 会将数据展平为 1 个序列),因此每个 DP rank 各处理一行,即 rank i 前向传播第 i 行。这些 micro-batch 中的 gradient_accumulation_steps 个构成一次优化器更新。因此,一个 step 总共覆盖 gradient_accumulation_steps × world_size 行。下方每个 _per_step 指标都是整个 step 内所有 rank 的总和;而 batch/row_* 指标则是各行数据的均值。
| metric | 含义 |
|---|---|
batch/forwarded_tokens_per_step, batch/trained_tokens_per_step | 在一个优化器步骤中,分别用于前向传播和训练的 token 数量 |
batch/samples_per_step | 每个优化器步骤的训练样本数 |
batch/microbatches_per_step | 通过计数得出,而非从配置中读取 |
batch/masked_token_frac | completion_mask == 0 的转发 token —— 前向传播中不产生梯度的部分 |
batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max | 规划器为每个 rank 的行分配了多密集 |
batch/row_fill_frac | 行令牌与token_budget的对比。较低的值表示预算未被充分利用 |
batch/row_imbalance | max Σ Lᵢ² / mean Σ Lᵢ² 跨行计算。由于 Attention 的复杂度为 O(L²),该指标可预测哪个 rank 会阻塞梯度的 all-reduce。1.0 表示完美 |
batch/pad_frac | rank 间填充。仅产生广播字节开销;在前向传播前会被移除 |
batch/dropped_oversize_count | 因超出 token_budget 而被丢弃的样本 |
发散
目标函数本身所度量的值,在窗口内已训练 token 上取平均。这些数值用于衡量学习情况,而非吞吐量。
| metric | 含义 |
|---|---|
jsd | 在配置的 beta 下,损失函数所最小化的广义 JSD。数值下降表明学生模型的分布正在向教师模型的分布收敛 |
entropy | 学生自身的预测熵。如果此处发生坍缩且 jsd 下降,说明学生模型是在收窄而非学习 |
teacher_entropy | 教师模型对其报告的候选项的熵。由于只有teacher_top_k个候选项通过传输,因此该值低于真实值。 |
teacher/<id>/jsd | MOPD 专用:jsd 仅限于教师模型打分的 token。不同领域的教师模型可能以截然不同的速率产生分歧,而混合的 jsd 会将这些情况混为一谈 |
teacher/<id>/entropy | 仅适用于 MOPD:teacher_entropy 的相同分解 |
teacher/<id>/token_frac | MOPD 专用:教师模型所选取的已评分 token 占比。路由偏差在其他情况下是不可见的:即使教师模型因缺乏数据行而处于饥饿状态,其 teacher/<id>/jsd 指标仍会显示为正常。 |
aux_loss | MoE 路由器在每个微批次上的负载均衡损失,在 rank 之间取平均值,当模型返回路由器 logits 且 router_aux_loss_coef 不为 0 时记录。与上面的行不同,它不是按 token 取平均值 |
不存在按教师划分的entropy:学生的熵是其自身策略的属性,而非由哪个教师对样本进行评分所决定,因此混合指标已经涵盖了这一点。
性能
吞吐量衡量训练器每秒处理的 token 数量。模型浮点运算利用率 (MFU) 估算用于模型前向和反向传播的训练设备理论计算能力的百分比。用于此估算的计算能力取决于硬件和训练精度。
吞吐量 (Throughput) 和 MFU 基于两种时间基准进行报告:
fwd_bwd_用于衡量前向传播和反向传播期间的性能。wall_clock_衡量完整优化器步骤的性能,包括优化器更新、权重同步以及等待 rollout 的时间。
这种差异有助于区分计算性能与等待和协调的开销。这两个 MFU 指标仅描述训练设备:它们不包括外部 rollout 或 teacher 服务器的计算量或硬件容量。Wall-clock MFU 反映的是训练器等待这些服务所花费的时间,而非这些服务自身的利用率。
仅当已知所选精度下本地训练设备的峰值计算能力,且 FLOPs 估算支持该模型的架构(例如 Llama、Qwen2、Qwen3、Qwen3-MoE 或 Qwen3-VL)时,才会报告 MFU。否则,将省略 MFU;训练将继续进行,且吞吐量和计时指标仍然可用。
| metric | 含义 |
|---|---|
perf/step_s | 优化器步骤之间的实际耗时:包括计算、优化器、权重同步和队列等待 |
perf/fwd_bwd_s | 前向 + 反向,对步骤中的微批次求和。这是下方所有 fwd_bwd_ 指标的 |
perf/fwd_s | 它的前向部分。fwd_s / fwd_bwd_s 接近 1/3 是常见的比例;该值更高意味着反向传播开销较低,或者在前向阶段支付了重计算的代价 |
perf/optimizer_s | optimizer.step() |
perf/rollout_wait_s | 训练器因队列为空而阻塞了多长时间。参见rollout 队列 |
perf/weight_sync_s | 一次完整的同步,外加 _pause_s(等待 vLLM)、_barrier_s(rank 偏差)和 _transfer_s(传输的字节数) |
perf/fwd_bwd_forwarded_tokens_per_s, perf/wall_clock_forwarded_tokens_per_s | 每个基准上每秒转发的 token 数 |
perf/wall_clock_trained_tokens_per_s | 相同,仅计算损失函数所见的 token |
perf/fwd_bwd_mfu, perf/wall_clock_mfu | 每个基准上的模型 FLOPs 利用率 |
设计哲学
该训练器有意保持精简,并非旨在发展为通用解决方案。如果您需要某项未支持的功能,我们建议克隆该仓库并直接根据您的需求对训练器进行适配。只有当社区存在显著需求时,才会考虑添加新功能。
AsyncDistillationConfig
类 trl.experimental.async_distillation.AsyncDistillationConfig
< source >( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool | None = Nonegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 1logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Truerestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonedtype: str = 'float32'trust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonemax_completion_length: int = 2048temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonerepetition_penalty: float = 1.0chat_template_kwargs: dict | str | None = Nonevllm_server_base_url: str = 'http://localhost:8000'vllm_server_timeout: float = 1800.0teacher_server_urls: dict[str, str] | str | None = Nonebeta: float = 0.0teacher_temperature: float = 1.0teacher_top_k: int = 8add_tail_bucket: bool = Truetoken_budget: int | None = Nonemax_concurrent_rollouts: int = 512max_staleness: int = 4weight_sync_steps: int = 1rollout_worker_timeout: float = 300.0log_completions: bool = Falselog_completions_steps: int = 100num_completions_to_print: int | None = None )
控制模型的参数
- model_init_kwargs (
dict[str, Any]或str,可选) — 用于 from_pretrained 的关键字参数,在从路径实例化学生模型时使用。revision的值在加载处理类时也会用到。 - dtype (
str, 可选, 默认为"float32") — 用于加载学生模型的数据类型,可选值之一为"auto","bfloat16","float16"或"float32". 其默认值为"float32",因为异步训练器所衡量的训练-推理不匹配问题(通过 FP16 克服训练-推理不匹配) )对训练器自身的精度很敏感。要端到端地弥合这一差距,还需要以相同的 dtype 提供学生模型的 vLLM 服务器(vllm serve --dtype). Adtype位于model_init_kwargs中的 dtype 具有优先权。教师服务器不受影响:它们永远不会被更新。这仅设置了权重加载时的 dtype。在 FSDP 混合精度下(
bf16=True为默认值),accelerate 会在分片前将每个可训练参数上转为 fp32,因此无论dtype如何设置,主权重和优化器状态均为 fp32,而前向和反向传播则在 bf16 或 fp16 下运行。随后,检查点将以该混合精度 dtype 写入,而非 fp32。在没有 FSDP 的情况下,不会进行任何上转:dtype="bfloat16"配合bf16=True会保持 bf16 权重和优化器状态,即纯 bf16 训练。 - trust_remote_code (
bool,可选,默认为False) — 是否允许加载附带自定义 Python 代码的模型和分词器。该参数会转发给 from_pretrained 和 from_pretrained。 - router_aux_loss_coef (
float, 可选) — 混合专家(MoE)模型中负载均衡辅助损失的系数,以该权重添加到训练损失中。如果未设置,则使用模型配置中声明的值。设置为0.0可将其禁用。与非 MoE 模型一起使用时会失败。
控制生成的参数
- max_completion_length (
int,可选,默认为2048) — 每次补全生成的最大 token 数。 - temperature (
float, 可选,默认为1.0) — 用于采样学生模型在策略内补全的温度。 - top_p (
float,可选,默认为1.0) — 用于 on-policy 生成的 Top-p(核)采样参数。 - top_k (
int,可选,默认为0) — 用于 on-policy 生成的 Top-k 采样参数。0表示禁用 top-k 过滤。 - min_p (
float, 可选) — 最小 token 概率,该值会按最可能 token 的概率进行缩放。它必须是0.0和1.0之间的值。典型值在0.01-0.2范围内。 - repetition_penalty (
float,可选,默认为1.0) — 一个浮点数,根据新 token 是否出现在提示词和迄今为止生成的文本中来对其进行惩罚。 值 >1.0会鼓励模型使用新的 token,而值 <1.0会鼓励模型重复使用 token。 - chat_template_kwargs (
dict[str, Any], 可选) — 在生成补全时传递给apply_chat_template函数的其他关键字参数。
控制 vLLM 服务器的参数
- vllm_server_base_url (
str,可选,默认为"http --//localhost:8000"): 学生模型的 vLLM 服务器的基础 URL,同时用于生成和流式权重更新。 - vllm_server_timeout (
float, 可选,默认为1800.0) — 对 vLLM 服务器调用的超时时间(秒):包括启动时等待学生服务器就绪、每个生成或评分请求,以及每次权重同步调用。等待服务器就绪和权重同步调用在超时会抛出异常;超时的生成或评分请求会被重试。 - teacher_server_urls (
dict[str, str], 可选,默认为{"default" -- "http://localhost:8001"}): 教师 vLLM 服务器,每个服务器均通过vllm serve <teacher-model> --logprobs-mode processed_logprobs --max-logprobs -1启动。所有教师均为静态:该训练器不会向任何教师流式传输权重更新,因此教师既不需要VLLM_SERVER_DEV_MODE,也不需要权重传输后端,只需要上述两个标志,即可使其评分精确(参见teacher_temperature和teacher_top_k)。每个教师必须与学生共享同一个 tokenizer:补全内容以原始 token id 形式发送,而教师返回的 id 会直接用于在compute_loss中索引学生自身的词表。如果教师的词表不同,训练将针对错误的 token 进行;若其词表大小不超过学生的词表,这种错误会静默发生。评分是针对学生自身补全 token 的 teacher-forced 请求(max_tokens=1、prompt_logprobs=teacher_top_k、temperature=teacher_temperature),与同步服务器教师训练器中get_sequence_logprobs()发出的请求相同。由于存在这个一次性 token,教师的--max-model-len必须大于学生的,否则最长的补全内容将无法评分。单个条目会对所有样本进行评分(普通的单教师 on-policy 蒸馏,即默认行为)。多个条目则启用 MOPD(多教师 on-policy 蒸馏,参见 MOPD):每个训练行的teacher_id列用于选择哪个条目对其进行评分,例如{"math": "http://localhost:8002", "code": "http://localhost:8003"},每行的teacher_id为"math"或"code"。
控制蒸馏损失的参数
- beta (
float, 可选,默认为0.0) — 广义 Jensen-Shannon 散度的插值系数。0.0对应前向 KL(均值寻求),1.0对应反向 KL(众数寻求),介于两者之间的值则进行插值,遵循 DistillationTrainer 内部计算的同一广义 JSD 公式。计算散度所依据的支持集因区间而异,与ServerDistillationTrainer保持一致:当beta=0.0时,使用完整的teacher_top_k宽度的教师报告支持集(外加尾部桶),因为前向 KL 的加权恰好由该支持集提供。当beta != 0.0时,支持集缩小为仅两个候选——教师自身的 top-1 token 和补全的实际/已实现 token——因为在不传输更宽(或完整)词表的情况下,线协议仅保证这两个 token 身份具有教师对数概率;任何更宽的范围都只是对学生自身可能 token 覆盖范围的概率近似,而非保证。 - teacher_temperature (
float,可选,默认为1.0) — 散度的 Softmax 温度,应用于两侧:发送给教师模型,以便 vLLM 在服务端以该温度计算其 logprobs(精确计算,而非客户端重新缩放),并应用于compute_loss中学生自身的 logits,以镜像ServerDistillationTrainer中单一的temperature。与temperature无关,后者仅控制学生模型如何采样其补全内容。教师的服务器必须以--logprobs-mode processed_logprobs运行,此设置才能影响其返回的 logprobs;否则, 教师将静默地报告原始 logprobs,此设置仅影响学生一侧。 - teacher_top_k (
int, 可选,默认为8) — 通过prompt_logprobs从教师模型请求的每个位置的候选 token 数量。仅使用这些候选项(加上实际生成的 token,即使其不在 top-k 范围内,vLLM 也会始终报告该 token;再加上一个尾部桶,用于捕获剩余的剩余概率质量,参见add_tail_bucket)来近似教师模型的分布,完整的词表永远不会通过 HTTP 传输。散度计算中学生一侧是精确的(在本地计算,而非近似),因为学生模型正是正在训练的模型,其完整的 logits 已在compute_loss中可用。8是用于冒烟测试的轻量级默认值;相邻 RL 框架中生产环境的 on-policy-distillation 配置通常使用大致相同范围的稀疏教师支持(miles 默认为16,EasyOPD 为64),因此在正式训练时将其提高到16–64是合理的。任何高于20的值都要求教师服务器在启动时指定--max-logprobs -1,以解除 vLLM 默认的每个 token 的 logprob 上限。 - add_tail_bucket (
bool,可选,默认为True) — 是否追加一个尾部桶,用于表示teacher_top_k之外的剩余概率质量,以避免在teacher_top_k较小时出现微不足道的散度。 - token_budget (
int, 可选) — 单个行(即一个 DP rank 的前向传播)中打包的真实 token 的最大数量。TokenBudgetBatcher会构建基于 Σ Lᵢ² 平衡的微批次,确保每一行都保持在该预算之内,从而独立于样本数量地限制峰值内存(每行中的样本数量变为动态)。如果为None(默认值),则将其设置为学生 vLLM 服务器的max_model_len(在训练开始时查询)——即提示词加补全长度的上限——因此任何 rollout 样本都不会超出预算。长度超过token_budget的样本无法放入任何一行,将被丢弃并记录警告,计入batch/dropped_oversize_count。
控制异步 rollout 流水线的参数
- max_concurrent_rollouts (
int, 可选,默认为512) — 同时针对学生模型和教师模型的 vLLM 服务器正在生成或正在评分的 rollout 的最大数量。 - max_staleness (
int,可选,默认为4) — 在 rollout 样本被丢弃之前,其权重更新步骤最多可以落后于当前模型版本的步数。生成过程受此约束:只有当排队中和正在传输中的 token 数量能够被训练器在max(max_staleness, 1)步内消耗完时,rollout 才会启动。 - weight_sync_steps (
int,可选,默认为1) — 将权重同步到学生模型的 vLLM 服务器之间的训练步数。 - rollout_worker_timeout (
float, 可选,默认为300.0) — 自 rollout worker 上次心跳以来,经过多少秒后训练器将其视为挂起并中止。
控制日志记录的参数
- log_completions (
bool,可选,默认为False) — 是否每log_completions_steps个被评分的样本记录一次 (prompt, completion) 对的样本。 - log_completions_steps (
int,可选,默认为100) — 记录 completions 日志之间的已评分样本数量。仅当log_completions为True时使用。该计数基于 rollout worker 已评分的样本数,而非优化器步数:worker 在与 trainer 分离的进程中运行,无法访问self.state.global_step。 - num_completions_to_print (
int, 可选) — 使用rich打印的补全数量。如果为None,则记录所有补全。
experimental.async_distillation.AsyncDistillationTrainer 的配置类。
此类仅包含异步在线策略蒸馏特有的参数。完整的训练参数列表请参阅 TrainingArguments 文档。请注意,此类中的默认值可能与 TrainingArguments 中的不同。其结构与 AsyncGRPOConfig 保持一致(异步流水线、vLLM 服务器、日志字段均相同),但将 GRPO 的裁剪/分组字段替换为以下教师蒸馏损失字段。
这些参数的默认值与 TrainingArguments 不同:
logging_steps: 默认值为1,而不是500。gradient_checkpointing:默认值为True,而非False。bf16:如果未设置fp16,则默认值为True,而不是False。learning_rate:默认值为1e-6,而非5e-5。ignore_data_skip:默认值为True而非False;基础 Trainer 的跳过并重放循环不适用于异步 rollout 队列。
AsyncDistillationTrainer
类 trl.experimental.async_distillation.AsyncDistillationTrainer
< source >( model: str | PreTrainedModelargs: trl.experimental.async_distillation.async_distillation_config.AsyncDistillationConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)peft_config: PeftConfig | None = None )
参数
- model (
str或 PreTrainedModel) — 要训练的 Student 模型。可以是以下之一:- 一个字符串,作为托管在 huggingface.co 模型仓库中的预训练模型的 model id,或指向使用 save_pretrained 保存模型权重的 directory 的路径。通过 from_pretrained 加载。
- 一个 PreTrainedModel 对象。其注意力实现会切换为训练器的 FlashAttention 后端,以进行无填充训练。
配置中的模型名称用于在 vLLM 服务器上识别学生模型。
- args (experimental.async_distillation.AsyncDistillationConfig,可选) —
此训练器的配置。如果为
None,则使用默认配置。 - train_dataset (Dataset 或 IterableDataset) —
用于训练的 Dataset。必须包含
"prompt"列(conversational 格式)。其他附加列将被忽略。 - processing_class (PreTrainedTokenizerBase, 可选) —
用于处理数据的处理类。如果为
None,则通过 from_pretrained 从模型名称加载。如果它没有填充标记,则使用tokenizer.eos_token。 - callbacks(TrainerCallback 列表,可选)— 用于自定义训练循环的回调列表,会添加到默认回调中(参见 此处)。
- optimizers (
tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None],可选,默认为(None, None)) — 一个包含要使用的优化器和调度器的元组。默认为AdamW和由args控制的线性调度。 - peft_config (PeftConfig, 可选) —
用于包装模型的 PEFT 配置。如果为
None,则不包装模型。当学生的 vLLM 服务器以--enable-lora启动时,LoRA 适配器将作为适配器而非合并权重同步到该服务器;请参阅 AsyncDistillation 文档中的 LoRA 部分。
DistillationTrainer 的异步对应版本,其架构与 AsyncGRPOTrainer 完全一致:一个后台 rollout 工作进程生成学生的 on-policy 补全,并将其与教师服务器进行评分,同时训练并行进行,从而将 rollout 与梯度更新循环解耦。GRPO 的裁剪策略梯度损失读取的是组相对优势,而此训练器的 compute_loss 读取的是稀疏的逐位置教师分布,并针对该分布最小化广义 JSD(参见 AsyncDistillationConfig.beta),且始终为 on-policy:学生生成其用于训练的每一个补全。
与同步的 DistillationTrainer 不同,该训练器仅支持对通过 HTTP 提供的教师模型(外部 vLLM 服务器)进行评分。本地(进程内、GPU)教师前向传播无法像 GRPO 的奖励函数那样在 rollout worker 的禁用 CUDA 的派生子进程中运行,而需要回到主训练进程中执行;该路径尚未实现。
示例:
>>> from trl.experimental.async_distillation import AsyncDistillationTrainer
>>> from datasets import load_dataset
>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")
>>> trainer = AsyncDistillationTrainer(
... model="Qwen/Qwen2.5-0.5B-Instruct",
... train_dataset=dataset,
... )
>>> trainer.train()