glpi-ai-agent/UPGRADE.md

Upgrade-Hinweise: Learning + Web-KB

Neue/empfohlene Variablen

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:

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:

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:

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:

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:

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:

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:

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.