Whisper API
Eine lokale Whisper-API mit GPU-Beschleunigung und Web-Admin-Interface für die Transkription von Audio-Dateien.
Features
- OpenAI-kompatible API - Drop-in Ersatz für OpenAI Whisper API
- GPU-beschleunigt - Nutzt NVIDIA GPUs (CUDA) für schnelle Transkription
- 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
- Cross-Platform - Docker-basiert, läuft auf Windows und Linux
- Automatische Cleanup - Logs nach 30 Tagen automatisch gelöscht
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
- Repository klonen:
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api
- Umgebungsvariablen konfigurieren:
cp .env.example .env
# Bearbeite .env nach deinen Wünschen
- Docker-Container starten:
docker-compose up -d
- Erster Start:
- Das
large-v3Modell (~3GB) wird automatisch heruntergeladen - Dies kann 5-10 Minuten dauern
- Status überprüfen:
docker-compose logs -f
- Das
Verifizierung
# 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:
Authorization: Bearer sk-dein-api-key-hier
Endpunkte
POST /v1/audio/transcriptions
Transkribiert eine Audio-Datei.
Request:
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:
{
"text": "Hallo Welt, das ist ein Test."
}
POST /v1/audio/transcriptions (mit Timestamps)
Request:
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:
{
"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 /health
Health-Check mit GPU-Status.
Response:
{
"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
- API-Keys: Verwalten (erstellen, deaktivieren, löschen)
- Logs: Detaillierte Transkriptions-Logs mit Filter
Konfiguration
.env.example
# 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
services:
whisper-api:
# ...
environment:
- PORT=8000 # Änderbar
- WHISPER_MODEL=large-v3
volumes:
- ./models:/app/models # Persistiert Modelle
- ./data:/app/data # SQLite Datenbank
- ./uploads:/app/uploads # Temporäre Uploads
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
Migration zu Linux
Die Docker-Konfiguration ist plattformunabhängig. Für Linux:
- NVIDIA Docker installieren:
# 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
- Projekt klonen und starten:
git clone https://gitea.ragtag.rocks/b0rborad/whisper-api.git
cd whisper-api
docker-compose up -d
- GPU-Passthrough verifizieren:
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
Integration mit Clawdbot
Für die Integration in einen Clawdbot Skill:
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"]
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
Troubleshooting
GPU nicht erkannt
# NVIDIA Container Toolkit prüfen
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
# Logs prüfen
docker-compose logs whisper-api
Modell-Download langsam
# Manuelles Downloaden möglich
mkdir -p models
# Modelle werden von HuggingFace heruntergeladen
Port belegt
# Port in .env ändern
PORT=8001
Backup
Wichtige Daten:
./data/- SQLite Datenbank (API-Keys, Logs)./models/- Heruntergeladene Whisper-Modelle./.env- Konfiguration
# Backup erstellen
tar -czvf whisper-api-backup.tar.gz data/ models/ .env
Lizenz
MIT License - Siehe LICENSE Datei
Support
Bei Problemen:
- Logs prüfen:
docker-compose logs -f - Health-Check:
curl http://localhost:8000/health - Issue auf Gitea erstellen
Erstellt für: b0rborad @ ragtag.rocks
Hardware: Dual RTX 3090 Setup
Zweck: Clawdbot Skill Integration