当前位置： 首页 > news >正文

【Agentic RL / 强化学习 / OPD】OpenClaw-RL 源码阅读笔记 --- (14)--- Teacher

news 2026/7/29 21:13:50

【Agentic RL / 强化学习 / OPD】OpenClaw-RL 源码阅读笔记 --- (14)--- Teacher

目录
  • 【Agentic RL / 强化学习 / OPD】OpenClaw-RL 源码阅读笔记 --- (14)--- Teacher
    • 0x00 概要
    • 0x01 基础背景
      • 1.1 完整数据流
      • 1.2 关键点
        • 公式
        • 代码与文件
    • 0x02 教师模型
      • 2.1 具体是什么模型？
      • 2.2 教师模型的架构特性
      • 2.3 教师模型的工作机制
      • 2.4 教师模型的具体应用场景
      • 2.5 教师模型API服务器
        • 关键代码结构
        • 核心实现
        • 双重SGLang架构
      • 2.6 流程
    • 0x03 Teacher log-probs 计算流程
      • 3.1 ① 构建带hint的输入序列
      • 3.2 ② Teacher前向计算
        • prompt
        • 如何让 Teacher 返回 log-probs(不生成新 token)
        • SGLang 返回什么
      • 3.3 ③ 解析 logprobs
      • 3.4 ④ Top-k 变体
      • 3.5 ⑤ 存入Sample
      • 3.6 ⑥ 汇总对比
      • 3.7 完整代码
        • _compute_teacher_log_probs()
        • _compute_teacher_topk_logprobs()
    • 0x04 logprobs分析
      • 4.1 学生(rollout/response)token logprobs
        • 数学符号解释
        • 关键信息
          • 数据收集阶段
          • 训练使用阶段
        • 与其他logps的区别
        • 结论
      • 4.2 教师 token logprobs(单token 路径)
      • 4.3 教师 top-k logprobs(Top-K分布路径)
      • 4.4 Reference logprobs(ref_log_probs)
      • 4.5 训练/前向产生的log_probs(trainer内部)
      • 4.6 元数据/输入输出相关的 logprobs字段(辅助字段)
      • 4.7 关键要点
        • 存储字段&代码中的映射(谁写入、谁读出)
        • 关键实现文件
        • 实践注意事项(代码层)
    • 0x05 Top-K 解读
      • 5.1 为什么需要 Top-K 蒸馏？
      • 5.2 Top-K 蒸馏在 OpenClaw 中的位置
      • 5.3 核心机制：Tail Trick + Reverse KL
        • 5.3.1 问题：15 万词表 vs 50 个 top-K
        • 5.3.2 Tail 的数值计算
        • 5.3.3 Reverse KL 散度
      • 5.4 完整数据流：从 API Server 到 Loss
      • 5.5 关键设计选择：Teacher Top-K vs Student Top-K
        • 5.5.1 为什么选 Teacher Top-K？
        • 5.5.2 Student Top-K 的优势(OpenClaw 放弃的)
      • 5.6 数值风险
      • 5.7 两种 OPD 路径对比总表
      • 5.8 常见问题
    • 0xFF 参考

0x00 概要

本系列的目的是：借着对 OpenClaw-RL 源码的学习，来梳理强化学习的一些相关概念和思想。所以，会有一些基础知识、扩展和发散，OpenClaw-RL 只是一个切入点。而且，因为整篇系列是一个整体，所以有些概念的解读/学习会在不同的文章中出现，还请大家谅解。

OpenClaw-RL 是一个用于在线强化学习(Online RL)的框架，专门针对智能体工具使用场景。它通过从环境反馈中提取过程奖励信号来训练语言模型，支持三种主要模式：

  • openclaw-rl：基于二元奖励的强化学习(Binary RL / GRPO)
  • openclaw-opd：基于后见之明提示的在线策略蒸馏(On-Policy Distillation, OPD)
  • openclaw-combine：联合方法，在同一 PPO 更新中同时利用 RL reward 和 OPD teacher signal

frameworkOPD的流程如下：

[Rollout/Agent] ──生成样本──► [Data Buffer]│                           ▲▼                           │
[Judge/Hint/PRM] ──奖励/hint───────┤│                           │▼                           │
[Teacher Model] ──log-probs────────┤│                           │▼                           │
[Trainer] ◄───读取样本/训练──────────┘│▼
[参数同步] ──更新权重──► [Rollout/Agent]

我们今天要看看其 Teacher 部分。教师模型是OpenClaw-RL项目中实现高效在线蒸馏学习的关键组件，它通过将延迟反馈转化为即时的token级别监督信号，显著提升了学习效率和模型性能。其设计充分考虑了实际部署的需求，在保证性能的同时兼顾了资源利用效率和系统稳定性。

0x01 基础背景

1.1 完整数据流

OpenClaw-OPD 完整数据流如下：

14-完整数据流

具体参见下表

流向 说明
Rollout/Agent → Judge/Hint/PRM 生成数据送评判
Judge/Hint/PRM → Teacher Model 提取 hint 后送教师模型
Judge/Hint/PRM → Data Buffer 奖励/hint 信息送入缓冲区
Teacher Model → Data Buffer teacher 信号送入缓冲区
Rollout/Agent → Trainer 学生模型参与训练
Data Buffer → Trainer 缓冲数据送入优化器
Teacher Model → Trainer 教师信号用于损失计算
Trainer → 参数同步 训练完成，更新参数
参数同步 → Rollout/Agent 同步后模型用于下一轮采样

1.2 关键点

公式

优势计算:  A_t = teacher_logp - student_logp(即教师模型与学生模型的对数概率之差)

代码与文件

  • openclaw_opd_api_server.py：消息规范、hint提取、Sample 组装的入口逻辑。
  • README.md：OPD 的算法说明、Top-K选项与公式。
  • run_qwen3_4b_openclaw_opd.sh：启动参数、HF_CKPT、并发设置OPENCLAW_OPD_TEACHER_LP_MAX_CONCURRENCY。
  • openclaw_combine_api_server.py：展示了如何把 teacher_log_probs 写到 Sample(padding/cropping)。
  • README.md：Data Buffer、rollout 与 trainer 的模块级别职责说明。
  • slime/utils/types.py(样本类型定义，可查看 Sample 字段结构)。

0x02 教师模型

教师模型的设计使得OPD能够获得比普通 RL更丰富、更细粒度的监督信号，从而实现更快的收敛速度和更好的最终性能。

openclawrl1performance

2.1 具体是什么模型？

在OpenClaw-RL框架中，教师模型是一个具有双重角色的核心组件，主要用于On-Policy Distillation(OPD)训练方法。 教师模型本质上是一个高质量的参考模型，用于从延迟的用户反馈中提取密集的监督信号，从而指导学生策略模型的学习。

OpenClaw-RL 中的“教师模型"主要指在 On-Policy Distillation (OPD)阶段用于为学生模型提供 token-level 指导信号的模型。根据训练脚本和文档，教师模型默认是 Qwen3-4B(Qwen3-4B-Thinking-2507)，即通过 qwen3-4B.sh 配置和HF_CKPT 路径指定的 HuggingFace Qwen3-4B 权重。

