GPUPlane

Plano de control de entrenamiento nativo para agentes, pensado para entornos GPU personales y de pequeña escala. Plano de control para entrenamiento de GPU personal: cola y programación de tareas, métricas/registros en tiempo real, registro de checkpoints, diagnóstico de eventos — diseñado para agentes (MCP) y navegadores, sin depender de SSH + tmux + mirar la loss a ojo.

Sitio de documentación del producto: https://ericyuan2007.github.io/GPUPlane/ (inicio rápido / guías / referencia de herramientas MCP); Los documentos de diseño están en docs/ (investigación de producto / diseño de producto / diseño de sistema / hoja de ruta MVP), y también se pueden leer en el archivo de documentos de diseño del sitio de documentación.

Características (v0.1)

• Cero intrusión en el código de entrenamiento: python train.py siempre se puede ejecutar de forma independiente; GPUPlane solo se encarga de la gestión de procesos y la observación, el SDK es completamente opcional y nunca lanza excepciones al proceso de entrenamiento.

• Programación de slots GPU: asignación exclusiva por tarjeta (sin adivinar disponibilidad por uso), cola de prioridad, reintento automático ante fallos (excepto OOM), inyección automática de CUDA_VISIBLE_DEVICES.

• Integración de métricas en tres niveles: tail en tiempo real del directorio de TensorBoard (L1, cero cambios), reporte directo vía SDK (L2, from gpuctl import run), métricas de sistema NVML (L3).

• Registros: volcado completo del agente en disco + últimas 2000 líneas en el servidor + flujo SSE en tiempo real, gpuctl logs -f para seguimiento directo.

• Detección de checkpoints: escaneo con debounce del directorio, asociación con la mejor métrica por step.

• Capa semántica de eventos: LOSS_NAN / OOM / DISK_LOW / eventos de ciclo de vida, determinación determinista mediante motor de reglas.

• SQLite de archivo único: sin Kafka/Redis/Postgres, modo WAL, copia de seguridad en línea con un solo comando.

• Resiliencia offline: spool local en jsonl del agente, reproducción tras reconexión; cursor del servidor con deduplicación idempotente, sin pérdidas ni duplicados al reiniciar el agente.

Related MCP server: Train in Silence

Características (v0.2, aceptadas)

• Gestión de experimentos: CRUD de Project/Experiment y agrupación de runs; página de Experiments en la Web UI + vista de comparación de runs (superposición de métricas de múltiples runs, ordenación por best).

• Bucle de evaluación: POST /checkpoints/{id}/evaluations encola un job EVALUATE (hereda el working_dir/recursos del job de entrenamiento) → los resultados se vuelven a adjuntar → GET /checkpoints:recommend recomienda checkpoint según la métrica primaria.

• Reglas de eventos completas: LOSS_SPIKE / OVERFITTING_SUSPECTED / GPU_UNDERUTILIZED / DISK_LOW, ventana deslizante en proceso + debounce.

• Reintento con clasificación de fallos: OOM / EXIT_CODE / DISPATCH_FAILED no se reintentan automáticamente, el resto se reprograma según max_attempts.

• DockerRunner: misma semántica que ProcessRunner (registros/código de salida/slots), inyección con --gpus, cancelación con docker kill.

• Extrapolación de eventos: configuración de webhooks ntfy/Bark en server.yaml (filtro por severity/type, best-effort); gpuctl event-hook despierta scripts locales con el flujo de eventos.

• Callbacks de frameworks: gpuctl.callbacks ofrece envoltorios ligeros para Lightning / HF Trainer, importación opcional sin dependencias.

• UI de MetricDefinition: edición visual de direction y primary global/project/experiment; orden de resolución experiment → project → global, impulsa la recomendación de checkpoints.

Características (v0.3, aceptadas)

• Agent-native (MCP): gpuctl-mcp es un proceso/paquete independiente (fastmcp 3.4.7 fijado) que expone 21 herramientas — 11 observe + 5 control + 5 semantic; núcleo stateless con HTTP streamable. Si falla, no afecta al servidor (design §15).

• Capa semántica (sin LLM): diagnose_run / compare_runs / compare_checkpoints / get_best_checkpoint / explain_failure, cinco funciones de Python puro (reglas + estadística), REST y MCP son capas de exposición delgadas; cada una devuelve next_actions para guiar el siguiente paso del agente, sin necesidad de polling.

• 3 Skills: run-experiment / monitor-experiment / analyze-results (.claude/skills/gpu-training/), frontmatter de 6 campos, allowed-tools preautoriza las herramientas MCP, codifican el bucle de experimentos "enviar→monitorear→comparar→recomendar".

• Empaquetado de plugin: .claude-plugin/plugin.json (MCP stdio + skills + hooks distribuibles); .mcp.json (http, gitignored).

