GPUPlane

Agent-native Trainings-Kontrollplan für private & kleine GPU-Umgebungen. Die Steuerungsebene für privates GPU-Training: Auftragswarteschlange und Scheduling, Echtzeitmetriken/Logs, Checkpoint-Registrierung, Ereignisdiagnose – gebaut für Agenten (MCP) und Browser, nicht mehr abhängig von SSH + tmux und dem Beobachten der Loss-Kurve mit bloßem Auge.

Produktdokumentationseite: https://ericyuan2007.github.io/GPUPlane/ (Schnellstart / Anleitungen / MCP-Werkzeugreferenz); Systemdokumentation in docs/ (Produktrecherche / Produktdesign / Systemdesign / MVP-Fahrplan), auch lesbar unter dem Archiv der Systemdokumente der Dokumentationsseite.

Funktionen (v0.1)

• Null invasive Integration für Trainingscode: python train.py bleibt jederzeit eigenständig ausführbar; GPUPlane übernimmt nur Prozessverwaltung und Beobachtung. Das SDK ist vollständig optional und wirft niemals eine Ausnahme in den Trainingsprozess.

• GPU-Slot-Planung: exklusive Zuweisung pro GPU-Karte (keine Ableitung von freien Slots anhand der Auslastung), Prioritätswarteschlange, automatische Wiederholung bei Fehlern (außer OOM), automatische Injektion von CUDA_VISIBLE_DEVICES.

• Dreistufige Metrikanbindung: Live-Tail auf TensorBoard-Verzeichnisse (L1, keine Codeänderung), SDK-Direktmeldungen (L2, from gpuctl import run), NVML-Systemmetriken (L3).

• Logs: vollständige Festplatten-Protokollierung im Agenten + letzte 2000 Zeilen am Server + SSE-Stream in Echtzeit, mit gpuctl logs -f direkt verfolgbar.

• Checkpoint-Erkennung: überwachte Verzeichnisse mit Entprell-Scanning, Zuordnung von Bestmetriken zum jeweiligen Schritt.

• Events-Sementik: LOSS_NAN / OOM / DISK_LOW / Lebenszyklus-Ereignisse, deterministische Bewertung durch die Regelengine.

• SQLite als Einzeldatei: kein Kafka/Redis/Postgres, WAL-Modus, Online-Backup mit einem einzigen Befehl.

• Offline-Resil: lokaler JSONL-Spool beim Agent, Wiedergabe nach Verbindungsabbruch; serverseitiger Cursor mit idempotenter Deduplizierung – nach Agent-Neustart weder Verluste noch Duplikate.

Related MCP server: Train in Silence

Funktionen (v0.2, freigegeben)

• Experimente-Verwaltung: CRUD für Project/Experiment und Gruppierung von Runs; Experiments-Seite in der Web-UI + Run-Vergleichsansicht (Metriken mehrer Runs überlegen, Beitrag über Sortierung nach Bestwert).

• Geschlossener Evaluierungskreislauf: POST /checkpoints/{id}/evaluations protokolliert einen EVALUATE-Auftrag (erbt working_dir/Ressourcen des Trainingsjobs) → Ergebnis wird zurückgeschrieben → GET /checkpoints:recommend empfiehlt Checkpoints anhand der primären Metrik.

• Vollständige Ereignisregeln: LOSS_SPIKE / OVERFITTING_SUSPECTED / GPU_UNDERUTILIZED / DISK_LOW, mit rollierendem Fenster im Prozess und Debouncing.

• Wiederholung nach Fehlertyp: OOM / EXIT_CODE / DISPATCH_FAILED nie automatisch wiederholt, alle anderen Fehler werden nach max_attempts neu eingereiht.

• DockerRunner: gleiche Semantik wie ProcessRunner (Logs/Exitcodes/Slots), Injektion von --Generate, region via docker kill.

• Ereignisweiterleitung: server.yaml für ntfy/Bark-Webhooks (Filter nach severity/typ, best-effort); gpuctl event-hook weckt ein lokales Skript durch den Ereignis-Stream.

• Framework-Callbacks: gpuctl.callbacks für Lightning / HF Trainer, dünne Wrapper, optional importierbar, keine Abhängigkeiten.

