289 lines
4.4 KiB
Markdown
289 lines
4.4 KiB
Markdown
# Developer Setup Guide
|
||
|
||
Dieses Dokument befähigt jeden Entwickler dazu, das komplette XTTS2-TTS-System lokal aufzusetzen, zu verstehen, zu debuggen und zu erweitern – ohne Rückfragen.
|
||
|
||
---
|
||
|
||
# 1. Ziel des Dokuments
|
||
|
||
* Lokale Entwicklungsumgebung vollständig einrichten
|
||
* Services starten & stoppen
|
||
* Worker skalieren
|
||
* API testen
|
||
* Debugging-Strategien
|
||
* Best Practices für Code, Deployment & GPU-Nutzung
|
||
|
||
---
|
||
|
||
# 2. Voraussetzungen
|
||
|
||
## Software
|
||
|
||
* Docker ≥ 24.x
|
||
* Docker Compose ≥ v2.x
|
||
* Git
|
||
* Python 3.10–3.11
|
||
* Optional: Editor wie VS Code mit Python- & Docker-Extensions
|
||
|
||
## Hardware
|
||
|
||
* Linux (empfohlen), macOS oder Windows WSL2
|
||
* Für GPU-Betrieb: NVIDIA GPU + Container Toolkit
|
||
|
||
GPU prüfen:
|
||
|
||
```bash
|
||
nvidia-smi
|
||
```
|
||
|
||
NVIDIA Docker prüfen:
|
||
|
||
```bash
|
||
docker run --rm --gpus all nvidia/cuda:12.1.0-base nvidia-smi
|
||
```
|
||
|
||
---
|
||
|
||
# 3. Repository klonen
|
||
|
||
```bash
|
||
git clone <repo-url>
|
||
cd tts-server
|
||
```
|
||
|
||
---
|
||
|
||
# 4. Projektstruktur
|
||
|
||
```
|
||
tts-server/
|
||
├── gateway/ → FastAPI-Gateway
|
||
│ ├── main.py
|
||
│ ├── api/
|
||
│ ├── core/
|
||
│ ├── voices/
|
||
│ ├── logs/
|
||
│ └── Dockerfile
|
||
│
|
||
├── worker/ → XTTS2 Worker
|
||
│ ├── main.py
|
||
│ ├── engine/
|
||
│ ├── core/
|
||
│ └── Dockerfile
|
||
│
|
||
├── scripts/
|
||
│ └── find_port.py → Portscanner (8000–8100)
|
||
│
|
||
├── docker-compose.yml → Multi-Service Orchestration
|
||
├── Makefile → PRO Workflow
|
||
├── README.md
|
||
└── ONBOARDING.md
|
||
```
|
||
|
||
---
|
||
|
||
# 5. Docker-basiertes Development (empfohlen)
|
||
|
||
## 5.1 Images bauen
|
||
|
||
```bash
|
||
make build
|
||
```
|
||
|
||
## 5.2 Server starten
|
||
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
Der Portscanner wählt automatisch den ersten freien Port (8000–8100) und legt ihn ab in:
|
||
|
||
```
|
||
gateway/port.txt
|
||
gateway/logs/gateway.log
|
||
```
|
||
|
||
## 5.3 Logs ansehen
|
||
|
||
```bash
|
||
make logs
|
||
```
|
||
|
||
## 5.4 Services stoppen
|
||
|
||
```bash
|
||
make down
|
||
```
|
||
|
||
## 5.5 Status anzeigen
|
||
|
||
```bash
|
||
make status
|
||
```
|
||
|
||
---
|
||
|
||
# 6. Ohne Docker entwickeln (lokales Debugging)
|
||
|
||
## 6.1 Virtuelle Umgebung
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
## 6.2 Abhängigkeiten installieren
|
||
|
||
Gateway:
|
||
|
||
```bash
|
||
pip install -r gateway/requirements.gateway.txt
|
||
```
|
||
|
||
Worker:
|
||
|
||
```bash
|
||
pip install -r worker/requirements.worker.txt
|
||
```
|
||
|
||
Redis lokal starten:
|
||
|
||
```bash
|
||
docker run -p 6379:6379 redis:7
|
||
```
|
||
|
||
Gateway starten:
|
||
|
||
```bash
|
||
python gateway/main.py
|
||
```
|
||
|
||
Worker starten:
|
||
|
||
```bash
|
||
python worker/main.py
|
||
```
|
||
|
||
---
|
||
|
||
# 7. TTS API testen
|
||
|
||
## 7.1 Healthcheck
|
||
|
||
```bash
|
||
curl http://localhost:<PORT>/health
|
||
```
|
||
|
||
## 7.2 TTS Anfrage
|
||
|
||
```bash
|
||
curl -X POST http://localhost:<PORT>/v1/audio/speech \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "xtts-v2",
|
||
"input": "Das ist ein Test.",
|
||
"voice": "auto",
|
||
"format": "wav"
|
||
}' \
|
||
--output test.wav
|
||
```
|
||
|
||
## 7.3 Stimme registrieren
|
||
|
||
```bash
|
||
curl -X POST http://localhost:<PORT>/v1/voices/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "german_narrator",
|
||
"samples": ["https://example.com/sample.wav"]
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
# 8. Worker skalieren
|
||
|
||
Höhere Last? Mehrere Worker starten:
|
||
|
||
```bash
|
||
make worker-scale N=4
|
||
```
|
||
|
||
Redis verteilt Jobs automatisch FIFO.
|
||
|
||
---
|
||
|
||
# 9. Selftest
|
||
|
||
```bash
|
||
make selftest
|
||
```
|
||
|
||
Testet:
|
||
|
||
* Redis erreichbar
|
||
* Gateway online
|
||
* Worker zieht Jobs
|
||
* Synthese funktioniert
|
||
|
||
---
|
||
|
||
# 10. Debugging
|
||
|
||
## Gateway startet nicht
|
||
|
||
* Prüfen: `gateway/logs/`
|
||
* Port frei? `gateway/port.txt`
|
||
* Redis erreichbar?
|
||
|
||
## Worker lädt nicht
|
||
|
||
* XTTS2 Modell verfügbar?
|
||
* GPU verfügbar? `nvidia-smi`
|
||
* Torch CUDA Version kompatibel?
|
||
|
||
## Audio-Probleme
|
||
|
||
* Voice Sample ungeeignet
|
||
* Sprache nicht angegeben
|
||
* Format falsch
|
||
|
||
---
|
||
|
||
# 11. Code Guidelines
|
||
|
||
* PEP8 Stil
|
||
* Logging strukturiert (JSON empfohlen)
|
||
* Kein Hardcoding von Pfaden
|
||
* Hohe Modularität
|
||
* Unit Tests für Kernkomponenten
|
||
* Feature Branches: `feature/<name>`
|
||
* Commits: Conventional Commits
|
||
|
||
---
|
||
|
||
# 12. Best Practices
|
||
|
||
* Worker lieber horizontal skalieren statt optimieren
|
||
* Keine sensiblen Voice Samples committen
|
||
* Docker Images regelmäßig aktualisieren
|
||
* Für Public Deployments: Auth Layer aktivieren
|
||
|
||
---
|
||
|
||
# 13. Nächste Schritte für Entwickler
|
||
|
||
* Monitoring & Dashboards
|
||
* WebSocket Realtime TTS
|
||
* Mehrsprachige Voice Registry
|
||
* Model Hot-Swapping (XTTS2, F5, Kokoro)
|
||
* CI/CD Pipeline hinzufügen
|
||
|
||
---
|
||
|
||
# 14. Fertig!
|
||
|
||
Wenn du dieses Dokument verstanden hast, kannst du das Projekt vollständig entwickeln, erweitern und deployen.
|
||
|
||
Viel Erfolg! 🚀
|