简要总结：

  • 数师模型 = Qwen3-4B(Qwen3-4B-Thinking-2507)
  • 用于 OPD 阶段，提供 token 级别的 log-prob指导信号

2.2 教师模型的架构特性

双重角色统一端点

  • 使用同一个SGLang服务端点同时承担PRM评估(提示提取)和教师模型(对数概率计算)双重功能
  • 通过不同的请求参数来区分具体功能，实现资源的有效复用

模型配置特点

  • 默认情况下使用与学生策略相同的基座模型(如Qwen3-4B系列)
  • 运行时不加载LoRA适配器，确保提供稳定、高质量的监督信号
  • 支持通过环境变量或命令行参数单独指定不同的教师模型

2.3 教师模型的工作机制

确定性推理配置

  • 使用temperature=0.0确保推理结果的一致性

  • 设置max_new_tokens=0，只计算已有 token 的 logprobs，不生成新内容

  • 这种配置保证了在相同输入下始终产生相同的输出分布

并发控制机制

  • 通过_teacher_lp_semaphore信号量限制最大并发查询数量

  • 默认并发数由环境变量OPENCLAW_OPD_TEACHER_LP_MAX_CONCURRENCY控制

  • 防止教师模型服务过载，确保系统稳定性

增强Prompt构建流程

  • 首先从用户反馈中提取有效的“hint”(提示)

  • 将提取的提示注入到原始对话历史中，构建增强的prompt

  • 基于这个增强prompt查询教师模型的对数概率分布

2.4 教师模型的具体应用场景

OPD训练流程中的作用

原始对话 → 学生响应 → 用户反馈 → 提示提取 → 增强prompt → 教师logprobs → 蒸馏训练

与传统RL的区别

  • 传统RL：使用标量奖励(+1/-1/0)，提供稀疏的试错信号

  • OPD教师模型：提供token级别的对数概率分布，提供密集的监督信号

资源分配

  • 在多GPU部署中，教师模型通常分配专门的GPU资源(通过PRM_GPUS参数配置)
  • 与学生策略模型和rollout收集器并行运行，形成完整的异步训练流水线

2.5 教师模型API服务器

  • openclaw-opd/openclaw_opd_api_server.py：包含完整的教师模型查询逻辑
    • 教师模型端点配置(_prm_url变量)
    • 并发控制机制(_teacher_lp_semaphore信号量)
    • 确定性推理参数设置
    • 增强prompt构建和logprobs计算

关键代码结构

关键代码结构如下

OpenClaw-OPD API Server (根节点)├─ 初始化阶段 (分支)│   ├─ PRM/教师模型URL配置 (叶子)│   ├─ 并发信号量初始化 (叶子)│   └─ Tokenizer加载 (叶子)│├─ 评估阶段 (分支)│   ├─ 提示提取 (hint extraction) (叶子)│   ├─ 增强prompt构建 (叶子)│   └─ 教师logprobs查询 (叶子)│└─ 提交阶段 (分支)├─ 样本格式化 (叶子)└─ 训练队列提交 (叶子)

核心实现

OPD的核心实现在openclaw-opd/目录下，主要包含三个关键文件：

  • openclaw_opd_api_server.py：核心业务逻辑，包含提示提取、教师查询、双重评估
    • 提示提取评估 (_build_hint_judge_messages())
    • 教师模型查询(_append_hint_to_messages())
    • 双重评估机制(提示提取+PRM评估)样本构建和队列提交
  • openclaw_opd_rollout.py：与Slime训练框架的集成接口
    • rollout 函数，
    • generate_rollout_openclaw_opd() 函数
    • 与AsyncRolloutworker 的集成接口
  • topk_distillation_loss.py：
    • Top-K蒸馏损失函数实现
    • 支持Top-K logits蒸馏的损失计算
    • 教师一学生对数概率差计算

双重SGLang架构

OPD使用同一个PRM URL同时承担双重角色：

  • 资源复用：同一个 SGLang 实例承担双重角色
  • PRM评估角色：执行提示提取和PRM评分
  • 教师模型角色：执行教师对数概率计算
  • 不同payload：通过不同的请求参数区分用途

2.6 流程

OPD 实现中各阶段的函数调用链如下（2.4 节给出了概念流程，这里给出具体的代码调用链）：

用户请求 → OpenClawOPDAPIServer._handle_main_turn()↓ (SGLang 推理)学生模型生成响应 + logprobs↓ (状态缓冲)缓存当前回合数据↓ (下一状态触发)新请求到达 → 触发 _fire_opd_task()↓ (异步任务)_opd_evaluate() → 提示提取评估↓ (成功提取提示)构建增强 prompt（注入提示）↓ (教师查询)_compute_teacher_log_probs() → 调用 PRM/教师 SGLang↓ (样本构建)构建包含 teacher_log_probs 的 Sample↓ (队列提交)output_queue.put() → Slime 训练器

我们以 _compute_teacher_log_probs 为基础，来看看 Teacher log-probs 计算流程。为了完整叙事，此处也会把前面完整流程的某些其它部分带入。

0x03 Teacher log-probs 计算流程

Teacher forward pass 的关键：

  • hint 注入最后一个 user 消息；
  • max_new_tokens=0 不生成，只算log-probs;
  • “logprob_start_len只取 response 部分。SGLang被当成"log-prob 计算器"。

触发条件：

  • Hint Judge 接受了 hint(select_best_hint返回非None)。

实现细节：

  • 构建完整文本：enhanced_full_text =enhanced_prompt_text+ turn_data["response_text"]

  • Token化：enhanced_ids = self.tokenizer(enhanced_full_text,add_special_tokens=False)["input_ids"]

  • 并发控制：async with self._teacher_lp_semaphore:

  • _查询教师模型：通过HTTP请求到PRM/教师端点获取log probabilities

  • Top-K蒸馏扩展：

    • 条件判断：if self._use_topk_distillation:
    • 调用：topk_lp，topk_idx = await self._compute_teacher_topk_logprobs(enhanced_ids，response_len)
    • 存储单独的top-k字段

我们接下来看看具体细节。

3.1 ① 构建带hint的输入序列

核心方法：_opd_evaluate

具体实现步骤：

  • 构建评估消息：_build_hint_judge_messages(turn_data["response_text"]，next_state_text，next_state_role)
  • 应用tokenizer模板：self._prm_tokenizer.apply_chat_template()
  • 并行执行M次投票：asyncio.gather(*[self._query_judge_once(judge_prompt， i) for i in range(self._prm_m)])
  • PRM 评估提示构建：_build_prm_eval_prompt()
  • PRM 多数投票：prm_eval_majority_vote()
  • PRM 评分解析：_parse_prm_eval_score()
  • 解析提示提取结果：_parse_judge_result()
  • 选择最佳提示：selected =_select_best_hint(votes)

投票逻辑：

  • 每次投票返回评分(+1/-1)和可选的hint文本
  • 选择最长的有效正面提示
  • 如果没有有效提示，则丢弃该样本

关键函数：

  • _append_hint_to_messages：将提取的hint添加到原始对话末尾
  • normalize_messages_for_template：标准化消息格式
  • apply_chat_template：应用tokenizer的聊天模板

具体逻辑如下：