• MetricDefinition-UI: sichtbare Bearbeitung von Richtung und primärer Metrik (global/project/experiment); Shapesosungsunterschied: experiment → project → global, steuert Checkpoint-Empfehlung.

Funktionen (v0.3, freigegeben)

• Agent-native (MCP): gpuctl-mcp als unabhängiger Prozess/Paket (fastmcp 3.4.7 gepinnt) exponoughs 21 Werkzeuge – 11 observe + 5 control + 5 semantic; streamable HTTP, statistischer Kern. Ein Ausfall beeinträchtigt den Server nach Design §15 nicht.

• Semantische Schicht (ohne LLM): diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure – fünf pure Python-Funktionen (Regeln + Statistik), Unit REST und MCP sind nur dünne Expositionsschichten; jede Antwort enthält next_actions, um den Agenten ohne Polling zum nächsten Schritt zu führen.

• 3 Skills: run-experiment / monitor-experiment / analyze-results (.claude/skills/gpu-training/), 6 Felder Frontmatter, allowed-tools vorstandard für MCP-Werkzeuge; der Lifecycle „Einreichen → Überwachen → Vergleichen → Empfehlen“ codiert darin.

• Plugin-Bündelung: .claude-plugin/plugin.json (stdio-MCP + Skills + Hooks verteilbar); .mcp.json (http, gitignored).

• AGENTS.md: Repo-weite Agent-Regeln (kanonisch, in CLAUDE.md gespiegelt) – blank-Process + SQLite als rote Linien, Experiment-Lebenszyklus, Metrik/Job/Checkpoint-Konventionen, OOM-Runbook.

• Lese-Schreib-Abstufung: GET /auth/whoami liefert {name, scope, can_write}, Schreiboperationen (submit/cancel/retry/evaluate) verlangen ein Token mit write-Bereich; schreibgeschützte Token erhalten WriteScopeError.

Abnahme: Der Agent bewältigt den gesamten Zyklus „Training senden → überwachen → vergleichen → empfehlen“, allein mit natürlicher Sprache und MCP – ohne Handplattform-Interaktion. Siehe docs/08-v0.3-acceptance.md.

Schnellstart (Standard-Deployment in 30 Minuten)

Umgebung: Python ≥3.12, uv.

git clone <repo> && cd GPUPlane
uv sync                          # 安装全部组件（server/agent/cli/sdk）

# 1. 启动 server（GPU 机器上；首启自动生成 admin token 写入 ~/.gpuctl/server.yaml）
uv run gpuctl-server

# 2. 启动 agent（同机；token 从 server.yaml 复制到 ~/.gpuctl/agent.yaml）
uv run gpuctl-agent

# 3. 提交训练（cpu_only 示例先跑通，再上 GPU）
uv run gpuctl job submit -n mnist -g 1 \
  -d "$PWD/examples/mnist" --watch checkpoints \
  -- python train.py --epochs 3

# 注意：-d/--working-dir 按【agent 所在机器】解释，CLI 不做本地改写；
# 从笔记本向远端提交时传远端绝对路径。

# 4. 观测
uv run gpuctl status             # 节点/队列总览
uv run gpuctl job list           # 任务状态
uv run gpuctl logs -f <job-id>   # 实时日志
uv run gpuctl run show <run-id>  # 指标摘要（latest/best/trend）

# 5. Web UI（server 自动托管 web/dist；也可用 GPUCTL_WEB_DIST 指定）
open http://<gpu-host>:8600      # 输入 token 登录

Import vorhandener Experimente (TensorBoard-Events + Checkpoints → Imported Run):

uv run gpuctl import-run ~/experiments/old-run --project legacy

Eingeschränkte/Offline-Netzinstallation

Nur Anzahl wenig kleine Wheels nötig (torch ist keine Abhängigkeit – vorhandene Trainingsumgebung reicht). In Netzwerkumgebungen mit Abschnitten auf einer zugänglichen Maschine vorab laden, auf die Zielmaschine kopieren und offline installieren:

