跳转到内容
GPUPlane

架构总览

GPUPlane 由三类组件构成：server（调度 + 存储 + API）、agent（跑在 GPU 机器上的执行器）、 以及客户端（Web UI / CLI / MCP adapter / 训练侧 SDK）。

训练侧（你的代码）执行侧控制面客户端训练脚本train.py · 你的代码TensorBoard事件文件目录checkpoint 目录（可选 watch）gpuctl-agentGPU 主机 · 裸进程Runner · TBAdapterCkptWatcher · NVML心跳 + 出站 WS 连接gpuctl-server控制面 · 单机即可FastAPI · SchedulerEventDetector · RollupSQLite（WAL）单文件存储Web UI:8600 · 浏览器gpuctl CLI运维 · 脚本gpuctl-mcp独立适配器进程Claude Code任意 MCP 客户端stdout·日志tail 指标ckpt 监听WS 出站RESTMCPSDK 直报（可选）
同一张图的纯文本版（进程视图，含内部模块）
┌─────────────────────────── 控制端（可与 GPU 主机同机） ───────────────────────────┐
│  gpuctl-server (uvicorn 单 worker, FastAPI)                                      │
│  ├── REST API        /api/v1/...                                                 │
│  ├── Agent Gateway   /api/v1/agent/ws      (WebSocket, agent 主动外连)           │
│  ├── UI Stream       /api/v1/jobs/{id}/logs/stream (SSE)                         │
│  ├── Scheduler       (asyncio task)                                              │
│  ├── Event Detector  (规则引擎, 消费 metrics/logs)                                │
│  ├── Rollup Worker   (metrics 降采样与 retention)                                │
│  └── SQLite (WAL)    ~/.gpuctl/server/gpuctl.db                                  │
│                                                                                  │
│  gpuctl-mcp (独立进程, streamable HTTP / stdio) —— server 的 Agent 适配器         │
│  web/ (React SPA, 构建后由 gpuctl-server 静态托管)                                │
└───────────────────────────────────┬─────────────────────────────────────────────┘
                                    │ WebSocket 长连接 (agent → server, NAT 友好)
┌───────────────────────────────────▼────────────────── GPU 主机 ──────────────────┐
│  gpuctl-agent (asyncio 常驻进程, systemd user service)                            │
│  ├── NodeMonitor        NVML + psutil                                             │
│  ├── Runner             ProcessRunner（默认）/ DockerRunner（可选）               │
│  ├── LogCollector       stdout/stderr → 本地文件 + WS 批量上报                    │
│  ├── TBAdapter          tail TensorBoard event 文件                               │
│  ├── CheckpointWatcher  输出目录监视（防抖 + 指纹）                               │
│  └── SpoolBuffer        断线时 jsonl 本地缓冲，重连回放                           │
│                                                                                  │
│  用户训练进程  python train.py  (+ 可选 gpuctl-sdk)                               │
└──────────────────────────────────────────────────────────────────────────────────┘

关键架构决策

Section titled “关键架构决策”
  • Agent 单向出站：agent 主动发起 WebSocket 长连接，GPU 机器无需任何入站端口， NAT/防火墙友好；断线自动重连，期间数据进本地 spool，恢复后幂等回放（不丢不重）。
  • SQLite 单文件：无 Kafka/Redis/Postgres。WAL 模式 + synchronous=NORMAL， 指标 raw/rollup 双表，一条命令在线备份。个人规模下这是特性而非妥协。
  • MCP 是独立适配器进程：gpuctl-mcp 不依赖 server/agent 包，经 REST 调用 server。 fastmcp/mcp 版本断裂不会波及控制面本体（设计文档 §15）。
  • 语义层无 LLM：诊断/对比/推荐是纯 Python 规则与统计函数，REST 和 MCP 只是薄暴露层。 LLM 推理留给调用方 Agent，平台负责把十万条 metric point 压成语义结论。
  • Web UI 由 server 托管：FastAPI 直接挂载 web/dist，与 REST 同源同端口（默认 8600）， 不需要独立前端服务。

代码结构（uv workspace monorepo）

Section titled “代码结构（uv workspace monorepo）”
GPUPlane/
├── packages/
│   ├── common/    gpuctl-common    # Pydantic 协议模型 / ID 生成 / 常量（零重依赖）
│   ├── sdk/       gpuctl-sdk       # 训练侧 SDK（仅 httpx）
│   ├── agent/     gpuctl-agent     # NodeMonitor / Runner / TBAdapter / CkptWatcher
│   ├── server/    gpuctl-server    # FastAPI + Scheduler + EventDetector
│   ├── mcp/       gpuctl-mcp       # MCP 适配器（fastmcp 钉版）
│   ├── cli/       gpuctl           # typer CLI
│   └── tbreader/                   # TensorBoard event 解析
├── web/             # React + Vite + Tailwind v4 + uPlot
├── deploy/systemd/  # user service 单元
├── docs/            # 设计文档（本站 archive 区的来源）
├── examples/        # 示例训练项目（mnist 等）
└── tests/           # pytest（asyncio_mode=auto）

包依赖方向：common ← sdk / agent / server / cli / mcp。 server 不依赖 agent，agent 不依赖 server——两者只通过协议模型（common）通信。

设计红线

Section titled “设计红线”
  • 训练代码零侵入：python train.py 永远独立可跑，SDK 完全可选。
  • 保持裸进程 + SQLite：不引入容器编排、队列服务、云 SDK。
  • 不做多租户：单用户多 token，命令注入防护不在威胁模型内（使用者即拥有者）。

延伸阅读

Section titled “延伸阅读”