# PR #2359 完整报告

- 仓库：`radixark/miles`
- 标题：docs: dashboard advanced features and example visualization 
- 合并时间：2026-08-12 01:33
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2359

---

# 执行摘要

- 一句话：dashboard 文档配六张真实运行截图并重构视图章节
- 推荐动作：值得快速浏览而非精读：无代码逻辑，但有两个方法论值得借鉴——用同一真实运行喂全部截图、让正文数字可对照查验，以及视图优先于架构的叙事重构，对后续 dashboard 文档和其它功能文档有示范意义。合入后建议人工检查文档站各截图是否正常渲染，并关注 #2353 的合并顺序与 README 图片链接的最终落地状态。

# 功能与动机

PR body 明确指出旧文档的缺陷：The dashboard doc named every panel but showed none of them, so the only way to find out what a view looks like was to go run it against a dump（文档只点名面板、不给画面，读者想知道视图长相只能自己对着 dump 跑一遍）。第二次提交进一步指出结构问题：旧文档用 145 行架构描述开场，读者要先穿越存储布局才能看到工具本身。因此动机是双重的——补齐可视化参考，并把叙事重心从架构移到屏幕上实际有什么。此外 sglang 分类在数据源、x 轴、图例交互上的三点差异，旧文本从未提及，属于真实存在的知识缺口。

# 实现拆解

1. **重写 Views 章节并配六张截图**：`docs/user-guide/dashboard.md`（+292/−221）为每个视图配一张 1600×1200 截图，正文围绕画面组织。新增的关键语义说明包括：sglang 分类与其它指标的三点差异（数据来自引擎 scrape 而非 `metrics.jsonl`、x 轴是墙钟时间而非 `rollout/step`、Engines 图例每引擎一个复选框且取消勾选会连同 y 轴缩放一起剔除该引擎）；Compute Utilization 按集群总览 → 每步 wait-ratio 条带 → 每 lane 细节自上而下拆解；Batch anatomy 的橙色随 weight version 变化、绿色为工具调用阻塞时间、按墙钟跨度排序找长尾；Groups 页红行表示组内样本同分导致 advantage 全零、无梯度贡献（图中 8 组有 6 组红）；头部 `—` 瓦片表示该列缺失而非零。
2. **重构页面结构为视图优先**：新结构按 What it shows（三个视图与截图）→ 如何开启 → 工作原理排列，开头放问题 → 打开哪个视图的速查表（Is the run learning? → Metrics；Why is a step slow? → Compute Utilization），正文改用更平实的短句，sglang 差异从长从句改为编号列表。
3. **图片资产按主题建目录**：新增 `docs/assets/images/dashboard/`（六张截图，去掉引擎 schema 里必须的 dashboard- 前缀）与 `docs/assets/images/brand/`（logo/favicon），并同步更新三处引用：`docs/docs.json` 的 logo/favicon 路径、`docs/assets/stylesheets/extra.css` 的背景图路径、根 `README.md` 的 logo 链接；删除 `imgs/` 下四个与 `docs/assets` 字节完全一致的重复文件（`arch.png`、`miles_logo.png`、`miles_square.png`、`p2p_vs_nccl_scaling.png`），`docs/assets` 成为图片唯一仓库。
4. **把资产约定写进文档**：`docs/README.md` 新增规则——一个主题超过一张图就建子目录、目录名用页面或区域名，单张孤图留在顶层。
5. **验证与配套**：所有事实数字（6/8 零标准差组、32+32 GPU、4 引擎、100 步 11.2 h、无 eval 分类）都通过该次运行的 API 核对而非凭记忆书写。无源码、测试或部署配套改动；与 #2353 的 `dashboard.md` 编辑存在重叠区间，需按合入顺序做一次小手动合并。

