336 lines
7.5 KiB
Markdown
336 lines
7.5 KiB
Markdown
# 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
|
|
|
|
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 /health
|
|
|
|
Health-Check mit GPU-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
|
|
- **API-Keys:** Verwalten (erstellen, deaktivieren, löschen)
|
|
- **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
|
|
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:
|
|
|
|
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"]
|
|
```
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Manuelles Downloaden möglich
|
|
mkdir -p models
|
|
# Modelle werden von HuggingFace heruntergeladen
|
|
```
|
|
|
|
### Port belegt
|
|
|
|
```bash
|
|
# Port in .env ändern
|
|
PORT=8001
|
|
```
|
|
|
|
## Backup
|
|
|
|
Wichtige Daten:
|
|
- `./data/` - SQLite Datenbank (API-Keys, Logs)
|
|
- `./models/` - Heruntergeladene Whisper-Modelle
|
|
- `./.env` - Konfiguration
|
|
|
|
```bash
|
|
# Backup erstellen
|
|
tar -czvf whisper-api-backup.tar.gz data/ models/ .env
|
|
```
|
|
|
|
## 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
|