dschlueter
ba98ac4eb4
Deleting an episode does not delete its data. DELETE /api/podcasts/episodes/{id}
resolves episode.audio_file and unlinks that one MP3 — the enclosing
data/podcasts/episodes/<uuid>/ directory, holding clips/ (one MP3 per dialogue
segment), outline.json and transcript.json, is never touched. Failed and
/retry-replaced runs leak a directory as well. Nothing reaps any of it: this
deployment had 15 directories on disk against 4 episodes in the database.
That is an upstream gap (roughly a shutil.rmtree of audio_path.parent.parent in
that handler), not something configurable here. Deliberately not patched by
bind-mounting a modified router — that would fork app logic into a deployment
repo and rot silently against pull_policy: always. Local cleanup instead.
scripts/prune_podcast_data.py reconciles the episode list from the API against
the directories on disk and removes:
- orphaned directories (no corresponding episode), and
- clips/ of completed episodes, since the clips are intermediate output once
the final MP3 exists.
Dry-run by default; --yes applies, --keep-clips restricts it to orphans.
Two guards, both tested: it aborts when any job is running/pending (a running
job has no audio_file yet, so its working directory is indistinguishable from an
orphan) and it skips directories touched within the last 60 minutes (--min-age).
It also refuses to act if the API is unreachable, rather than guessing.
Deletion runs inside the container (docker compose exec … rm -rf): the container
writes as root, so the host user cannot remove those directories — a plain
host-side rmtree fails with EPERM after the first directory.
Verified on this deployment: freed 13 MB (10 orphaned dirs + clips of 3 episodes,
49 MB -> 36 MB); all four surviving episodes still stream byte-identical MP3s
from /audio afterwards.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
246 lines
11 KiB
Markdown
246 lines
11 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)
|
||
|
||
./scripts/prune_podcast_data.py # Podcast-Datenmüll anzeigen (Trockenlauf)
|
||
./scripts/prune_podcast_data.py --yes # ... und löschen
|
||
```
|
||
|
||
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
|
||
│ └── prune_podcast_data.py # verwaiste Podcast-Ordner + Zwischenclips aufräumen
|
||
├── 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).
|
||
- **Episoden löschen räumt nicht auf.** Der Mülleimer-Button (bzw.
|
||
`DELETE /api/podcasts/episodes/{id}`) entfernt nur die finale MP3 und den DB-Eintrag — der
|
||
Ordner `notebook_data/podcasts/episodes/<uuid>/` mit den Einzelclips, `outline.json` und
|
||
`transcript.json` bleibt liegen. Das ist eine Lücke im Upstream-Code, kein lokales
|
||
Konfigurationsproblem. Abhilfe: `./scripts/prune_podcast_data.py`.
|
||
- **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).
|