# PR #2651 完整报告

- 仓库：`radixark/miles`
- 标题：docs: fix stale paths, flags, env vars and metric names
- 合并时间：2026-08-18 23:44
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2651

---

## 执行摘要

本 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 参数组模型的重述：

```markdown
<!-- 核心修正：该功能只新增两个 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`.

```

```markdown
<!-- 关键改写：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 遗留争议的正式收口。