Files

team 1 f79062c336 update .md

2026-05-11 19:05:52 +02:00

18 KiB

Raw Permalink Blame History

RAG_SYSTEM_OVERVIEW.md

RetrieX v1.6.0 – Systemüberblick

Hinweis: Die Datei heißt weiterhin RAG_SYSTEM_OVERVIEW.md, das System selbst wird fachlich jedoch als RetrieX bezeichnet.

Grundidee

RetrieX ist ein dokumentenbasiertes Assistenzsystem mit Retrieval-Augmented Generation. Version 1.6.0 beschreibt den aktuellen Stand aus RAG-Kern, Commerce-Erweiterung, Chat-/Admin-Trennung, Rollenmodell und Governance-Guardrails.

Das bedeutet:

Antworten sollen nicht frei erfunden werden.
Wissen stammt primär aus aktivierten Dokumentversionen.
Die KI formuliert auf Basis von abgerufenem Kontext.
Bei Produktanfragen können Live-Shopdaten einbezogen werden.
Chat- und Adminzugang sind rollenbasiert getrennt.
Konfigurierbare Fachlogik liegt überwiegend in YAML statt im PHP-Core.

RetrieX ist damit kein frei antwortender Chatbot, sondern ein kontrolliertes System aus:

versionierten Wissensdokumenten
deterministischem Ingest
hybridem Retrieval
optionaler Commerce-Erweiterung
LLM-basierter Antwortformulierung
SSE-basierter Browserausgabe
rollenbasierter Betriebs- und Administrationslogik

Die Hauptbausteine des Systems

1. Dokumente als Wissensbasis

Die Wissensbasis besteht aus hochgeladenen Dokumenten, aktuell verifiziert für:

PDF
TXT
Markdown

Diese Dokumente werden nicht direkt zur Laufzeit vollständig gelesen, sondern in einen verarbeitbaren Wissensindex überführt.

Wichtige Eigenschaften:

Dokumente sind versioniert.
Pro Dokument gibt es fachlich genau eine aktive Version.
Nur aktive Inhalte fließen in den Wissensindex ein.
Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle.

Die eigentliche Wissensquelle sind also die aktiven Dokumentversionen, nicht frei bearbeitete Textfragmente.

2. Ingest und Indexierung

Sobald eine Dokumentversion ingestiert oder aktiviert wird, läuft ein technischer Verarbeitungsprozess.

Dabei passiert im Kern:

Dokumentinhalt wird extrahiert.
Inhalt wird in Chunks zerlegt.
Chunk-Datensätze werden in index.ndjson geschrieben.
Der Vektorindex wird vollständig neu aufgebaut.
Runtime-Metadaten werden aktualisiert.
Der Status der Version wird auf INDEXED gesetzt.

Der Ingest ist bewusst deterministisch aufgebaut. Derselbe Datenstand soll denselben Indexzustand erzeugen.

3. Retrieval zur Laufzeit

Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht das ganze Dokument direkt, sondern den vorbereiteten Wissensbestand.

Das Retrieval ist im aktuellen Stand hybrid und routingfähig:

Query Cleaning
Query Enrichment
Intent-Erkennung
Tag-Routing zur Kandidatendokument-Vorselektion
FAISS-Vektor-Retrieval
optionale gescopte Suche auf Kandidatendokumente
Score- und RRF-basierte Fusion
Sonderroute für Katalog-/Listenanfragen
Präzisionsrouten für exakte Tabellen-/Grenzwert-/Indikatorfragen
optionale Ergänzung durch Live-Shopdaten bei Commerce-Intent

Das System liefert also nicht einfach irgendwelche Treffer, sondern baut einen gezielten Kontextblock für das Modell.

4. Antwortgenerierung

Aus den ermittelten Informationen wird ein finaler Prompt aufgebaut.

Dieser Prompt kann aus mehreren Blöcken bestehen:

aktiver System-Prompt
Gesprächskontext des Nutzers
Live-Shop-Ergebnisse
abgerufene Wissens-Chunks
optional extrahierter Inhalt einer URL aus der Nutzeranfrage
aktuelle Nutzerfrage

Die KI ist damit die Formulierungsinstanz, nicht die eigentliche Wissensquelle.

5. Chat, Admin und Betrieb

