执行摘要

本 PR 对 docs/ 做了一次系统化审计，核心目标是消除与 main 分支代码不符的文档陈述：会直接执行失败的命令、已不存在的符号与 flag、与源码不一致的默认值和指标名。共改动 28 个文件，重写了 argument-groups.md 对 launcher 的刻画（Python <group>_args 模型，新增 misc_args），对齐 --rm-type / --sglang-* 的真实取值，并将 mismatch 监控指标名与 mis.py 实际输出对齐。纯文档改动、无运行时代码风险，但 review 中暴露了 eval/skipped_* 删除依据不成立的事实性瑕疵，且 PR 刻意不处理 coverage gaps，建议读者结合 follow-up 清单看待文档完整性。

功能与动机

PR body 原话："Audit of docs/ against main. This PR only fixes claims that are wrong — commands that fail as written, symbols that no longer exist, and values that disagree with the code."

文档与代码在重构后长期脱节，用户按文档操作会直接报错：例如 scripts/model_args.py 已被迁移为 miles/utils/external_utils/model_args_utils.py，但 17 处示例早已更新、两处 GLM 页仍用旧路径；--sglang-enable-ep-moe 等 4 个 flag 已从 pinned SGLang ServerArgs 移除；--update-weight-buffer-size 文档写 1 GB，arguments.py:773 实际是 512 * 1024**2。作者刻意限定范围——只修"错误陈述"，不补"存在但未文档化"的缺口，后者在 body 末尾单列 5 项 follow-up（MLflow / TensorBoard / Prometheus 全家族缺失、6 个 hook 未文档化、Ascend NPU 无页面等）。

实现拆解

本次改动按问题类型分为五条线推进：

1. 修复会直接失败的命令（models/glm/glm4-5、glm4-7-flash、ci/02-docker-build、developer/versions）：转换命令改指 miles/utils/external_utils/model_args_utils.py；Docker --variant 改为 docker/build.py 与 docker-build.yml 中真实存在的 rocm700-mi30x / rocm700-mi35x / rocm720-mi35x，并补上此前两表都缺的 rocm700-mi35x。
2. 移除不存在的符号与 flag：train-infer-mismatch-helper 中只有 --use-rollout-logprobs 与 --use-tis 是 CLI 开关，--tis-* / --rs-* 均为 mis.yaml 里的配置键；deepseek-v4-flash 删除不存在的 MILES_HACK_TRAIN_TORCH_DETERMINISTIC 与 with_transformers_patch() 表述；--sglang-enable-* 组替换为 --sglang-ep-size（75 处）、--sglang-moe-a2a-backend（15）、--sglang-moe-runner-backend（40）、--sglang-deepep-mode（13）。
3. 重写核心概念页：argument-groups.md 从"bash arrays"改写为 Python launcher 模型，逐组说明 <group>_args 的来源；新增 misc_args 组并保留 <a id> 锚点，避免入链失效；concepts、training-backend、launch-script、contributor-guide、kimi-k2.5 五处引用同步更名。
4. 指标与枚举对齐：mis.py 输出的指标名统一纳入 train/ 命名空间并加 mis_ 前缀（training_log_ppl → train/mis_training_log_ppl），区分内置 vanilla_tis_function 的少量输出；--rm-type 补 gemma_math、deterministic_random 与 boxed_ 前缀，并改为 str 类型；CI 标签表补齐 eval、fully-async、miles-plugin、amd 四个漏项。
5. 验证配套：pre-commit run --all-files 与 sync_example_docs.py --check 均干净，重新审计结果为 0 断链、0 缺失图片、0 不存在的仓库路径。第二个 commit 依 review 补修三处：misc_args 交叉引用、--train-deterministic 默认值表述、mis_ 前缀。

以下是 train-infer-mismatch-helper 与 argument-groups 两处核心改写的文档片段，分别体现"CLI 开关 vs YAML 配置键"的厘清和 launcher 参数组模型的重述：

<!-- 核心修正：该功能只新增两个 CLI 开关，其余全部是 YAML 配置键。
     旧文档把 `--tis-mode`、`--tis-level` 等写成命令行 flag，会直接误导用户 -->
You may choose from above algorithms with the two command-line flags below. They are the
only CLI flags this feature adds; everything in **Configs and Recommended Settings** is a
key in the YAML file you pass to `--custom-config-path`.
​
`--use-rollout-logprobs`: True if only use `rollout_log_probs` to compute the loss,
bypassing old_log_probs calculated by training engine;
​
`--use-tis`: True if apply importance sampling/rejection sampling to loss.
​
<!-- 指标命名规则：mis.py 在 wrapper 出口统一加 `mis_` 前缀，
     因此 `training_log_ppl` 到 wandb 变成 `train/mis_training_log_ppl`；
     而 `train_rollout_logprob_abs_diff` 来自 miles 本体，不加前缀 -->
