# PR #2785 完整报告

- 仓库：`radixark/miles`
- 标题：docs: add the Qwen3.8-Flash-Next RL recipe page
- 合并时间：2026-08-28 00:55
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2785

---

# 执行摘要

- 一句话：新增 Qwen3.8-Flash-Next RL 配方文档页并接入导航
- 推荐动作：若在做 Qwen3.8-Flash-Next 或类似 GDN/QSA 模型的接入，值得精读该页面中“三大超纲组件”段落，尤其是 `hc_head_contraction` 与 PLE 权重更新跳过列表；其余读者快速扫过即可。值得关注的设计决策：作者将复杂技术权衡写进 recipe 而非 PR 讨论，方便后续维护者追溯实现动机。

# 功能与动机

PR body 说明：Qwen3.8-Flash-Next 是 Qwen4 架构的 GDN + QSA 混合 MoE 预览，不是密集版 Qwen3.8-27B 的变体，因此应作为独立页面放在 Qwen3-Next 旁，而不是塞进 Qwen3.8 小节。这是与历史 GLM-5.3-Flash recipe 页（PR#2788）一致的文档组织决策。

# 实现拆解

1. **新增独立 recipe 页 **`docs/models/qwen/qwen3-8-flash-next.md`（+250 行）：完整描述模型定位、三个超出标准 Megatron 层的组件（hyper-connections 替代 block layernorm、QSA 稀疏注意力、冻结的 host-resident PLE 表）及对应实现要点（`hc_head_contraction` 新 Megatron 槽位、Triton 前反向 kernel、PLE 侧信道）。为什么：这一页是 #2777 等三个未合入分支的落地说明，所有链接与镜像标签都对齐这些分支。
2. **更新 Qwen 索引 **`docs/models/qwen/index.md`：修订 description 与 “Fastest path to train” 建议，新增表格行 Qwen3.8-Flash-Next（MoE GDN + QSA，6 B/176 B）。原因：让按模型选路线的用户能从此入口到达。
3. **更新总索引 **`docs/models/index.md`：在 Qwen 一行最前加入页面链接，保持与其他系列入口一致。
4. **接入侧边栏导航 **`docs/docs.json`：在 Qwen3.8 分组之后、`qwen3-next` 之前插入 `models/qwen/qwen3-8-flash-next`，使文档站点可直接渲染该页面。
5. **配套说明**：无源码、测试改动；合并前由两位维护者（Shi-Dong、yushengsu-thu）approve，claude 机器人自动 review 未发现问题。

关键文件：
- `docs/models/qwen/qwen3-8-flash-next.md`（模块 模型文档；类别 docs；类型 documentation）: 新增 250 行 recipe 页，是本次 PR 的核心交付，完整描述 Qwen3.8-Flash-Next 的架构定位与三分支实现方案。
- `docs/models/qwen/index.md`（模块 模型文档；类别 docs；类型 documentation）: Qwen 系列索引，加入新模型行与 Qwen4 架构预览说明，决定用户在总入口的可见性。
- `docs/docs.json`（模块 导航配置；类别 config；类型 configuration）: 接入文档站点侧边栏，否则新页面无法在 docs 站渲染；同时确认其被放在 Qwen3-Next 旁而非 Qwen3.8 组内。
- `docs/models/index.md`（模块 模型文档；类别 docs；类型 documentation）: 总模型索引首行加入链接，保持各系列入口一致性。

关键符号：未识别


# 评论区精华

Shi-Dong 在关联 Issue #2777 下评论 `@claude review always`，使该 PR 自动获得 claude[bot] 审查；机器人最终给出 “Code review found no issues” 的结论。两位维护者（Shi-Dong、yushengsu-thu）均直接 APPROVED，未提出实质性异议。由于文档引用仍处 open 状态的实现分支，唯一隐含的讨论点是“文档与未合入代码的风险”，但作者在 PR body 中主动声明并接受了这种前置发布方式。

- claude review 自动订阅与审查结果 (other): 机器人审查通过；两位维护者 Shi-Dong 与 yushengsu-thu 均 APPROVED。
- 文档指向未合入实现分支的风险 (question): 无 review 讨论记录；作者在 body 中主动说明这些依赖并接受该状态。

# 风险与影响

- 风险：文档指向仍在 open 的 miles#2777、SGLang 分支 `sglang-miles-qwen38next` 与 Megatron-LM#89，并固定引用 `docker.io/radixark/miles:qwen38next` 镜像；这些分支若在合入前被改写或镜像被覆盖，文档内容会失真。另外文档声称的架构细节（如 `hc_head_contraction`、PLE 表 ~102 GB）没有链接检查或渲染校验保护，属于纯人肉维护，后续模型实现若有调整需要人工同步。
- 影响：面向使用文档选模型的用户，新增了 Qwen4 架构预览模型的 RL 训练入口；对团队而言是 #2777 功能合入的前置配套，影响范围限于 docs 站点导航与 Qwen 系列索引，无运行时影响。对文档维护者而言，该页面也是‘文档先于实现合入’流程的一例，需要跟踪 #2777 的合并状态。
- 风险标记：文档引用未合入的实现分支 , 依赖临时 docker 镜像 tag, 架构细节无渲染校验保护

# 关联脉络

- PR #2777 Qwen3.8-Flash-Next RL training support: 本 PR 文档页面向的实现 PR，仍在 open 状态；页面中固定引用了该分支与配套镜像。
- PR #2788 docs: add the GLM-5.3-Flash RL recipe page: 同为新增 recipe 文档页的姊妹 PR，同样修改 docs/docs.json 与 docs 索引，体现文档组织模式的一致性。