Version 1.6.0 trennt den öffentlichen Chat-Einstieg architektonisch vom Adminbereich:

Chat: /, /chat, /chat/login, /chat/logout
Chat-APIs: /ask-jobs, /ask-sse, /ask-sse/{jobId}, /history, /chat-messages/frontend
Admin: /admin...

Beide Bereiche nutzen denselben User-Provider, aber getrennte Firewalls und Rollenregeln. Dadurch kann ein Benutzer z. B. nur Chatrechte, nur Adminbasisrechte oder erweiterte Adminrechte besitzen.

Architektur in fünf Ebenen

1. Primärquellen

Primärquellen sind die fachlichen Eingaben des Systems:

Dokumente
Dokumentversionen
aktive System-Prompts
Modellkonfiguration
YAML-Konfigurationen
optional externe Shopdaten

Diese Ebene bestimmt, welches Wissen und welche Regeln verwendet werden dürfen.

2. Index- und Retrieval-Ebene

Diese Ebene erzeugt und verwaltet den Suchraum:

index.ndjson als Chunk-Quelle
index_meta.json als Struktur- und Governance-Metadaten
index_runtime.json als Laufzeitstatus
vector.index als FAISS-Index
tags.ndjson und vector_tags.index für Tag-Routing

Diese Ebene ist für Suche, Relevanz und Reproduzierbarkeit zuständig.

3. Orchestrierungsebene

Diese Ebene verbindet alle Teile des Systems:

Anfrageannahme
Client-ID-Auflösung
Gesprächskontext
URL-Auswertung
Retrieval
Intent-Erkennung
Shop-Suche
Query-Reparatur
Prompt-Aufbau
Streaming der Modellantwort
Historienpersistenz

Zentrale Laufzeitklasse ist AgentRunner.

4. Ausgabe- und UI-Ebene

Die Antwort wird per Server-Sent Events gestreamt.

Die UI kann anzeigen:

laufende Statusphasen
Datenbasis und Confidence-Hinweise
RAG-/Shop-Quellen
Shopkarten
gesendete Shopquery oder Einzelqueries
Follow-up-Actions wie Preis anzeigen, nur Zubehör anzeigen oder technische Details anzeigen

Seit den neueren v1.6.0-Patches sind Follow-up-Actions kontextsensitiver und vermeiden Selbstloops, wenn dieselbe Shopquery bereits ausgeführt wurde.

5. Betriebs- und Governance-Ebene

Diese Ebene umfasst:

Chat-/Admin-Firewalls
Rollenmatrix
Admin-Userverwaltung
Aktiv-/Inaktiv-Loginprüfung
Access-Denied-Handler
403/404/500-Fehlerseiten
Konfigurationsvalidierung
Source-Audit
Core-Pattern-Audit
Regressionstests

Damit wird RetrieX nicht nur fachlich, sondern auch organisatorisch betreibbar.

Wissensspeicher und Indexdateien

`index.ndjson`

index.ndjson ist die zentrale Chunk-Datei des Systems.

Eigenschaften:

NDJSON statt großes JSON-Array
streamingfähig
append-/rewrite-fähig
geeignet für größere Bestände
operative Grundlage für den Vector-Rebuild

Jede Zeile repräsentiert einen Chunk-Datensatz.

`index_meta.json`

index_meta.json beschreibt den strukturellen Zustand des Index.

Beispielhafte Inhalte:

index_version
embedding_model
embedding_dimension
chunk_size
chunk_overlap
scoring_version
index_format
vector_backend

Diese Datei ist wichtig für Guardrails. Wenn sich Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.

`index_runtime.json`

index_runtime.json enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, z. B. Chunk-Zählungen und Rebuild-Zeitpunkte.

Diese Datei dient nicht als Primärquelle, sondern als technische Betriebsmetadatei.

`vector.index`

vector.index ist der FAISS-Vektorindex des Systems.

Er wird nicht manuell gepflegt, sondern aus index.ndjson neu erzeugt.

`tags.ndjson` und `vector_tags.index`

Neben dem Hauptindex existiert eine Tag-Ebene:

tags.ndjson
vector_tags.index
vector_tags.index.meta.json

Diese Ebene unterstützt Tag-Routing und Kandidatendokument-Vorselektion.

