# Upgrade-Hinweise: Learning + Web-KB ## Neue/empfohlene Variablen ```env OLLAMA_NUM_PREDICT=768 OLLAMA_JSON_RETRIES=1 LEARNING_ENABLED=true LEARNING_MAX_EXAMPLES=500 LEARNING_EXAMPLES_PER_CATEGORY=5 # Nur bei authentifiziertem Dashboard aktivieren: KNOWLEDGE_WEB_EDIT_ENABLED=true ``` `KNOWLEDGE_DIR` bleibt statisch/read-only. Im Dashboard erzeugte Artikel werden automatisch unter `DATA_DIR/knowledge-managed/` gespeichert. Bestätigte Kategorie-Lernbeispiele liegen in `DATA_DIR/category-learning.json`. ## Gitea-Registry / Linux Das Image weiterhin in Gitea bauen. Auf dem Zielsystem ist kein lokaler Build erforderlich: ```bash export AGENT_IMAGE=gitea.example.de/organisation/glpi-ai-agent:latest mkdir -p data knowledge sudo chown 65532:65532 data docker compose -f docker-compose.registry.yml up -d --pull always ``` Der statische Ordner `./knowledge` bleibt read-only. Da Web-KB und Lernspeicher unter `./data` liegen, müssen nur die Daten für UID/GID `65532:65532` beschreibbar sein. ## Sicherer Start Für die ersten Lernläufe empfohlen: ```env DRY_RUN=true AUTO_CATEGORY=true AUTO_REPLY=false CATEGORY_CONFIDENCE=0.90 ``` Im Dashboard anschließend Entscheidungen bestätigen/korrigieren. Erst nach genügend beobachteten Tickets Schwellwerte oder Schreibrechte anpassen. ## GLPI Knowledge Base Connector Für den neuen read-only GLPI-KB-Sync ergänzen Sie bei Bedarf: ```env KNOWLEDGE_ALLOWED_SOURCES=internal-kb,glpi-kb GLPI_KB_ENABLED=true GLPI_KB_PATH=auto GLPI_KB_SYNC_INTERVAL=10m GLPI_KB_LIMIT=500 GLPI_KB_SOURCE=glpi-kb GLPI_KB_AUTO_REPLY=false GLPI_KB_AUTO_REPLY_CATEGORY_IDS= ``` Der sichere Start ist `GLPI_KB_AUTO_REPLY=false`. Erst nachdem die importierten Artikel im Dashboard geprüft wurden, sollte `glpi-kb` optional in `KNOWLEDGE_AUTO_REPLY_SOURCES` aufgenommen und eine explizite Whitelist von GLPI-Knowledge-Base-Kategorie-IDs gesetzt werden. ## Hybrid Knowledge Scoring Diese Version ersetzt den einzelnen Dokument-Cosine-Score durch ein Hybrid-Scoring mit Body-Chunks, Titel, Keywords und Kategorie-/Lernsignalen. Der bestehende `data/embeddings.json` Cache wird bei Bedarf automatisch im neuen Format aufgebaut; ein manuelles Löschen ist nicht erforderlich. Für bestehende `.env`-Dateien werden folgende Werte empfohlen: ```env KNOWLEDGE_MIN_SCORE=0.70 KNOWLEDGE_WEIGHT_SEMANTIC=0.50 KNOWLEDGE_WEIGHT_TITLE=0.25 KNOWLEDGE_WEIGHT_KEYWORDS=0.15 KNOWLEDGE_WEIGHT_CATEGORY=0.10 KNOWLEDGE_CHUNK_WORDS=160 KNOWLEDGE_CHUNK_OVERLAP_WORDS=30 KNOWLEDGE_MAX_CHUNKS_PER_DOC=24 ``` Der neue Hybrid-Score ist nicht direkt mit alten Cosine-Scores vergleichbar. Nach dem Upgrade zunächst im Dry-Run beobachten und den Mindestscore anhand realer Tickets kalibrieren. ## Dashboard / Knowledge-Editor v2 Das Dashboard wurde grundlegend überarbeitet. Es zeigt jetzt: - eine Betriebsübersicht mit GLPI-/Ollama-/GLPI-KB-Gesundheit, - die effektiven, nicht geheimen ENV-Werte gruppiert nach Agent, Ollama, RAG, GLPI-KB und Kontextquellen, - eine Detailansicht je Verarbeitung mit KI- und Policy-Entscheidung, - die Top-Knowledge-Kandidaten inklusive Hybrid-, Semantik-, Titel-, Keyword- und Kategorie/Lernscore, - die tatsächlich verwendeten Ticket-/KB-Chunks, - kompakte Details zu Changes, Major Incidents, Uptime-Kuma-Störungen und Benutzergeräten, - Filter für Verarbeitungen, Knowledge Base und Lernbeispiele. ### Geänderte Knowledge-API Der Webeditor verwendet jetzt explizite CRUD-Semantik: - `GET /api/knowledge/{id}` lädt einen Artikel frisch vom Server. - `POST /api/knowledge` legt einen neuen Web-Artikel an und liefert bei einer bereits existierenden ID `409 Conflict`. - `PUT /api/knowledge/{id}` aktualisiert ausschließlich einen bestehenden, Web-verwalteten Artikel. - Die ID eines Artikels kann beim Bearbeiten nicht geändert werden. - `DELETE /api/knowledge/{id}` löscht weiterhin nur Web-verwaltete Artikel. Statische Git-/Datei-Artikel und synchronisierte GLPI-KB-Artikel bleiben read-only. Neue Läufe speichern zusätzlich die Top-Knowledge-Kandidaten und kompakte Kontextdetails im Audit. Ältere `runs.jsonl`-Einträge bleiben kompatibel; dort sind diese neuen Detailfelder naturgemäß leer. ## Rich-Text-Antworten aus der GLPI Knowledge Base Synchronisierte GLPI-KB-Artikel behalten ab dieser Version zwei getrennte Darstellungen: - `text` / `answer`: bereinigter Plaintext für RAG, Ranking und LLM-Kontext. - `answer_html`: originales GLPI-Rich-Text-Markup ausschließlich für die spätere Ticketantwort. Dadurch bleiben bei Auto-Replies unter anderem Überschriften, Fett/Kursiv, Listen, Tabellen und Links erhalten. Das Rich-Text-Markup wird nicht an Ollama gesendet und beeinflusst keine Embeddings. Anrede und Signatur werden HTML-sicher um den KB-Inhalt ergänzt. Es sind keine neuen ENV-Variablen erforderlich. Nach dem Upgrade führt der initiale GLPI-KB-Sync automatisch dazu, dass `answer_html` im lokalen GLPI-KB-Cache ergänzt wird. ## Dynamisches Knowledge Top-K Für Installationen mit vielen Knowledge-Artikeln wird die Kandidatenauswahl ab dieser Version dynamisch begrenzt. Empfohlene Werte: ```env KNOWLEDGE_TOP_K=6 KNOWLEDGE_AUDIT_TOP_K=10 KNOWLEDGE_CANDIDATE_MAX_GAP=0.20 KNOWLEDGE_RETRIEVAL_FLOOR=0.30 ``` `KNOWLEDGE_TOP_K` ist die maximale Anzahl von Artikeln im Ollama-Prompt. Artikel werden nur übergeben, wenn sie mindestens den Retrieval-Floor erreichen und nicht mehr als `KNOWLEDGE_CANDIDATE_MAX_GAP` unter dem besten Treffer liegen. `KNOWLEDGE_AUDIT_TOP_K` steuert separat, wie viele Treffer für Dashboard/Audit aufbewahrt werden. Bestehende `.env`-Dateien sollten die drei neuen/angepassten Werte explizit ergänzen. ## Shared KB category compatibility Local knowledge JSON files may now use external string labels in `categories`. Recommended migration settings: ```env KNOWLEDGE_CATEGORY_MODE=unscoped KNOWLEDGE_CATEGORY_MAP_FILE=/app/data/knowledge-category-map.json KNOWLEDGE_IGNORE_GLOBS= ``` Unmapped labels no longer crash startup in `unscoped` mode. Such documents remain searchable but their `auto_reply` is disabled until all external labels are mapped. Use `skip` to ignore those documents or `strict` to retain fail-fast behavior. ## Große lokale Knowledge Bases (vNext) Lokale Knowledge-Verzeichnisse werden beim Prozessstart nicht mehr synchron vor dem HTTP-Server indexiert. Das WebUI startet zuerst; Scan, JSON-Validierung, Cache-Prüfung und Embeddings laufen anschließend im Hintergrund. Währenddessen gilt: - `/healthz` bleibt erreichbar. - `/readyz` liefert HTTP 503, bis GLPI, Ollama und die lokale Knowledge Base bereit sind. - Ticket-Polling und Worker starten erst nach erfolgreicher Knowledge-Initialisierung. - `/api/status` und das Dashboard zeigen Phase, Datei-/Dokumentfortschritt, Cache-Treffer, offene Embeddings und Fehler. - Bei einem fehlerhaften KB-Dokument bleibt das WebUI erreichbar und zeigt den Initialisierungsfehler an. Die Embedding-Erzeugung verarbeitet große Korpora dokumentweise in Batches. Nach dem ersten vollständigen Aufbau wird ein atomarer persistenter Snapshot geschrieben; spätere Starts verwenden diesen Snapshot und führen nur Delta-Scans aus. ## Persistenter inkrementeller Knowledge-Index Für große lokale KB-Bestände sollte die bestehende `.env` ergänzt werden: ```env KNOWLEDGE_INDEX_MODE=incremental KNOWLEDGE_EMBED_BATCH_SIZE=64 KNOWLEDGE_INDEX_SCAN_INTERVAL=5m ``` Der neue Snapshot liegt unter `DATA_DIR/knowledge-index/snapshot.gob`. Bei Docker muss `DATA_DIR` deshalb dauerhaft gemountet und für UID/GID `65532:65532` beschreibbar bleiben. `docker compose down -v` bzw. das Löschen des Host-Verzeichnisses entfernt auch den persistenten Index. Beim ersten Start dieser Version existiert noch kein Snapshot. Der Agent kann vorhandene gültige Vektoren aus dem bisherigen `DATA_DIR/embeddings.json` übernehmen und schreibt nach erfolgreichem Aufbau den neuen Snapshot. Danach wird `embeddings.json` für die lokale KB nicht mehr als primärer Index benötigt. Normaler Neustart in `incremental`: 1. Snapshot laden. 2. Knowledge sofort als `ready` markieren. 3. Ticketverarbeitung starten. 4. Quelldateien im Hintergrund per Größe/`mtime` vergleichen. 5. Nur geänderte Dateien lesen/hashen/parsen und nur geänderte Retrieval-Texte neu embedden. 6. Geänderten Snapshot atomar ersetzen. `KNOWLEDGE_INDEX_MODE=rebuild` erzwingt einen vollständigen Quellen-Scan. `readonly` verwendet ausschließlich den vorhandenen Snapshot und führt keine lokalen Delta-Scans aus. ## KI-Kennzeichnung Automatische Antworten tragen standardmaessig den TrustedNet-Kennzeichnungsblock am Anfang. Zum expliziten Aktivieren/Deaktivieren: `AI_CONTENT_LABEL_ENABLED=true|false`.