• AGENTS.md: reglas de agente a nivel de repositorio (canonical, espejo de CLAUDE.md) — líneas rojas de proceso desnudo + SQLite, bucle de experimentos, convenciones de metric/job/ckpt, runbook de OOM.

• Niveles de dominio de lectura/escritura: GET /auth/whoami expone {name, scope, can_write}; las operaciones de escritura (submit/cancel/retry/evaluate) requieren token con write-scope, los tokens de solo lectura devuelven WriteScopeError.

Aceptación: el agente, solo con lenguaje natural + MCP y sin ninguna interacción manual con la plataforma, completa el bucle completo "enviar entrenamiento → monitorear → comparar → recomendar". Ver docs/08-v0.3-acceptance.md.

Inicio rápido (despliegue estándar en 30 minutos)

Entorno: 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 登录

Importar experimentos históricos (eventos TB + checkpoints → run IMPORTED):

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

Instalación en redes restringidas/sin conexión

Las dependencias son solo unas 50 wheels pequeñas (torch no es dependencia de la plataforma, se usa el entorno existente de la máquina de entrenamiento). En redes restringidas, descargar previamente en una máquina con internet y copiar a la máquina objetivo para instalación sin conexión:

# 在能上网的机器（如 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

Dos topologías de despliegue

Misma máquina (recomendado para empezar): server + agent se ejecutan en la máquina GPU, el navegador/CLI del portátil accede vía LAN (host: 0.0.0.0 en server.yaml, autenticación con token).

Separada: el server se ejecuta en una máquina ligera siempre encendida (incluso Mac mini/NAS), el agent se ejecuta en cada máquina GPU, server_url en agent.yaml apunta al ws://<ip>:8600 del server. El agent establece una conexión saliente de larga duración, las máquinas GPU no necesitan ningún puerto de entrada, reconexión automática ante desconexión + reproducción del spool.

Envío de eventos al móvil / hooks locales (v0.2)

Añadir webhook en ~/.gpuctl/server.yaml (ejemplo con ntfy; Bark usa kind: bark + URL del dispositivo):

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

Automatización local (ejecutar un comando en la máquina actual cuando llega un evento, por ejemplo despertar un agente local):

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

Agent-native: impulsar el bucle de experimentos con lenguaje natural (v0.3)

gpuctl-mcp es un proceso adaptador independiente (no depende de server/agent) que expone el plano de control como 21 herramientas MCP. Una vez configurado, Claude Code (o cualquier cliente MCP) completa "enviar entrenamiento → monitorear anomalías → comparar checkpoints → dar recomendaciones" con lenguaje natural, sin tocar Web/CLI en todo el proceso:

# 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"

Niveles de dominio de lectura/escritura: con token de solo lectura, submit_job/cancel_job/retry_job/evaluate_checkpoint/set_primary_metric devuelven WriteScopeError. Los tres skills (.claude/skills/gpu-training/) codifican el bucle de experimentos y preautorizan las herramientas MCP; ver docs/08-v0.3-acceptance.md.

SDK del lado de entrenamiento (opcional)

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()

Dentro de los jobs despachados por la plataforma, configuración cero (inyección automática de env); fuera de la plataforma, ejecución directa registra automáticamente un run con source=sdk; sin server, degrada silenciosamente a jsonl local (~/.gpuctl/spool/), el comportamiento del script de entrenamiento no cambia en absoluto.

Arquitectura

┌────────────┐   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/ (skills de agente) + .claude-plugin/. packages/mcp es un proceso adaptador independiente, no depende de server/agent.

Operaciones comunes

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

El runner Docker es una capacidad opcional; el runner Process sigue siendo el predeterminado. Antes de usar contenedores GPU, el host del agente debe instalar primero el Container Toolkit según la guía oficial de NVIDIA y escribir el runtime en la configuración de Docker:

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

En WSL2 también se debe confirmar primero que la transferencia del host funciona correctamente (nvidia-smi muestra la GPU); el Toolkit solo se encarga de exponer la GPU ya transferida al contenedor, no puede sustituir al driver de Windows/WSL.

Líneas rojas de diseño (leer antes de contribuir)

1. Independencia del código de entrenamiento: python train.py debe estar siempre disponible fuera de la plataforma.

2. Telemetría best-effort: cualquier fallo de reporte solo se guarda en el búfer local, nunca lanza excepciones al proceso de entrenamiento.

3. El runner Process es ciudadano de primera clase, no se obliga a Docker/Git.

4. La programación de GPU es por slots exclusivos, nunca se determina disponibilidad por uso.

5. Job ≠ Run: Job es la unidad de programación, Run es la unidad semántica de entrenamiento (un Run por attempt).

6. SQLite + sin cola de mensajes; server de un solo worker (el pub/sub en memoria es intencional).

Licencia

GPUPlane está licenciado bajo la Apache License 2.0. La información de atribución está en NOTICE.