# 在能上网的机器（如 Mac）上，为 Linux x86_64 + py3.12 下载
uv export --format requirements-txt --locked --no-hashes --no-dev -o /tmp/reqs.txt
grep -v '^-e ' /tmp/reqs.txt > /tmp/reqs-clean.txt
uv run --python 3.12 --with pip python -m pip download -r /tmp/reqs-clean.txt hatchling editables \
  --python-version 312 --only-binary=:all: \
  --platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \
  --platform manylinux2014_x86_64 -d ./wheels
rsync -az ./ ./wheels/ gpu-host:~/GPUPlane-wheels/   # 含仓库本体

# 目标机（离线）
cd ~/GPUPlane && uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --no-index --find-links ~/GPUPlane-wheels \
  -r ~/GPUPlane-wheels/reqs-clean.txt hatchling editables
uv pip install --python .venv/bin/python --no-index --no-build-isolation \
  -e ./packages/common -e ./packages/tbreader -e ./packages/sdk \
  -e ./packages/server -e ./packages/agent -e ./packages/cli

Two Zwei-Bereitstellungstopologien

Gleiche Maschine (empfohlener Einstieg): Server und Agent laufen auf GPU-Maschine, Browser und CLI über LAN zugänglich (host: 0.0.0.0 in server.yaml, Token-Authentifizierung).

Getrennte: Server läuft auf einer dauerhaft verfügbaren Leichtmaschine (auch Mac mini/NAS), Agenten auf den einzelnen GPU-Maschinen; agent.yaml zeigt mit server_url auf ws://<ip>:8600 des Servers. Der Agent hält eine reine Ausgangs-Langverbindung, die GPU-Maschinen brauchen keinerlei eingehenden Ports, nach einer Trennung gibt es automatisches Wiederverw.:

Ereignisbenachrichtigung aufs Handy / Lokale Automatisierung (v0.2)

Webhook in ~/.gpuctl/server.yaml (ntfy-Beispiel; Bark mit kind: bark + Geräte-URL):

webhooks:
  - url: "https://ntfy.sh/my-gpu-topic"   # 手机装 ntfy 订阅同一 topic
    kind: ntfy
    min_severity: warning                  # info|warning|critical，低于此不推
    # types: ["OOM", "LOSS_NAN"]           # 可选：只推这些事件类型

Lokale Automatisierung (bei Ereigniseingang einen Befehl auf dem Gerät ausführen, z.B. einen lokalen Agenten aus dem Standby —):

gpuctl event-hook --severity critical -- /path/to/on-event.sh
# 事件经 GPUCTL_EVENT_TYPE/SEVERITY/MESSAGE/RUN_ID/... 环境变量 + stdin JSON 传入

Agent-native: Experiment-Schleife mit natürlicher Sprachsteuerung (v0.2)

gpuctl-mcp ist ein eigenständiger Adapter-Prozess (unabhängig von server/agent) und exponiert die Kontrollellebene als 21 MCP-Werkzeuge. Nach Konfiguration steuert Claude Code (oder ein beliebiger MCP-Client) den Ablauf „Submit training → over monitor anomalies → compare Checkpoints → recommendation“ allein über natürliche Sprache – ohne Web/CLI zu nutzen:

# 1. 起 adapter（独立进程；指向 server，带 write-scope token）
GPUCTL_SERVER_URL=http://127.0.0.1:8600 GPUCTL_MCP_TOKEN=<write-token> \
  gpuctl-mcp serve --port 18602            # streamable HTTP, stateless
# stdio 形态（插件用）：gpuctl-mcp stdio

# 2. 让 Claude Code 发现它（仓库根 .mcp.json，已 gitignore）
cat > .mcp.json <<'JSON'
{ "mcpServers": { "gpuctl": { "type": "http",
  "url": "http://127.0.0.1:18602/mcp",
  "headers": { "Authorization": "Bearer <write-token>" } } } }
JSON

# 3. 自然语言驱动（skill 自动加载，无需手点工具）
claude -p "提交一个 mnist 训练，跑完告诉我结果，再对比最近两次 run 给我最好的 checkpoint"

