# PR #2788 完整报告

- 仓库：`radixark/miles`
- 标题：docs: add the GLM-5.3-Flash RL recipe page
- 合并时间：2026-08-28 03:44
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2788

---

# 执行摘要

- 一句话：新增 GLM-5.3-Flash RL 配方文档页并接入导航
- 推荐动作：常规文档 PR，无需精读代码，但建议：
 1) 用 2 分钟浏览页面结构与 #2786 的对应关系，确认命令和镜像版本；
 2) 在 #2786 合并时做一次同步复核，避免文档与实现漂移。值得借鉴的是「文档先行 + 版本固定 + 验证范围声明」的写法，适合作为后续新模型配方文档的模板。

# 功能与动机

PR body 明确指出：GLM-5.3-Flash（`model_type: glm5_next`）是 45 层 KDA + DSA 混合架构，是 "a different architecture from the 744 B GLM5 line rather than a smaller cut of it"，因此需要独立页面而非作为 glm5 / glm5-2 下的小节；同时页面刻意保持简短，只覆盖模型是什么、用哪个镜像、如何转换 checkpoint、launch 形态与健康 run 的报告，不做逐参数讲解，也不与其它文档页做交叉链接。

# 实现拆解

1. 新增页面 `docs/models/glm/glm5-3-flash.md`：第 1 节给出架构参数（45 层混合：34 层 KDA 线性注意力 + 11 层 DSA 稀疏注意力；288 专家 top-8 sigmoid 路由，前 3 层稠密；逐块 mHC 超连接；NoPE MLA；kpool 压缩 lightning indexer；hidden 4096 / FFN 12288 / 64 头 / vocab 154880 / rotary base 800000；训练丢弃 MTP）；第 2 节列出 Full、8 层切片、4 层切片三种变体及对应 `--model-name`；第 3 节固定镜像 `docker.io/radixark/miles:glm53next` 及 miles@1cd14c00、sglang-miles-glm53next@9a26e749、Megatron-LM#89@e8f57451 三个组件版本，并给出 `hf download` 与 `convert_hf_to_torch_dist.py` 转换命令（转换前由 `miles/utils/external_utils/model_args_utils.py glm5.3-flash` 生成 `MODEL_ARGS_LINE`，并设置 `CONVERT_KEEP_PP1=1`）；第 4 节说明通过 ray cluster 与 `MILES_SCRIPT_EXTERNAL_RAY=1` 运行 `scripts/run_glm5_3_flash.py train` 的 launch 方式；第 5 节引用 #2786 的验证数据（16 × 4 GB300、DAPO 在 DAPO-Math-17k 上），仅 16 × 4 标记为 validated，8 × 4 与 6 × 4 仅列出。
2. 注册 `docs/docs.json`：在 GLM 组 `pages` 数组首位插入 `models/glm/glm5-3-flash`，保证文档站侧边栏可见。
3. 更新 `docs/models/glm/index.md`：description 加入 "KDA + DSA 混合 " 表述；variants 表新增 GLM-5.3-Flash 行（45 层 · 288 专家 top-8）；fastest path 列表追加 "Hybrid linear + sparse attention with mHC" 入口。
4. 更新 `docs/models/index.md`：GLM 行首位插入 GLM-5.3-Flash 链接，保持总索引与系列索引一致。
配套说明：无测试、schema 与部署改动，`docs.json` 的注册属于纯站点导航配置。

