# 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: 1. Dokumentinhalt wird extrahiert 2. Inhalt wird in Chunks zerlegt 3. Chunk-Datensätze werden in `index.ndjson` geschrieben 4. der Vektorindex wird vollständig neu aufgebaut 5. 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: 1. Dokumente und Versionen definieren den Wissensstand 2. Ingest erzeugt daraus NDJSON-Chunks 3. daraus wird der FAISS-Index vollständig neu aufgebaut 4. bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche 5. PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten 6. das Modell formuliert daraus die Antwort 7. 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.