English | 简体中文
本指南汇总 MoE 路由重放、单轮代码任务和外部 Agent 的支持范围、配置及验证入口。 训练环境见 Docker 运行说明,各任务的数据准备和启动方法见对应示例。
| 功能 | 支持范围 | 使用入口 |
|---|---|---|
| Qwen3-30B-A3B | GRPO、colocated native vLLM、训练 TP1/TP2 与 EP/EDP;EPLB 关闭,不设置已删除的 consistency 字段 | MoE rollout |
| MoE R3 | Qwen3-MoE Actor 的路由重放;internal 单轮/连续多轮、Codex 逐调用轨迹 | R3 配置、GSM8K 示例 |
| 单轮 Python code | 私有 stdin/stdout 测试、TP owner 唯一判题、独立 SandboxFusion 服务 | code 示例 |
| 外部 Agent | 每次模型调用保留真实 prompt/action,episode GRPO,DP 零损失补齐 | Agent 合同、Search-R1 |
| 仓库 Code Agent | 隔离候选工作区、冻结产物、独立 grader;本地或远端执行 | SWE-Smith 示例 |
MoE 不支持 PPO、disjoint rollout 或 Hyper-vLLM。R3 尚未适配 DeepSeek runner, 不支持与启用的 distillation/OPD 组合。模型格式错误或已确认的任务预算耗尽可形成任务失败; 通信、执行服务和未知错误必须向上传播,不能静默记零分或丢弃候选。
Rollout Router Replay(R3)记录采样时的 expert 选择,在 Actor 的概率计算、训练前向和
activation checkpoint 反向重算时重放。重放的是离散 expert ID;权重仍根据当前 router 概率
计算,router 和 expert 梯度正常参与更新。Reference 保持原生路由,old_log_probs 保留 rollout 原始值。
R3 的数据传递与微批作用域属于通用 RL 功能,与数据集、奖励规则和 Agent 调用预算独立。 当前只有 Qwen3-MoE 的 gate 接口适配,并不表示任意 MoE 模型都可直接启用。 适配位于 RL 内,不要求修改共享模型、FSDP/HSDP、TP/EP 或优化器代码。
默认配置不改变原有行为:
train:
router_replay:
mode: disabled # R3 同时开启 rollout capture 和 Actor replay
model_init_cpu_threads: null
rollout:
vllm:
sleep_level: 1推荐从 Qwen3-30B-A3B Codex 四卡配置 开始。在已安装当前 checkout 的训练容器中,挂载配置要求的权重与数据后执行:
python -m torch.distributed.run --standalone --nproc_per_node=4 \
hyper_parallel/rl/train_rl.py \
hyper_parallel/rl/examples/gsm8k/configs/qwen3_30b_a3b_codex_multi_turn.yaml \
--train.router_replay.mode=R3该配方预设训练 TP2/EP2/EDP2、rollout TP4/DP1,R3 默认仍关闭。
开启 R3 不会调整候选数、工具调用次数、上下文、生成预算、评测或保存设置。
无需单独配置 enable_return_routed_experts;若手动设置,必须与 R3 开关一致。
固定运行环境为 Transformers 5.5.4、vLLM 0.23.0 / vLLM-Ascend 0.23.0.post1。 适配器区分 Transformers 5.6 前的概率返回值与 5.6 起的 logits 返回值,保留原生 gate 输出契约。 更换 Transformers 版本仍须验证适配器及完整训练流程,不能仅依赖同名类;固定真机验证环境不变。 当前要求:
model_implementation: native、deployment: colocated、enforce_eager: true、logprobs_mode: raw_logprobs。- 关闭 EPLB,不设置已删除的 consistency 字段;训练 CP=PP=1。
- rollout
data_parallel_size: 1,TP 覆盖共用设备;此限制来自该 Ascend capture 的 DP padding 布局, 不限制训练 DP。若从单轮 MoE 配方启用 R3,须同时将其 rollout DP2/TP2 改为 DP1/TP4。
初始化线程与睡眠级别可独立选择:--train.model_init_cpu_threads=8 仅临时调整模型构建的
intra-op 线程;--rollout.vllm.sleep_level=2 丢弃旧推理权重以降低 CPU 内存占用,
恢复采样前必须完整发布权重。默认仍是 null 和 1,不会因 R3 自动改变。
完整条件见 初始化线程和
推理生命周期。full_gather 的设备侧聚合内置生效,没有新增开关。
vLLM capture → GenerationResult → Trajectory → ExperienceBatch
→ Actor 微批 RouterReplay.use → gate hook → expert / EP
→ backward 完成后清理 replay 状态
RouterTrace 保存 CPU 整数 expert_ids[S,L,K]、布尔 valid_mask[S] 和稳定 layer_ids。
路由按模型输入 token 位置对齐,不使用 next-token logprob 的 shift。
例如 [p0,p1,a0,a1] 通常只有前三个输入位置执行过 forward,最后采样的 a1 没有路由。
最后有效 action 位于 m 时,0..m-1 的因果前缀均需有效,不能只采集 action mask 对应位置。
最后未执行的 token、终态 observation 和 padding 保持无效;无效位置使用原生路由,不能伪造 expert 0。 trace 随训练行保存在 CPU,微批执行时才补齐并传到设备。传输使用紧凑二进制,NPY 解码禁用 pickle。 shape、层映射、专家范围、重复 expert 或因果覆盖不合法时明确失败,不回退到普通训练。
router_adapter.py 仅在已构建 Actor 的 gate 实例安装可移除 hook,
以 rollout ID gather 当前概率,并按模型原有规则归一化;不改变参数名称、state_dict 或优化器引用。
微批作用域覆盖 forward 和 backward,包括 checkpoint 重算,正常或异常退出均清理状态。
| 轨迹方式 | trace 处理 | 原因 |
|---|---|---|
| internal 连续上下文 | 新一轮完整 trace 替换旧快照;重叠有效前缀的有序 expert ID 必须一致 | 新 prompt 已包含历史 action 和 observation,直接拼接 trace 会重复前缀 |
| Codex 逐调用训练 | 每次真实 prompt/action 保留独立 trace,不删除早期调用 | harness 可以改写或裁剪上下文,最后一次调用不能替代历史调用 |
Codex Gateway 从模型响应提取路由,Agent 只接收正常响应。路由不重复写入审计 metadata, 调用身份、策略版本、episode 奖励及 DP 零损失补齐仍沿用 Agent 合同。 Search-R1 引用修正等追加调用同样经过该路径,无需按数据集增加重放逻辑。
接入新任务时,重点检查是否改变原始 token、调用记录或轨迹拼接。仅改变题目和奖励无需复制 R3 实现; 引入新的上下文截断、调用合并或传输边界时,应补对应验证。
下列路径相对 hyper_parallel/rl/:
| 职责 | 文件 |
|---|---|
| 数据合同与训练行绑定 | rl/data/contracts.py、rl/data/experience.py |
| capture 解码与 TP 传输 | rl/rollout/router_capture.py、rl/rollout/vllm.py |
| 模型无关 replay 作用域 | rl/workers/adapters/router_replay.py |
| Qwen3-MoE gate 适配与 Actor 接线 | rl/workers/adapters/router_adapter.py、rl/workers/actor.py |
| 多轮调用记录与轨迹 | rl/agentic/codex/gateway.py、harness.py、rl/agentic/core/ |
| 配置与装配 | rl/config/validate.py、rl/trainer/sync.py |
实现参考 R3 论文及以下固定版本:
- verl: replay indices、当前概率计算权重及 forward/backward 作用域;router 适配留在 RL 层。
- Agent Lightning: Proxy 提取路由与逐调用训练记录;连续轨迹聚合时才能删除被覆盖的旧 trace。
- Uni-Agent: 连续 token chain 使用最新完整路由。该优化不能直接用于本仓 Codex 的独立调用行。
UT 位于 tests/ut/rl/,以下为核心验证入口,覆盖 CPU 逻辑和必要的 mock:
| 模块 | 代表性测试(相对 UT 根目录) |
|---|---|
| MoE 配置与同步 | trainer/test_moe_config.py、weight_sync/test_moe_weight_sync.py |
| R3 位置、梯度、重算和 capture | policy/test_router_replay.py、rollout/test_router_capture.py |
| 设备聚合、桶释放和 sleep 2 | weight_sync/test_packed_weight.py、weight_sync/test_weight_sync_transaction.py |
| 初始化 CPU 线程恢复 | policy/test_actor_roles.py、trainer/test_config_runtime.py |
| code 数据、判题和轨迹 | data/test_code_data.py、agentic/test_code_judge.py、agentic/test_code_runner.py |
| Agent 调用、预算和补齐 | data/test_episodes.py、agentic/test_agent_program.py、agentic/codex/test_gateway_transport.py |
| 仓库任务与启动流程 | agentic/swe_smith/ |
python -m pytest -q tests/ut/rlST 位于 hyper_parallel/rl/tests/st/,由 test_feature_st.py 显式启动。
_moe_train.py、_code_train.py、_agent_train.py 和 _agent_dp.py 为子进程 worker;
已有 dense、PPO 用例仍由 test_rl_st.py 独立承载。
两进程 CPU/Gloo 验证比较不等长调用补齐前后的梯度与更新参数,不需要 NPU:
python -m pytest -q hyper_parallel/rl/tests/st/test_feature_st.py::test_agent_dp_padding真实 MoE/R3 训练使用已有 MoE 配方,准备模型、数据、设备并按需开启 R3:
export RL_ST_MOE_CONFIG=/path/to/resolved-moe.yaml
export RL_ST_WORLD_SIZE=4
export RL_ST_RESULT_DIR=/path/to/new-results
export RL_ST_REQUIRED=1
python -m pytest -q 'hyper_parallel/rl/tests/st/test_feature_st.py::test_feature_training[moe]'配置必须与设备数一致,结果目录须为空。code 和 agent 分别使用 RL_ST_CODE_CONFIG、
RL_ST_AGENT_CONFIG 与参数 [code]、[agent]。测试保留两步参数更新与策略版本检查;
R3 observer 额外验证真实 gate 的 expert ID、当前权重、checkpoint 重算和 router 梯度。
Agent 用例要求真实多调用及不等行数补齐,不能将未触发的场景记为通过。
SandboxFusion 的独立真实服务测试不需要模型或 NPU,入口与资源配置见 code 示例。
缺少资源时 skip 不算通过;设置 RL_ST_REQUIRED=1 后,缺失配置会失败。
所有运行结果写入独立输出目录,不纳入版本管理。
| 路径 | 已有功能覆盖 | 结论限制 |
|---|---|---|
| 单轮 MoE R3 | 路由、gate 权重、反向重算、两步更新和版本发布 | 限已适配模型与固定运行时 |
| GSM8K Codex R3 | 工具上下文、逐调用 trace、预算终止及两步闭环 | 不代表训练收敛 |
| Search-R1 Codex R3 | 搜索上下文、不等调用 DP 补齐、首步重放与更新发布;引用修正调用的采集 | 未完成完整两步闭环,不能把后续采集记为训练重放通过 |
| internal 多轮 / SWE-Smith R3 | 连续前缀检查 / 逐调用路由交接的 CPU 合同 | 未单独完成对应 R3 多轮真机闭环 |
| 独立代码沙箱 | 隔离合同及 dense code 两步训练、评测和保存 | 不代表全部数据标签正确或 checkpoint 恢复通过 |
精确重放 expert 选择不等于训练与推理 logprob 一致;当前 MoE 同权重更新前仍存在概率差异, 未声明 bit-exact 或学习收益。通用训练与 Agent 功能通过,也不自动证明其与 R3 的所有组合已验证。 更换模型、capture 后端、并行布局或轨迹结构后,应重新执行受影响的合同和真实运行验证。