关键文件：
- `docs/user-guide/dashboard.md`（模块 仪表盘文档；类别 docs；类型 documentation）: 本 PR 核心文件：以六张同源截图为中心重写 Views 章节，重构页面结构为视图优先，并补齐 sglang 分类、Compute Utilization、Batch anatomy、Groups 红行等关键语义说明。
- `docs/docs.json`（模块 文档配置；类别 config；类型 configuration）: 文档站配置：logo 与 favicon 路径从 images/ 迁移到 images/brand/，是本 PR 资产目录重组的关键引用方之一。
- `docs/assets/images/dashboard/metrics-rollout.png`（模块 仪表盘截图；类别 other；类型 assets）: 六张新增 dashboard 截图之一，全部来自同一次 GLM-5.2 744B terminal-bench-2 运行，是文档配图改动的视觉主体。
- `docs/assets/images/brand/miles_logo_light.png`（模块 品牌图片；类别 other；类型 rename-or-move）: 品牌图从 images/ 顶层重命名迁移到 brand/ 子目录，代表四个同名品牌资产的 rename-or-move 变更。
- `docs/assets/stylesheets/extra.css`（模块 样式资源；类别 other；类型 configuration）: 文档站点样式中的背景图路径随迁移更新，是资产重组的另一个引用方。
- `docs/README.md`（模块 文档约定；类别 docs；类型 documentation）: 把图片资产组织约定写入文档：主题多图建子目录、孤图留顶层，为后续配图确立可复用规范。
- `imgs/arch.png`（模块 废弃资源；类别 other；类型 deletion）: 代表 imgs/ 目录清理：四个与 docs/assets 字节完全重复的顶层图片被删除，docs/assets 成为唯一图片仓。
- `README.md`（模块 仓库首页；类别 docs；类型 documentation）: 根 README 的 logo 链接由 imgs/ 改为 docs/assets 下的绝对 raw URL，是本 PR 资产收敛的外部引用方。

关键符号：未识别


# 评论区精华

评审过程干净利落：Shi-Dong 直接 APPROVED，仓库内零评论、零 review 讨论线程。唯一需要协调的内容写在 PR body 里：作者主动披露 #2353 同时在编辑 `dashboard.md`（追加 Model FLOPs utilization 章节到 Compute Utilization 之后），与本 PR 的 Views 重写重叠，后合入方需要做一次小规模手动合并，并明确声明图片文件无重叠。另外提交信息中还记录了一个技术取舍：根 README 的 logo 改用指向 main 分支的 `raw.githubusercontent.com` 绝对 URL，因为 README 会在仓库之外渲染，代价是合并前该链接会 404，作者承认这是移动文件必然的代价。

- 暂无高价值评论线程

# 风险与影响

- 风险：资源路径迁移风险：logo、favicon、CSS 背景图路径全部变更，任何未覆盖的引用方都会破图；已确认 docs.json、extra.css、README.md 三处引用同步更新，imgs/ 删除后仓库外历史链接会失效但本 PR 内无法验证。合并冲突风险：#2353 与本 PR 共同编辑 dashboard.md，后合入方必须手动合并，处理不当会丢 Model FLOPs utilization 章节或本 PR 的截图引用。链接可用性风险：README 图片 URL 指向 main 分支，合并前 404、合并后生效，若分支回滚或改名会长期失效。文档时效性风险：文中具体数字（reward 0.3→0.9、prefix_cache_hit_rate 0.96→0.94 等）绑定 GLM-5.2 某一次特定运行，dashboard 行为演进后可能过时，但 `—` 瓦片语义、sglang 三点差异等结构性说明长期有效。
- 影响：对用户：首次能在文档中看到 dashboard 各视图的真实长相与读图方式，显著降低必须跑一次 dump 才能理解面板的上手成本；sglang 差异与 Groups 红行说明直接帮助训练中诊断（优势消失、无梯度贡献）。对系统：零运行时影响（纯文档与静态资源），但文档站构建依赖新图片路径，docs.json 与 extra.css 引用不一致会导致破图或构建告警。对团队：确立图片资产组织约定（主题子目录），后续配图有章可循；资产从 imgs/ + docs/assets 双份收敛为单一仓库，减少重复维护。整体影响面集中在文档站与开发者阅读体验，程度中等偏低。
- 风险标记：文档资产路径迁移 , 与 #2353 合并冲突 , README 图片链接合并前 404, 文档数字绑定单次运行

# 关联脉络

- PR #2353 素材未提供标题；与本 PR 同改 dashboard.md: 同一文件编辑：该 PR 在 Compute Utilization 后追加 Model FLOPs utilization 章节，与本 PR 的 Views 重写重叠，PR body 明确说明后合入方需手动小合并。
- PR #2366 docs: rewrite the fully async page around schedule, data path, eval, and metrics: 同为围绕真实内容重写文档结构、对齐代码的方法论，可见仓库正在系统性提升文档质量。
- PR #2300 scripts: enable the Miles dashboard in the quick-start launcher: dashboard 功能线的使用入口：启动脚本默认开启 dashboard 遥测，本 PR 补齐了高级功能与读图文档，形成完整闭环。