关键文件：
- `docs/models/glm/glm5-3-flash.md`（模块 模型文档；类别 docs；类型 documentation）: 本次 PR 的核心产物：承载 GLM-5.3-Flash 的架构说明、镜像 / 组件版本固定表、checkpoint 转换命令、launch 形态与验证数据，是用户训练该模型的唯一入口文档。
- `docs/docs.json`（模块 文档导航；类别 config；类型 configuration）: 站点导航注册文件，新增页面若不在此注册不会出现在文档站侧边栏；GLM 组 pages 数组首位插入 glm5-3-flash。
- `docs/models/glm/index.md`（模块 模型文档；类别 docs；类型 documentation）: GLM 家族总览页：更新 description、变体表和 fastest path 列表，加入 GLM-5.3-Flash 行并明确其与 GLM5 线的架构差异。
- `docs/models/index.md`（模块 模型文档；类别 docs；类型 documentation）: 全部模型入口索引表，GLM 行首位加入 GLM-5.3-Flash 链接，保持各系列导航一致。

关键符号：未识别

## 关键源码片段

### `docs/docs.json`

站点导航注册文件，新增页面若不在此注册不会出现在文档站侧边栏；GLM 组 pages 数组首位插入 glm5-3-flash。

```jsonc
{
  "group": "GLM",
  "pages": [
    // 新增的 GLM-5.3-Flash 页面注册：独立页面而非 glm5 下小节，
    // 与 docs/models/glm/index.md 的变体表保持一致
    "models/glm/index",
    "models/glm/glm5-3-flash",
    "models/glm/glm5-2",
    "models/glm/glm5",
    "models/glm/glm4-7-flash",
    "models/glm/glm4-5"
  ],
  "expanded": false
}
```

# 评论区精华

本 PR 没有任何 review comment：claude[bot] 仅输出仓库手动 review 机制的自动提示，QQontheMoon 以空 body 直接 approve。没有技术争议或未解决疑虑；唯一的「风险讨论」是 PR body 自述——实现 PR #2786 尚未合并、文档先行、验证数据引用自 #2786 且仅 16 × 4 形态标记为 validated。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险点集中在文档与实现的同步上：
 1) 页面描写的 `--model-name`、转换命令、镜像 tag 与 launch 脚本均来自未合并的 #2786，若实现合并时细节调整，文档会失真；
 2) `docs/docs.json` 的 pages 为手写路径且无自动化校验（仓库 CI 曾对 test-discovery 规则踩坑，路径拼错会静默丢失侧边栏入口）；
 3) 页面仅将 16 × 4 形态标记为已验证，8 × 4 与 6 × 4 只是 launcher assert 接受，用户按后两者运行可能遇到未覆盖的问题；
 4) 镜像内固定了 miles、SGLang、Megatron-LM 三个 commit，组件升级重建镜像后若不更新文档表，用户会拿到过期信息。均为低概率、低影响的文档侧风险，不涉及代码路径。
 - 影响：影响范围限定在文档站点：新增 1 个页面并接入导航，两级索引同步更新；用户获得 GLM-5.3-Flash 训练入口（架构说明、镜像、转换、launch），团队确立了「文档先行」模式，可在 #2786 合并时对照复核。无代码、测试、镜像或训练链路影响，影响程度低。
 - 风险标记：文档先行于实现 PR, 镜像版本需随组件升级同步 , 仅 16×4 形态已验证

# 关联脉络

- PR #2786 Implementation PR for GLM-5.3-Flash: PR body 中引用的实现 PR（合并时仍 open）：文档规定的命令、镜像与验证数据均来自它；标题未在材料中给出。
- PR #2785 docs: add the Qwen3.8-Flash-Next RL recipe page: 同类型的模型 RL 配方文档 PR，采用完全相同的模式：独立页面 + docs.json 注册 + 两级索引更新。
- PR #2716 fix: align MLA RoPE types with model configs: GLM 系列 launch/ 模型脚本线：GLM-5.3-Flash 文档中的 model_args_utils.py glm5.3-flash 与 scripts/models/*.py 同一机制相关。
- PR #2673 Bump Megatron-LM to miles-main-20260819 (latest NVIDIA dev): Megatron-LM 版本管理与镜像构建线：文档把 Megatron-LM#89@e8f57451 固定进 glm53next 镜像，与 Dockerfile 的 MEGATRON_BRANCH 管理同源。