Lese/Schreib-Schutz: Mit einem read-only Token geben submit_job/cancel_job/retry_job/evaluate_checkpoint/set_primary_metric einen WriteScopeError zurück. Die drei Skills (.claude/skills/gpu-training/) kodieren den Experiment-Zyklus und autorisieren MCP-Werkzeuge; siehe docs/08-v0.3-acceptance.md.

Trainingseite SDK (optional)

from gpuctl import run

run.init(project="qwen-sft", experiment="lr-2e5", config={...})   # 平台 job 内自动 attach，可省略
run.log({"train/loss": loss.item()}, step=step)                   # 有界队列，绝不阻塞/抛错
run.log_checkpoint(path, step=step)                               # 只登记，不搬运文件
run.finish()

In einem via Plattform gestarteten Job ist keinerlei Konfiguration nötig (Env-, Injektion automatisch). Ein außerhalb der Plattform (bare run) wird automatisch als Run mit source=sdk registriert; ohne Server wird still auf einen lokalen jsonl (~/.gpuctl/spool/) zurückgegriffen, das Trainingsskript bleibt unverändert.

Architektur

┌────────────┐   WS (出站)   ┌──────────────┐    REST/SSE    ┌──────────┐
│  Agent(s)  │ ───────────► │    Server    │ ◄────────────  │ CLI/Web  │
│ monitor/   │  heartbeat   │  scheduler   │                │ (同源)   │
│ runner/tb  │  metrics/logs│  SQLite(WAL) │ ◄──── HTTP ─── │ SDK      │
└────────────┘              └──────────────┘                └──────────┘

Monorepo: packages/{common,server,agent,sdk,cli,mcp,tbreader} + web/ + examples/mnist + .claude/skills/ (Agent Skills) + .claude-plugin/. packages/mcp ist ein unabhängiger Adapter-Prozess und benötigt weder server noch agent.

Häufigste Operationen

uv run gpuctl backup             # 在线备份 SQLite 到 <data_dir>/backups/
uv run gpuctl backup-agent       # 在每台 Agent 主机归档完整 job 日志/runtime/spool
# 常驻运行见 deploy/systemd/（user unit + enable-linger）
uv run gpuctl job retry <id>     # 失败任务重新排队
uv run gpuctl job cancel <id>    # SIGTERM → 5s → SIGKILL（整进程组）
uv run pytest tests/ -q          # Python 测试（当前 145 个用例）
cd web && pnpm test:e2e          # 浏览器 smoke（2 个用例）
uv run ruff check . && uv run mypy

Docker-Runner ist ein optional; der Process-Runner bleibt Standard. Vor der Verwendung von GPU-Containern muss auf dem Agent-Host das NVIDIA Container Toolkit installiert und die Runtime in die Docker-Konfiguration aufgenommen werden:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker       # 先确认没有运行中的容器
docker run --rm --gpus all <cuda-image> nvidia-smi

UnterWSL2 sollte zuerst die Host-Stotzübergabe geprüft werden (GPU in nvidia-smi sichtbar); das Container Toolkit setzt lediglich die bereits durchgereichte GPU im Container um—kein Ersatz für den Windows/WSL-Treibz.

5 Design-Leitplanken (vor einem Beitrag lesen)

1. Keepensshofr? Ne, "Trainingscode bleibt Plattform-unabhängig": python train.py muss jederzeit innerhalb und außerhalb des Systems laufen.

2. Telemetrie im Best-Effort-Eindeutig: Berichte, die einmal scheitern, werden nur lokal auf warten und werfen dem Trainingsprozess niemals einen Fehler zu.

3. Requirements mit bestehenden Prozessen (Prozess-Runner ist erste Klasse); Docker/Git werden nicht erzwungen.

4. GPU-Scheduling strikt Slot-basis; Flexierung niemals über die GPU-Auslastung definiert.

5. Job ≠ Run: Job ist die Scheduling-Einheit, Run ist die Training-SM-Einheit (ein Run pro Start-Versuch).

6. SQLite und keine Message-Queue; Server als Ein-Worker-Operation, das In-Memory-Pub/Sub ist bewusst gehalten.

License

GPUPlane steht unter der Apache License 2.0. Weitere Angaben: NOTICE.