Dokument-Lifecycle

1. Dokument anlegen

Ein Dokument wird als fachliches Objekt im Adminbereich gepflegt.

2. Versionen verwalten

Dokumente besitzen Versionen. Diese Versionen sind der eigentliche inhaltliche Träger.

3. Aktivierung

Wird eine Version aktiviert, wird ein definierter Prozess ausgelöst. Die aktive Version bestimmt den Wissensstand des Dokuments.

4. IngestJob

Ingest-Jobs führen den Verarbeitungsprozess nachvollziehbar aus.

5. Chunk-Erzeugung

Aus der aktiven Version werden Chunk-Records erzeugt.

6. NDJSON-Update

Der Chunk-Bestand wird dokumentbezogen aktualisiert.

7. Vollständiger Vector-Rebuild

Nach relevanten Ingest-Schritten wird der FAISS-Index vollständig neu aufgebaut.

Ingest-Logik

`GuardrailValidator`

Prüft, ob der bestehende Index strukturell zur aktiven Konfiguration passt.

`ChunkWriteService`

Kapselt Schreiboperationen auf index.ndjson.

`VectorRebuildService`

Baut den Vektorindex neu und aktualisiert Runtime-Metadaten.

`IngestFlow`

Orchestriert Einzel-Ingest, Global Reindex und Lösch-/Reset-Flows.

Guardrails und Reproduzierbarkeit

RetrieX schützt sich gegen strukturellen Drift.

Lokaler Ingest darf nicht weiterlaufen, wenn sich z. B. diese Strukturparameter geändert haben:

Embedding-Modell
Embedding-Dimension
Chunk-Größe
Chunk-Overlap
Scoring-Version
Indexformat
Vector-Backend

Dann ist ein Global Reindex erforderlich.

Global Reindex

Der Global Reindex baut den operativen Wissensbestand aus den aktiven Dokumentversionen neu auf.

Ziel:

konsistenter Chunk-Bestand
konsistenter Vektorindex
aktualisierte Runtime-Metadaten
reproduzierbarer Systemzustand

In v1.6.0 ist der Global-Reindex-Zugriff serverseitig und im Admin-UI auf ROLE_SUPER_ADMIN eingeschränkt.

Retrieval zur Anfragezeit

Hybrid-Retrieval

Der aktive Retriever kombiniert mehrere Signale:

bereinigte Nutzerfrage
Query-Enrichment-Regeln
Intent-Routing
Vektortreffer
Tag-Routing
gescopte Suche
RRF-/Score-Fusion
dokumentbezogene Begrenzung

Tag-Routing

Tags können Kandidatendokumente vorselektieren. Dadurch kann die spätere Vektorsuche fokussierter laufen.

Katalog-/Listenroute

Katalog- oder Listenfragen können direkt in einen Katalogblock führen, statt nur einzelne Textchunks zu liefern.

Ergebnisbegrenzung

Parameter aus retrieval.yaml, model.yaml und prompt.yaml begrenzen Kandidaten, Chunks und Promptbudget.

Commerce-Erweiterung und Shop-Suche

`CommerceIntentLite`

Erkennt, ob eine Anfrage Commerce-Relevanz hat.

Mögliche Zustände:

keine Commerce-Suche
Produktsuche
beratende Produktsuche

`CommerceQueryParser`

Bereinigt und normalisiert Shopqueries:

bekannte Marken behalten
Bedienphrasen entfernen
Tippfehler korrigieren
Token kanonisieren
Kontext-/Preservation-Tokens erhalten
Preis-/Farb-/Größenmuster erkennen

`ShopSearchService`

Führt die Shopware-Suche aus und kann Repair-Queries nachschieben, wenn primäre Treffer fehlen oder zu ungenau sind.

Rolle der Shopdaten

Shopdaten sind für Produktinformationen autoritativ, insbesondere für:

Produktname
Artikelnummer
Preis
Verfügbarkeit
Hersteller
Shop-URL
Shop-Beschreibung und Custom Fields

Balance zwischen Shop und Wissen

Shopdaten ersetzen nicht automatisch fachliche Eignungsbelege. Bei technischen Eignungsfragen müssen RAG-Kontext, Shopdaten und Prompt-Guardrails zusammenpassen.

v1.6.0 Commerce- und Follow-up-Guards

