文章

扩展点与真实场景

从 import-path hook 和 Sample 契约出发,设计搜索、工具、sandbox、代码 Agent、多 Agent、VLM 与 OPD 训练方案。

2026年7月26日 更新于 2026年8月29日 约 15 分钟

专题 slime 面试与源码解读指南 第 8 篇 / 共 12 篇

快照说明:本文基于 main@3778dbf6d1a533ab478ecf5ddaa11449a47752b2(v0.3.2,2026-08-29 扫描)整理。扩展函数签名和示例会随代码演进;本文中的命令全部是示例,不保证在本机直接运行。第三方工具、搜索服务和 sandbox 还涉及网络、凭据与隔离策略,不能把 recipe 当作生产安全承诺。

slime 的核心扩展思路是:用 Python import path 替换流水线中的一个窄环节,只有默认外循环不再适用时才替换整个 rollout。 面试中不要只背参数名,应说清“为什么选这一层、输入输出契约是什么、怎样验证不会把错误 token 训练进去”。

1. import-path hook 到底是什么

slime 的 loader 接受形如 package.module.attribute 的点分路径:先 importlib.import_module(package.module),再 getattr(attribute),实现见 load_function。因此:

  • 这里的可靠格式是 your_pkg.rollout.generate,不是文件路径,也不是 module.py:function。
  • 包必须在 driver 和所有 Ray worker 的 PYTHONPATH 上;只在当前 shell cd 到某目录不够。
  • import 会执行模块顶层代码。不要在顶层连接数据库、下载模型或读取秘密;把副作用放进函数或显式初始化 hook。
  • hook 是可信代码边界,不是安全沙箱。加载用户不可控的 import path 等同于执行任意 Python。

示例(只验证 import,不保证本机可运行):

PYTHONPATH=/path/to/project python -c \
  'from slime.utils.misc import load_function; print(load_function("my_rl.rollout.generate"))'

2. 扩展层怎么选

slime-extension-real-world-scenarios 架构图 1

主扩展点对比

