From 6c85aaf7a1c977573354e9701e203d8fcf6a30f9 Mon Sep 17 00:00:00 2001 From: Dominic Ballenthin Date: Thu, 29 Jan 2026 02:14:16 +0100 Subject: [PATCH] Update German README with new features: multi-model support, CPU/GPU toggle, persistent volumes --- README.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 133 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 92ed2b3..a0162be 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,15 @@ Eine lokale Whisper-API mit GPU-Beschleunigung und Web-Admin-Interface für die - **OpenAI-kompatible API** - Drop-in Ersatz für OpenAI Whisper API - **GPU-beschleunigt** - Nutzt NVIDIA GPUs (CUDA) für schnelle Transkription +- **CPU Fallback** - Automatischer Wechsel zu CPU wenn keine GPU verfügbar +- **Multi-Model Support** - Unterstützung für alle Whisper Modelle (tiny bis large-v3) +- **Model Management** - Modelle herunterladen, wechseln und löschen via Admin Panel - **Default: large-v3** - Beste Qualität mit deiner RTX 3090 -- **Web-Admin-Interface** - API-Key Management und Statistiken unter `/admin` -- **API-Key Authentifizierung** - Sichere Zugriffskontrolle +- **Web-Admin-Interface** - API-Key Management, Model Management und Statistiken unter `/admin` +- **API-Key Authentifizierung** - Sichere Zugriffskontrolle (Environment + Datenbank) - **Cross-Platform** - Docker-basiert, läuft auf Windows und Linux - **Automatische Cleanup** - Logs nach 30 Tagen automatisch gelöscht +- **Persistente Speicherung** - Modelle und Daten in Docker Volumes ## Architektur @@ -139,9 +143,62 @@ curl -X POST http://localhost:8000/v1/audio/transcriptions \ Liste verfügbarer Modelle. +#### GET /v1/available-models + +Liste aller verfügbaren Whisper Modelle mit Download-Status. + +**Response:** +```json +{ + "models": [ + { + "name": "large-v3", + "size": "2.88 GB", + "description": "Best accuracy", + "is_downloaded": true, + "is_active": true + } + ] +} +``` + +#### GET /v1/model-status + +Aktueller Download-Status des Modells. + +**Response:** +```json +{ + "name": "large-v3", + "loaded": true, + "is_downloading": false, + "download_percentage": 100, + "status_message": "Model loaded successfully" +} +``` + +#### POST /v1/switch-model + +Zu einem anderen Modell wechseln. + +**Request:** +```bash +curl -X POST http://localhost:8000/v1/switch-model \ + -H "Authorization: Bearer sk-dein-api-key" \ + -F "model=base" +``` + +#### POST /v1/reload-model + +Aktuelles Modell neu herunterladen. + +#### DELETE /v1/delete-model/{model_name} + +Ein heruntergeladenes Modell löschen. + #### GET /health -Health-Check mit GPU-Status. +Health-Check mit GPU- und Model-Status. **Response:** ```json @@ -169,8 +226,13 @@ Das Web-Interface ist erreichbar unter: `http://localhost:8000/admin` ### Features -- **Dashboard:** Übersicht über Nutzung, Performance-Statistiken +- **Dashboard:** Übersicht über Nutzung, Performance-Statistiken, **Model Download Status** - **API-Keys:** Verwalten (erstellen, deaktivieren, löschen) +- **Models:** + - Alle Whisper Modelle verwalten (tiny, base, small, medium, large-v1, large-v2, large-v3) + - Modelle herunterladen, aktivieren und löschen + - **CPU/GPU Mode Toggle** + - Model neu herunterladen - **Logs:** Detaillierte Transkriptions-Logs mit Filter ## Konfiguration @@ -209,17 +271,23 @@ services: environment: - PORT=8000 # Änderbar - WHISPER_MODEL=large-v3 + - WHISPER_DEVICE=cuda # oder 'cpu' für CPU-Modus volumes: - - ./models:/app/models # Persistiert Modelle - - ./data:/app/data # SQLite Datenbank - - ./uploads:/app/uploads # Temporäre Uploads + - whisper_models:/app/models # Persistiert Modelle (Named Volume) + - whisper_data:/app/data # SQLite Datenbank + - whisper_uploads:/app/uploads # Temporäre Uploads deploy: resources: reservations: devices: - driver: nvidia - count: 1 + count: all capabilities: [gpu] + +volumes: + whisper_models: + whisper_data: + whisper_uploads: ``` ## Migration zu Linux @@ -271,6 +339,22 @@ def transcribe_audio(audio_path): return response.json()["text"] ``` +## Verfügbare Modelle + +| Modell | Größe | Beschreibung | Geschwindigkeit | Genauigkeit | +|--------|-------|--------------|-----------------|-------------| +| **tiny** | 39 MB | Schnellste, niedrigste Qualität | Sehr schnell | Niedrig | +| **base** | 74 MB | Gut für Tests | Schnell | Mittel | +| **small** | 244 MB | Balance Speed/Qualität | Mittel | Gut | +| **medium** | 769 MB | Gute Genauigkeit | Langsam | Sehr gut | +| **large-v2** | 2.87 GB | Höhere Genauigkeit | Sehr langsam | Exzellent | +| **large-v3** | 2.88 GB | Beste Genauigkeit (Default) | Sehr langsam | Exzellent | + +**Empfehlungen:** +- **Entwicklung/Tests:** `base` oder `small` +- **Produktion:** `large-v3` (mit RTX 3090) +- **CPU-Modus:** `small` oder `medium` + ## Performance Mit RTX 3090 und large-v3: @@ -278,24 +362,45 @@ Mit RTX 3090 und large-v3: - **VRAM-Nutzung:** ~10 GB - **Batch-Verarbeitung:** Möglich für parallele Requests +Mit CPU und small: +- **1 Minute Audio:** ~30-60 Sekunden Verarbeitungszeit +- **RAM-Nutzung:** ~1 GB + ## Troubleshooting -### GPU nicht erkannt +### GPU nicht erkannt / Automatischer CPU Fallback + +Falls keine GPU erkannt wird, schaltet die API automatisch auf CPU-Modus um: ```bash # NVIDIA Container Toolkit prüfen docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi -# Logs prüfen +# Logs prüfen - sollte "GPU not available, falling back to CPU mode" zeigen docker-compose logs whisper-api ``` +**Manueller Wechsel:** Über Admin Panel (`/admin/models`) oder API: +```bash +curl -X POST http://localhost:8000/v1/switch-device \ + -H "Authorization: Bearer sk-dein-api-key" \ + -F "device=cpu" +``` + +### Modell-Download Status anzeigen + +- **Dashboard:** Zeigt Download-Fortschritt in Echtzeit +- **API:** `GET /v1/model-status` für aktuellen Status +- **Logs:** `docker-compose logs -f` zeigt Download-Progress + ### Modell-Download langsam ```bash -# Manuelles Downloaden möglich -mkdir -p models -# Modelle werden von HuggingFace heruntergeladen +# Im Admin Panel unter Models ein kleineres Modell wählen (z.B. base, small) +# Oder via API: +curl -X POST http://localhost:8000/v1/switch-model \ + -H "Authorization: Bearer sk-dein-api-key" \ + -F "model=base" ``` ### Port belegt @@ -307,14 +412,25 @@ PORT=8001 ## Backup -Wichtige Daten: -- `./data/` - SQLite Datenbank (API-Keys, Logs) -- `./models/` - Heruntergeladene Whisper-Modelle +Wichtige Daten (Docker Named Volumes): +- `whisper_data` - SQLite Datenbank (API-Keys, Logs) +- `whisper_models` - Heruntergeladene Whisper-Modelle - `./.env` - Konfiguration ```bash # Backup erstellen -tar -czvf whisper-api-backup.tar.gz data/ models/ .env +docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "tar czf /backup/whisper-api-backup.tar.gz -C / data models" + +# Oder komplettes Backup inkl. .env +cp .env .env.backup +docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine tar czf /backup/whisper-api-full-backup.tar.gz -C / data models +``` + +### Backup wiederherstellen + +```bash +# Backup extrahieren +docker run --rm -v whisper-api_whisper_data:/data -v whisper-api_whisper_models:/models -v $(pwd):/backup alpine sh -c "cd / && tar xzf /backup/whisper-api-backup.tar.gz" ``` ## Lizenz