dschlueter
03877588e1
Podcast generation failed twice at the audio stage, for two unrelated reasons that look similar from the UI but need opposite fixes. 1) TTS/STT ran as nohup background processes and silently did not survive a reboot. Podcasts then failed with "Failed to generate speech: All connection attempts failed" (httpx.ConnectError) even though outline and transcript had generated fine. Both now run as systemd user units. The unit files are versioned in services/systemd/ (using %h, not a hardcoded home) and installed by scripts/start_services.sh, which also enables linger so they start on boot without a login session. They pin GPU 2 by UUID, not by index: CUDA orders devices "fastest first", so index 2 can resolve to the T600. 2) GPU 2 is shared by three processes (TTS, STT and the separate chatterbox-tts MCP service on :9999), leaving ~12 GB of headroom. podcast_creator sends TTS_BATCH_SIZE (default 5) clips concurrently, and since /audio/speech is a sync FastAPI handler, they generated genuinely in parallel on one shared model. Activation memory multiplied, the TTS process hit 16.7 GB and threw torch.OutOfMemoryError, surfacing as "HTTP 500" from the endpoint. tts_server.py now serializes generation behind a lock (GPU-bound work, so parallelism buys no throughput — it only multiplies peak VRAM) and frees the cache afterwards. TTS_BATCH_SIZE=1 keeps the client from queuing requests in that lock and running into esperanto's 300s TTS timeout; ESPERANTO_TTS_TIMEOUT is raised to 600s as headroom. Verified: 5 concurrent /audio/speech requests all return 200 with GPU 2 peaking at ~11.5 GB (was 16.7 GB for the TTS process alone), and the previously failed episode now completes end to end — 38/38 batches, 10:56 min of audio, zero OOM. Docs record both failure signatures side by side, since ConnectError (server dead) and HTTP 500 (server alive, out of VRAM) have very different remedies. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
237 lines
10 KiB
Markdown
237 lines
10 KiB
Markdown
# Open Notebook (lokales Deployment)
|
||
|
||
Selbst gehostetes [Open Notebook](https://github.com/lfnovo/open-notebook) per Docker Compose —
|
||
KI-gestützter Notiz-/Recherche-Assistent mit Chat, Quellenverwaltung und Podcast-Erstellung.
|
||
|
||
**Nur zwei KI-Provider:**
|
||
- **Ollama** (lokal, auf dem Host, GPU 1+2 — RTX 3090) für Chat, Embedding, Tools
|
||
- **OpenRouter** (Cloud, einziger externer Provider) als Alternative/Ergänzung
|
||
|
||
Text-to-Speech und Speech-to-Text laufen ebenfalls lokal: [Chatterbox TTS](https://github.com/resemble-ai/chatterbox)
|
||
(mit Stimmklonung) und [faster-whisper](https://github.com/SYSTRAN/faster-whisper), beide über
|
||
schlanke selbstgeschriebene OpenAI-kompatible HTTP-Wrapper in `services/`.
|
||
|
||
Ausführliche Bedienung (Chat-Modi, Podcasts, Stimmen, Troubleshooting): siehe
|
||
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md). Architektur- und Betriebsdetails für
|
||
Weiterentwicklung: siehe [`CLAUDE.md`](CLAUDE.md).
|
||
|
||
---
|
||
|
||
## Architektur
|
||
|
||
| Komponente | Läuft wo | Zweck |
|
||
|---|---|---|
|
||
| `surrealdb` | Docker | Datenbank (nur `127.0.0.1:8000`) |
|
||
| `open_notebook` | Docker | Web-UI (`:8502`) + REST-API (`:5055`) |
|
||
| Ollama | Host (systemd) | Chat-/Embedding-Modelle, GPU 1+2 |
|
||
| `services/tts_server.py` | Host (systemd-User-Dienst) | Chatterbox TTS, GPU 2, Port `8901` |
|
||
| `services/stt_server.py` | Host (systemd-User-Dienst) | faster-whisper STT, GPU 2, Port `8902` |
|
||
|
||
Der `open_notebook`-Container erreicht Ollama und die TTS/STT-Wrapper über
|
||
`host.docker.internal` (Linux-Route via `extra_hosts: host-gateway`).
|
||
|
||
---
|
||
|
||
## 1. Voraussetzungen
|
||
|
||
- **Docker** + Docker Compose (Plugin), Daemon läuft
|
||
- **Ollama** installiert und als Dienst aktiv (`systemctl status ollama`), erreichbar auf `11434`
|
||
- Empfohlene systemd-Umgebung für Multi-GPU-Setups mit dedizierter Desktop-GPU:
|
||
`CUDA_VISIBLE_DEVICES=1,2` (GPU 0 ausschließen), `OLLAMA_KEEP_ALIVE=-1`,
|
||
`OLLAMA_CONTEXT_LENGTH=131072`
|
||
- Benötigte Modelle: `qwen3.5:27b`, `nomic-embed-text` (weitere optional, siehe
|
||
`scripts/setup_models.sh`) — mit `ollama pull <modell>` laden
|
||
- **Python-Umgebungen für TTS/STT** (bereits vorhandene Installationen dieses Systems):
|
||
- Conda-Env `chatterbox` mit [chatterbox-tts](https://github.com/resemble-ai/chatterbox)
|
||
(`~/miniforge3/envs/chatterbox`, siehe `~/chatterbox-tts-cli/`)
|
||
- System-Python mit `faster-whisper`, `fastapi`, `uvicorn`
|
||
- **OPENROUTER_API_KEY** als Umgebungsvariable im Environment verfügbar (für die Secret-Generierung
|
||
in Schritt 2)
|
||
- **`ufw`** (falls als Firewall aktiv) — Standardrichtlinie „deny incoming“ wird vorausgesetzt
|
||
- **`openssl`**, **`ffmpeg`**, **`curl`**, **`python3`**
|
||
|
||
---
|
||
|
||
## 2. Installation
|
||
|
||
### 2.1 Repository
|
||
|
||
```bash
|
||
cd ~/open-notebook # bzw. Zielverzeichnis
|
||
git status # falls schon vorhanden: prüfen statt neu klonen
|
||
```
|
||
|
||
### 2.2 Secrets erzeugen (`.env`)
|
||
|
||
```bash
|
||
ENC_KEY=$(openssl rand -base64 32)
|
||
DB_PASS=$(openssl rand -base64 24 | tr -d '/+=')
|
||
cat > .env <<EOF
|
||
OPEN_NOTEBOOK_ENCRYPTION_KEY=${ENC_KEY}
|
||
SURREAL_USER=root
|
||
SURREAL_PASSWORD=${DB_PASS}
|
||
OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
|
||
EOF
|
||
chmod 600 .env
|
||
```
|
||
|
||
`.env` wird nicht committed (siehe `.gitignore`). `.env.example` ist das Template.
|
||
|
||
### 2.3 Container starten
|
||
|
||
```bash
|
||
docker compose pull
|
||
docker compose up -d
|
||
docker compose ps # beide Container sollten "Up" sein
|
||
```
|
||
|
||
Web-UI: `http://localhost:8502` · REST-API: `http://localhost:5055` (beide nur `127.0.0.1`).
|
||
|
||
### 2.4 Firewall öffnen für TTS/STT
|
||
|
||
Die TTS/STT-Wrapper laufen auf dem Host; der Docker-Container erreicht sie über die
|
||
Docker-Bridge, was bei aktiver `ufw`-Firewall (Standard: deny incoming) explizit erlaubt werden muss —
|
||
analog zur bestehenden Regel für Ollama (`11434/tcp`):
|
||
|
||
```bash
|
||
sudo ufw allow 8901/tcp comment 'open-notebook TTS (chatterbox)'
|
||
sudo ufw allow 8902/tcp comment 'open-notebook STT (faster-whisper)'
|
||
```
|
||
|
||
Ohne diesen Schritt bleiben TTS/STT vom Container aus unerreichbar (Timeout), obwohl sie lokal
|
||
laufen und funktionieren.
|
||
|
||
### 2.5 TTS/STT-Server einrichten
|
||
|
||
```bash
|
||
./scripts/start_services.sh
|
||
```
|
||
|
||
Installiert `services/systemd/*.service` nach `~/.config/systemd/user/`, aktiviert `linger`
|
||
(damit die Dienste auch ohne aktive Login-Session laufen) und startet beide. Sie laufen auf
|
||
GPU 2 — nicht GPU 0/1, um die Desktop-GPU und Ollamas Chat-Modell nicht zu verdrängen.
|
||
|
||
Das Skript ist idempotent und **überlebt Reboots**: die Dienste starten automatisch mit. Status
|
||
und Logs:
|
||
|
||
```bash
|
||
systemctl --user status open-notebook-tts open-notebook-stt
|
||
journalctl --user -u open-notebook-tts -f
|
||
```
|
||
|
||
> Der erste Start dauert bis zu einer Minute, weil whisper `large-v3` geladen wird.
|
||
|
||
Für Stimmklonung mindestens eine Referenz-WAV in `services/voices/default.wav` ablegen (z. B.
|
||
Symlink auf eine eigene Sprachaufnahme, 10–30s, WAV) — siehe
|
||
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#stimmklonung).
|
||
|
||
### 2.6 KI-Provider und Modelle registrieren
|
||
|
||
```bash
|
||
./scripts/setup_models.sh
|
||
```
|
||
|
||
Richtet automatisch ein:
|
||
- Ollama-Credential (Chat + Embedding) mit `num_ctx=98304` — **wichtig**, siehe Warnkasten unten
|
||
- Kuratierte Ollama-Modelle: `qwen3.5:27b` (Standard für Chat/Tools/großer Kontext),
|
||
`nomic-embed-text` (Standard-Embedding), `qwen3-coder-30b-128k` (optional für Code)
|
||
- OpenRouter-API-Key aus `.env`/Environment in die verschlüsselte Datenbank migriert
|
||
- Kuratierte OpenRouter-Modelle (Claude Sonnet 5, Qwen3-Max, Gemini 3.5 Flash)
|
||
- Lokale TTS/STT-Wrapper als `openai_compatible`-Credentials + Standardmodelle
|
||
|
||
> **Warum `num_ctx` explizit gesetzt werden muss:** Ohne diese Einstellung begrenzt die
|
||
> zugrunde liegende Bibliothek (`esperanto`) jede Ollama-Chat-Anfrage stillschweigend auf
|
||
> 8192 Tokens Kontext — unabhängig vom eigentlichen Modell-Limit. Größere Chat-Kontexte
|
||
> (z. B. ganze Bücher im „Volltext"-Modus) werden dann abgeschnitten, und weil `qwen3.5:27b`
|
||
> ein „denkendes" Modell ist, kommt dabei oft eine **leere Antwort statt eines Fehlers**
|
||
> heraus. `98304` ist der größte Wert, der auf dieser Hardware (RTX 3090, 24 GB) noch
|
||
> vollständig auf der GPU bleibt (`ollama ps` → `100% GPU`). Details:
|
||
> [`CLAUDE.md`](CLAUDE.md).
|
||
|
||
### 2.7 Verifikation
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:5055/api/models/providers | python3 -m json.tool
|
||
```
|
||
|
||
Erwartung: `"available": ["openrouter", "ollama"]`. TTS/STT-Gesundheit:
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8901/health # Chatterbox TTS
|
||
curl -s http://127.0.0.1:8902/health # faster-whisper STT
|
||
```
|
||
|
||
UI öffnen (`http://localhost:8502`), ein Notebook anlegen, eine Quelle hinzufügen und chatten —
|
||
siehe [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md) für die weitere Bedienung.
|
||
|
||
---
|
||
|
||
## 3. Alltägliche Befehle
|
||
|
||
```bash
|
||
docker compose up -d # starten
|
||
docker compose down # stoppen (Daten bleiben erhalten)
|
||
docker compose logs -f open_notebook # Logs verfolgen
|
||
docker compose ps # Status
|
||
|
||
systemctl --user status open-notebook-tts open-notebook-stt # TTS/STT-Status
|
||
systemctl --user restart open-notebook-tts # z.B. nach neuer Stimme
|
||
journalctl --user -u open-notebook-tts -f # TTS-Logs
|
||
./scripts/start_services.sh # Units neu installieren + starten (idempotent)
|
||
```
|
||
|
||
TTS/STT starten nach einem Reboot von selbst — `start_services.sh` ist nur für die
|
||
Ersteinrichtung bzw. nach Änderungen an den Unit-Dateien nötig.
|
||
|
||
---
|
||
|
||
## 4. Verzeichnisstruktur
|
||
|
||
```
|
||
open-notebook/
|
||
├── docker-compose.yml # SurrealDB + open_notebook
|
||
├── .env # Secrets (gitignored)
|
||
├── .env.example # Template
|
||
├── surreal_data/ # DB-Daten (gitignored)
|
||
├── notebook_data/ # Notebook-Dateien/Uploads (gitignored)
|
||
├── services/
|
||
│ ├── tts_server.py # Chatterbox-Wrapper (OpenAI-API-kompatibel)
|
||
│ ├── stt_server.py # faster-whisper-Wrapper
|
||
│ ├── systemd/ # Unit-Dateien für die beiden Wrapper
|
||
│ ├── voices/ # Referenz-WAVs fürs Voice-Cloning (gitignored)
|
||
│ └── logs/ # (gitignored, Altlast der früheren nohup-Variante)
|
||
├── scripts/
|
||
│ ├── setup_models.sh # Provider/Modelle einrichten (idempotent)
|
||
│ └── start_services.sh # TTS/STT als systemd-User-Dienste installieren+starten
|
||
├── README.md # diese Datei
|
||
├── BEDIENUNGSANLEITUNG.md # ausführliche Bedienungsanleitung (Deutsch)
|
||
└── CLAUDE.md # technische Architektur-Doku für Weiterentwicklung
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Bekannte Stolpersteine
|
||
|
||
Kurzreferenz — Details jeweils in [`CLAUDE.md`](CLAUDE.md):
|
||
|
||
- **Embedding-Modell muss klein sein.** `qwen3-embedding` (ein zweckentfremdetes 8B-LLM,
|
||
~13 GB geladen) konkurriert mit dem Chat-Modell um GPU-Speicher und fällt dann teilweise auf
|
||
die CPU zurück — einzelne Embeddings dauern dann 40+ Sekunden und reißen Timeouts.
|
||
`nomic-embed-text` (274 MB) ist der Standard hier.
|
||
- **`num_ctx` beim Ollama-Chat-Credential ist Pflicht** (siehe Warnkasten in 2.6) — sonst
|
||
leere Chat-Antworten bei größerem Kontext, ohne sichtbaren Fehler.
|
||
- **Neue Host-Ports brauchen eine `ufw`-Regel**, sonst kann der Container sie nicht erreichen
|
||
(Timeout, keine Fehlermeldung in Open Notebook selbst).
|
||
- **GPU 2 teilen sich drei Prozesse** (TTS, STT und der separate `chatterbox-tts`-MCP-Dienst auf
|
||
Port 9999) — es bleiben nur ~12 GB Arbeitsspeicher für die Sprachsynthese. Deshalb serialisiert
|
||
`tts_server.py` seine Generierung intern und `TTS_BATCH_SIZE=1` steht in `docker-compose.yml`:
|
||
ohne beides schickt der Podcast-Generator 5 Clips gleichzeitig, die parallel auf der GPU laufen
|
||
und sie mit `CUDA out of memory` sprengen (sichtbar als `HTTP 500` beim Vertonen).
|
||
- **Podcast-Sprache** wird über das `language`-Feld des Episode-Profils gesteuert, aber nur
|
||
dank der gepatchten Prompt-Vorlagen unter `prompts/podcast/` (per Bind-Mount in
|
||
`docker-compose.yml` eingehängt) — die Original-Vorlagen im Image ignorieren `language`, was
|
||
englische Podcasts (von der deutsch-fixierten TTS mit Akzent vorgelesen) verursachte. Die
|
||
Vorlagen enthalten zusätzlich `/no_think`, damit `qwen3.5:27b` bei langem Quellinhalt nicht
|
||
durch überlange Reasoning-Blöcke ungültiges JSON liefert. Änderst du die Vorlagen, danach
|
||
`docker compose up -d --force-recreate open_notebook`. Details:
|
||
[`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md#10-troubleshooting) und [`CLAUDE.md`](CLAUDE.md).
|