Add CPU embeddings for OpenClaw memory

2026-09-21 08:31:45 +02:00
parent de3f8fd7aa
commit 302b08e051
13 changed files with 231 additions and 7 deletions
@@ -1,8 +1,8 @@
 # Container-Inventar auf Athena

-Stand: 20. September 2026 (lesender Docker-Abgleich)
+Stand: 21. September 2026

-Athena hatte beim lesenden Abgleich 30 Docker-Container. Nicht jeder Container enthält
+Athena hat 31 reguläre Docker-Container. Nicht jeder Container enthält
 ein KI-Modell: Router, Oberflächen, Netzwerk, Steuerung und Sicherung sind
 gewöhnliche Dienste. Die rechenintensiven GPU-Worker werden absichtlich nur bei
 Bedarf gestartet. Ein Container im Zustand `Created` oder `Exited (0)` ist daher
@@ -11,6 +11,7 @@ nicht automatisch ein ungenutzter Rest.
 | Container | Modell oder wesentliche Komponente | Aufgabe |
 |---|---|---|
 | `mike-ai-backup` | kein Modell; Offen Docker Volume Backup `v2` (Digest vom 15. September 2026) | Sichert `/data`, `/etc/mike-ai`, den Stack und die persistenten Docker-Volumes im Fünf-Stunden-Takt. |
+| `mike-ai-embedding` | EmbeddingGemma 300M QAT Q8 | Dauerhafter CPU-only-Endpunkt für OpenClaws semantische und hybride Memory-Suche; teilt ausschließlich den privaten Netzwerk-Namespace des WireGuard-Gateways. |
 | `mike-ai-bonsai2-ab` | Bonsai-2-Vergleichsmodell | Gestoppter, reproduzierbar dokumentierter A/B-Testcontainer; kein Produktivprofil. |
 | `mike-ai-applio-studio` | Applio/RVC; Stimmenmodelle werden nutzerseitig ergänzt | Vollständige RVC-Oberfläche für Inferenz, Modellverwaltung und Training auf der RTX 5080. Für eine Konvertierung ist ein importiertes oder trainiertes `.pth`-Modell nötig; eine Referenzaufnahme allein reicht nicht. |
 | `mike-ai-image-worker` | FLUX.2 Klein 9B FP8, Qwen3-8B NF4 Textencoder und VAE | Erzeugt und bearbeitet Bilder transaktional; nutzt während eines Auftrags RTX 5080 und RTX 3060. |
@@ -1,6 +1,6 @@
 # Geprüfter Live-Stand auf Athena

-Stand: **20. September 2026**. Quelle: lesender SSH-Abgleich von Docker,
+Stand: **21. September 2026**. Quelle: lesender SSH-Abgleich von Docker,
 Compose-Dateien, Git-Inhalten, Images, Health-Endpunkten und Backup-Timern.
 Containerzustände sind Momentaufnahmen; der Controller darf Profile danach
 umschalten. Es wurde für diesen Abgleich kein Dienst neu gestartet.
@@ -45,6 +45,15 @@ nicht mehr den aktuellen Containerzustand.
  1280 × 1280 lief im Test in CUDA-OOM.
 - Qwen3-TTS 1.7B auf 3060 hinter dem TTS-Gateway; kein Piper-Fallback.
 - Whisper.cpp `ggml-small` auf CPU über `/v1/audio/transcriptions`.
+- `mike-ai-embedding` stellt EmbeddingGemma 300M Q8 CPU-only über den privaten
+  WireGuard-Endpunkt `http://192.168.1.212:8082/v1/embeddings` bereit. Eine
+  Probe mit zwei deutschen Texten lieferte zwei Vektoren mit je 768 Dimensionen.
+  Gemessen wurden rund 86 MiB RAM im Leerlauf, rund 1,1 GiB beim vollständigen
+  Indexaufbau und 0,044 Sekunden für die abschließende Netzwerkprobe. OpenClaw
+  indexierte 107 Dateien mit 1.139 Chunks vollständig; die semantische Suche
+  und der 768-dimensionale Vektorindex sind aktiv. Der
+  GPU-Versuch war zwar schneller (0,077 Sekunden), ließ im Ultra-Profil aber
+  nur 372 MB VRAM auf der RTX 3060 frei und wurde deshalb verworfen.
 - Der gesunde Dienst `mike-ai-realtime-voice` vermittelt OpenClaw Talk über
  WebRTC zwischen Whisper, dem normalen OpenClaw-Agenten und Qwen3-TTS.
  Er braucht keine GPU und keinen Profilwechsel. Das Plugin liegt in
@@ -59,7 +68,7 @@ nicht mehr den aktuellen Containerzustand.
  trotzdem Status, Modelle und vorbereitende Aufgaben anzeigen; eine echte
  Konvertierung verlangt den Applio-Modus.

-Der vollständige Bestand der **30** angelegten Docker-Container steht im
+Der vollständige Bestand der **31** angelegten Docker-Container steht im
 [Container-Inventar](CONTAINER_INVENTORY.md). `Created` oder `Exited` bei
 Spezialworkern bedeutet nicht automatisch einen zu entfernenden Testrest.

