# 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: ``` --- ## Endpoints ### GET /infra/vast/status Gibt den aktuellen Status der vast.ai Instanz zurück. **Response (200):** ```json { "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:** ```json { "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):** ```json { "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:** ```json {} ``` **Response (200):** ```json { "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):** ```json { "status": "recorded", "last_activity": "2024-01-15T10:30:00Z" } ``` --- ### GET /infra/vast/costs Gibt Kosten-Statistiken zurück. **Response (200):** ```json { "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):** ```json [ { "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:** ```bash VAST_AUTO_SHUTDOWN=true # Feature aktivieren VAST_AUTO_SHUTDOWN_MINUTES=30 # Timeout in Minuten ``` --- ## Konfiguration Umgebungsvariablen in `.env`: ```bash # 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: ```bash # 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 ```bash # .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