breakpilot-pwa/backend/docs/llm-platform/api/vast-ai-api.md

vast.ai GPU Infrastructure API Dokumentation

Version: 0.1.0 Base URL: /infra/vast

---

Übersicht

Die vast.ai Infrastructure API ermöglicht die Steuerung von GPU-Instanzen direkt aus dem Admin Panel. Features:

• Start/Stop: GPU-Instanz ein- und ausschalten
• Auto-Shutdown: Automatisches Stoppen bei Inaktivität (Kostenkontrolle)
• Kosten-Tracking: Laufzeit und Kosten pro Session
• Audit-Log: Protokollierung aller Aktionen

---

Authentifizierung

Alle Endpoints erfordern den CONTROL_API_KEY im Header:

X-API-Key: <CONTROL_API_KEY>

---

Endpoints

GET /infra/vast/status

Gibt den aktuellen Status der vast.ai Instanz zurück.

Response (200):

{
  "instance_id": 12345,
  "status": "running",
  "gpu_name": "RTX 3090",
  "dph_total": 0.45,
  "endpoint_base_url": "http://10.0.0.1:8001",
  "last_activity": "2024-01-15T10:30:00Z",
  "auto_shutdown_in_minutes": 25,
  "total_runtime_hours": 2.5,
  "total_cost_usd": 1.12,
  "message": null
}

Status-Werte:

Status	Beschreibung
running	Instanz läuft
stopped	Instanz gestoppt (Disk bleibt)
exited	Instanz beendet
loading	Instanz startet
scheduling	Wartet auf GPU-Zuweisung
creating	Wird erstellt
unconfigured	VAST_API_KEY nicht gesetzt
not_found	Instance ID nicht gefunden

---

POST /infra/vast/power/on

Startet die vast.ai Instanz.

Request Body:

{
  "wait_for_health": true,
  "health_path": "/health",
  "health_port": 8001
}

Parameter:

Parameter	Typ	Default	Beschreibung
wait_for_health	boolean	true	Warten bis LLM-Server erreichbar
health_path	string	"/health"	Health-Check Endpoint
health_port	integer	8001	Port für Health-Check

Response (200):

{
  "status": "running",
  "instance_id": 12345,
  "endpoint_base_url": "http://10.0.0.1:8001",
  "health_url": "http://10.0.0.1:8001/health",
  "message": "Instance running and healthy"
}

Errors:

Code	Beschreibung
401	Unauthorized (falscher API Key)
500	VAST_API_KEY oder VAST_INSTANCE_ID nicht konfiguriert
502	vast.ai API Fehler
504	Health-Check Timeout

---

POST /infra/vast/power/off

Stoppt die vast.ai Instanz (Disk bleibt erhalten).

Request Body:

{}

Response (200):

{
  "status": "stopped",
  "session_runtime_minutes": 45.5,
  "session_cost_usd": 0.34,
  "message": "Instance stopped. Session: 45.5 min, $0.340"
}

---

POST /infra/vast/activity

Zeichnet Aktivität auf und verzögert den Auto-Shutdown Timer.

Verwendung: Sollte vom LLM Gateway bei jedem Request aufgerufen werden.

Response (200):

{
  "status": "recorded",
  "last_activity": "2024-01-15T10:30:00Z"
}

---

GET /infra/vast/costs

Gibt Kosten-Statistiken zurück.

Response (200):

{
  "total_runtime_hours": 12.5,
  "total_cost_usd": 5.62,
  "sessions_count": 5,
  "avg_session_minutes": 150.0
}

---

GET /infra/vast/audit

Gibt die letzten Audit-Log Einträge zurück.

Query Parameter:

Parameter	Typ	Default	Beschreibung
limit	integer	50	Max. Anzahl Einträge

Response (200):

[
  {
    "ts": "2024-01-15T10:30:00Z",
    "event": "power_on_complete",
    "actor": "system",
    "meta": {
      "instance_id": 12345,
      "endpoint": "http://10.0.0.1:8001"
    }
  },
  {
    "ts": "2024-01-15T09:00:00Z",
    "event": "auto_shutdown",
    "actor": "system",
    "meta": {
      "inactive_minutes": 30.5
    }
  }
]

Event-Typen:

Event	Beschreibung
power_on_requested	Start angefordert
power_on_complete	Start abgeschlossen
power_on_health_timeout	Health-Check fehlgeschlagen
power_off_requested	Stop angefordert
power_off_complete	Stop abgeschlossen
auto_shutdown	Automatischer Stop wegen Inaktivität
auto_shutdown_complete	Auto-Stop abgeschlossen

---

Auto-Shutdown

Der Auto-Shutdown Mechanismus stoppt die Instanz automatisch bei Inaktivität:

1. Bei jedem LLM-Request wird /activity aufgerufen
2. Ein Hintergrund-Task prüft alle 60s die letzte Aktivität
3. Nach VAST_AUTO_SHUTDOWN_MINUTES ohne Aktivität wird gestoppt
4. Session-Kosten werden berechnet und geloggt

Konfiguration:

VAST_AUTO_SHUTDOWN=true           # Feature aktivieren
VAST_AUTO_SHUTDOWN_MINUTES=30     # Timeout in Minuten

---

Konfiguration

Umgebungsvariablen in .env:

# vast.ai Credentials
VAST_API_KEY=your-vast-api-key          # von https://cloud.vast.ai/cli/
VAST_INSTANCE_ID=12345                   # numerische Instance ID

# Admin-Schutz
CONTROL_API_KEY=your-control-key         # generieren mit: openssl rand -hex 32

# Health Check
VAST_HEALTH_PORT=8001                    # Port auf der Instanz
VAST_HEALTH_PATH=/health                 # Health-Endpoint
VAST_WAIT_TIMEOUT_S=600                  # Timeout beim Start (10 min)

# Auto-Shutdown
VAST_AUTO_SHUTDOWN=true
VAST_AUTO_SHUTDOWN_MINUTES=30

# State Persistence (optional)
VAST_STATE_PATH=./vast_state.json
VAST_AUDIT_PATH=./vast_audit.log

---

Architektur

┌─────────────────────────────────────────────────────────────────┐
│                      Admin Panel (Browser)                       │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  GPU Infra Tab                                          │   │
│   │  [Start] [Stop] [Refresh]   Status: Running             │   │
│   │  GPU: RTX 3090   Cost: $0.45/h   Session: 25 min        │   │
│   │  Auto-Shutdown in: 5 min                                │   │
│   └─────────────────────────────────────────────────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Breakpilot Backend                            │
│   ┌───────────────────┐   ┌───────────────────┐                 │
│   │  /infra/vast/*    │   │  Auto-Shutdown    │                 │
│   │  (FastAPI Router) │   │  Background Task  │                 │
│   └─────────┬─────────┘   └─────────┬─────────┘                 │
│             │                       │                            │
│             ▼                       ▼                            │
│   ┌─────────────────────────────────────────────┐               │
│   │           VastAIClient                       │               │
│   │   (REST API zu vast.ai Console)             │               │
│   └─────────────────────────────────────────────┘               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                   vast.ai Cloud API                              │
│               https://console.vast.ai/api/v0/                    │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    vast.ai GPU Instance                          │
│   ┌───────────────────────────────────────────────────────┐     │
│   │  Docker Container: vLLM                               │     │
│   │  - Model: Mistral-7B-Instruct                        │     │
│   │  - Port 8000: /v1/chat/completions                   │     │
│   │  - Port 8001: /health (nginx proxy)                  │     │
│   └───────────────────────────────────────────────────────┘     │
│   GPU: RTX 3090 (24GB VRAM)                                     │
└─────────────────────────────────────────────────────────────────┘

---

vast.ai Instance Setup

1. Instance buchen

• Typ: On-Demand (nicht Contract)
• GPU: RTX 3090 (24GB) oder RTX 4090
• RAM: >= 32 GB
• Disk: >= 150 GB
• Interruptible: Nein (Non-interruptible)

2. vLLM mit systemd autostart

Auf der vast.ai Instanz:

# Docker Compose erstellen
mkdir -p ~/llm-stack
cd ~/llm-stack

# docker-compose.yml und health-nginx.conf erstellen
# (siehe vast.ai Implementierung.docx)

# Systemd Service erstellen
sudo tee /etc/systemd/system/llm-stack.service > /dev/null <<'EOF'
[Unit]
Description=LLM Stack via Docker Compose
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/ubuntu/llm-stack
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable llm-stack.service
sudo systemctl start llm-stack.service

3. Backend konfigurieren

# .env
VAST_API_KEY=vast_...
VAST_INSTANCE_ID=12345
CONTROL_API_KEY=$(openssl rand -hex 32)

---

Fehlerbehandlung

Fehler	Ursache	Lösung
500: VAST_API_KEY not configured	ENV nicht gesetzt	.env prüfen
502: vast CLI failed	vast.ai API Fehler	Instance ID prüfen
504: Health check timeout	vLLM startet nicht	SSH auf Instanz, Logs prüfen
Instance stuck in scheduling	GPU nicht verfügbar	Andere GPU wählen

---

Kosten-Beispiele

GPU	$/Stunde	1h Test	8h Tag
RTX 3090	~$0.45	$0.45	$3.60
RTX 4090	~$0.75	$0.75	$6.00

Mit Auto-Shutdown (30 min):

• Vergessen auszuschalten: max. $0.23 (3090) bzw. $0.38 (4090) extra