All names below are logged under the `train/` namespace, and every key `mis.py` produces
carries a `mis_` prefix that its wrapper adds on the way out — so `training_log_ppl`
reaches wandb as `train/mis_training_log_ppl`.

<!-- 关键改写：launcher 是 Python 而非 bash 数组；每个操作关注点对应一个字符串变量，
     最终由 execute_train 拼成 train_args 并作为 Ray job 提交 -->
Miles launch scripts are Python (`scripts/run_*.py`). The grouping is deliberately
boring: each script builds one string per operational concern, concatenates them into
`train_args`, and hands that to `execute_train`.
​
| Group | Owns | Where it comes from |
|---|---|---|
| [model args](#model-args) | Architecture constants and plugin specs | `scripts/models/<megatron_model_type>.py`, spliced in by `execute_train` |
| [`ckpt_args`](#ckpt-args) | Actor, reference, HF tokenizer/config, save paths | Launch script |
| [`misc_args`](#misc-args) | GPU layout, colocation, dropout, dashboard | Launch script |
​
<!-- 新增组：misc_args 承载 GPU 布局与杂项；model args 是唯一不由 launcher 构建的组，
     由 execute_train 根据 megatron_model_type 解析 scripts/models/ 下对应文件 -->
Model args are the one group a launcher does not build: it passes `megatron_model_type`
to `execute_train`, which resolves the matching file under `scripts/models/` and
prepends those flags to the command line.

评论区精华

1. eval/skipped_* 删除被证伪：nblintao 指出"These two do have emitters — eval_fleet.py raises EvalSkip("unhealthy") / EvalSkip("pin_violation") and metrics.py logs eval/skipped_{reason}"，即字面量 grep 不到不等于没有 emitter。claude[bot] 进一步确认 EvalFleet.pin() 在 --eval-num-gpus > 0 的 Dedicated fleet 路径下必然触发，且新通用行将其归因于用户 CheckpointEvalFn 也不准确。该意见未被最终 commit 采纳。
2. mis_ 前缀必须补：nblintao 指出 compute_mis_weights_with_cp 与 compute_mis_weights_fsdp 都以 result_metrics[f"mis_{key}"] 收尾，wandb 实际 key 是 train/mis_tis_truncate_fraction 等；claude[bot] 补充默认 vanilla_tis_function 只输出 tis / tis_clipfrac / tis_abs。已解决。
3. 默认值框架纠正：claude[bot] 指出 ScriptArgs 中 train_deterministic 默认 True，"Passing" 一词把默认开启写成可选，需 --no-train-deterministic 关闭；V4-Pro 页同样问题。已解决。

风险与影响

• 事实性风险：fully-async.md 删除的两条 eval/skipped_* 指标行，经两名 reviewer 证实确有 emitter（EvalFleet.pin() 抛 EvalSkip("unhealthy") / EvalSkip("pin_violation")，metrics.py 记录 eval/skipped_{reason}），PR 的删除理由不成立。该争议未回补，读者在 Dedicated fleet 模式下看到的指标与文档不符。
• 无自动化校验：flag 存在性、默认值、指标名没有机器可读对照，pre-commit 只覆盖镜像与链接检查，文档仍会随代码重构再次漂移。
• 覆盖缺口有意保留：cli-reference 只覆盖 344 个 flag 中的 91 个，MLflow / TensorBoard / Prometheus 与 Ascend NPU 全部缺失，用户短期内仍会遇到"flag 存在但文档没有"的场景。
• 影响：纯文档改动无运行时代码风险，但覆盖面广（28 个文件、5 个文档分区），且 argument-groups 新命名口径（小写组名）会约束后续所有文档的写法。

关联脉络

本 PR 处于 v0.1 发布前的 docs 治理节奏中：#2564 已将版本置为 0.1.0，#2657 添加发布公告，本 PR 则是发布前最后一次大规模的事实校对。从更长的演进看，它与 #2581（rollout 模块指标与路径重构）、#2589（sglang 引擎行为调整）等代码侧 PR 互为表里——文档中修正的 rollout_manager.py 路径、--sglang-* 新 flag、mis_ 指标名，正是这些代码重构的直接产物。若后续有 PR 回补 eval/skipped_unhealthy / eval/skipped_pin_violation，将是对本 PR 遗留争议的正式收口。