Version 1.6.0 enthält mehrere Präzisionsmechanismen:

Direkte Produktnamen werden in Shopqueries erhalten.
Noise-Tokens wie reine Bedien-, Relations- oder Denkmarker werden entfernt.
Tippfehler wie schwinnbad können zu schwimmbad korrigiert und erhalten werden.
Modellkürzel wie LAB CL bleiben erhalten, wenn sie im konfigurierten Kontext auftreten.
generische Geräteanfragen können auf exakte fachliche Produktanker aufgelöst werden, z. B. bei SiO2/Silikat.
Produktlisten-Follow-ups werden in einzelne Produktqueries aufgeteilt.
Produktanker-Kanonisierung ist YAML-gestützt statt im PHP-Core hartcodiert.
Exakte Zubehörcodes werden als exakte Codes behandelt.
Preis-Folgeaktionen verwenden sichtbare Produktidentitäten mit Produktnummern.
Schwache referenzielle Shopqueries können auf History-Modellanker zurückfallen.

URL-Auswertung

UrlAnalyzer extrahiert Inhalt aus der ersten URL in einer Nutzerfrage.

Der Inhalt wird als unterstützende Quelle in den Prompt aufgenommen, nicht als Primärindex gespeichert.

Prompt-Aufbau

Der final zusammengesetzte Prompt kann enthalten:

1. Systemblock

Aktiver System-Prompt.

2. Gesprächskontext

Historie des Nutzers, regulär oder explizit als Full-Context.

3. Live-Shop-Block

Shopware-Produkte mit Produktnummer, Preis, Verfügbarkeit, Hersteller, URL und weiteren Feldern.

4. Retrieved Knowledge

RAG-Chunks aus index.ndjson.

5. URL-Content

Optional extrahierter Inhalt einer URL.

6. Nutzerfrage

Aktuelle Frage.

Antwort-Streaming

`AskSseController`

Der Controller stellt zwei Streaming-Wege bereit:

Job-basierter Flow: POST /ask-jobs plus GET /ask-sse/{jobId}
direkter Flow: POST /ask-sse

Der Job-basierte Flow unterstützt Statusabfrage, Event-IDs, Replay/Tailing und Stale-Erkennung.

Vorteil

Der Browser erhält schrittweise Ausgabe und kann Statusinformationen, Shopkarten und Folgeaktionen während bzw. nach der Antwort anzeigen.

Conversation Context und Historie

ContextService speichert abgeschlossene Turns pro Client-ID.

Aktuelle Standardwerte:

regulär: 25 Zeilen
Full-Context: 500 Zeilen

Full-Context ist nicht mehr implizit der Browserstandard, sondern muss ausdrücklich angefordert werden.

Security und Rollenmodell

Firewalls

config/packages/security.yaml definiert getrennte Firewalls:

admin für ^/admin
chat für Chat-, Ask-, SSE-, History- und Frontend-Message-Routen
main für sonstige öffentliche/statische Ressourcen

Rollenmatrix

Bereich	Effektive Rolle
Chat, Ask/SSE, History, Frontend-Messages	`ROLE_CHAT_USER`
Admin-Dashboard, Guides, Jobs	`ROLE_ADMIN_AREA`
Dokumente, Versionen, Tags, Dokument-Ingest	`ROLE_EDITOR`
Modell-/Retrieval-Konfiguration, Ingest-Profile ansehen	`ROLE_KNOWLEDGE_ADMIN`
Userverwaltung, Logs, System Prompt/Agent, Global Reindex, Reset/Delete	`ROLE_SUPER_ADMIN`

ROLE_USER alleine reicht für keinen Bereich.

Admin-Bereich

Admins können je nach Rolle steuern:

Dokumente und Versionen
Tags und Tag-Zuweisungen
Ingest-Jobs
Global Reindex
Modell-/Retrieval-Konfiguration
Ingest-Profile
System Prompt
System Agent
Logs
Benutzerverwaltung

Die Admin-Navigation blendet Aktionen passend zur Rolle aus. Serverzugriffe sind zusätzlich über access_control und Controller-Checks geschützt.

Userverwaltung

Die Userverwaltung in v1.6.0 umfasst:

Liste, Anlage und Bearbeitung von Benutzern
Rollenzuweisung
Passwortsetzen
Aktiv-/Inaktiv-Schaltung
Self-Protection
Schutz des letzten aktiven Super-Admins
Loginblock für deaktivierte Benutzer
Session-Abmeldung für nachträglich deaktivierte Benutzer

Fehlerseiten und Access Denied

RetrieX rendert konsistente Fehlerseiten für:

403
404
500
generische Fehler

Der Access-Denied-Handler unterscheidet Chat- und Adminbereich und zeigt die benötigte Rolle sowie sinnvolle Rücksprung- und Logout-Optionen.

Modell- und Antwortsteuerung

Die Antwortqualität wird gesteuert durch:

aktiven System-Prompt
prompt.yaml
model.yaml
retrieval.yaml
language.yaml
vocabulary.yaml
commerce.yaml
search_repair.yaml
agent.yaml
genre.yaml
chat-messages.yaml

Viele fachliche Listen liegen bewusst in YAML und nicht hartcodiert im PHP-Core.

Was Admins fachlich steuern

Admins und Knowledge-Admins steuern je nach Rolle:

welche Dokumentversion aktiv ist
wann ingestiert oder reindiziert wird
welche System-Prompts aktiv sind
welche Modellkonfiguration genutzt wird
welche Ingest-Profile sichtbar bzw. aktiv sind
welche Benutzer Zugriff auf Chat oder Admin haben

Was die Antwortqualität tatsächlich beeinflusst

1. Dokumentqualität

Schlecht strukturierte oder inhaltlich schwache Dokumente führen zu schwachen Antworten.

2. Aktivierungslogik

Nur aktive Versionen zählen.

3. Chunking

Chunkgröße und Overlap beeinflussen, wie viel Kontext pro Treffer verfügbar ist.

4. Retrieval-Konfiguration

Schwellenwerte, Routing, Tag-Suche, Query-Enrichment und Ergebnisbegrenzung bestimmen den Kontext.

5. System-Prompt und Prompt-Regeln

Diese Regeln bestimmen, wie das Modell mit Wissen, Shopdaten, Unsicherheit und Quellen umgeht.

6. Commerce-Daten

Shopware-Daten beeinflussen Produkt-, Preis-, Verfügbarkeits- und Linkantworten.

7. Rollen und UI-Flows

Rollen, Loginstatus und Access-Denied-Verhalten bestimmen, welche Nutzer welche Funktionen erreichen.

Grundprinzipien des Systems

Keine freie Wissensbehauptung ohne Datenbasis.
Aktive Dokumentversionen sind fachliche Primärquelle.
Shopdaten sind autoritativ für Produkt-/Preis-/Verfügbarkeitsdaten.
Technische Eignung darf nicht aus Shopdaten allein überinterpretiert werden.
YAML ist Source of Truth für konfigurierbare Fachlogik.
PHP-Core soll Orchestrierung leisten, nicht Domainlisten verstecken.
Rollen müssen UI-seitig und serverseitig konsistent sein.
Regressionstests schützen bekannte stabile Flows.

Was RetrieX ausdrücklich nicht ist

RetrieX ist nicht:

ein frei improvisierender Chatbot
ein Ersatz für Datenpflege
ein Ersatz für validierte technische Beratung in Grenzfällen
ein manuell gepflegter Chunk-Editor
ein Shop-Scraper
ein unkontrollierter Prompt-Wrapper um ein LLM

Kurz zusammengefasst

Dokumente und Versionen definieren den Wissensstand.
Ingest erzeugt Chunks und FAISS-Indizes.
Retrieval sucht gezielt Kontext.
Commerce kann Shopware-Daten ergänzen.
PromptBuilder setzt Systemregeln, Kontext, Shopdaten und Frage zusammen.
Das LLM formuliert die Antwort.
SSE streamt die Antwort ins Frontend.
Rollen und Adminlogik steuern Zugriff und Betrieb.
YAML- und Audit-Guardrails schützen die Wartbarkeit.

Merksatz

RetrieX v1.6.0 ist kein Chatbot mit Dokumentanhang, sondern eine kontrollierte Antwortinfrastruktur aus Wissen, Suche, Shopdaten, Rollenmodell und Governance.

18 KiB Raw Permalink Blame History Unescape Escape