@@ -0,0 +1,90 @@
+# OpenClaw Memory über Athena
+
+Stand: **21. September 2026**
+
+OpenClaw verwendet für seine Memory-Suche einen eigenen, dauerhaft laufenden
+Embedding-Dienst auf Athena. Der Chat-Router auf Port 8081 bleibt unverändert;
+Embeddings laufen getrennt auf Port 8082.
+
+## Aufbau
+
+- Container: `mike-ai-embedding`
+- Modell: `ggml-org/embeddinggemma-300m-qat-q8_0-GGUF`, Q8_0
+- Datei: `/data/models/embeddinggemma/embeddinggemma-300m-qat-Q8_0.gguf`
+- SHA-256: `6fa0c02a9c302be6f977521d399b4de3a46310a4f2621ee0063747881b673f67`
+- Laufzeit: eigener, auf Athenas CPU nativ optimierter CPU-only-Build von
+  llama.cpp ohne CUDA-Abhängigkeit, zusätzlich erzwungen durch
+  `--n-gpu-layers 0`
+- API: `http://192.168.1.212:8082/v1/embeddings`
+- Zugriff: privater WireGuard-Netzwerk-Namespace; kein öffentlicher Host-Port
+- Ergebnisdimension: 768
+- vier CPU-Slots mit insgesamt 4096 Kontexttoken
+- logische Batchgröße 4096 und physische Micro-Batchgröße 1024; damit passen
+  auch größere OpenClaw-Memory-Chunks in einen Slot und mehrere Chunks werden
+  beim Indexaufbau gemeinsam verarbeitet
+
+Der Dienst benötigt im Leerlauf rund 86 MiB und während eines vollständigen
+Indexaufbaus rund 1,1 GiB RAM. Die abschließende Netzwerkprobe von Unraid aus
+lag bei 0,044 Sekunden. Ein Betrieb auf der RTX 3060
+wurde verworfen: Im Ultra-Profil blieben nur 372 MB VRAM Reserve, während der
+Zeitgewinn lediglich rund 0,06 Sekunden betrug.
+
+## OpenClaw-Konfiguration
+
+OpenClaw nutzt den offiziellen generischen Anbieter `openai-compatible`. Die
+bestehenden Quellen-, Scope- und Chunking-Einstellungen unter `memory.search`
+bleiben dabei erhalten.
+
+```json5
+{
+  memory: {
+    search: {
+      provider: "openai-compatible",
+      model: "embeddinggemma",
+      fallback: "none",
+      remote: {
+        baseUrl: "http://192.168.1.212:8082/v1",
+        apiKey: "local"
+      }
+    }
+  }
+}
+```
+
+`local` ist hier nur ein nicht geheimes Kompatibilitätskennwort. Der Dienst
+liegt im privaten VPN und llama.cpp verlangt selbst keinen Schlüssel.
+
+## Prüfung
+
+Auf Athena:
+
+```bash
+docker inspect -f '{{.State.Health.Status}}' mike-ai-embedding
+docker exec mike-ai-embedding curl -fsS \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"embeddinggemma","input":["Athena Speicherprobe"]}' \
+  http://127.0.0.1:8082/v1/embeddings
+```
+
+Auf Unraid:
+
+```bash
+docker exec OpenClaw openclaw memory status --deep --agent main
+docker exec OpenClaw openclaw memory index --force --agent main
+docker exec OpenClaw openclaw memory search --agent main "GPU-Aufteilung"
+```
+
+Nach einem Wechsel von Anbieter oder Modell muss der Index ausdrücklich neu
+aufgebaut werden. OpenClaw erledigt das absichtlich nicht still im Hintergrund.
+Der produktive Neuaufbau am 21. September umfasste 107 Dateien und 1.139
+Chunks. Danach meldete OpenClaw `dirty: false`, einen vollständigen
+768-dimensionalen Vektorindex, aktive semantische Suche und eine erfolgreiche
+Anbieterprobe. Eine Suchprobe lieferte drei Treffer.
+
+## Wiederherstellung
+
+Der Athena-Installer lädt das Modell anhand der fest hinterlegten URL und
+Prüfsumme. Danach startet `./manage.sh deploy core` den Embedding-Dienst mit.
+Auf Unraid werden die vier oben dokumentierten `memory.search`-Werte gesetzt
+und anschließend der Index erzwungen neu aufgebaut. Weder API-Schlüssel noch
+Memory-Inhalte liegen in diesem Git-Repository.
@@ -20,6 +20,9 @@ Quelle ist im Git-Repository unter `integrations/openclaw-athena-talk` erfasst.
 Piper-Daten sind kein aktueller Sicherungsbestand. Modellgewichte unter
 `/data/models` und das reproduzierbare Whisper-Volume gehören nicht zu diesen
 Backup-Mounts. Ein Backup ausschließlich auf `/data` schützt nicht vor deren Ausfall.
+Das gilt auch für das reproduzierbare EmbeddingGemma-Gewicht unter
+`/data/models/embeddinggemma`; URL und SHA-256 stehen in
+`config/install.env.example`, sodass der Installer es erneut laden und prüfen kann.

 Die verschlüsselten Notfallpakete über `athena-export-backup.timer` laufen
 ebenfalls im Fünf-Stunden-Takt; beim Abgleich war der Timer aktiv und der