SWIFT 知识蒸馏实战指南GKD、OPD-RL 与 OPSD 三种蒸馏方法的原理、参数与多教师路由【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift知识蒸馏是将教师模型的能力迁移到学生模型的训练方式其核心在于让学生对齐教师在每个 token 位置上的输出分布获得比单纯模仿标注答案更丰富的监督信号。本文基于 SWIFTms-swift官方蒸馏文档展开系统讲解蒸馏为什么有效从稀疏到密集信号、蒸馏方法的统一设计框架散度方向、计算粒度、信号传递路径并完整覆盖 SWIFT 提供的三种蒸馏训练方法——GKD、OPD-RL、OPSD 的参数配置、教师模型接入方式本地教师 / 外部 API / 自蒸馏与多教师路由的实操细节并结合仓库源码剖析 JSD 损失计算、top-k 近似与教师 logprobs 拉取的真实实现路径。1. 为什么做蒸馏从稀疏信号到密集信号大模型的能力通常由层层训练阶段堆叠而成预训练Pre-training习得语言、世界知识、基础推理等通用能力中训练Mid-training注入代码、医学、企业内文档等领域知识后训练Post-training激发目标行为如指令遵循、数学推理、对话风格。蒸馏主要发生在后训练阶段。要理解它的价值可以沿两个相互独立的维度审视后训练方法采样模式数据从哪来训练序列是学生自己生成的on-policy还是来自外部固定数据off-policy反馈密度每条序列能教多少整条序列只有单个奖励per-sequence稀疏还是每个 token 都有信号per-token密集。SFT / 离线蒸馏off-policy dense在固定数据上对齐标签或教师分布。信号是密集的但训练只能看到教师/标签所处的状态这些状态与学生自己推理时会进入的状态不同——一旦学生早期犯了一个教师不会犯的错误就会进入未曾见过的状态误差随之累积这就是暴露偏差exposure bias。RLon-policy sparse学生自己采样轨迹基于最终结果获得奖励。分布与学生推理一致但奖励通常是序列级标量无法指出具体哪个 token 出了问题。在线策略蒸馏On-policy distillationon-policy dense学生采样轨迹教师对轨迹上的每个 token打分。训练分布与学生推理一致且反馈是逐 token 的。SFT 是蒸馏的特例理解蒸馏最自然的入口是 SFT 损失。SFT 的交叉熵损失等价于在标注 token 处对一个 one-hot“教师”分布 $\delta_{y^*}$ 的 KL 散度$$-\log P_S(y^t) \text{KL}(\delta{y^} ,|, P_S)$$知识蒸馏只是把这个确定性的 one-hot“教师”替换为教师模型的软分布 $P_T$在每个 token 上优化 $\text{KL}(P_T ,|, P_S)$从而提供比 one-hot 更丰富的监督。方法采样模式反馈密度教师分布SFToff-policy固定数据denseper-tokenone-hot $\delta_{y^*}$离线off-policy蒸馏off-policy固定或教师生成的数据denseper-token教师软分布RLon-policy学生采样sparseper-sequence无在线策略蒸馏on-policy学生采样denseper-token教师软分布2. 蒸馏的两个核心选择不同蒸馏方法的差异几乎总能归结为两个问题。理解了这两个维度下面各方法只是它们的不同组合。2.1 如何计算教师信号在每个 token 位置量化教师分布 $P_T$ 与学生分布 $P_S$ 的差异称为Teacher KL存在两个子选择。(a) 散度方向散度定义优化行为信息论含义Forward KL$\text{KL}(P_T ,|, P_S)$Mode-covering学生必须为教师高概率区域分配足够概率Reverse KL$\text{KL}(P_S ,|, P_T)$Mode-seeking学生主要拟合教师的主峰高概率区域Generalized JSD($\beta$)$\beta,\text{KL}(P_T|M) (1-\beta),\text{KL}(P_S|M)$其中 $M\beta P_T(1-\beta)P_S$在两者之间插值$\beta0$ 退化为 Forward KL$\beta1$ 退化为 Reverse KLSFT 等价于 Forward KL教师是 one-hot。在 SWIFT 中GKD 默认 $\beta0.5$JSD用--beta在 Forward / JSD / Reverse 之间选择OPD-RL 使用 Reverse KL 的 k1 估计量 $\log\pi_{\text{teacher}}(y_t)-\log\pi_{\text{student}}(y_t)$ 作为逐 token advantage。从源码看这一插值由 jsd_loss 统一实现beta 0时计算kl_div_fn(s_log, t_log)即 $\text{KL}(P_T | P_S)$Forwardbeta 1时计算kl_div_fn(t_log, s_log)Reverse其余情况用logsumexp构造混合分布 $M$ 后按 $\beta \text{KL}(M|P_T) (1-\beta)\text{KL}(M|P_S)$ 加权求和。该函数按chunk_size512分块计算以降低显存峰值并且是 HF、Megatron、Ray 三个后端共享的唯一散度计算入口见 gkd_loss.py 文件头注释。(b) 计算粒度粒度需要的教师信息说明全词表教师完整的下一 token 分布精确散度显存开销高Top-K教师概率最高的 K 个 token在 top-K 上重归一化后的近似适合外部 API受max_logprobs限制采样 token教师对学生采样 token 的单个 logpReverse KL 的单样本蒙特卡洛估计通信成本最低精度 vs 成本全词表需要物化完整 logits采样 token 只需要教师对采样 token 的 logp可走远程 API。DeepSeek-V4 技术报告指出仅用采样 token 的对数比作为 advantage 会导致较高梯度方差因此其全词表 OPD 采用完整 logit 蒸馏。2.2 如何把信号传递给学生路径 AGKD直接损失路径 BOPD-RLRL advantage训练范式--rlhf_type gkd--rlhf_type grpo 教师信号传递信号直接作为 loss信号作为 advantage 经策略梯度传入梯度流经学生全词表logits或 top-k仅学生采样 token的 $\nabla\log\pi(y_t)$需要的教师信息完整分布或 top-k logits采样 token 上的单个 logp散度选择Forward / Reverse / JSD--betaReverse KLk1 对数比与任务奖励组合通过sft_alpha混合 SFT loss可与 GRPO 奖励叠加进 advantage两条路径共享同一套教师基础设施见下一节区别仅在于 Teacher KL 的用法。蒸馏的常见用途能力融合把多个专家模型蒸馏进一个统一模型强带弱把大模型能力迁移给小模型防止遗忘用旧 checkpoint 当教师在多阶段训练后找回原有能力。3. SWIFT 中的蒸馏方法SWIFT 提供三种蒸馏训练方法它们共享同一套教师基础设施方法信号路径启用方式一句话说明GKD直接损失路径 A--rlhf_type gkd教师散度作为 loss 反向传播支持全词表 / top-k 散度OPD-RLRL advantage路径 B--rlhf_type grpo 教师教师对数比注入 GRPO advantage可与任务奖励组合OPSD路径 A 或 B在上述基础上提供teacher_prompt单模型自蒸馏教师输入包含特权信息如参考解答三种教师来源GKD 与 OPD-RL 共享--teacher_model在训练进程中加载一个独立的冻结教师模型--teacher_model_server连接外部教师服务通过swift deploy启动的 vLLM 服务训练 GPU 上不加载教师权重。GKD 使用 API 时还需设置--gkd_logits_topk。支持单 URL 与多教师 JSON 配置自蒸馏教师与学生同源。LoRA 训练且--teacher_model等于--model时通过disable_adapter()用基础模型作为固定教师无需额外加载若不设置--teacher_model或teacher_model_server学生当前权重即为动态教师GKD 中为所有 batchGRPO 中仅当数据包含teacher_prompt时生效见 3.3 OPSD。上述行为在参数校验层有明确实现TeacherModelArguments 定义了teacher_model、teacher_adapters、teacher_model_type、teacher_model_revision、teacher_deepspeed、teacher_model_server、offload_teacher_model等字段rlhf_args.py 中同时设置teacher_model与teacher_model_server会直接抛错teacher_model model且使用 LoRA 时打印日志并置空teacher_model改走disable_adapter()的固定教师路径。参数默认值说明--teacher_modelNone教师模型路径GKD 中省略则使用动态自蒸馏--teacher_model_serverNone教师 API URL格式见下文--teacher_tag_keydataset多教师路由时用于把样本 tag 匹配到教师tags的列名--teacher_deepspeedNone教师模型的 DeepSpeed 配置如zero3可取zero0/zero1/zero2/zero3/zero2_offload/zero3_offload或 JSON 文件路径--offload_teacher_modelFalse非前向阶段把教师卸载到 CPU仅对teacher_model生效完整参数说明见 命令行参数文档。3.0 外部教师 API通过swift deploy --model xxx --infer_backend vllm部署教师训练进程按 prompt 请求 logprobs训练 GPU 上不加载教师权重。GKD必须设置--gkd_logits_topkAPI 只返回 top-k logprobs以计算 JSD 散度损失OPD-RL使用采样 token 的 logpprompt_logprobs0注入 advantage系数为全局参数--teacher_kl_coef见 3.2 节。参数校验中同样有硬约束teacher_model_server已设置而gkd_logits_topk为空时直接报错见 rlhf_args.py。3.0.1 多教师路由多教师模式连接多个外部教师 API按 tag 把每个样本路由到其中一个教师适合领域专家蒸馏。teacher_model_server格式# 单教师 --teacher_model_server http://localhost:8000 # 多教师tags 需与 --dataset 或数据列匹配见下方 Mode 1 --teacher_model_server [{url:http://t1:8000,tags:[data/math.jsonl]},{url:http://t2:8001,tags:[data/code.jsonl]}]每个教师条目的字段字段说明url教师 API URLtags该教师负责的数据源单教师时可省略多教师时各条目不得重叠且必须与下方路由标识匹配路由模式Mode 1按数据集路由默认传入多个--dataset时样本按来源数据集匹配教师。默认--teacher_tag_key为dataset。把每个教师的tags设为对应的--dataset条目即可# Hub 数据集 ID --dataset AI-ModelScope/alpaca-gpt4-data-en AI-ModelScope/alpaca-cleaned \ --teacher_model_server [{url:http://t1:8000,tags:[AI-ModelScope/alpaca-gpt4-data-en]},{url:http://t2:8001,tags:[AI-ModelScope/alpaca-cleaned]}] # 本地路径 --dataset data/math.jsonl data/code.jsonl \ --teacher_model_server [{url:http://t1:8000,tags:[data/math.jsonl]},{url:http://t2:8001,tags:[data/code.jsonl]}]Mode 2按样本路由在数据中加一列如teacher_tag并设置--teacher_tag_key teacher_tagtags与该列取值匹配。适用于只传单个--dataset但仍需要多个教师的场景。从源码结构看路由与取数的解耦做得比较彻底GKDTrainer._fetch_and_assemble_teacher_logprobs 把各 micro-batch 的样本与请求拍平后交给fetch_teacher_parsed_by_routinggkd_helpers.py按 tag 分组——单教师时整个 DP gather 只做一轮请求/推理/切片OPD-RL 走 GRPO 路径时共用同一套教师客户端所有教师共享全局--teacher_kl_coef见 gkd_helpers.py 注释。示例GKD 多教师# 部署两个教师服务GKD 要求 max_logprobs gkd_logits_topk CUDA_VISIBLE_DEVICES1 swift deploy --model Qwen/Qwen3.5-4B --port 8000 --max_logprobs 64 CUDA_VISIBLE_DEVICES2 swift deploy --model Qwen/Qwen3.5-1.7B --port 8001 --max_logprobs 64 CUDA_VISIBLE_DEVICES0 swift rlhf \ --rlhf_type gkd \ --model Qwen/Qwen3.5-0.6B \ --teacher_model_server [{url:http://localhost:8000,tags:[data/math.jsonl]},{url:http://localhost:8001,tags:[data/code.jsonl]}] \ --gkd_logits_topk 64 \ --dataset data/math.jsonl data/code.jsonl \ ...示例OPD-RL 多教师CUDA_VISIBLE_DEVICES1 swift deploy --model Qwen/Qwen3.5-4B --port 8000 --max_logprobs 1 CUDA_VISIBLE_DEVICES2 swift deploy --model Qwen/Qwen3.5-1.7B --port 8001 --max_logprobs 1 CUDA_VISIBLE_DEVICES0 swift rlhf \ --rlhf_type grpo \ --model Qwen/Qwen3.5-0.6B \ --teacher_model_server [{url:http://localhost:8000,tags:[data/math.jsonl]},{url:http://localhost:8001,tags:[data/code.jsonl]}] \ --teacher_kl_coef 1.0 \ --dataset data/math.jsonl data/code.jsonl \ --use_vllm true --vllm_mode colocate \ ...3.1 GKD散度作为直接损失GKDGeneralized Knowledge DistillationAgarwal et al., 2023直接把教师-学生散度作为损失函数反向传播。损失函数$$ \mathcal{L}{\text{GKD}}(x, y) \sum{t1}^{|y|} D_{\text{JSD}(\beta)}\big(P_{\text{teacher}}(\cdot|x,y_{t}),, P_{\text{student}}(\cdot|x,y_{t})\big) $$散度 $D$ 由--beta选择见 2.1 节$\beta0$ 为 Forward KL$\beta1$ 为 Reverse KL$0\beta1$ 为广义 JSD默认 $0.5$。On-Policy 与 Off-PolicylmbdaGKD 用lmbda控制每个 batch 使用学生在线采样的概率if random() lmbda: y student.generate(x) # on-policy学生采样 else: y y_ground_truth # off-policy使用数据集标签 loss D(P_teacher(·|x, y), P_student(·|x, y))lmbda0纯离线传统 SFT 蒸馏lmbda1纯在线学生从自己的错误中学习即在线策略蒸馏0lmbda1混合。想使用教师生成的数据时先离线用教师生成响应写入数据集再以lmbda0训练。实现上有两处值得注意的细节其一GKDTrainer._rollout_samples 中按random() lmbda决定数据源为DataSource.STUDENT还是DataSource.DATASET且随机数由 种子与 global_step 构成的独立 Random 实例 生成保证多进程间行为一致、不干扰全局随机态其二compute_loss 中sft_alpha混合的 SFT 损失只加在非学生生成的数据上data_source ! DataSource.STUDENT即纯在线 batch 只含散度损失。GKD 参数参数类型默认值说明--betafloat0.5散度插值0Forward KL0.5JSD1Reverse KL--lmbdafloat0.5在线采样概率0离线1纯在线--sft_alphafloat0SFT 损失混合比例loss gkd_loss sft_alpha * sft_loss仅对非学生生成数据--gkd_logits_topkintNone只用教师 top-K logits 计算 KL使用teacher_model_server时必填Top-K KL 计算默认 KL 在全词表上计算大词表下可能 OOM此时用--gkd_logits_topk。外部教师 API设置--teacher_model_server时须同时设置--gkd_logits_topkAPI 只返回 top-k logprobs。示例# Step 1: 部署教师模型max_logprobs 必须 gkd_logits_topk CUDA_VISIBLE_DEVICES0 swift deploy \ --model Qwen/Qwen3.5-9B \ --infer_backend vllm \ --port 8000 \ --max_logprobs 64 # Step 2: 启动 GKD 训练 CUDA_VISIBLE_DEVICES1,2,3,4 \ NPROC_PER_NODE4 \ swift rlhf \ --rlhf_type gkd \ --model Qwen/Qwen3.5-2B \ --teacher_model_server http://localhost:8000 \ --gkd_logits_topk 64 \ --lmbda 1.0 \ --beta 1.0 \ --dataset xxx源码中top-k 表示由 TeacherOutput 统一封装本地教师的全量 logits 可通过to_topk(k)现场截取API 返回的 top-k logprobs/indices 直接装入gkd_loss 在 top-k 模式下把学生 logits 按教师 top-k 索引 gather 出来仅在 top-K 集合上做 log_softmax 与 KL从而实现“top-K 上重归一化”的近似。此外 extract_active 会断言学生/教师两侧有效 token 数一致OPSD 下两侧 prompt 不同但响应 token 数必须相同并自动丢弃 top-k 全为-inf教师未覆盖的位置。在线采样加速当lmbda 0时学生必须在线生成序列。可用 vLLM 加速采样colocate / server 模式与 GRPO 相同见 GRPO 文档。多轮 GKDGKD 支持多轮训练与 GRPO 共享同一套MultiTurnScheduler基础设施。完整调度器接口与自定义方式见 GRPO 多轮文档。参考脚本基础训练examples/train/rlhf/gkd/多轮训练examples/train/rlhf/gkd/multi_turn.sh多模态examples/train/multimodal/rlhf/gkd/Megatronexamples/megatron/rlhf/gkd/含dense.sh、multi_turn.sh、opsd.sh、teacher_server.sh此外GKD 还支持--use_liger_kernel走 Liger 融合 JSD 损失以节省显存但要求本地教师不支持 API 与自蒸馏、sft_alpha 0且不使用 top-k见 GKDTrainer._prepare_liger_loss。3.2 OPD-RLKL 作为 RL AdvantageOPDOn-Policy DistillationRL 把教师 KL 注入 GRPO 的逐 token advantage经策略梯度更新学生。原理标准 GRPO 的 advantage 来自组内归一化的任务奖励序列级标量。OPD-RL 在 advantage 归一化之后逐 token 注入教师信号$$ A_t A_t^{\text{base}} \alpha \cdot \big(\log \pi_{\text{teacher}}(y_t|x,y_{t}) - \log \pi_{\text{student}}(y_t|x,y_{t})\big) $$$A_t^{\text{base}}$GRPO 归一化后的任务奖励 advantage没有奖励函数时为 0$\alpha$--teacher_kl_coef教师信号强度$\log\pi_{\text{teacher}}(y_t) - \log\pi_{\text{student}}(y_t)$教师对数比即 Reverse KL 梯度中 $\nabla_\theta\log\pi_\theta(y_t)$ 的系数所对应的 k1 估计量对应实现compute_teacher_logratio/ compute_teacher_kl_per_token。纯蒸馏模式不设置--reward_funcs时base advantage 为 0教师信号成为唯一驱动$A_t \alpha\cdot(\log\pi_{\text{teacher}}(y_t)-\log\pi_{\text{student}}(y_t))$。监控指标日志中的teacher_kl是 k3 估计量 $e^{d}-d-1$$d\log\pi_{\text{teacher}}-\log\pi_{\text{student}}$度量学生与教师的距离可在 GRPO 训练器 的指标计算处看到其接入点。启用方式在--rlhf_type grpo下设置--teacher_model或--teacher_model_server即自动启用 OPD-RL——无需额外开关教师参数沿用 3 节开头的共享参数表。OPD-RL 专属参数参数默认值说明--teacher_kl_coef1.0教师对数比注入 advantage 的系数 $\alpha$定义于 args_mixin.py参考脚本HFexamples/train/grpo/opd_rl.shMegatronexamples/megatron/grpo/opd_rl.shRayexamples/ray/grpo/run_opd.sh3.3 OPSD在线策略自蒸馏OPSDOn-Policy Self-Distillation2026是一种单模型自蒸馏方法同一个模型分别构造学生与教师输入教师侧额外接收特权信息如参考解答然后对学生采样出的响应做输出分布对齐。核心机制学生只看到题目正常推理教师通过teacher_prompt看到特权文本通过teacher_images看到特权图像或两者兼有训练目标在同一个学生采样响应上用散度JSD / KL对齐学生与教师的输出分布。OPSD 可以走 GKD 或 OPD-RL 任一路径GKD OPSD--rlhf_type gkd教师 KL 作为直接损失OPD-RL OPSD--rlhf_type grpo动态模式省略--teacher_model固定模式把--teacher_model设为与--model相同。两种自蒸馏权重模式模式配置教师权重说明动态省略--teacher_model学生当前权重教师随训练一起更新固定设置--teacher_model与--model相同初始教师权重教师权重固定数据格式OPSD 数据集提供teacher_prompt列、teacher_images列或两者。teacher_images省略None时教师复用学生的images显式传空列表则教师只获得纯文本视图只提供teacher_images而无teacher_prompt时教师使用学生 messages 配合独立的教师图像。生效教师 prompt 中image标签数量应与教师图像数量一致否则多余标签会残留为文本模板会发出警告。通过--external_plugins加载数据预处理插件来构造教师侧字段。以下以数学推理数据集open-r1/OpenThoughts-114k-math为例from swift.dataset import DatasetMeta, RowPreprocessor, register_dataset class OpenThoughtsOPSDPreprocessor(RowPreprocessor): def preprocess(self, row): if not row.get(correct, True): return None problem row.get(problem, ) solution row.get(solution, ) teacher_prompt f{problem}\n\nReference solution:\n{solution}\n\nNow articulate your own reasoning. messages [ {role: system, content: Please reason step by step, and put your final answer within \\boxed{}.}, {role: user, content: problem}, ] return {messages: messages, teacher_prompt: teacher_prompt} register_dataset(DatasetMeta( ms_dataset_idopen-r1/OpenThoughts-114k-math, preprocess_funcOpenThoughtsOPSDPreprocessor(), tags[math, opsd], ))从源码看OPSD 的关键在于“同一批响应、两套编码”GKDTrainer._encode_samples 对样本同时编码出学生端与教师端输入教师端仅 OPSD 时非 None随后 compute_loss 中两侧各自独立做logits_to_keep裁剪——因为 OPSD 下教师 prompt 与学生 prompt 长度不同损失计算由 extract_active 用各自的 labels 掩码对齐仅要求有效响应 token 数一致。参考脚本HFexamples/train/rlhf/opsd/Megatronexamples/megatron/rlhf/gkd/opsd.sh4. 小结与选型建议离线蒸馏 / 教师生成数据GKD lmbda0或--teacher_model_server--gkd_logits_topk追求简单可控、逐 token 密集监督在线策略蒸馏GKD lmbda1可配 vLLM 加速采样或直接走 OPD-RL既要任务奖励又要教师信号OPD-RL把教师对数比与 GRPO 奖励叠加进 advantage可用teacher_kl指标监控师生距离单模型防遗忘 / 特权信息蒸馏OPSD通过teacher_prompt/teacher_images提供特权上下文动态与固定两种权重模式任选多领域专家融合--teacher_model_server多教师 JSON 按数据集或按样本列路由。三种方法共用同一套教师参数--teacher_model/--teacher_model_server/--teacher_tag_key/--teacher_deepspeed/--offload_teacher_model与底层 logprobs 取数链路实际切换时只需更换--rlhf_type与信号使用方式loss 或 advantage配置迁移成本很低。参考文献Kevin Lu Thinking Machines Lab. On-Policy Distillation. 2025.Agarwal et al. On-Policy Distillation of Language Models (GKD). 2023.Gu et al. MiniLLM: Knowledge Distillation of Large Language Models. 2023.DeepSeek-AI. DeepSeek-V4. 2026.Qwen Team. Qwen3 Technical Report. 2025.Zhipu AI. GLM-5: from Vibe Coding to Agentic Engineering. 2026.Kimi Team. Kimi K2.5: Visual Agentic Intelligence. 2026.【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考