213 lines
8.2 KiB
Markdown
213 lines
8.2 KiB
Markdown
# Neural Knowledge Brain
|
||
|
||
Eigenständiger Go-Dienst für Agent, lokale Knowledgebase, GLPI-Knowledgebase und autonome AI-THINK-Anreicherung. Der Dienst hält einen vollständigen Wissensgraphen im Arbeitsspeicher und rendert eine hierarchisch verdichtete Fullscreen-Ansicht als lebende Hirnaktivität.
|
||
|
||
## Kernfunktionen
|
||
|
||
- Fullscreen-Canvas mit 3D-Hirnform, semantischen Cortex-Regionen und hierarchischem Level-of-Detail.
|
||
- Umschaltbare Honeycomb-Ansicht: gleichmäßig verteilte Notes in einer automatisch skalierten 3D-Gehirnwabe, ohne Edge-Rendering.
|
||
- Laufzeitsteuerung für Learning und Thinking sowie getrennte Kategorie-Filter für Lernen, Anzeige und AI-THINK.
|
||
- Echtzeitaktivierung über Server-Sent Events: Nodes glühen, aggregierte Edges leuchten und Partikel folgen tatsächlichen Wissenspfaden.
|
||
- Ingest lokaler produktiver Knowledge-JSONs sowie separater AI-THINK-Staging-Dateien.
|
||
- Optionaler read-only Ingest sichtbarer Beiträge aus der GLPI-Knowledgebase.
|
||
- Read-only Tailing der Agent-`runs.jsonl` und optionale Suchtelemetrie aus Agent und KB.
|
||
- Ollama-Pool mit mehreren unabhängigen Instanzen, Routing, Healthchecks, Cooldown und Failover.
|
||
- Embeddings über `embeddinggemma`, Beziehungsanalyse über `qwen3:8b`.
|
||
- Sequenzieller autonomer AI-THINK-Worker mit optionaler SearXNG-Recherche.
|
||
- Gebündelte Festplattenpersistenz: Graph, GLPI-KB-Cache und AI-THINK-Dateien werden standardmäßig nur alle fünf Minuten sequenziell geschrieben.
|
||
|
||
## Vertrauens- und Schreibgrenzen
|
||
|
||
Das Brain liest produktive Quellen und GLPI-KB ausschließlich. Es schreibt niemals in produktive Knowledge-Dateien oder nach GLPI zurück.
|
||
|
||
Schreibbar sind nur:
|
||
|
||
- das eigene `BRAIN_DATA_DIR` für Graphzustand und GLPI-KB-Cache;
|
||
- der erste Pfad aus `BRAIN_STAGING_DIRS` für AI-THINK-Entwürfe.
|
||
|
||
AI-THINK bleibt `auto_reply: false`, trägt die Kategorien `AI-THINK` und `AI-Staging` und wird erst nach einer expliziten Freigabe im bestehenden Editor produktiv.
|
||
|
||
## Schnellstart
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Pfade, Ollama-Pool und optional GLPI-Zugangsdaten anpassen.
|
||
set -a; . ./.env; set +a
|
||
go run ./cmd/brain
|
||
```
|
||
|
||
Oberfläche: `http://localhost:8090`
|
||
|
||
Docker:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
## Mehrere Ollama-Instanzen
|
||
|
||
`OLLAMA_URLS` hat Vorrang vor dem weiterhin unterstützten `OLLAMA_URL`.
|
||
|
||
```env
|
||
OLLAMA_URLS=http://10.20.30.21:11434,http://10.20.30.22:11434,http://10.20.30.23:11434
|
||
OLLAMA_NODE_NAMES=gpu-01,gpu-02,gpu-03
|
||
OLLAMA_NODE_WEIGHTS=1,1,4
|
||
OLLAMA_ROUTING_MODE=least_inflight
|
||
OLLAMA_NODE_MAX_INFLIGHT=1
|
||
OLLAMA_FAILOVER_ENABLED=true
|
||
OLLAMA_FAILOVER_ATTEMPTS=0
|
||
OLLAMA_REQUIRE_SAME_MODEL_DIGEST=true
|
||
OLLAMA_REQUIRE_EMBEDDING_MODEL=true
|
||
```
|
||
|
||
Unterstützte Routing-Modi:
|
||
|
||
- `least_inflight` – bevorzugt den aktuell am wenigsten belasteten Node;
|
||
- `round_robin` – zyklische Verteilung;
|
||
- `weighted` – Verteilung entsprechend `OLLAMA_NODE_WEIGHTS`;
|
||
- `fastest_recent` – bevorzugt die zuletzt schnellsten Nodes.
|
||
|
||
Jeder Node muss das Chatmodell besitzen. Mit `OLLAMA_REQUIRE_EMBEDDING_MODEL=true` muss außerdem jeder Node das Embeddingmodell besitzen. Bei aktivierter Digest-Prüfung wird ein Pool mit unterschiedlichen Modellständen fail-closed behandelt.
|
||
|
||
Mehr Details: [`OLLAMA-POOL.md`](OLLAMA-POOL.md).
|
||
|
||
## GLPI-Knowledgebase einbeziehen
|
||
|
||
Die Integration verwendet denselben read-only OAuth-/OpenAPI-Ansatz wie der Agent. GLPI entscheidet anhand des Service-Accounts, welche Beiträge sichtbar sind.
|
||
|
||
```env
|
||
GLPI_KB_ENABLED=true
|
||
GLPI_URL=https://glpi.example.org
|
||
GLPI_API_VERSION=v2.3
|
||
GLPI_CLIENT_ID=...
|
||
GLPI_CLIENT_SECRET=...
|
||
GLPI_USERNAME=...
|
||
GLPI_PASSWORD=...
|
||
GLPI_KB_PATH=auto
|
||
GLPI_KB_LIMIT=500
|
||
GLPI_KB_SYNC_INTERVAL=10m
|
||
GLPI_KB_SOURCE=GLPI Knowledge Base
|
||
```
|
||
|
||
Bei `GLPI_KB_PATH=auto` sucht das Brain im GLPI-OpenAPI-Dokument die lesbare `KnowbaseItem`-Collection. Die Beiträge werden als produktive Wissens-Nodes mit `glpi://KnowbaseItem/<id>`-URI aufgenommen. Kategorien und Quelle erzeugen verifizierte Edges. Es gibt keine GLPI-Schreiboperation.
|
||
|
||
Manueller Sync:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8090/api/glpi-kb/sync
|
||
```
|
||
|
||
Mehr Details: [`GLPI-KB.md`](GLPI-KB.md).
|
||
|
||
## Gebündelte Persistenz
|
||
|
||
```env
|
||
BRAIN_PERSIST_INTERVAL=5m
|
||
```
|
||
|
||
Im Arbeitsspeicher sind neue Nodes, Edges und AI-THINK-Ergebnisse sofort verfügbar. Auf die Festplatte wird jedoch sequenziell geschrieben:
|
||
|
||
1. ausstehende AI-THINK- und Cache-Dateien atomar, Pfad für Pfad;
|
||
2. anschließend genau ein Graph-Snapshot;
|
||
3. zusätzlich ein finaler Flush beim geregelten Shutdown.
|
||
|
||
Das reduziert Schreibzugriffe deutlich. Der Preis ist ein konfigurierbares Durability-Fenster: Bei einem harten Stromausfall können die seit dem letzten Flush entstandenen Änderungen fehlen.
|
||
|
||
Manueller Flush:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8090/api/flush
|
||
```
|
||
|
||
Mehr Details: [`PERSISTENCE.md`](PERSISTENCE.md).
|
||
|
||
## Laufzeitsteuerung und Honeycomb
|
||
|
||
Die untere Steuerleiste enthält direkte Schalter für **LEARNING**, **THINKING**, **NEURAL** und **HONEYCOMB**. Sind Learning und Thinking deaktiviert, bleibt das System im Living-Modus; eingehende Agent- oder KB-Anfragen können weiterhin die tatsächlich verwendeten Notes aktivieren.
|
||
|
||
Über **FILTER** lassen sich drei unabhängige Kategorienlisten pflegen:
|
||
|
||
- **Lernen**: neue Embeddings nur für passende Kategorien;
|
||
- **Anzeige**: Browser-Rendering nur für passende Notes;
|
||
- **Thinking**: neue AI-THINK-Kandidaten nur innerhalb der gewählten Kategorien.
|
||
|
||
Leere Listen bedeuten „alle Kategorien“. Die Werte werden über die vorhandene Persistenzqueue in `runtime-settings.json` geschrieben.
|
||
|
||
```env
|
||
BRAIN_LEARNING_ENABLED=true
|
||
BRAIN_THINKING_ENABLED=true
|
||
BRAIN_LEARNING_CATEGORIES=
|
||
BRAIN_DISPLAY_CATEGORIES=
|
||
BRAIN_THINKING_CATEGORIES=
|
||
BRAIN_DEFAULT_VIEW=neural
|
||
```
|
||
|
||
Honeycomb rendert nur `knowledge`, `ai-think` und `external`. Ein 3D-Gitter mit einheitlichem Punktabstand wird auf die Gehirngeometrie beschnitten und automatisch an die sichtbare Anzahl von Notes angepasst. Edges, LOD-Gruppen und Cortex-Flächen bleiben dort unsichtbar; bei einer Anfrage leuchten nur die referenzierten Notes.
|
||
|
||
Mehr Details: [`RUNTIME-CONTROLS-HONEYCOMB.md`](RUNTIME-CONTROLS-HONEYCOMB.md).
|
||
|
||
## Autonome Anreicherung
|
||
|
||
Der Worker arbeitet bewusst sequenziell:
|
||
|
||
1. Kandidatenpaar aus bestehenden Vektoren auswählen;
|
||
2. Beziehung durch Qwen mit festem JSON-Schema prüfen;
|
||
3. Edge als `staging` oder `rejected` im In-Memory-Graph ablegen;
|
||
4. optional kontrolliert recherchieren;
|
||
5. AI-THINK-Entwurf in die Schreibwarteschlange legen;
|
||
6. beim nächsten Persistenz-Flush atomar in Staging schreiben.
|
||
|
||
```env
|
||
BRAIN_AUTO_ENRICH=true
|
||
BRAIN_ENRICH_INTERVAL=90s
|
||
BRAIN_ENRICH_BATCH_SIZE=3
|
||
BRAIN_ENRICH_STEP_DELAY=3s
|
||
```
|
||
|
||
Der manuelle AI-THINK-Button bleibt vorhanden. Alternativ:
|
||
|
||
```bash
|
||
curl -X POST 'http://localhost:8090/api/enrich?async=1'
|
||
```
|
||
|
||
## HTTP-Endpunkte
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| `GET` | `/api/status` | Gesamtstatus inklusive Ollama-Pool, GLPI-KB und Persistenzqueue |
|
||
| `GET` | `/api/graph` | vollständiger aktueller In-Memory-Graph |
|
||
| `GET` | `/api/analysis` | strukturelle Graphanalyse |
|
||
| `GET` | `/api/runtime-settings` | aktuelle Learning-, Thinking-, Filter- und View-Einstellungen |
|
||
| `PUT` | `/api/runtime-settings` | Laufzeiteinstellungen ändern und gebündelt persistieren |
|
||
| `GET` | `/api/categories` | verfügbare Note-Kategorien mit Anzahl |
|
||
| `GET` | `/api/stream` | SSE-Aktivitätsstrom |
|
||
| `POST` | `/api/query` | programmatische Wissensanfrage; in der Fullscreen-UI verborgen |
|
||
| `POST` | `/api/events` | optionale Agent-/KB-Telemetrie |
|
||
| `POST` | `/api/reindex` | lokaler Scan und Embedding-Abgleich |
|
||
| `POST` | `/api/enrich` | AI-THINK-Zyklus einplanen/ausführen |
|
||
| `POST` | `/api/glpi-kb/sync` | GLPI-KB manuell synchronisieren |
|
||
| `POST` | `/api/flush` | ausstehende Dateien und Graph sofort persistieren |
|
||
|
||
Mit `BRAIN_API_KEY` werden POST-Endpunkte über `Authorization: Bearer …` oder `X-Brain-Key` geschützt.
|
||
|
||
## Statusdiagnose
|
||
|
||
```bash
|
||
curl http://localhost:8090/api/status | jq
|
||
```
|
||
|
||
Wichtige Bereiche:
|
||
|
||
- `ollama_pool.nodes[]`: Health, Kompatibilität, Inflight, Requests, Fehler und mittlere Laufzeit;
|
||
- `glpi_kb`: letzter Sync, Dokumentanzahl, Pfad und Fehler;
|
||
- `persistence`: ausstehende Dateien, Dirty-Status, letzter Flush und Flush-Fehler;
|
||
- `enrich_*`: Zustand des autonomen AI-THINK-Workers.
|
||
|
||
## Validierung
|
||
|
||
```bash
|
||
go test ./...
|
||
go vet ./...
|
||
node --check internal/web/static/app.js
|
||
```
|