Files

team 1 f0a483198a new Overview

2026-04-15 09:42:36 +02:00

16 KiB

Raw Blame History

RAG_SYSTEM_OVERVIEW.md

RetrieX – 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.

Das bedeutet:

Antworten sollen nicht frei erfunden werden
Wissen stammt primär aus den aktivierten Dokumenten im System
die KI formuliert auf Basis von abgerufenem Kontext
bei Produktanfragen können zusätzlich Live-Shopdaten einbezogen werden

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

versionierten Wissensdokumenten
deterministischem Ingest
hybridem Retrieval
optionaler Commerce-Erweiterung
LLM-basierter Formulierung der Antwort

Die Hauptbausteine des Systems

1. Dokumente als Wissensbasis

Die Wissensbasis besteht aus hochgeladenen Dokumenten, zum Beispiel:

PDF
DOCX
Markdown
TXT

Diese Dokumente werden nicht direkt „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
Laufzeit-Metadaten werden aktualisiert

Der Ingest ist bewusst deterministisch aufgebaut.
Das heißt: derselbe Datenstand soll immer wieder 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:

Vektor-Retrieval über FAISS
zusätzliches Tag-Routing zur Vorselektion möglicher Dokumente
Score-basierte Auswahl relevanter Chunks
Sonderroute für Katalog-/Listenanfragen
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

Erst danach erzeugt das Sprachmodell die eigentliche Antwort.

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

Architektur in vier Ebenen

1. Primärquellen

Primärquellen sind die fachlichen Eingaben des Systems:

Dokumente
Dokumentversionen
aktive System-Prompts
Modellkonfiguration
optional externe Shopdaten

Diese Ebene bestimmt, welches Wissen und welche Regeln überhaupt 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
URL-Auswertung
Retrieval
Intent-Erkennung
Shop-Suche
Prompt-Aufbau
Streaming der Modellantwort
Historienpersistenz

Zentrale Klasse für die Laufzeit ist hier insbesondere der AgentRunner.

4. Ausgabe- und UI-Ebene

Die Antwort wird per Server-Sent Events (SSE) gestreamt.

Dadurch erhält das Frontend die Ausgabe schrittweise, statt auf eine vollständige Blockantwort zu warten.

Der aktuelle Projektstand setzt für Browser-Streaming bevorzugt auf SSE.

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
dient als 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 die Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.

index_runtime.json

index_runtime.json enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, zum Beispiel aktualisierte Chunk-Zählungen.

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

Diese wird für Tag-Routing bzw. thematische Vorselektion verwendet.

Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.

Dokument-Lifecycle

1. Dokument anlegen

Ein Dokument wird als fachliche Einheit gespeichert.

2. Versionen verwalten

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

3. Aktivierung

Wird eine Version aktiviert, wird nicht einfach nur „ein Text ausgetauscht“, sondern ein definierter Prozess ausgelöst.

4. IngestJob

Die Aktivierung führt in die Ingest-Orchestrierung.

5. Chunk-Erzeugung

Aus der aktiven Version werden Chunk-Records erzeugt.

6. NDJSON-Update

Bestehende Chunks des betroffenen Dokuments werden entfernt und durch neue ersetzt.

7. Vollständiger Vector-Rebuild

Anschließend wird der gesamte FAISS-Index aus dem aktuellen NDJSON-Bestand neu gebaut.

Ingest-Logik im aktuellen Stand

Der Ingest ist in mehrere spezialisierte Services getrennt.

GuardrailValidator

Prüft, ob der aktuelle Indexzustand mit der erwarteten Struktur kompatibel ist.

Wenn nicht, wird lokaler Ingest blockiert.

ChunkWriteService

Kapselt die Schreibvorgänge auf der Chunk-Ebene, insbesondere:

Chunks zählen
Chunks für ein Dokument entfernen
neue Chunks anhängen
gesamten NDJSON-Bestand neu schreiben

VectorRebuildService

Verantwortet den vollständigen Rebuild des Vektorindex und die Aktualisierung der Runtime-Metadaten.

IngestFlow

Der IngestFlow orchestriert den Gesamtprozess.

Für Dokument-Ingest bedeutet das insbesondere:

Guardrail prüfen
Status auf laufend setzen
alte Dokument-Chunks entfernen
neue Chunks streamingfähig anhängen
Chunk-Limits überwachen
Vector-Rebuild auslösen
finalen Status setzen

Guardrails und Reproduzierbarkeit

RetrieX schützt sich bewusst gegen strukturellen Drift.

Wenn sich zentrale Indexparameter ändern, etwa:

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

dann darf ein lokaler Ingest nicht stillschweigend in einen inkompatiblen Index hineinschreiben.

Stattdessen wird ein Global Reindex erforderlich.

Das verhindert inkonsistente Mischzustände.

Global Reindex

