From 54ce057ef0902ccbc53793cbdbf28315ec08bab0 Mon Sep 17 00:00:00 2001 From: team2 Date: Sat, 28 Feb 2026 20:43:56 +0100 Subject: [PATCH] harden system --- MATRIX_PARAMS.md | 2 +- RAG_SYSTEM_OVERVIEW.md | 140 ++++++++++++++++++++++++++++ src/Intent/CatalogIntentLite.php | 4 +- templates/admin/base.html.twig | 30 ++++++ templates/admin/tag/index.html.twig | 3 +- 5 files changed, 175 insertions(+), 4 deletions(-) create mode 100644 RAG_SYSTEM_OVERVIEW.md diff --git a/MATRIX_PARAMS.md b/MATRIX_PARAMS.md index d4d1706..f1aee9f 100644 --- a/MATRIX_PARAMS.md +++ b/MATRIX_PARAMS.md @@ -1,4 +1,4 @@ -# Tabelle 1: Alle Parameter, die Retrieval beeinflussen (mit Kurz-Erklärung) +# Alle Parameter, die Retrieval beeinflussen (mit Kurz-Erklärung) | Ebene | Ort | Parameter | Standard / aktuell | Zweck / Einfluss | |---|---|---|---:|---| diff --git a/RAG_SYSTEM_OVERVIEW.md b/RAG_SYSTEM_OVERVIEW.md new file mode 100644 index 0000000..08d8e39 --- /dev/null +++ b/RAG_SYSTEM_OVERVIEW.md @@ -0,0 +1,140 @@ +# RAG-System - Wie funktioniert das System? + +## Grundidee + +Dieses System ist ein sogenanntes **RAG-System** (Retrieval Augmented Generation). + +Das bedeutet: + +> Die KI antwortet nicht frei oder kreativ, +> sondern ausschließlich auf Basis der hier hinterlegten Wissensdokumente. + +Oder einfacher gesagt: + +Die KI „weiß“ nur das, was Sie ihr hier als Dokumente geben. + +--- + +# Die drei Ebenen des Systems + +## 1. Dokumente (Ihre Wissensquelle) + +Sie laden Dokumente hoch (z. B. PDF, DOCX, Markdown, TXT). + +Diese Dokumente sind: + +- versioniert +- unveränderlich gespeichert +- die einzige Wissensgrundlage des Systems + +Wichtig: +Dokumente werden nicht direkt beantwortet, sondern technisch vorbereitet. + +--- + +## 2. Ingest & Indexierung (technische Aufbereitung) + +Sobald ein Dokument aktiviert wird: + +1. Es wird in kleinere Textabschnitte („Chunks“) zerlegt +2. Diese Chunks werden strukturiert gespeichert (NDJSON) +3. Der Vektorindex wird vollständig neu aufgebaut + +Nur aktive Dokumentversionen werden berücksichtigt. + +Das System arbeitet deterministisch und reproduzierbar. + +--- + +## 3. Anfrage & Antwort + +Wenn ein Nutzer im Frontend eine Frage stellt: + +1. Das System durchsucht den Index nach passenden Inhalten +2. Relevante Textstellen werden ausgewählt +3. Diese werden an das KI-Modell übergeben +4. Die KI formuliert daraus eine Antwort + +Die KI erfindet keine Inhalte. +Sie formuliert ausschließlich das, was in Ihren Dokumenten steht. + +--- + +# Steuerungsmöglichkeiten im Adminbereich + +Im Adminbereich können zentrale Parameter gesteuert werden. +Diese beeinflussen, wie das System antwortet und wie es Inhalte verarbeitet. + +## Modell- & Antwortparameter + +| Parameter | Bedeutung | Wirkung | +|------------|------------|----------| +| **Modell** | Auswahl des KI-Modells | Bestimmt Stil, Qualität und Sprachverhalten | +| **Temperatur** | Kreativitätsgrad der Antwort | Niedrig = sachlich & stabil, Hoch = freier formuliert | +| **Top K (LLM)** | Token-Auswahlbreite | Steuert Varianz bei der Wortauswahl | +| **Top P** | Wahrscheinlichkeitsfilter | Begrenzt unplausible Wortkombinationen | +| **Streaming** | Antwort wird live ausgegeben | Verbessert UX im Frontend | + +--- + +## Retrieval- & Wissensparameter + +| Parameter | Bedeutung | Wirkung | +|------------|------------|----------| +| **vectorTopK** | Anzahl gefundener Chunks | Mehr = breiter Kontext, weniger = fokussierter | +| **maxChunks** | Maximale Übergabe an das Modell | Begrenzt Kontextgröße | +| **Tag-Routing aktiv** | Aktiviert Tag-Vorselektion | Präzisere Themenfilterung | +| **Scoring-Version** | Bewertungslogik | Steuert Priorisierung relevanter Inhalte | + +--- + +## Ingest- & Indexparameter + +| Parameter | Bedeutung | Wirkung | +|------------|------------|----------| +| **Chunk-Größe** | Länge eines Textabschnitts | Klein = präziser, Groß = mehr Kontext | +| **Chunk-Overlap** | Überlappung zwischen Chunks | Verhindert Kontextverlust | +| **Embedding-Modell** | Modell für Vektorisierung | Bestimmt Suchqualität | +| **Global Reindex** | Vollständiger Neuaufbau | Erzwingt saubere Reproduzierbarkeit | + +--- + +# Was bedeutet das für Sie als Admin? + +Sie steuern: + +- Welche Dokumente aktiv sind +- Welche Versionen gültig sind +- Wie Inhalte indexiert werden +- Wie stark gefiltert wird +- Wie das Modell antwortet + +Die Qualität der Antworten hängt direkt ab von: + +- der Dokumentstruktur +- der Chunk-Logik +- der Retrieval-Konfiguration +- der Modellkonfiguration + +--- + +# Grundprinzip des Systems + +> „Wir nutzen KI nicht, um kreativ zu raten, +> sondern um verlässlich auf Basis Ihres Wissens zu antworten.“ + +Das System ist: + +- deterministisch +- versioniert +- governance-stabil +- reproduzierbar + +--- + +# Kurz zusammengefasst + +Dokumente → werden aufbereitet → indexiert → gezielt durchsucht → KI formuliert Antwort. + +Sie kontrollieren das Wissen. +Die KI formuliert es. \ No newline at end of file diff --git a/src/Intent/CatalogIntentLite.php b/src/Intent/CatalogIntentLite.php index 196a6df..a879ddf 100644 --- a/src/Intent/CatalogIntentLite.php +++ b/src/Intent/CatalogIntentLite.php @@ -29,13 +29,13 @@ final class CatalogIntentLite * Minimaler Similarity-Score. * Verhindert Rauschen. */ - private const MIN_SCORE = 0.50; + private const MIN_SCORE = 0.75; /** * Differenz zwischen Top1 und Top2, * damit kein unsicherer Treffer akzeptiert wird. */ - private const AMBIGUITY_DELTA = 0.01; + private const AMBIGUITY_DELTA = 0.03; public function __construct( private readonly TagVectorSearchClient $tagVectorClient, diff --git a/templates/admin/base.html.twig b/templates/admin/base.html.twig index aeac20e..c32c2dc 100644 --- a/templates/admin/base.html.twig +++ b/templates/admin/base.html.twig @@ -147,6 +147,36 @@ + \ No newline at end of file diff --git a/templates/admin/tag/index.html.twig b/templates/admin/tag/index.html.twig index 6941f38..7299463 100644 --- a/templates/admin/tag/index.html.twig +++ b/templates/admin/tag/index.html.twig @@ -154,7 +154,8 @@ + placeholder="Semantische Beschreibung des Tags" + required/>