456 lines
12 KiB
Markdown
456 lines
12 KiB
Markdown
# Whisper API
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
Eine lokale Whisper-API mit GPU-Beschleunigung und Web-Admin-Interface für die Transkription von Audio-Dateien. OpenAI-kompatible API mit Multi-Model-Support.
|
|
|
|
**🇩🇪 Deutsche Version** | [🇺🇸 English Version](README_EN.md)
|
|
|
|
## Features
|
|
|
|
- **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, 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
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Client/App │────▶│ FastAPI App │────▶│ Whisper GPU │
|
|
│ (Clawdbot etc) │ │ (Port 8000) │ │ (large-v3) │
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────┐
|
|
│ /admin Panel │
|
|
│ - Key Mgmt │
|
|
│ - Dashboard │
|
|
│ - Logs │
|
|
└──────────────────┘
|
|
```
|
|
|
|
## Schnellstart
|
|
|
|
### Voraussetzungen
|
|
|
|
- Docker Desktop (Windows) oder Docker + docker-compose (Linux)
|
|
- NVIDIA GPU mit CUDA-Unterstützung (RTX 3090)
|
|
- NVIDIA Container Toolkit installiert
|
|
|
|
### Installation
|
|
|
|
1. **Repository klonen:**
|
|
```bash
|
|
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
|
|
cd whisper-api
|
|
```
|
|
|
|
2. **Umgebungsvariablen konfigurieren:**
|
|
```bash
|
|
cp .env.example .env
|
|
# Bearbeite .env nach deinen Wünschen
|
|
```
|
|
|
|
3. **Docker-Container starten:**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Erster Start:**
|
|
- Das `large-v3` Modell (~3GB) wird automatisch heruntergeladen
|
|
- Dies kann 5-10 Minuten dauern
|
|
- Status überprüfen: `docker-compose logs -f`
|
|
|
|
### Verifizierung
|
|
|
|
```bash
|
|
# Health-Check
|
|
curl http://localhost:8000/health
|
|
|
|
# API-Info
|
|
curl http://localhost:8000/v1/models
|
|
```
|
|
|
|
## API-Dokumentation
|
|
|
|
### Authentifizierung
|
|
|
|
Alle API-Endpunkte (außer `/health` und `/admin`) benötigen einen API-Key:
|
|
|
|
```bash
|
|
Authorization: Bearer sk-dein-api-key-hier
|
|
```
|
|
|
|
### Endpunkte
|
|
|
|
#### POST /v1/audio/transcriptions
|
|
|
|
Transkribiert eine Audio-Datei.
|
|
|
|
**Request:**
|
|
```bash
|
|
curl -X POST http://localhost:8000/v1/audio/transcriptions \
|
|
-H "Authorization: Bearer sk-dein-api-key" \
|
|
-H "Content-Type: multipart/form-data" \
|
|
-F "file=@/pfad/zur/audio.mp3" \
|
|
-F "model=large-v3" \
|
|
-F "language=de" \
|
|
-F "response_format=json"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"text": "Hallo Welt, das ist ein Test."
|
|
}
|
|
```
|
|
|
|
#### POST /v1/audio/transcriptions (mit Timestamps)
|
|
|
|
**Request:**
|
|
```bash
|
|
curl -X POST http://localhost:8000/v1/audio/transcriptions \
|
|
-H "Authorization: Bearer sk-dein-api-key" \
|
|
-F "file=@audio.mp3" \
|
|
-F "timestamp_granularities[]=word" \
|
|
-F "response_format=verbose_json"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"text": "Hallo Welt",
|
|
"segments": [
|
|
{
|
|
"id": 0,
|
|
"start": 0.0,
|
|
"end": 1.5,
|
|
"text": "Hallo Welt",
|
|
"words": [
|
|
{"word": "Hallo", "start": 0.0, "end": 0.5},
|
|
{"word": "Welt", "start": 0.6, "end": 1.2}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### GET /v1/models
|
|
|
|
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- und Model-Status.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"gpu": {
|
|
"available": true,
|
|
"name": "NVIDIA GeForce RTX 3090",
|
|
"vram_used": "2.1 GB",
|
|
"vram_total": "24.0 GB"
|
|
},
|
|
"model": "large-v3",
|
|
"version": "1.0.0"
|
|
}
|
|
```
|
|
|
|
## Admin-Interface
|
|
|
|
Das Web-Interface ist erreichbar unter: `http://localhost:8000/admin`
|
|
|
|
### Login
|
|
|
|
- **Benutzername:** `admin` (konfigurierbar in `.env`)
|
|
- **Passwort:** `-whisper12510-` (konfigurierbar in `.env`)
|
|
|
|
### Features
|
|
|
|
- **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
|
|
|
|
### .env.example
|
|
|
|
```bash
|
|
# Server
|
|
PORT=8000
|
|
HOST=0.0.0.0
|
|
|
|
# Whisper
|
|
WHISPER_MODEL=large-v3
|
|
WHISPER_DEVICE=cuda
|
|
WHISPER_COMPUTE_TYPE=float16
|
|
|
|
# Authentifizierung
|
|
# Mehrere API-Keys mit Komma trennen
|
|
API_KEYS=sk-dein-erster-key,sk-dein-zweiter-key
|
|
ADMIN_USER=admin
|
|
ADMIN_PASSWORD=-whisper12510-
|
|
|
|
# Daten-Retention (Tage)
|
|
LOG_RETENTION_DAYS=30
|
|
|
|
# Optional: Sentry für Error-Tracking
|
|
# SENTRY_DSN=https://...
|
|
```
|
|
|
|
### Docker-Compose Anpassungen
|
|
|
|
```yaml
|
|
services:
|
|
whisper-api:
|
|
# ...
|
|
environment:
|
|
- PORT=8000 # Änderbar
|
|
- WHISPER_MODEL=large-v3
|
|
- WHISPER_DEVICE=cuda # oder 'cpu' für CPU-Modus
|
|
volumes:
|
|
- 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: all
|
|
capabilities: [gpu]
|
|
|
|
volumes:
|
|
whisper_models:
|
|
whisper_data:
|
|
whisper_uploads:
|
|
```
|
|
|
|
## Migration zu Linux
|
|
|
|
Die Docker-Konfiguration ist plattformunabhängig. Für Linux:
|
|
|
|
1. **NVIDIA Docker installieren:**
|
|
```bash
|
|
# Ubuntu/Debian
|
|
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
|
|
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
|
|
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
|
|
|
|
sudo apt-get update
|
|
sudo apt-get install -y nvidia-docker2
|
|
sudo systemctl restart docker
|
|
```
|
|
|
|
2. **Projekt klonen und starten:**
|
|
```bash
|
|
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
|
|
cd whisper-api
|
|
docker-compose up -d
|
|
```
|
|
|
|
3. **GPU-Passthrough verifizieren:**
|
|
```bash
|
|
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
|
|
```
|
|
|
|
## Integration mit Clawdbot
|
|
|
|
Für die Integration in einen Clawdbot Skill:
|
|
|
|
```python
|
|
import requests
|
|
|
|
API_URL = "http://localhost:8000/v1/audio/transcriptions"
|
|
API_KEY = "sk-dein-api-key"
|
|
|
|
def transcribe_audio(audio_path):
|
|
with open(audio_path, "rb") as f:
|
|
response = requests.post(
|
|
API_URL,
|
|
headers={"Authorization": f"Bearer {API_KEY}"},
|
|
files={"file": f},
|
|
data={"language": "de"}
|
|
)
|
|
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:
|
|
- **1 Minute Audio:** ~3-5 Sekunden Verarbeitungszeit
|
|
- **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 / 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 - 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
|
|
# 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
|
|
|
|
```bash
|
|
# Port in .env ändern
|
|
PORT=8001
|
|
```
|
|
|
|
## Backup
|
|
|
|
Wichtige Daten (Docker Named Volumes):
|
|
- `whisper_data` - SQLite Datenbank (API-Keys, Logs)
|
|
- `whisper_models` - Heruntergeladene Whisper-Modelle
|
|
- `./.env` - Konfiguration
|
|
|
|
```bash
|
|
# Backup erstellen
|
|
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
|
|
|
|
MIT License - Siehe LICENSE Datei
|
|
|
|
## Support
|
|
|
|
Bei Problemen:
|
|
1. Logs prüfen: `docker-compose logs -f`
|
|
2. Health-Check: `curl http://localhost:8000/health`
|
|
3. Issue auf Gitea erstellen
|
|
|
|
---
|
|
|
|
**Erstellt für:** b0rborad @ ragtag.rocks
|
|
**Hardware:** Dual RTX 3090 Setup
|
|
**Zweck:** Clawdbot Skill Integration
|