Ein Global Reindex unterscheidet sich bewusst vom lokalen Dokument-Ingest.

Dabei passiert:

alle aktiven Dokumente werden neu verarbeitet
index.ndjson wird vollständig neu geschrieben
der Vektorindex wird komplett neu gebaut
die index_version wird erhöht

Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sauber auf den gesamten Wissensbestand anzuwenden.

Retrieval zur Anfragezeit

Hybrid-Retrieval

Das aktuelle System verwendet kein rein lineares Suchmodell, sondern kombiniert mehrere Schritte:

Query-Cleaning
Query-Enrichment
Intent-Erkennung
Tag-Routing
globale Vektorsuche
optional gescopte Vektorsuche auf Kandidatendokumente
Fusion und Auswahl relevanter Chunks

Das Ziel ist nicht einfach „mehr Treffer“, sondern passendere, stabilere Kontexterzeugung.

Tag-Routing

Vor der eigentlichen Chunk-Auswahl kann das System thematisch passende Dokumente über Tags eingrenzen.

Das reduziert die Suchfläche und erhöht die Wahrscheinlichkeit, dass relevante Dokumente bevorzugt werden.

Katalog-/Listenroute

Für bestimmte Anfragen erkennt das System, dass keine klassische Chunk-Antwort, sondern eher eine Listen- oder Katalogausgabe sinnvoll ist.

Dann kann statt normaler Chunk-Selektion ein Katalogblock erzeugt werden.

Ergebnisbegrenzung

Die Zahl der zurückgegebenen Wissens-Chunks ist konfigurationsgetrieben.

Wichtige Steuergrößen sind:

retrievalMaxChunks
retrievalVectorTopK

Diese Werte stammen aus der aktiven Modell-/Generierungskonfiguration.

Commerce-Erweiterung und Shop-Suche

Ein zentrales Merkmal des aktuellen Systemstands ist die optionale Shopware-Store-API-Anbindung.

Diese wird nicht immer verwendet, sondern nur dann, wenn die Anfrage nach Commerce-Logik aussieht.

CommerceIntentLite

Die Anfrage wird heuristisch auf Commerce-Signale geprüft, zum Beispiel:

Produktsuche
Preisbezug
Größen-/Farbhinweise
SKU-ähnliche Nummern
typische Produkt- oder Empfehlungsfragen

Das Ergebnis ist einer von drei Zuständen:

none
product_search
advisory_product_search

CommerceQueryParser

Wenn Commerce erkannt wird, wird die Nutzeranfrage deterministisch aufbereitet.

Dabei werden strukturierte Suchinformationen abgeleitet, etwa:

Suchkern
Preis
Größe
Farbe
weitere Suchsignale

ShopSearchService

Der ShopSearchService baut daraus eine Shopware-Store-API-Anfrage und mappt die Ergebnisse in ein internes, schlankes Produktformat.

Typische Produktinformationen sind dann:

Name
Produktnummer
Hersteller
Preis
Verfügbarkeit
URL
Beschreibung
Bild
ausgewählte Zusatzinformationen

Rolle der Shopdaten

Shopdaten werden im Prompt ausdrücklich als authoritative for products behandelt.

Das bedeutet:

für reale Produktdaten sind Live-Shopdaten führend
Wissens-Chunks bleiben unterstützend
das System trennt damit Produktwahrheit und Dokumentwissen bewusst voneinander

Balance zwischen Shop und Wissen

Wenn Commerce aktiv ist, wird die Zahl der Wissens-Chunks reduziert:

bei product_search stärker
bei advisory_product_search moderat

So soll verhindert werden, dass Shopdaten im finalen Prompt von allgemeinen Wissens-Chunks verdrängt werden.

URL-Auswertung

Wenn die Nutzeranfrage eine URL enthält, kann RetrieX den Inhalt dieser URL zusätzlich extrahieren.

Dazu wird:

die erste URL im Prompt erkannt
der Inhalt geladen
über Readability verarbeitet
HTML entfernt
Text normalisiert
auf eine maximale Länge begrenzt

Der extrahierte Inhalt wird anschließend als zusätzlicher unterstützender Wissensblock in den Prompt aufgenommen.

Das ist hilfreich, wenn ein Nutzer auf eine konkrete externe Quelle verweist.

Prompt-Aufbau

Der finale Prompt wird systematisch zusammengesetzt.

1. Systemblock

Der aktive System-Prompt wird aus der Datenbank geladen.

Er ist die führende Regel- und Verhaltensbasis des Modells.

2. Gesprächskontext

Frühere Nachrichten des Nutzers werden als autoritativer Konversationskontext eingebunden.

So bleibt der Dialog über mehrere Turns konsistent.

3. Live-Shop-Block

Wenn Shop-Ergebnisse vorliegen, werden diese als eigener Block eingebaut.

Sie sind für Produktfragen führend.

4. Retrieved Knowledge

