feat: Add XTTS v2 support, refactor Docker/GPU infra, and improve Piper engine

- Add XTTS v2 configuration to .env.example
- Refactor Dockerfile to multi-stage build with CUDA 12.1 support
- Update Makefile with Kokoro and XTTS test environment targets
- Refactor Piper engine (app/engines/piper.py) to use python module execution
- Add comprehensive documentation for Kokoro and XTTS plans
- Add helper scripts and patches for build process
This commit is contained in:
2025-12-13 11:37:58 +01:00
parent d6d1fe9d23
commit 91887ae296
19 changed files with 1625 additions and 46 deletions

View File

@ -0,0 +1,84 @@
# Technische Beschreibung: Multi-Stage Docker Build für GPU-fähige PyTorch-Umgebungen
## Zielsetzung
Der Ansatz ermöglicht ein Docker-Image, das GPU-beschleunigte Frameworks (PyTorch + CUDA + Torchaudio) enthält, dabei jedoch kompakt bleibt, ohne Runtime-Downloads auskommt und reproduzierbar gebaut werden kann.
---
## 1. Grundprinzip
### Stage 1 – Build-/Dependency Stage
- CUDA-fähiges Base-Image (z. B. `nvidia/cuda:12.1.0-runtime-ubuntu22.04`)
- Installation schwerer Abhängigkeiten:
- `torch` (CUDA-Build)
- `torchaudio`
- Enthält alle Build-Tools und Systemdependencies
- Ergebnis: vollständiges GPU-fähiges `site-packages`
### Stage 2 – Runtime Stage
- Leichtes Slim-Python-Image (z. B. `python:3.11-slim`)
- Nur das fertige `site-packages` aus Stage 1 wird kopiert
- Keine Build-Kette, keine Compiler, keine großen Pakete
---
## 2. Vorteile gegenüber anderen Ansätzen
### Gegenüber Single-Stage Builds
| Problem | Multi-Stage Lösung |
|--------|---------------------|
| Finales Image wird 5–10 GB groß | Nur Runtime-Layer → deutlich kleiner |
| Komplexer Build im finalen Image | Build isoliert in Stage 1 |
| Sicherheitsrisiken | Minimale Angriffsfläche im Runtime-Image |
### Gegenüber Runtime-Installation (EntryPoint)
| Runtime-Install | Multi-Stage |
|------------------|-------------|
| Lange Startup-Zeit | Installation beim Build |
| Internetzugang nötig | Runtime benötigt kein Netzwerk |
| Nicht deterministisch | Reproduzierbare Builds |
---
## 3. Technischer Ablauf im Detail
### Stage 1: Builder
- CUDA-fähiges Image
- Installation aller Dependencies inkl. Torch + CUDA
- Resultierendes `site-packages` wird vorbereitet
### Stage 2: Runtime
- Schlankes Python-Image
- Kopieren der vorbereiteten Pakete aus Stage 1
- Hinzufügen der Anwendung
- Setzen des Entrypoints
**Host-Anforderungen:**
- NVIDIA Treiber
- NVIDIA Container Toolkit
- Start mit `--gpus all`
---
## 4. CI/CD Eignung
- Deterministische Builds
- Weniger Storage
- Schnelleres Deployment
- Keine externen Abhängigkeiten bei Runtime
- Ideal für Kubernetes, GitLab CI, GitHub Actions, ArgoCD
---
## 5. Risiken & Mitigation
| Risiko | Mitigation |
|--------|------------|
| CUDA-Version mismatch | Versionen pinnen & Kompatibilitätsmatrix nutzen |
| GPU nicht verfügbar | CPU-Fallback implementieren |
| Torch-Wheel entfernt | internes Wheel-Repository verwenden |
---
## 6. TL;DR
Multi-Stage Build =
**Torch/CUDA in eigener Build-Stage installieren → fertige Pakete in ein leichtes Runtime-Image kopieren → kleines, GPU-fähiges, sauberes Deployment.**