159 lines
7.0 KiB
Markdown
159 lines
7.0 KiB
Markdown
# 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 und schreibt periodische Cache-Checkpoints. Dadurch wird ein Verzeichnis mit vielen tausend Dateien nicht mehr als ein riesiger Embedding-Request im Speicher aufgebaut.
|