执行摘要
本 PR 为 miles dashboard 补充了用户面向的完整文档 docs/user-guide/dashboard.md,此前只有实现者 README。文档覆盖 dashboard 的设计(两条数据源、存储布局、读写路径、失败策略)与使用(采集参数、服务方式、视图解释),所有事实均基于源码核对,并修正了 README 中失效的安装指令。同时接入 User Guide 导航并链接到监控页。
功能与动机
PR body 明确说明:此前 dashboard 只有实现者 README,公开文档中没有任何内容解释如何记录遥测或如何解读视图。因此本 PR 的目标是补齐用户指南,使使用者能够理解 dashboard 的双数据源机制、存储设计的意义以及故障处理行为,从而正确采集和阅读遥测数据。
实现拆解
- 新增
docs/user-guide/dashboard.md(+325 行):核心文档,分为 Design 与 Usage 两大部分。
- 设计部分详述两条独立数据源:实时遥测(Timer 阶段 sink、rollout hooks、NVML sampler、sglang scraper → DashboardCollector 命名 actor)和训练产物(--dump-details 写入的各类文件)。
- 解释存储布局动机:append only 流支持 follow() 字节偏移尾部追踪、并发读无锁;高吞吐流用 polars 列式帧减少内存开销;小时分区与惰性解析处理长运行任务。
- 明确失败策略:producer 为 fire and forget,collector 异常不影响训练;写失败会 loud 报错。
- 使用部分列出全部采集参数及默认值,说明服务方式、三视图(Metrics、Compute Utilization、Rollouts)用途,以及未启用 --use-miles-dashboard 时的可用能力。
- 修改
docs/docs.json(+1 行):在 User Guide 导航数组中加入 user-guide/dashboard,使文档站点可见。
- 修改
miles/dashboard/README.md(+4/-1):修正 pip install -e .[dashboard](该 extra 不存在)为直接安装 fastapi、uvicorn、polars,并注明用户文档位置。
- 修改
docs/user-guide/monitoring.md(+3 行):在监控页顶部添加指向 dashboard 指南的链接。
无测试、配置或部署配套改动,属于纯文档与导航调整。
本次 PR 为纯文档变更,没有涉及源码实现,因此不展示代码片段。核心内容见 docs/user-guide/dashboard.md 文档本身。
评论区精华
本 PR 无实质 review 讨论。唯一评论来自 gemini-code-assist[bot],声明其审查服务已停止;审核者 yueming-yuan 直接 APPROVED,无评论内容。
风险与影响
风险极低,主要是文档与未来代码变更的一致性维护问题:
- dashboard 的视图结构、数据流、存储格式若后续调整,需同步更新本文档,否则会误导用户(本 PR 已发生过一次事实纠正,如 Efficiency 视图并入 Compute Utilization)。
- README 中直接列出的依赖若未来变动,需保持同步。
影响面为文档读者,对系统运行无任何影响。团队可从文档中快速掌握 dashboard 的设计边界和故障行为,降低支持成本。
关联脉络
本 PR 与 dashboard 相关历史 PR 相互补充:#1965 修复 dashboard 阶段可见性,本 PR 文档中描述的视图行为与其对应;#2028 扩展 session 计数器采集,属于文档中的遥测数据源之一。整体上,dashboard 正在从一个仅实现者了解的内部功能走向对用户开放的正式能力,本 PR 是这一演进的关键文档配套。
参与讨论