Die ausgewählten Wissens-Chunks werden als unterstützender Wissensblock eingefügt.

5. URL-Content

Optional kommt zusätzlich extrahierter Webinhalt hinzu.

6. Nutzerfrage

Am Ende steht die aktuelle Benutzerfrage.

Antwort-Streaming

Die Antwort wird nicht gesammelt und dann komplett ausgeliefert, sondern als Stream übertragen.

AskSseController

Der AskSseController stellt den SSE-Endpunkt bereit.

Dabei werden:

Buffer geleert
Cookies weitergereicht
SSE-Header gesetzt
Daten als data:-Zeilen gesendet
am Ende ein done-Event ausgeliefert

Vorteil

Das Frontend kann Antworten live darstellen und laufend erweitern.

Das verbessert die Benutzererfahrung deutlich, besonders bei längeren Antworten.

Conversation Context und Historie

RetrieX verwaltet Nutzerkontext über eine eigene Context-Schicht.

Dazu gehören insbesondere:

Aufbau eines nutzerspezifischen Gesprächskontexts
Einbindung früherer Turns in den Prompt
Persistierung der finalen Antworthistorie

So kann das System nicht nur auf Einzelfragen, sondern auf fortlaufende Dialoge reagieren.

Modell- und Antwortsteuerung

Ein Teil des Systemverhaltens wird über Modellkonfigurationen gesteuert.

Dazu gehören fachlich und technisch insbesondere:

welches Modell verwendet wird
wie Retrieval parametriert ist
wie viele Chunks eingebunden werden
wie breit die Vektorsuche sucht
wie stark die Antwort durch System-Prompt und Kontext geprägt wird

Diese Konfiguration ist bewusst nicht „wild überschreibbar“, sondern an die aktiven Systemobjekte gebunden.

Was Admins fachlich steuern

Aus Admin-Sicht wird nicht nur „die KI“ gesteuert, sondern ein ganzes Wissens- und Antwortsystem.

Steuerbar sind unter anderem:

welche Dokumente im System existieren
welche Version aktiv ist
welche Ingest-Profile gelten
wann Reindexing ausgelöst wird
welcher System-Prompt aktiv ist
welche Modellkonfiguration aktiv ist
ob und wie Commerce integriert ist

Was die Antwortqualität tatsächlich beeinflusst

Die Qualität der Antworten hängt direkt von mehreren Ebenen ab:

1. Dokumentqualität

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

2. Aktivierungslogik

Nur aktive Versionen zählen.
Falsche Aktivierung bedeutet falscher Wissensstand.

3. Chunking

Chunk-Größe und Overlap beeinflussen, wie gut relevante Informationen später gefunden werden.

4. Retrieval-Konfiguration

Top-K, Auswahlgrenzen und Routing beeinflussen, welche Informationen überhaupt im Prompt landen.

5. System-Prompt

Der System-Prompt bestimmt Stil, Regelverhalten und Prioritäten der Ausgabe.

6. Commerce-Daten

Bei Produktfragen entscheidet die Qualität der Live-Shopdaten über die Produktwahrheit der Antwort.

Grundprinzipien des Systems

RetrieX folgt im aktuellen Stand diesen Grundprinzipien:

dokumentenzentriert statt modellzentriert
deterministisch statt zufällig orchestriert
reproduzierbar statt implizit
governance-fähig statt unkontrolliert
hybrid im Retrieval
erweiterbar durch Shopdaten
streamingfähig in der Ausgabe

Was RetrieX ausdrücklich nicht ist

RetrieX ist im aktuellen Design:

kein rein freier LLM-Chat
kein ausschließlich kreatives Generierungssystem
kein manuell gepflegter Chunk-Editor
kein Produktkatalog ohne Wissenslogik
kein rein vektorbasierter Blackbox-Sucher

Es ist ein kontrolliertes Antwortsystem, das Wissen, Routing, Produktdaten und Modellformulierung zusammenführt.

Kurz zusammengefasst

RetrieX arbeitet im Kern so:

Dokumente und Versionen definieren den Wissensstand
Ingest erzeugt daraus NDJSON-Chunks
daraus wird der FAISS-Index vollständig neu aufgebaut
bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche
PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten
das Modell formuliert daraus die Antwort
die Ausgabe wird per SSE ins Frontend gestreamt

Kurzform:

Dokumente → Ingest → NDJSON → Vector Index → Retrieval → Prompt-Aufbau → LLM-Antwort → SSE-Streaming

Merksatz

Sie steuern in RetrieX nicht einfach nur ein Modell.
Sie steuern die zugelassene Wissensbasis, die Suchlogik, die Antwortregeln und – bei Produktfragen – die produktbezogene Live-Datenquelle.

Die KI formuliert.
RetrieX bestimmt, worauf sie sich dabei stützen darf.

16 KiB Raw Blame History Unescape Escape