Prhub

#1932 docs: the miles dashboard design and usage

原始 PR 作者 Zhichenzzz 合并时间 2026-07-30 02:18 文件变更 4 提交数 2 评论 1 代码增减 +333 / -1

执行摘要

新增 dashboard 用户指南并接入文档导航

PR body 明确指出:'Until now it had only an implementer's README under miles/dashboard/, so nothing in the published docs explained how to record telemetry or how to read the views.' 即 dashboard 功能已存在但缺少用户指南,导致用户无法了解如何采集遥测数据、如何解读视图。作者希望通过文档补全这一空白,并确保所有事实性陈述均与源码核对。

值得阅读,尤其对于使用或打算使用 miles dashboard 的工程师。文档不仅是使用手册,还深入解释了存储布局设计和失败策略,对理解 dashboard 的架构很有帮助。建议在后续 dashboard 功能变更时,以本 PR 为基准同步维护该文档。

讨论亮点

本 PR 没有实质性的 review 讨论,唯一一条评论来自 gemini-code-assist[bot],声明其代码审查服务已停止,不构成技术讨论。yueming-yuan 审核通过(APPROVED),无评论内容。

实现拆解

本 PR 为纯文档变更,包含 4 个文件的改动,分步拆解如下:

  1. 新增 docs/user-guide/dashboard.md(+325 行):这是核心交付物。文档分为 DesignUsage 两大部分:
    • Design 部分详细描述了 dashboard 依赖的两条独立数据源:实时遥测(由 Timer 阶段 sink、rollout hooks、每 GPU 节点一个 NVML sampler、sglang scraper 产生,通过 DashboardCollector 命名 actor 收集)和训练产物(--dump-details 写入的 .ptdashboard_columns/ parquet、trajectory/ jsonl)。
    • 解释了存储布局的设计动机:append only 流保证 follow() 是字节偏移尾部追踪、并发读无需加锁;高吞吐流使用 polars 列式帧;phasesgpu_utilengine_series 按小时分区惰性解析。
    • 说明了训练路径的失败策略:producer 是 fire and forget,collector 死掉不影响训练;写入失败会 loud 报错。
    • Usage 部分列出了采集参数、服务方式、三个视图(Metrics、Compute Utilization、Rollouts)的用途,以及未启用 --use-miles-dashboard 时仍可用的功能。
    • 文档中所有事实均与源码核对,例如确认只有三个顶层视图、Efficiency 面板并入 Compute Utilization。
  2. 修改 docs/docs.json(+1 行):在 User Guide 导航的 pages 数组中新增 user-guide/dashboard,使新页面出现在文档站点侧边栏。
  3. 修改 miles/dashboard/README.md(+4/-1):将失效的 pip install -e .[dashboard] 修正为直接安装 fastapiuvicornpolars(这三个依赖已在训练镜像中),并在文件头部说明用户文档的位置。
  4. 修改 docs/user-guide/monitoring.md(+3 行):在监控页开头增加指向 Miles Dashboard 的链接,方便用户从现有监控路径跳转到 dashboard 指南。

没有测试或配置配套改动,属于纯文档与导航调整。

文件 模块 状态 重要度
docs/user-guide/dashboard.md 用户指南 added 5.04
docs/docs.json 文档导航 modified 2.76
miles/dashboard/README.md 仪表盘模块 modified 1.96
docs/user-guide/monitoring.md 用户指南 modified 1.82

分析完成后,这里会展示 LLM 生成的相对完整源码片段和详细注释。

评论区精华

没有提炼出高价值讨论线程

当前评论区没有形成足够清晰的争议点或结论,后续有更多讨论时会体现在这里。

风险与影响

由于是纯文档变更,技术风险极低。主要风险集中在文档与实现的一致性上:dashboard 的功能(如视图数量、数据流表、存储格式)可能在后续迭代中变化,若未能同步更新该文档,将误导用户。例如 PR 中已经发生一次事实纠正(Efficiency 视图改为渲染在 Compute Utilization 内),未来类似变更需要维护者留意。另一个小风险是 README.md 中的安装指令改为直接列出依赖,若后续加入新依赖而未更新文档,会导致用户安装缺包。

影响范围主要是文档读者(使用 miles dashboard 的用户),他们现在可以从官方文档中了解 dashboard 的采集方式、视图含义和故障行为,降低使用门槛。对系统本身无运行影响,不涉及代码行为变化。对团队而言,该文档明确了 dashboard 的设计边界(如只读文件、失败策略),有助于后续维护和功能扩展。

文档与实现一致性风险 纯文档变更

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接,后续同步到相关引用后会出现在这里。

完整报告

参与讨论