==========================================================================
【步骤一】构建带hint的输入序列
==========================================================================代码实现：hint = selected["hint"].strip()enhanced_messages = _append_hint_to_messages(turn_data["messages"], hint)norm_enhanced = _normalize_messages_for_template(enhanced_messages)enhanced_prompt_text = self.tokenizer.apply_chat_template(norm_enhanced,tools=turn_data.get("tools"),tokenize=False,add_generation_prompt=True,)原始messages (无hint)：
[system:,..., user："帮我写排序"，assistant："..."，user："能优化吗"]hint 注入  (_append_hint_to_messages):找到messages中"最后一条user消息" (从后往前遍历)在其content末尾追加："\n\n[user's hint/ instruction]\n{hint.strip()}" ↓
enhanced_messages:
[system:,..., user："帮我写排序\n\n[user'shint/instruction]\n使用快排,...,]apply_chat_template(enhanced_messages)→ enhanced_prompt_text 
enhanced_full_text = enhanced_prompt_text + response_text (原始response)
enhanced_ids=tokenizer(enhanced_full_text)["input_ids"]||[prompt_with_hint_tokens ... response_tokens]| ←-----start_len-------→    ←-response_len--→ |(prompt部分，含hint)▼

3.2 ② Teacher前向计算

==========================================================================
【步骤二】Teacher前向计算 (max_new_tokens=0)
==========================================================================并发控制:Semaphore (max_concurrency=3) (OPENCLAW_OPD_TEACHER_LP_MAX_CoNCURRENCY) POST→PRM Engine  (GPU 6-7)/generate
┌─────────────────────────────────────────────────────────┐ 
│ payload:                                                │ 
│     "input_ids":enhanced_ids (prompt_with_hint+ response│ 
│     "sampling_params":{"temperature":0.0,               │ 
│     "max_new_tokens":0  ←- 纯前向，不生成任何token         │ 
│     }                                                   │ 
│     "return_logprob":True                               │ 
│     "logprob_start_len":start_len                       │ 
│         = max(0,len(enhanced_ids) -response_len)        │ 
│         ←-只返回 response 位置的 logprobs，节省带宽         │ 
└─────────────────────────────────────────────────────────┘ 返回：`meta_info["input_token_logprobs"]:[ (lp_0,tok_0), (1p_1,tok_1),..., (1p_T，tok_T)](start_len之后的位置)

prompt

Teacher 用的是用户对话中原本就有的 system prompt(如果有的话)。即，Teacher 不添加任何额外 system prompt。它看到的完全是用户的原始对话+hint 注入到最后一个 user 消息。

对比如下：

对象 System Prompt
用户对话 用户自己设的（或App默认的）
Teacher forward pass 和用户对话相同（原封不动保留）
PRM/Hint Judge 独立的评分system prompt
训练sample 和用户对话相同（sample.tokens来自原始messages）

如何让 Teacher 返回 log-probs(不生成新 token)

关键参数：

payload = {"input_ids": enhanced_ids,            # ← 完整序列 (prompt + response)"sampling_params": {"temperature": 0.0,               # ← 不重要，因为不生成，不影响forward pass"max_new_tokens": 0,              # ← 🔑 关键！不生成任何新 token，只做forward pass"skip_special_tokens": False,},"return_logprob": True,               # ← 🔑 返回 log-probs"logprob_start_len": start_len,       # ← 🔑 只返回 response 部分的 log-probs"top_logprobs_num":K,                 # ← 🔑 返回每位置top-K个token的logprob
}

核心技巧：max_new_tokens=0把SGLang当成"log-prob计算器“而非"文本生成器"。max_new_tokens=0 的含义如下：

正常生成(max_new_tokens > 0)：输入 [prompt] → 模型生成 [token1, token2, ...] → 返回生成的 tokensTeacher forward pass(max_new_tokens = 0)：输入 [prompt + response] → 模型只做 forward pass → 不生成任何 token但计算了每个位置的 log P(token_t | context_<t) → 返回这些 log-probs

logprob_start_len 的含义：

enhanced_ids = [p1, p2, ..., pN, r1, r2, ..., rT]└──── prompt ────┘ └─ response ─┘start_len = len(enhanced_ids) - response_len = N→ 只返回位置 N 之后的 log-probs(即 response 部分)
→ 省掉了 prompt 部分的 log-probs(我们不需要)

SGLang 返回什么

{"meta_info": {"input_token_logprobs": [null, // 位置 0 (第一个 token 无条件概率)[-2.3, 15234], // 位置 1: logprob=-2.3, token_id=15234[-1.5, 8901], // 位置 2: logprob=-1.5[-0.8, 3456], // ......]}
}

3.3 ③ 解析 logprobs

==========================================================================
【步骤三】解析 logprobs - 对齐到response tokens
==========================================================================all_lp=[item[o] for item in input_token_logprobs] 注意：SGLang返回的input_token_logprobs 包含一个偏移： all_lp=all_lp[1:] ← 去掉第一个 (位置偏移修正)对齐到response_len：对齐到response_len：len(all_lp) >= response_len:teacher_log_probs=all_lp[-response_len:] ← 取末尾T个 len(all_lp)<response_len:teacher_log_probs=[0.0]*(response_len-len(all_lp))+ all_lp ← 前补零最终：teacher_log_probs shape=[T]log π_teacher(r_t| prompt_with_hint,r_1..r_{t-1}) for t in 1..T

解析 log-probs 的代码如下：

# 解析 SGLang 返回的 log-probs
all_lp = []
for item in inp:if isinstance (item, (list, tuple)) and len (item) >= 1:val = item [0] # 取第一个元素 = log-proball_lp.append (float (val))elif isinstance (item, dict) and "logprob" in item:val = item ["logprob"] # 或 dict 格式all_lp.append (float (val))all_lp = all_lp [1:] # 跳过位置 0 (BOS)
return all_lp [-response_len:] # 只取最后 response_len 个

3.4 ④ Top-k 变体

当distill_topk>0时(如K=5)，会进行 top-k计算，不只记录teacher对当前token的log-prob，而是记录每个位置teacher最高K个token的分布。

==========================================================================	
【Top-k 变体】(_compute_teacher_topk_logprobs,--distill-topk K) 
==========================================================================# teacher_topk_log_probs：[T，K]←.T个位置，每个位置top-K个log-prob
# teacher_topk_indices：[T，K]对应的 token ID
# Loss: reverse KL over K+1 bins(top-K+ tail mass)    async def _compute_teacher_log_probs(self, input_ids, response_len):# 关键: max_new_tokens=0 -> 不生成, 只前向传播payload = {"input_ids": input_ids,    # 增强prompt + 原始response的token ids"sampling_params": {"temperature": 0.0,"max_new_tokens": 0,   # <- 只计算 log-probs, 不采样},"return_logprob": True,"logprob_start_len": start_len,  # 只返回 response 部分的 log-probs}# 返回: teacher 在看到 hint 后, 对原始 response 每个 token 的 log-prob此函数表达的语义: 如果 teacher 在生成时拥有这个 hint (事后诸葛亮信息), 它对这段 response 的每个 token 的置信度是多少?                      额外参数："top_logprobs_num"：K → SGLang 返回每个位置top-K候选meta_info["input_top_logprobs"]:
[[(1p，tok_id)，(lp,tok_id),...xk]， ← position 0
[(lp，tok_id),...xk],                ← position 1
...                                   ← position T ]同样[1：]偏移修正 + 对齐response_len： teacher_topk_log_probs  shape=[T,K]teacher_topk_indices    shape=[T,K]用途：SDFT/SDPO风格蒸馏student在每个位置学习对top-Kteacher候选的概率分布而非仅对 response 中实际 token 的单点 log-prob

3.5 ⑤ 存入Sample

此部分完成样本提交：_submit_turn_sample方法

数据处理(解析返回)：

  • 对齐teacher_log_probs和response_ids长度

  • 处理长度不匹配的情况(截断或填充)

  • 构建完整的训练样本包含：

    • prompt_ids
    • response_ids
    • teacher_log_probs
    • rollout_log_probs
response.meta_info.input_token_logprobs → 解析 → teacher_log_probs
teacher_log_probs =[-0.9, -0.6,-1.8,-1.0,...]↑每个 response token 的log P(token |enhanced_prompt + 前文)

存入Sample / 队列提交：

  • 通过self.output_queue.put()将样本提交到训练队列
  • 训练系统从队列中消费样本进行蒸馏训练
sample.teacher_log_probs = tensor(teacher_log_probs) 
→ 送给Slime计算OPD advantage

3.6 ⑥ 汇总对比

【汇总对比】三种 log-prob 的来源与用途
+------------------------+--------------------+-----------------------------------+
| log-prob 类型          | 计算时机            | 含义                               |
+------------------------+--------------------+-----------------------------------+
| rollout_log_probs      | SGLang 生成时       | log π_old(r|prompt)              |
| (old policy)           | 一次性获得          | 不含 hint, 原始对话上下文            |
+------------------------+--------------------+-----------------------------------+
| teacher_log_probs      | next_state 到来后   | log π_teacher(r|prompt+hint)     |
| (teacher forward pass) | 异步计算            | 含 hint, Teacher 怎么看该response  |
+------------------------+--------------------+-----------------------------------+
| new_log_probs          | Megatron 训练前向   | log π_new(r|prompt)               |
| (current policy)       | 每个 gradient step  | 训练中当前策略                      |
+------------------------+--------------------+-----------------------------------+OPD advantage per token t:Δ_t = teacher_log_probs[t] - rollout_log_probs[t]= log π_teacher(r_t | prompt+hint) - log π_old(r_t | prompt)直觉: hint 告诉 teacher "这里应该怎么做"teacher 给 response 中每个 token 打分越高 → 该 token 越值得被学习Δ_t > 0 → 强化该 token; Δ_t < 0 → 抑制该 token

3.7 完整代码

3.2-3.4 节给出了关键参数和解析逻辑的片段，这里给出两个核心函数的完整实现，便于对照。

_compute_teacher_log_probs()

async def _compute_teacher_log_probs(self, input_ids: list[int], response_len: int) -> list[float]:start_len = max(0, len(input_ids) - response_len)payload = {"input_ids": input_ids,"sampling_params": {"temperature": 0.0,           # 确定性推理"max_new_tokens": 0,          # 不生成新 token"skip_special_tokens": False,},"return_logprob": True,"logprob_start_len": start_len,   # 从响应开始位置计算}async with self._teacher_lp_semaphore:  # 并发控制（信号量）async with httpx.AsyncClient(timeout=None) as client:resp = await client.post(self._prm_url, json=payload)resp.raise_for_status()result = resp.json()meta = result.get("meta_info", {}) if isinstance(result, dict) else {}inp = meta.get("input_token_logprobs")if not isinstance(inp, list):return [0.0] * response_lenall_lp = []for item in inp:if isinstance(item, (list, tuple)) and len(item) >= 1:val = item[0]all_lp.append(float(val) if val is not None else 0.0)elif isinstance(item, dict) and "logprob" in item:val = item["logprob"]all_lp.append(float(val) if val is not None else 0.0)else:all_lp.append(0.0)if len(all_lp) > 1:all_lp = all_lp[1:]  # 跳过位置 0 (BOS)if len(all_lp) >= response_len:return all_lp[-response_len:]return [0.0] * (response_len - len(all_lp)) + all_lp

_compute_teacher_topk_logprobs()

async def _compute_teacher_topk_logprobs(self, input_ids: list[int], response_len: int
) -> tuple[list[list[float]], list[list[int]]]:"""Compute teacher's top-K log-probs and token indices for response tokens."""K = self.distill_topkstart_len = max(0, len(input_ids) - response_len)payload = {"input_ids": input_ids,"sampling_params": {"temperature": 0.0,"max_new_tokens": 0,"skip_special_tokens": False,},"return_logprob": True,"logprob_start_len": start_len,"top_logprobs_num": K,}async with self._teacher_lp_semaphore:async with httpx.AsyncClient(timeout=None) as client:resp = await client.post(self._prm_url, json=payload)resp.raise_for_status()result = resp.json()meta = result.get("meta_info", {}) if isinstance(result, dict) else {}inp_top = meta.get("input_top_logprobs")if not isinstance(inp_top, list):return [[0.0] * K] * response_len, [list(range(K))] * response_lenall_logprobs: list[list[float]] = []all_indices: list[list[int]] = []for pos_data in inp_top:if isinstance(pos_data, (list, tuple)):row_lp, row_idx = [], []for entry in pos_data:if isinstance(entry, (list, tuple)) and len(entry) >= 2:row_lp.append(float(entry[0]) if entry[0] is not None else 0.0)row_idx.append(int(entry[1]))elif isinstance(entry, dict):row_lp.append(float(entry.get("logprob", 0.0)))row_idx.append(int(entry.get("token_id", 0)))else:row_lp.append(0.0)row_idx.append(0)while len(row_lp) < K:row_lp.append(0.0)row_idx.append(0)all_logprobs.append(row_lp[:K])all_indices.append(row_idx[:K])else:all_logprobs.append([0.0] * K)all_indices.append(list(range(K)))if len(all_logprobs) > 1:all_logprobs = all_logprobs[1:]all_indices = all_indices[1:]if len(all_logprobs) >= response_len:return all_logprobs[-response_len:], all_indices[-response_len:]pad_len = response_len - len(all_logprobs)return ([[0.0] * K] * pad_len + all_logprobs,[list(range(K))] * pad_len + all_indices,)

0x04 logprobs分析

OpenClaw-RL 主要出现的 logprobs 类型有：学生侧(rollout)token logprobs、教师侧 token logprobs、教师侧top-k logprobs、训练/ 前向产生的model log_probs，以及著干元数据字段(input/output/top logprobs)。

四种主要logps类型：

  • Rollout Logps (学生当前策略)
  • Teacher Logps (标准 token级别)
  • Teacher Top-K Logps (分布级别)
  • Reference Logps (KL正则化)

各类型的应用场景：

  • Rollout Logps:所有RL和OPD方法都需要
  • Teacher Logps：OPD标准模式专用
  • Teacher Top-K Logps：OPD Top-K蒸馏模式专用
  • Reference Logps：KL正则化需要(可选启用)

数据流向

Rollout阶段 → 获取Rollout Logps↓ 
用户反馈 → 提示提取 → 增强Prompt↓ 
教师壹询 → 获取Teacher Logps/Top-K Logps↓ 
训练阶段 → 结合Reference Logps进行损失计算

4.1 学生(rollout/response)token logprobs

数学符号解释

  • log π_student(a_t|s)表示在状态s下，学生策略模型对动作a_t的对数概率
  • 这正是rollout阶段收集的学生模型log probabilities
  • 用于计算蒸馏优势：A_t=logπ_teacher(a_t|s+hint)-logπ_student(a_t|s)

关键信息

  • 名称与字段：常见字段名为 response_logprobs / rollout_log_probs(最终写入 Sample 为sample.rollout_log_probs)

  • 产生位置(实现)：openclaw_opd_api_server.py 中的 _extract_logprobs_from_chat response(从响应 meca 中抽取)及后续量值，另有生成端实现如 generate_with_retool.py 将output_token_logprobs 聚合到 sample.rollout_log_probs.

  • 用途与消费方：

    • 在rollout阶段由学生策略模型生成的对数概率

    • 用于计算策略梯度和KL散度正则化项

    • 数据收集阶段
      • 在openclaw-opd/openclaw_opd_api_server.py的_handle_request方法中_
      • 通过SGLang服务获取当前学生策略的logprobabilities
      • 存储为turn_data["rollout_log_probs"]
      训练使用阶段
      • 在提交样本时，这些rolloutlogprobs作为logr_student传递给训练系统
      • 在损失计算中直接用作学生策略的对数概率

    • 存储在turn_data["rollout_log_probs"]字段中

    • 作为“old/rollout logprobs“，用于监控rollout vs training drift(见combine loss.py 中 rollout_log_probs 分支)，也会被写入 Data Buffer 供 Trainer 计算优势或监控。

  • 数据形状：与 response_ids对齐，按token顺序的浮点 log-prob列表(长度不足时代码会pad0.0，超长则裁剪)

  • 获取方式

    • 通过SGLang服务调用时设置logprobs=True和top_logprobs=1
    • 在_handle_request方法中获取
    • 从SGLang响应的logprobs字段中提取

与其他logps的区别

log π_student 与Reference Logps的区别

  • Reference Logps来自参考模型(通常是初始策略)
  • Rollout Logps来自当前训练中的学生策略
  • 两者用途不同：前者用于KL正则化，后者用于策略梯度和蒸馏

动态更新特性

  • logπ_student随着训练进行而不断更新
  • 每次rollout都反映当前学生策略的能力
  • 这保证了蒸馏目标始终基于最新的学生表现

结论

  • log π_student就是学生模型logps(Rollout Log Probabilities)
  • 这是OPD方法中计算token级别蒸馏优势的关键组成部分，在整个训练流程中保持一致的语义和用途
  • 这种设计使得OPD能够提供精确的改进方向，支持高效的在线蒸馏学习
  • 相比传统RL的标量奖励，token级别的对比提供了更丰富的学习信号

4.2 教师 token logprobs(单token 路径)

teacher log-probs 只做forward pass(max_new_tokens=0)，不生成新 token。通过logprob_start_len参数只返回 response 部分的log-probs。这比生成+评估高效得多。

  • 名称与字段：teacher_log_probs(写入 Sample为 sample.teacher_log_probs)。

  • 标准token级别logps

    • 由教师模型在增强prompt基础上计算的对数概率
    • 存储在opd_result["teacher_log_probs"]字段中
    • 用于计算token级别的蒸馏优势：A_t=logπ_teacher-logπ_student
    • logπ_student 就是 学生模型logps(Rollout Log Probabilities)

  • 产生位置(实现)：在openclaw_opd_api_server.py，函数_compute_teacher_log_probs(以增强 prompt 调用教师模型并返回每) token log-prob)，以及 API server 将其放入返回结果/样本。openclaw_combine_api_server.py也有相同取用/载剪逻辑。

  • 用途与消费方：用于 OPD 的 token-level advantage 计算(A_t=log π_teacher-log π_student)，在 Trainer的OPD 损失路径中被消费(见README.md与训练损失实现处)

  • 数据形状：长度与响应token数对齐(代码保证pad/trim)。

  • 获取方式

    • 通过_compute_teacher_log_probs方法计算
    • 使用temperature = 0.0的确定性推理
    • 仅计算原始响应token的logprobabilities

4.3 教师 top-k logprobs(Top-K分布路径)

  • 名称与字段：teacher_topk_log_probs、teacher_topk_indices(写入 Sample为 sample.teacher_topk_log_probs / sample.teacher_topk_indices)

  • 产生位置(实现)：openclaw_opd_api_server.py的 _compute_teacher_topk_logprobs，会读取 meta 字段(如 input_top_logpr obs)并返回 [T，K] 的 top-Klogprobs 和对应索引。

  • 用途与消费方：供 Top-K蒸馏路径(SDFT/SDPo 风格)使用：损失实现见 topk_distillation_loss.py，该模块读取teacher_topk_log_probs + teacher_topk_indices。

  • 数据形状：二维数组，shape=[response_len，K]，短缺时pad，长余时截断(代码有相应处理)。

  • Top-K教师logps

    • 教师模型输出的top-Ktoken对数概率分布
    • 存储在opd_result["teacher_topk_log_probs"]字段中(形状[T，k])
    • 对应的token索引存储在teacher_topk_indices字段中

  • 实现细节

    • 通过_compute_teacher_topk_logprobs方法获取
    • 使用SGLang的input_top_logprobs参数请求top-Klogprobs
    • 默认K=50(可通过--distill-topk参数配置)

4.4 Reference logprobs(ref_log_probs)

  • 字段：ref_log_probs(可能存在于 batch/sample 中，trainer 可读取为 batch[“ref_log_probs"])
  • 产出／生成位置(实现)：
    • 训练端按需在线计算：rl_utils.py 中有计算 ref logprobs 的逻辑，通过带 torch.no_grad() 的 ref 模型前向收集 ref_logprobs 并放入 packing context，再传入 trainer。
    • actor/rollout 端可创建 ref 模型：actor.py 中有 _create_ref _model,actor 进程可加载 args.ref _load 指定的 reference checkpoint.
    • 运行脚本/环境变量：多个启动脚本(例如openclaw-opd/run_.sh、opericlaw-combine/run_.sh)接受REF_LOAD/ref-load，默认常设为 HF_CKPT 或显式路径；arguments.py 里会校验 args.ref_load。
  • 用途与消费方：
    • KL 正则：在 combine_loss.py 中，如果 args.use_kl_loss 且 batch.get("ref_log_probs") 存在，则把 ref log_probs 用作> 参考分布，调用 KLloss 函数(new_log_probs，ref_log_probs，kl_loss_type)。
      • 由参考模型(通常是初始策路或基座模型)计算的对数概率
      • 组于KL正则化，防止策略偏离太远
    • 监控/性能统计：train_metric_utils.py会以 perf/ref_log_probs_time 等项记录与计算性能指标。
    • 对齐/包装：rl_utils.py 提供.pack_inference_logprobs、align_unpacked_inference_logprobs 等，处理 ref_logprobs 在 pa cked/unpacked序列中的对齐。
  • 数据形状与对齐：ref_log_probs 与new_log_probs/old_log_probs 需形状对齐(按序列/packed bin)，代码在packing阶段> 将 ref_logprobs 拼接并放入 packing_context['ref_logprobs'](见 rl_utils)。当 batch 中存在 ref_log_probs 时，训练会 torch. cat(batch["ref_log_probs"],dim=0)。
  • 何时由样本携带vs 在线计算：项目支持两种方式：样本层携带(若 Data Buffer 提前填入)或训练端在forward 时根据args.re f_load 在线计算并注入 packing context；实际实现以训练配置为准(slime 会决定 actor/trainer 是否预先加载 ref 模型或在 trainer side 计算)。

4.5 训练/前向产生的log_probs(trainer内部)

  • 名称与字段：训练批次中有 log_probs（新 forward 计算得到）、old_log_probs/rollout_log_probs（来自样本）以及可选的 ref_log_probs（参考模型）。
  • 产生位置(实现)：训练时通过get_log_probs_and_entropy(在slime/backends或Megatron 的工具里)得到new_log_probs; 打包/对齐逻辑在 rl_utils.py的 pack_inference_logprobs/ align_unpacked_inference_logprobs 中。combine_loss.py 使用这些值计算PPO/kl/combined loss。
  • 用途与消费方：用于计算PPO风格的策略损失(newvsold)，与OPD的teacher信号联合计算优势/KL项。
  • 用于PPO/KL/combinedloss的主计算(见combine_loss.py)

4.6 元数据/输入输出相关的 logprobs字段(辅助字段)

  • 常见字段：input_token_logprobs、input_top_logprobs、output_token_logprobs 等，通常存在于模型返回的 meta 或推理请求体中
  • 位置与用途：这些字段在openclaw_opd_api_server.py 中被读取以加速/拼接teacher/topk计算；generate_with_retool.py产生 output_token_logprobs 用来汇总 rollout logprobs。

4.7 关键要点

存储字段&代码中的映射(谁写入、谁读出)

  • 写入 Sample(由 API server / rollout):sample.rollout_log_probs 由_extract_logprobs_from_chat_response /生成端累> 积写入。sample.teacher_log_probs/ sample.teacher_topk_log_probs ←由 _compute_teacher_log_probs / _compute_teacher_topk_l ogprobs 写入。
  • Trainer 读取：训练批次(来自 slime Data Buffer)供 combine_loss.py、topk_distillation_loss.py、Megatron 后端函数读取rollout_log_probs/ teacher_log_probs/ teacher_topk_log_probs/ log_probs 并计算损失。

关键实现文件

  • openclaw_opd_api_server.py：抽取响应 logprobs、计算teacher logprobs/top-k、组装sample(主要实现点)。
    openclaw_combine_api_server.py：样本合并、teacher log_probs 写入示例(裁剪/pad)。
  • topk_distillation_loss.py：读取并消费 teacher_topk_log_probs的损失实现。
  • combine_loss.py：训练端整合 rollout_log_probs、teacher_log_probs 与模型forward log_probs 的计算与合成损失。
  • generate_with_retool.py：生成端如何收集 output_token_logprobs 并累积到 sample.rollout_log_probs。
  • rl_utils.py：inference/pack/align logprobs的工具函数(trainer 内部对齐使用)。

实践注意事项(代码层)

  • 对齐与 tokenizer：教师与学生必须使用相同 tokenizer/ckpt，否则 response_ids 与 teacher_log_probs 无法正确对齐。
  • pad/trim策略：API server 中会对长度不一致做裁剪或pad(见openclaw-opd/openclaw-combine 的sample组装处)。
  • 并发与性能：教师查询并发受OPENCLAW_OPD_TEACHER_LP_MAX_CONCURRENCY 控制，Top-K会增加开销。
  • 监控：可对比rollout_log_probs 与训练时new_log_probs 的差异(combine_loss.py 中有监控代码段)。

0x05 Top-K 解读

5.1 为什么需要 Top-K 蒸馏？

为什么需要 Top-K 蒸馏？这是因为 单值 OPD 的局限。

标准 OPD(token-level)的工作方式是：对每个 token 位置，teacher 给一个 scalar logprob，trainer 计算 A_t = teacher_lp - student_lp，然后走 PPO。这个方案有一个根本的信息瓶颈：teacher 对每个位置只传了一个数字。teacher 知道"第 5 个 token 应该是 print"，但它也知道"如果不用 print，write 也比 echo 好得多"——这个排序信息在单值传输中完全丢失了。

问题 单 token OPD Top-K OPD
信息量 每位置 1 个 scalar 每位置 K+1 维分布
teacher 的第 2,3...K 选择 丢失 保留偏好排序
尾部 token 的处理 完全不知道 tail bin 保底
存储 [T] [T, K]（K=50 时 ×50）
学生遗忘风险 只看 teacher 最强 token，可能过拟合 K+1 维 KL 更温和

Top-K 蒸馏本质上是从"teacher 告诉你哪个 token 对"升级为"teacher 给你一份参考答案册"——不仅告诉你标准答案，还告诉你每个备选答案能得多少分。这个想法来自 SDFT (arXiv:2601.19897) 和 SDPO (arXiv:2601.20802) 两篇工作，它们的共同思路是：用 teacher 的 top-K logits + tail bin 做 KL 散度蒸馏，而不是传统的全词表 KL 或单 token CE。

5.2 Top-K 蒸馏在 OpenClaw 中的位置

Top-K 蒸馏不是替代标准 OPD，而是作为 OPD 的可选增强。两者的关系如下：

                         OPD│┌──────────────────┼──────────────────┐▼                  ▼                  ▼标准 OPD            Top-K OPD           RL-onlyteacher_lp         teacher_topk_lp      无 teacherteacher_topk_idx│▼topk_distillation_loss.py(含 tail bin + reverse KL)Combine│(继承 OPD)│可以用 Top-K 路径

两种模式通过 shell 脚本区分：

标准 OPD Top-K OPD
Shell 脚本 run_qwen3_4b_openclaw_opd.sh run_qwen3_4b_openclaw_opd_topk.sh
传输字段 teacher_log_probs [T] teacher_topk_log_probs [T,K] + teacher_topk_indices [T,K]
Advantage / Loss --advantage-estimator on_policy_distillation (Slime 内置 PPO) --custom-loss-function-path topk_distillation_loss (自定义 reverse KL)
数据量 ~300MB/sample（全 vocab logprobs） ~200KB/sample（K+1 维分布）

Binary RL 完全不涉及 Top-K——它只有 reward ±1 + GRPO advantage，没有任何蒸馏。

5.3 核心机制：Tail Trick + Reverse KL

5.3.1 问题：15 万词表 vs 50 个 top-K

teacher 只传了 Top-50 token 的 logprobs，但词表有 ~150K 个 token。剩下的 149,950 个 token 怎么办？

解法：Tail Trick。把词表从 150K 维压缩为 K+1 = 51 维——前 50 个 bin 各对应一个 teacher 选的 token，第 51 个 bin("tail")是所有剩余 token 的概率之和。

原始词表 (~150K tokens):token_1: P=0.35, token_2: P=0.25, ..., token_50: P=0.001token_51: P=0.0003, ..., token_150000: P=0.000001↓ Tail Trick
压缩为 K+1 = 51 bins:bin_1: P=0.35, bin_2: P=0.25, ..., bin_50: P=0.001bin_51 (tail): P = 1 - Σ(top-50)  ← 所有剩余 token 的总概率

5.3.2 Tail 的数值计算

实际计算在 log 空间进行，代码位于 openclaw-opd/topk_distillation_loss.py:83-89：

# 1. Top-K 概率之和(log 空间)
log_sum_topk = logsumexp(topk_logprobs)          # log(P1 + P2 + ... + P_K)# 2. 数值稳定：clamp 防止 log_sum_topk 接近 0 导致下溢
log_sum_topk = clamp(log_sum_topk, max=-1e-7)# 3. 用 expm1 计算 tail，避免 log(1-x) 的灾难性抵消
tail_logprob = log(-expm1(log_sum_topk))         # = log(1 - exp(log_sum_topk))# 4. 拼出 K+1 维分布
distribution = [topk_logprobs..., tail_logprob]  # shape: [K+1]

关键细节：clamp(max=-1e-7) 确保 log_sum_topk < 0，防止 exp(log_sum_topk)=1 导致 log(0) = -inf。expm1 是比 1-exp(x) 更数值稳定的实现。

5.3.3 Reverse KL 散度

有了 student 和 teacher 各自的 K+1 维分布后，计算 reverse KL：

# openclaw-opd/topk_distillation_loss.py:94-99
per_token_kl = F.kl_div(input=teacher_with_tail,      # teacher 的 log-probtarget=student_with_tail,     # student 的 log-problog_target=True,reduction="none",             # 不聚合，保留逐 token 维度
).sum(dim=-1)                    # 对 K+1 个 bin 求和loss = sum_of_sample_mean(per_token_kl)

PyTorch 约定：F.kl_div(input, target, log_target=True) 计算的是 D_KL(target || input)。代码中 input=teacher, target=student，因此计算的是 D_KL(student || teacher)——反向 KL。

选反向 KL 的原因是它的 mode-seeking 特性：

Forward KL: KL(teacher||student) Reverse KL: KL(student||teacher)
公式 Σ P_teacher × log(P_teacher/P_student) Σ P_student × log(P_student/P_teacher)
行为 均值寻求（mean-seeking） 众数寻求（mode-seeking）
效果 student 试图覆盖 teacher 的所有模式 student 集中学 teacher 最强的模式
Agent 场景 分散注意力 精确模仿最优行为

在 agent 训练中，我们希望学生专注学好 teacher 最强的行为模式，而不是试图模仿所有可能性。反向 KL 恰好鼓励这种行为。

可选：Entropy 正则化

if args.entropy_coef != 0.0:entropy = -(student_probs * student_logprobs).sum(dim=-1)loss = loss - entropy_coef * entropy  # 减去 → 鼓励探索

防止学生分布坍塌到单点(太确定)，保持探索能力。完整 loss：

L = KL(P_student || P_teacher)_{K+1 bins}  -  λ × H(P_student)

5.4 完整数据流：从 API Server 到 Loss

Step 1 — API Server 获取 teacher top-K(openclaw_opd_api_server.py)：

_compute_teacher_topk_logprobs(input_ids, response_len)├─ payload: max_new_tokens=0, return_logprob=True, top_logprobs_num=K│           (只做 forward pass, 不生成新 token)├─ 返回: teacher_topk_log_probs [T, K]  ← 每个位置 top-K 的 log P│       teacher_topk_indices  [T, K]  ← 对应的 token ID└─ 并发控制: self._teacher_lp_semaphore (max=3)

Step 2 — 传入 Slime 训练管道(slime/ray/rollout.py)：

train_data["teacher_topk_log_probs"] = [sample.teacher_topk_log_probs ...]
train_data["teacher_topk_indices"]  = [sample.teacher_topk_indices  ...]

Step 3 — 损失计算(openclaw-opd/topk_distillation_loss.py)：

# A. 收集 student 在 teacher 所选 K 个 token 上的 log-prob
for k in range(K):lp_k = compute_log_probs(logits, t_indices[:, k])
student_topk = stack(student_logps_k, dim=-1)        # [T, K]# B. Tail Trick(teacher 同理)
student_log_s = logsumexp(student_topk, dim=-1)       # Top-K 概率之和
student_log_s = clamp(student_log_s, max=-1e-7)       # 数值稳定
student_tail  = log(-expm1(student_log_s))            # 1 - Σtop_K# C. 拼成 K+1 维分布
student_with_tail = cat([student_topk, student_tail]) # [T, K+1]
teacher_with_tail = cat([teacher_topk, teacher_tail]) # [T, K+1]# D. Reverse KL
per_token_kl = F.kl_div(teacher, student, log_target=True,reduction="none").sum(dim=-1)  # [T]# E. 聚合
loss = sum_of_sample_mean(per_token_kl)

5.5 关键设计选择：Teacher Top-K vs Student Top-K

OpenClaw 做了一个有别于原版 SDFT/SDPO 的修改：使用 Teacher Top-K(查 teacher 概率最高的 K 个 token，再看 student 在这些位置上的概率)，而非 Student Top-K(查 student 的 top-K，再看 teacher 在这些位置上的概率)。代码注释中也提到："we use teacher top K instead of student top K, see issue #7."

# Top-K 的原版 SDFT/SDPO: Student Top-K
Step 1: Student forward → 取 student 概率最高的 K 个 token
Step 2: 查 teacher 在这 K 个位置上的 logprob
Step 3: D_KL(student_K+1 || teacher_K+1)# OpenClaw 修改: Teacher Top-K
Step 1: Teacher forward → 取 teacher 概率最高的 K 个 token(API 端完成)
Step 2: Student forward → 查 student 在这 K 个位置上的 logprob(训练端完成)
Step 3: D_KL(student_K+1 || teacher_K+1)

代码中的体现(topk_distillation_loss.py)：

t_indices = teacher_topk_indices[i]     # teacher 选的 K 个 token ID
for k in range(K):lp_k = compute_log_probs(logits, t_indices[:, k])# ↑ 查 student 在 teacher 位置上的 prob，而非用 student 自己的 argmax top-K

5.5.1 为什么选 Teacher Top-K？

原因一：架构约束(最根本)

Teacher Top-K 只需 1 次 HTTP 往返——SGLang 原生支持 top_logprobs_num=K 参数，teacher 一次返回 top-K logprobs + indices。Student Top-K 需要 2 次：先 student forward 取 top-K indices，再发给 teacher，teacher 返回对应位置的 logprob。

在 OpenClaw 的异步解耦架构中(teacher 在 GPU 6-7，trainer 在 GPU 0-3，中间只传 [T, K] 个数字)，Teacher Top-K 的实现成本远低于 Student Top-K。

原因二：teacher >> student 场景更合理

OpenClaw 的实际场景是 teacher 强于 student(teacher 有 hint 辅助)。Student 的 top-K 可能指向"垃圾模式"，teacher 在这些位置的分布不含有效信息。Teacher top-K 直接回答"应该学什么"，而非"我哪里和 teacher 不同"。

原因三：Tail Bin 更有区分度

Teacher Top-K 的 student_tail = 1 - Σ student_log_prob(teacher 选的 K 个 token)→ student 在 teacher 重视的位置上概率可能很低→ tail 很大，有信息量："student 的大部分概率不在 teacher 重视的地方"Student Top-K 的 student_tail = 1 - Σ student_log_prob(student 自己选的 K 个 token)→ student 自己的 top-K 已捕获大部分概率质量→ tail 很小，信息量低

当 student 和 teacher 分布差异大时，Teacher Top-K 的 tail bin 差异更大，信号更强。

维度 Teacher Top-K (OpenClaw) Student Top-K (原版 SDFT/SDPO)
实现难度 简单（1 次 API 调用） 复杂（2 次往返）
适合场景 teacher >> student teacher ≈ student
信息方向 "学 teacher 重视什么" "发现自己哪里错"
自我强化风险 低 高
Tail bin 精度 高（差异大时） 低（student 自身 top-K 已占大部分质量）
K 的合适大小 可以较大（K=50） 较小（K=10-20）即可

5.5.2 Student Top-K 的优势(OpenClaw 放弃的)

  • 梯度更直接：student 优化的就是自己概率最高的 token，梯度信号直指"把我的 top token 调整得更像 teacher"
  • 更好的 mode coverage：如果 student 有一个 teacher 没有的高概率 mode，Student Top-K 能发现并用 KL 惩罚修正
  • 自适应采样区域：随着训练推进，student 的 top-K 会变化

这些优势在 teacher ≈ student 的后期训练中更明显，但在 teacher 明显强于 student 的蒸馏场景下，Teacher Top-K 更合理。

5.6 数值风险

当 student 在 teacher 的 top-K 位置上概率之和接近 1 时(训练后期，student 已经学得很好)，1 - exp(log_sum_topk) → 0，tail → -∞。代码通过 clamp(log_sum_topk, max=-1e-7) 做了上界保护，但 没有 clamp tail 的下界，极端情况下可能产生 NaN。这是已知的工程取舍——训练初期 student 分布与 teacher 差异大时 tail 的行为是正常的，而后期 student 收敛后通常不再需要继续 Top-K 蒸馏。

5.7 两种 OPD 路径对比总表

维度 标准 OPD (token-level) Top-K 蒸馏 (SDFT/SDPO 风格)
存储字段 teacher_log_probs [T] teacher_topk_log_probs [T,K] + teacher_topk_indices [T,K]
Advantage / Loss A_t = teacher_lp - rollout_lp，融入 PPO clip 独立 D_KL(student || teacher) over K+1 bins
代码路径 Slime loss.py 内置 on_policy_distillation 分支 topk_distillation_loss.py 自定义 loss
信息量 每位置 1 个值 每位置 K+1 维分布
可并存性 字段不冲突 字段不冲突
适用场景 大多数 OPD 训练场景（默认推荐） 需要更丰富 teacher 信号的研究/高级蒸馏
Shell 启用 默认 --custom-loss-function-path topk_distillation_loss

5.8 常见问题

Q1: 反向 KL 在 Top-K 蒸馏中有什么潜在问题？何时该切换？

反向 KL 是 mode-seeking 的——student 一旦放弃 teacher 的某个 mode(某 bin 的 q_k → 0)，梯度 q_k·log(q_k/p_k) → 0，永远学不回来。训练后期 student ≈ teacher 时，考虑改用 JSD(对称、有界)或混合 KL：(1-α)·D_KL(Q||P) + α·D_KL(P||Q)，α 从 0 渐增到 0.5。

Q2: 从全词表 KL 到 Top-K+Tail 蒸馏，信息损失有多大？

tail bin 把 |V|-K 个 token 聚合为一个标量，丢失了 tail 内部的分布结构。可忽略的条件：teacher 分布足够 peaked(top-K 已捕获 >95% 概率质量)、K 足够大(K=50 对 |V|=150K 通常足够)、目标只是蒸馏(只需排序，不需精确匹配)。不可忽略的条件：teacher 分布平坦(高 entropy)或 K 太小(如 K=5)。

Q3: Top-K 蒸馏中的 Reverse KL 是 D_KL(student || teacher) 还是 D_KL(teacher || student)？

是 D_KL(student || teacher)。代码中 F.kl_div(input=teacher, target=student, log_target=True)，PyTorch 定义为 D_KL(target || input)，即 D_KL(student || teacher)。teacher 在 input 位置，student 在 target 位置。

TransFormer-封面

0xFF 参考

神仙思路！普林斯顿提出OpenClaw-RL：Agent在线挨骂在线升级！

http://www.jsqmd.com/news/1289522/

相关文章：

  • “千问办公”已经下载安装了
  • 6大AI入口谁全覆盖？2026年4家杭州GEO服务商交付流程横评 - 速递信息
  • AWS云技术基础：从基础设施到高可用Web应用实战
  • QuickRecorder：7种专业录制模式，打造macOS最佳屏幕录制体验
  • BeeRef常见问题解决：从日志查看 to 性能优化的实用技巧
  • 致焦虑的程序员：AI 不会让你失业，但“写 CRUD”会
  • 幻兽帕鲁存档的深度解析：掌握palworld-save-tools的核心架构与实战应用 [特殊字符]
  • RaZ引擎音频系统开发详解：3D空间音效与实时音频处理技术
  • 单级会员分销系统开发：从零到一构建你的社交电商核心
  • TaskbarX：Windows任务栏美化终极指南 - 42种动画效果打造专业桌面体验
  • 在树莓派上部署SPARTA：低成本空间音频开发方案详解
  • 企业如何管理员工AI使用成本？
  • 网络安全与前沿科技：挑战、防御与未来趋势
  • 2026“手残”是标签还是借口？成年人学习新技能的心理真相 - 热点速览
  • Python 编程入门指南
  • 2026闲置爱心商务卡如何回收变现？多渠道横向实测对比指南 - 京顺回收
  • 带镜子的蓝牙耳机实测横评：便携创新设计，多机型客观选购参考
  • 绝版胶片数字化最后窗口期：AI画面修复黄金72小时法则，错过将永久丧失纹理重建能力（附时间敏感性验证数据）
  • Spected与Ramda：函数式编程在数据验证中的完美结合
  • 2026南京卫生间漏水到楼下免砸砖怎么修｜屋顶外墙渗水维修，本地正规防水公司推荐【7月新更】 - 鑫诺很靠谱
  • 数据预处理中的数值变换技术与工程实践
  • 从零开始使用github-style主题：新手必备的Hugo博客搭建手册
  • My-Budget源代码解析：Electron框架如何构建跨平台桌面应用
  • AI 数据库混合搜索入门实践
  • 如何用seqlearn快速构建序列分类模型？初学者入门教程
  • Carla仿真系列：1_Carla + ROS 仿真环境从零搭建，跑通完整数据流
  • 现碾胚芽米生产厂家哪家专业 - GrowthUME
  • 合肥理工学校!电话是多少?职教高考能逆袭吗? - hflgzz
  • 京东e卡回收平台怎么选择？看这几个标准｜靠谱京东e卡安全回收指南 - 热点速览
  • 限时开放｜全国TOP10中学正在部署的AI学生套装配置表（含学科适配矩阵与伦理使用红线）