GPUPlane 产品设计文档
版本：v0.1-draft · 2026-08-17 本文档在原始产品方案基础上做批判性审视与精化。竞品验证详见 01-product-research.md，工程落地见 03-system-design.md。
1. 产品定位（修订后）
Section titled “1. 产品定位（修订后）”GPUPlane 是一套面向个人开发者与 1–8 卡小规模 GPU 环境的 Agent-native Training Control Plane。 以轻量 Agent 为执行端，在不改变既有 PyTorch 工作流的前提下，提供远程任务调度、资源监控、实验追踪、Checkpoint 与 Evaluation 管理，并通过 REST / CLI / Web / MCP 向人和 AI Agent 提供同一个控制面。
一句话：给个人的 GPU 训练补上“控制面”，让人和 Agent 用同一套语义操作训练生命周期。
1.1 定位的三个支点（差异化来源）
Section titled “1.1 定位的三个支点（差异化来源）”| 支点 | 含义 | 对立面 |
|---|---|---|
| 个人 GPU 优先 | 围绕 1–8 卡设计：SQLite、单 worker、独占调度、systemd 部署 | ClearML/K8s 系：为集群设计再向下裁剪，基础设施即成本 |
| 工作流兼容（Observer 而非 Trainer） | 平台在训练代码之外；python train.py 永远可独立运行；三级接入（零侵入/TB 约定/SDK） |
ClearML 的环境重建与 Git 强依赖；平台型 Trainer 对 loop 的接管 |
| Agent-native | 语义工具（diagnose/compare/best-checkpoint）+ MCP + Skill，平台持续监控、Agent 按事件介入 | 传统 tracker 只有 CRUD API，Agent 只能拿到原始点 |
2. 对原方案的批判性审视
Section titled “2. 对原方案的批判性审视”逐条列出：保留（验证成立）/ 修订（方向对但需调整）/ 新增（原方案遗漏）/ 风险（需持续警惕）。
2.1 经审视后保留的核心决策
Section titled “2.1 经审视后保留的核心决策”- Job ≠ Run 的分离（Job 调度 / Run 观测）——比“Job=Experiment”灵活，是评估流水线（train→ckpt→eval job）成立的前提。✅
- GPU 独占调度、不以 utilization 判空闲——util=0 可能是 DataLoader/Eval 阶段，这是个人 GPU 调度最常见的错误假设。✅
- LOST 状态 + reconcile——agent 失联语义清晰，比简单 FAILED 准确。✅
- 三级接入（零侵入 / TB 约定 / 可选 SDK）——是“不绑架训练过程”承诺的技术兑现。✅
- SQLite + 无 Kafka/Redis——个人规模的正确默认。✅
- MCP 只是 Core Service 的适配器、语义优先于原始数据——架构上最重要的两条原则。✅
2.2 修订建议（方向正确，设计需调整）
Section titled “2.2 修订建议（方向正确，设计需调整）”| # | 原方案 | 问题 | 修订 |
|---|---|---|---|
| R1 | 同一张 GPU 同时只允许一个 job（“gpu.owner_job”） | 未定义多卡节点与 cpu-only job | 抽象 GPU Slot：每卡一个槽；调度注入 CUDA_VISIBLE_DEVICES；gpu:0 的 job 走 cpu-only 并发通道（每节点上限 2），评估/导出不再排队等训练 |
| R2 | “日志实时发送至 Control Server” | 训练日志可上 GB，全量进 SQLite 必膨胀 | 全文日志只存 agent 本地文件；server 只持久化尾部 2000 行 ring buffer + 实时转发；--full 时按需向 agent 拉取 |
| R3 | Checkpoint 记录 hash |
GB 级文件全量 hash 太贵，watcher 会卡 | 改为快速指纹（size+mtime+头尾各 1MB 的 sha1）；全量校验做成手动 ckpt verify |
| R4 | Checkpoint Watcher“识别新生成的 checkpoint” | 未处理半成品写入（大文件写数分钟） | 防抖注册：mtime 稳定 10s 才上报；跳过 .tmp/.partial；识别 HF checkpoint-*/trainer_state.json 提取 step |
| R5 | 第一版调度 SQL 轮询 | 正确，但缺 dispatch 超时处理 | DISPATCHING 状态 ack 超时（30s）回 QUEUED，上限 3 次后置 FAILED（防 agent 假死吞 job） |
| R6 | WebSocket 提供 Web UI 实时日志 | 单向场景 WS 偏重 | UI 日志默认 SSE（浏览器自带重连）；WS 只留给交互操作（stdin/信号） |
| R7 | v0.1 范围（Agent+监控+队列+Runner+日志+Web UI+CLI+Run+指标+TB+Checkpoint） | 约 3 个里程碑的量，一次性交付风险高 | 拆为 M0–M5（见 04 路线图），Web UI 推迟到 M4，此前 CLI 闭环；每个里程碑都可独立使用 |
| R8 | SDK from gpuctl import run |
品牌不统一（目录 GPUPlane vs gpuctl） | 统一命令/包命名空间为 gpuctl（CLI、SDK import、数据目录 ~/.gpuctl/），产品名 GPUPlane 仅作品牌 |
| R9 | Run 与重试的关系未定义 | 重试时 metrics 归属易混淆 | 每次 dispatch（含 retry）创建新 Run（job_id + attempt），重试曲线天然隔离可对比 |
| R10 | “Agent 按事件介入” | 缺少 Agent 被唤醒的实际通道（MCP 是 request/response，平台推不动 agent） | 三通道落地：① webhook 外推（ntfy/Bark 通知人）② gpuctl event-hook 拉起本地 agent 会话 ③ Agent 侧分钟级低成本轮询 list_events + get_run_summary |
2.3 新增（原方案遗漏）
Section titled “2.3 新增（原方案遗漏）”| # | 遗漏 | 补法 |
|---|---|---|
| N1 | 认证与安全模型完全缺失（远程提交/取消任务是高危能力） | 单用户多 token + scope（read/write/agent/sdk）；MCP 默认只读，submit/cancel 需 write scope；跨网必须 TLS/Tailscale |
| N2 | 环境快照：方案明确拒绝环境重建（对），但连“记录”也没有 | dispatch 时 agent best-effort 采集 git commit/dirty、python 版本、关键包版本、argv 进 runs.env_snapshot——不重建，但可比较、可追溯，成本几乎为零 |
| N3 | 通知渠道：训练完成/OOM 时人不在电脑前 | v0.2 webhook（ntfy/Bark/自定义 URL）订阅事件类型推送 |
| N4 | SQLite 备份 | gpuctl server backup（在线备份 API + 日志打包），可选 litestream |
| N5 | uvicorn 单 worker 约束（内存态 pub/sub 多 worker 不共享） | 架构上确认单 worker 为既定约束并写入部署文档；pub/sub 抽象接口留扩展点 |
| N6 | 训练环境与平台依赖隔离 | SDK 零重依赖（仅 httpx）；agent/server 永远独立 venv，绝不装进训练环境 |
2.4 需要持续警惕的风险
Section titled “2.4 需要持续警惕的风险”- TB 解析的边界情况（tensor 化 scalar、半写 CRC、step 回退、大文件全量 CRC 慢）——已逐条给出工程对策（03 号文档 §7.4），集成测试必须用真实 PyTorch SummaryWriter 产物；
- MCP 生态版本动荡（官方 mcp 2.0 与 fastmcp 3/4 交替期存在硬冲突）——钉版 + MCP 独立成包 + v0.3 才接入，把生态风险排在最后；
- 功能蔓延：最容易发生在 Web UI（变成“小 W&B”）和 Scheduler（变成“小 K8s”）。每加一个功能问：1 张 5090 的用户需要它吗？
- 诊断规则的误报疲劳：OVERFITTING_SUSPECTED 等启发式规则误报会快速消耗信任——所有规则阈值可配，critical 级别宁缺毋滥。
3. 用户画像与核心场景
Section titled “3. 用户画像与核心场景”3.1 画像
Section titled “3.1 画像”- P1 个人研究者/独立开发者（主要）：1 台自装 GPU 工作站（如 RTX 5090），PyTorch/HF/TRL 技术栈，白天用笔记本、训练跑在家里/实验室的机器上；当前工作流 = SSH + tmux + 手动 nvidia-smi + TensorBoard；
- P2 小实验室（次要）：2–4 台异构 GPU 机（3090/4090/5090 混部），几个学生共用，需要“谁在用卡、排队”的可见性；
- P3 AI Agent（一等公民，非人类）：Codex/Claude Code 等，受用户委托执行“改代码→训练→评估→迭代”闭环。
3.2 核心场景（JTBD）
Section titled “3.2 核心场景（JTBD）”| # | 场景 | 现状痛点 | GPUPlane 体验 |
|---|---|---|---|
| S1 | 离开工位后想知道“训练还活着吗、loss 正常吗” | SSH 上去翻 tmux + 肉眼读日志 | 手机浏览器开 Dashboard：进度、曲线、事件一目了然 |
| S2 | 排队跑多个实验（改 lr 三连跑） | 手动守着一个个起，或写脆弱 shell 脚本 | 连提 3 个 job，独占调度串行执行，完成推送通知 |
| S3 | 训练挂了（OOM/NaN），快速定位 | 翻 stderr、猜原因、改完重跑 | OOM 事件 + tail 日志 + failure_reason；Agent 可自动诊断并改 batch size 重提 |
| S4 | 训完 10 个 checkpoint，选哪个 | 手动跑 eval、Excel 记结果 | checkpoint 自动注册 → 一键排队评估 → 按 primary metric 推荐 |
| S5 | 让 AI Agent 代管实验循环 | Agent 只能 SSH 瞎摸，无结构化观测 | MCP 语义工具：summary/diagnose/compare/best-checkpoint + Skill 工作流 |
| S6 | 上周裸跑的训练，想纳入管理 | 散落在 outputs/ 目录 | gpuctl import-run 离线导入，与平台内 run 同视图对比 |
4. 功能优先级（MoSCoW）
Section titled “4. 功能优先级（MoSCoW）”Must（v0.1，缺了就不是这个产品）
Section titled “Must（v0.1，缺了就不是这个产品）”Agent 心跳/GPU 监控 · Job 队列+独占调度 · ProcessRunner · 日志（本地全文+server tail+SSE） · Job 状态机含 LOST · SDK run.log · TB 自动接入 · Checkpoint 发现注册 · CLI 全命令 · Web 四页 · Run Summary · import-run · token 认证 · systemd 部署
Should（v0.2）
Section titled “Should（v0.2）”Project/Experiment · Evaluation Job 与结果回挂 · 事件规则全集 · Retry · DockerRunner · Webhook 通知 · MetricDefinition 管理 · SDK 框架 callback extras · 环境快照（提前到 v0.1 M2 低成本先做）
Could（v0.3）
Section titled “Could（v0.3）”MCP Server · 语义诊断五件套 · Skill/AGENTS.md 模板 · run 对比视图增强 · artifact 管理
Won’t（明确不做，与原方案一致并补充）
Section titled “Won’t（明确不做，与原方案一致并补充）”K8s/Slurm 调度 · 多租户与计费 · 云 GPU 供给 · Kafka 等消息基础设施 · 完整 W&B/MLflow 替代 · 强制 Docker/Git-clean/环境重建 · 模型文件托管与分发（checkpoint 只注册不搬运） · 抢占式调度
5. 版本边界与北极星指标
Section titled “5. 版本边界与北极星指标”- v0.1 北极星：用户连续 7 天没有为训练管理打开过 SSH+tmux；
- v0.3 北极星：一次“改配置→训练→评估→选 checkpoint”循环由 Agent 端到端完成，用户只在开始和结束时介入；
- 关键健康指标：agent 上报链路可用率（spool 兜底率 100%）、误报事件占比 <10%、server SQLite 体积增长 <50MB/周（日志策略生效的证据）。
6. 与竞品的关系（调研验证后定稿，论证见 01 号文档 §2/§4）
Section titled “6. 与竞品的关系（调研验证后定稿，论证见 01 号文档 §2/§4）”调研确认的关键事实（2026-08，两路独立调研交叉验证）：
- W&B 已有官方 MCP（2026-05，20 个 schema-first tools）与 Aria 研究 agent——但全部只读；W&B Launch 任务执行全 Docker 化，生产级自托管需 K8s+MySQL+S3+Redis（+ClickHouse）。W&B 验证了“Agent 消费训练语义”的需求真实性，但不碰“任务在我的 GPU 机器上怎么跑”；
- MLflow 3.x 已把 SQLite 定为默认后端——我们的存储选型获得行业背书；其官方 MCP（3.4 起）仅限 GenAI traces；
- ClearML 自托管 = apiserver+ES+Mongo+Redis 全家桶，执行模型强依赖 Git 快照+环境重建；dstack SSH fleet 需 Docker+免密 sudo，其官方 Agent Skill 是调研中唯一“agent 可提交任务”的成熟产品（CLI 驱动、非 MCP、无训练语义）；
- SwanLab 有硬件监控+通知但无任务执行；Aim 维护状态存疑（社区 issue 追问 + release 断档），不宜作为依赖；
- 训练作业生命周期（submit/monitor/kill/diagnose）没有任何权威 MCP server——空白经两路调研一致确认。
结论：GPUPlane 不与任何 tracker 抢“实验数据记录”的存量——占据的是 tracker 与 orchestrator 之间的空位：本地优先的执行控制面 + 训练语义 + Agent 可读写。与 wandb/TensorBoard 是互补关系（GPUPlane 消费 TB events；用户可继续用 wandb 追踪）。潜在威胁与护城河三件套（裸进程工作流 / checkpoint-evaluation 谱系语义 / SQLite 级零依赖）详见 01 号文档 §4.2。