需求首选参数典型契约什么时候升级到更重的 hook
生成后、打分前的轻量逐样本后处理(改写、打标、清理)--rollout-sample-hook-path(可重复,#2250 新增)hook(args, sample, *, rollout_id, evaluation, ...) -> Sample | None,sync/async 均可,list 输入递归保形处理需要改变生成流程本身或跨 sample 协调时改用 custom generate / rollout
多轮、搜索、工具调用、RAG、环境交互--custom-generate-function-path`async def generate(args, sample, sampling_params) -> Samplelist[Sample]`
替换整轮数据收集--rollout-function-pathdef generate_rollout(args, rollout_id, data_source, evaluation=False) -> RolloutFn*Output已经无法复用默认 oversampling、RM、filter、abort 逻辑
verifier / 规则 / 外部 RM--custom-rm-path常见为 `async def rm(args, sample, **kwargs) -> floatdict`
数据游标、队列、在线 buffer--data-source-path实现 get_samples/add_samples/save/load/__len__只想过滤默认静态数据时先用 filter hook
自定义训练目标--loss-type custom_loss + --custom-loss-function-path训练侧 loss callable,遵循默认 loss 调用形状只改 advantage 时不要连 loss 一起重写
自定义 advantage / return--custom-advantage-function-pathfunc(args, rollout_data),原地写入 advantages、returnsestimator 可由内置 GRPO/PPO/CISPO 等表达时直接用内置项
新 Megatron 架构--custom-model-provider-pathprovider(pre_process, post_process, vp_stage=None) -> GPTModel只是换权重或 tokenizer 时不需要模型插件

完整 rollout/data/reward hook 在 manager 初始化时通过 import path 加载,见 RolloutManager.__init__;custom advantage 的原地写入契约见 loss.py,custom loss 的选择入口见 loss.py。

“最窄 hook”原则

  1. 只改生成:保留默认 sglang_rollout,得到内置并发、reward、动态采样、filter、metrics 和 fault-tolerance 行为。
  2. 只改评分:保留真实生成 token,只替换 RM;避免把“环境逻辑”误塞进 loss。
  3. 只改学习信号:先选 advantage,再决定是否需要 custom loss。二者一起改会使 NaN/收益退化难定位。
  4. 完整 rollout:承担 batch 数量、嵌套形状、Sample 必填字段、metrics、取消与异常语义;这是能力最大、维护成本也最高的一层。

3. Sample 是跨层协议

一个可训练 sample 至少要让下游拿到:

字段含义关键约束
tokensprompt + response 的真实 token ids尽量保存模型实际采样的 ids,不要“decode 后再 tokenize”冒充原轨迹
response_lengthresponse token 数必须能从 tokens 尾部切出 response
reward标量或可按 key 取值的字典与 RM/--reward-key 约定一致
statuscompleted/truncated/failed/aborted 等主要是观测/控制信号;FAILED 不会自动过滤或清零梯度
loss_maskresponse 中每个 token 是否训练长度必须严格等于 response_length
rollout_id一次逻辑 rollout 的身份fan-out sibling 必须全部非空且相同

字段定义见 Sample。默认转换在 loss_mask is None 时把整个 response 置 1,remove_sample=True 时全部置 0,并断言 mask 长度正确,见 _convert_samples_to_train_data。所以对工具场景来说,“不填 loss mask”通常是危险默认值:tool observation、模板、环境错误文本可能被当成模型输出训练。仅设置 status=FAILED 也不够;基础设施失败必须显式重试/回填、过滤、设置 remove_sample=True 或全零 mask。

4. fan-out:ID、prompt 分组与 loss mask 的三重契约

一次 agent 执行可能产生 main agent、subagent、compact 前后片段等多个训练样本。此时:

一次逻辑 rollout
  ├─ Sample A: rollout_id=42, loss_mask=[模型 token=1, observation=0]
  ├─ Sample B: rollout_id=42, loss_mask=[subagent 模型 token=1, 工具输出=0]
  └─ Sample C: rollout_id=42, loss_mask=[final answer=1]

三个字段解决不同问题:

  • rollout_id 决定计数和归约单位。同一 fan-out 的 siblings 共享 id,训练 step 按 rollout 而不是按 fan-out 后的样本数计数;manager 会为整个 rollout 预计算 loss-mask 总量作为 denominator,见 rollout.py。
  • group_index 决定reward normalization 的 prompt 组。可变 fan-out 时,默认固定 reshape 会失败;若要逻辑 rollout 等权,应先在 prompt 组内按 rollout_id 聚合 reward,再归一化并广播回 siblings。
  • loss_mask 决定哪些 response token 产生梯度。prompt 不在 response mask 中;response 内的模型 token 通常为 1,模板、工具 observation、环境反馈、人工拼接文字通常为 0。

compact/subagent 三层嵌套输出会被显式校验:每个 sibling 都必须有相同的非空 rollout_id,否则立即断言失败,见 validate_rollout_id_annotated。

一个安全的 fan-out 伪代码

示例(教学伪代码,不保证本机可运行):

async def generate(args, sample, sampling_params):
    trajectory = await run_agent(sample.prompt)
    rid = sample.rollout_id if sample.rollout_id is not None else sample.index
    siblings = []
    for branch in trajectory.trainable_branches():
        child = branch.to_sample()       # 保留实际 token ids
        child.rollout_id = rid           # 同一次逻辑 rollout
        child.group_index = sample.group_index  # 保留 prompt reward group
        child.loss_mask = branch.mask()  # 模型输出 1,observation/template 0
        assert len(child.loss_mask) == child.response_length
        siblings.append(child)
    return siblings

不要给 siblings 分配不同 id 来“避免冲突”:那会把一次 agent execution 重复算成 N 次 rollout,并改变 loss 归一化与 step 切分。

若 siblings 数量可变,应再提供 --custom-reward-post-process-path,显式定义 sibling reward 如何聚合为逻辑 rollout reward。现有默认 post-process 和测试 helper 都不能自动替你决定该语义。另一个当前限制是 --group-rm 直接遍历 group 中的 Sample,无法处理 fan-out 产生的嵌套 list[Sample];不要在没有额外展平/组合测试时同时开启。

5. 方案 walkthrough A:数学 + 搜索工具

数学搜索目标

模型对数学题可多轮搜索,最终答案由规则 verifier 评分;搜索结果不参与梯度。

数学搜索设计

  1. 默认 sglang_rollout 负责 batch、并发和动态采样。
  2. custom generate 实现 thought → search query → observation → ... → answer。
  3. 搜索 query 和模型 answer 是模型生成 token,mask=1;系统拼接的搜索结果和 tool wrapper,mask=0。
  4. custom RM 解析最终答案,用数学 verifier 打 0/1;工具调用格式错误可记录 metadata,再由 reward 或 filter 处理。
  5. 若要 DAPO 风格动态采样,再接 --dynamic-sampling-filter-path,不要重写 rollout。

slime-extension-real-world-scenarios 架构图 2

示例参数(不保证本机可运行):

--custom-generate-function-path generate_with_search.generate \
--custom-rm-path generate_with_search.reward_func \
--loss-mask-type qwen \
--rollout-max-response-len 4096

仓库 recipe examples/search-r1 正是“custom generate + custom RM”的参考。它证明仓库提供了一种接法,不代表搜索服务 SLA、索引质量或外部 API 成本已经由 slime 保证。

数学搜索验收

  • dump 中能逐 token 对齐 tokens/response_length/loss_mask。
  • 搜索 observation 的 mask 全为 0,最终 answer 有非零可训练 token。
  • 对固定 20 条题,verifier 与离线脚本结果一致;reward 分组不是全常数。
  • 搜索 timeout 产生可诊断 metadata,并通过重试/回填或 filter/remove 清除训练贡献;仅写 FAILED 不会自动阻止训练。

6. 方案 walkthrough B:代码 Agent + sandbox + multi-agent fan-out

这里的 multi-agent 仍是默认 rollout 外循环中的 --custom-generate-function-path 扩展,不是 --rollout-function-path 的整轮替换;仓库脚本加载 examples.multi_agent.rollout_with_multi_agents.generate_with_multi_agents,见 examples/multi_agent/README.md。执行 trace 的采集与聚合已归入 slime/observability/trace_utils.py,viewer 的使用放在可观测性文档,不应被描述为 multi-agent hook 自带契约;本章只要求扩展正确填充 Sample/trace 数据,部署与解释见 可观测性文档。

代码 Agent 目标

模型在隔离环境里读代码、编辑、运行测试;subagent 与主 agent 分支都作为一次逻辑 rollout 的训练片段,最终 patch 在另一干净环境评分。

代码 Agent 设计

  1. custom generate 为每个 sample 创建短生命周期 sandbox,准备仓库与问题。
  2. agent harness 通过 SGLang adapter 发消息并调用 Read/Edit/Grep/Bash/Agent 等工具。
  3. trajectory manager 保存真实采样 token;工具结果、模板、后续拼接 observation 全部 mask=0。
  4. subagent 分支 fan-out 为 list[Sample],共享 rollout_id。
  5. 在第二个干净 sandbox 中应用 patch 并运行 grader,防止通过修改测试作弊;reward 写回 sample。
  6. 凭据只以最小权限注入 sandbox,日志/dump 必须脱敏;限制网络、CPU、内存、磁盘和 wall-clock。

示例参数(不保证本机可运行;真实路径和解析器依模型调整):

--custom-generate-function-path examples.coding_agent_rl.generate.generate \
--sglang-tool-call-parser qwen3_coder \
--save-debug-rollout-data /secure/debug/rollout_{rollout_id}.pt

参考实现地图见 examples/coding_agent_rl。该 README 描述了 per-sample sandbox、干净 evaluator 与 fan-out trajectory;这是 recipe,不等于任意 sandbox provider 都达到生产隔离等级。

失败策略

失败建议状态/处理不要做什么
sandbox boot timeout记录 provider/时延并重试;最终失败则 filter/remove 或全零 mask只写 FAILED 后仍让默认全 1 mask 进入训练
agent 超时TRUNCATED,保留已完成模型 token把 timeout 文本 mask=1
工具 JSON 解析失败低 reward 或格式 reward;保留原始生成 token修改 response 后忘记同步 token/mask
evaluator 基础设施失败与“patch 测试失败”分开,避免错误惩罚模型把基础设施错误当 0 分真值
fan-out 某分支为空删除空分支或全 mask=0,并保持 group id给空分支新 rollout id

7. 方案 walkthrough C:多轮 VLM + 环境反馈

多轮 VLM 目标

输入图片和几何题;模型可多轮调用环境获得提示,最终数学答案计分。

多轮 VLM 设计

  1. 数据层将 image path/URL 映射到 multimodal_inputs;processor 产生训练侧 multimodal inputs。
  2. 这个仓库示例复用默认 rollout 外循环,只以 custom generate 控制多轮图文上下文、SGLang 请求和 log-prob 对齐;只有还要改全局 batch 调度时才升级为完整 --rollout-function-path。
  3. 每轮模型文本 token mask=1;环境反馈 mask=0。图像占位 token 与训练 processor 的展开必须一致,不能只用字符串长度估算。
  4. response_length、loss mask、log-prob 必须在多轮拼接后仍逐 token 对齐。
  5. RM 只读取最终答案或环境终态,格式分与正确性分要明确是否相加。

示例参数(不保证本机可运行):

--custom-generate-function-path examples.geo3k_vlm_multi_turn.rollout.generate \
--multimodal-keys '{"image":"image_file"}' \
--loss-mask-type qwen3 \
--rm-type math

单轮入口见 examples/geo3k_vlm,多轮环境和 rollout 职责见 examples/geo3k_vlm_multi_turn。

多轮 VLM 验收

  • 图片在 driver、rollout worker 和 trainer 上均可访问,或已转为明确可传输的数据。
  • 同一 sample 的 multimodal token 展开、总 token、response span 和 loss mask 一致。
  • 环境反馈不会产生梯度;多轮达到 max turns/max tokens 时状态是 TRUNCATED。
  • 用少量固定样本做 rollout-only dump,再做 train-only replay。

8. 方案 walkthrough D:OPD(在策略蒸馏)

OPD 不是新的 advantage estimator,而是在基础 estimator 的 advantage 上叠加 teacher-student token KL;源码在 apply_opd_kl_to_advantages。

模式教师在哪里设计重点
--opd-type sglang外部 SGLang teacherrollout/RM 阶段取得逐 token teacher log-prob;网络超时和 token 对齐必须可观测
--opd-type megatron训练侧 Megatron teacher需要 --opd-teacher-load Megatron checkpoint;额外训练显存与计算成本

示例参数(不保证本机可运行):

--use-opd --opd-type sglang --opd-kl-coef 1.0 \
--rm-url http://teacher.example:8000/generate \
--custom-rm-path slime.rollout.on_policy_distillation.reward_func \
--custom-reward-post-process-path slime.rollout.on_policy_distillation.post_process_rewards

可运行思路和模式比较见 examples/on_policy_distillation 与 OPD 文档。不要把示例结果外推到其他学生/教师、数据集和 KL 系数。

9. 数据源、loss、advantage 与模型插件

自定义 DataSource

DataSource 要实现五件事:取样、退回样本、保存游标、加载游标、报告长度。默认全局数据源保存 sample_offset、epoch、group/sample index 和 metadata,见 data_source.py。

适合自定义 data source 的场景包括在线队列、课程学习、外部 replay buffer、按任务配额采样。关键不是“能拿到数据”,而是 save/load 与模型 checkpoint 使用同一个 rollout 边界,否则恢复后可能重复或跳过样本。

custom advantage 与 custom loss

  • custom advantage 在 KL 已计算后运行,必须原地填充每个 sample 的 advantages 和 returns;保留现有 loss 可减少变量。
  • custom loss 直接替换训练目标,应明确返回 loss/metrics 约定、mask 归约、DP/CP 语义和数值精度。优先从 loss.py 的内置分派 复制最接近的一支,再写契约测试。
  • reward postprocess 位于 reward 与 advantage 之间;适合 group normalization 或 teacher log-prob 整理,不适合偷偷改变 token 序列。

模型插件

模型 provider 解决的是 Megatron 如何构造架构;HF↔Megatron 权重映射解决权重名和张量布局;SGLang 是否支持该 HF 架构又是第三件事。真实接入要同时检查:

  1. HF config / tokenizer / processor;
  2. Megatron model provider;
  3. HF↔Megatron 权重映射;
  4. SGLang serving 支持;
  5. 在线权重同步在 TP/EP 变化下的映射。

HF↔Megatron 权重映射自 PR #2251 起已内部化:加载侧在 slime/backends/megatron_utils/hf_to_megatron/(按 model_type 注册 loader,覆盖 DeepSeek V3/V3.2、GLM4/4-MoE/DSA、Kimi-K2、Llama、MiMo、MiniMax-M2、Qwen2/3/3.5/Next 等家族),发布侧在 megatron_to_hf/;外部 mbridge / megatron-bridge 依赖与 slime_plugins/mbridge/ 目录已删除。模型结构插件样例集中在 slime_plugins/models(近期新增 qwen3_5_vl,gemma4 / gpt-oss 支持已移除)。不要因存在一个 provider 文件就宣称端到端训练、checkpoint round-trip 和在线同步均已覆盖。

10. 真实场景与示例地图

场景推荐起点仓库示例读它时关注
数学规则 RM内置/自定义 RMslime/rollout/rm_hub答案抽取、二值/非二值 reward、异常语义
搜索增强custom generate + RMexamples/search-r1多轮搜索、工具 observation mask、外部服务
Python 工具custom generate + sandboxexamples/retool工具 schema、执行隔离、reward
通用 agent tool loopcustom generateexamples/tau-benchuser simulator、环境终态、API key
框架适配custom generateexamples/strands_sglangtext↔token 对齐;README 明示本地 subprocess 非隔离
Coding-agent RLcustom generate + sandbox + fan-outexamples/coding_agent_rl干净 evaluator、轨迹分支、超时
Multi-agentcustom generateexamples/multi_agentshared rollout_id、分支 reward/权重
VLM 单轮multimodal data + 默认 rolloutexamples/geo3k_vlmprocessor、图像可达性、RM 精度
VLM 多轮完整 rollout 或 custom generateexamples/geo3k_vlm_multi_turn环境反馈、mask/log-prob 对齐
OPDteacher + reward postprocessexamples/on_policy_distillationteacher log-prob、KL、两种教师部署
long-tail 异步完整 rolloutexamples/fully_asyncstale policy、buffer、取消和背压

这里的证据要分四级:源码实现说明当前可达行为;CPU contract/unit test 只保护纯逻辑;GPU E2E 只覆盖记录中的模型、硬件与拓扑;examples/ recipe 和生产部署还需分别验证依赖、规模、安全与 SLA。四者不能互换表述。README 在项目层面声明 slime 用于 GLM-5.3 的 RL 训练(README.md),但本快照没有把 GLM-5.3 作为本章某个 example、固定配置或可复现 GPU E2E,因此这里只能引用为项目级声明,不能据此承诺模型支持范围、硬件规模或性能。

11. 扩展上线前的契约测试

项目提供 plugin contract tests,覆盖路径加载、生成、完整 rollout 和 runtime hooks;入口见 tests/plugin_contracts。对自己的扩展,至少验证:

  1. 点分路径可从干净 Python 进程 import。
  2. 函数签名、同步/异步形式和返回类型与调用点一致。
  3. 正常、timeout、空输出、解析失败、外部 5xx 都有确定状态。
  4. tokens、response_length、loss_mask、log-prob 逐 token 对齐。
  5. fan-out siblings 共享 rollout_id,跨 micro-batch 后 loss denominator 不变。
  6. DataSource save/load 恢复到同一游标。
  7. 日志和 debug dump 不包含 token、API key、用户隐私等不该落盘的数据。

示例(仅演示最小测试入口,不保证本机可运行):

pytest -q tests/plugin_contracts/test_plugin_generate_contracts.py
pytest -q tests/plugin_contracts/test_plugin_path_loading_contracts.py
pytest -q tests/test_qwen2.5_0.5B_fanout_short.py

前两个可能需要依赖/stub 环境,最后一个是 GPU E2E;应根据项目 CI 镜像选择,不要把未运行的命令报告为通过。

12. 面试速答

问:工具调用为什么通常选 custom generate,而不是完整 rollout?

答:工具逻辑只替换单 sample 生成时,默认 rollout 仍可提供 batch 并发、RM、动态采样、过滤、metrics 和容错;重写完整 rollout 会接管更多契约,维护面更大。

问:fan-out 最容易错在哪里?

答:一是 siblings 没共享 rollout_id,导致一次 agent execution 被多计;二是工具 observation/template 的 loss mask 没清零,导致训练环境文本。

问:自定义 RM、advantage、loss 的边界?

答:RM 产出任务得分,advantage 把 reward/KL/value 变成学习信号,loss 把 advantage 与 policy 输出组成可优化目标。先改最窄一层,避免三层同时变化。

问:示例目录存在是否代表生产可用?

答:不代表。需要区分默认源码行为、CI 保护的契约和仅供参考的 recipe,还要单独验证依赖、隔离、外部服务与数据安全。

本页目录