new mds

MATRIX_PARAMS.md

@@ -1,38 +1,142 @@
-# Alle Parameter, die Retrieval beeinflussen (mit Kurz-Erklärung)
+# MATRIX_PARAMS.md
 
-| Ebene | Ort | Parameter | Standard / aktuell | Zweck / Einfluss |
-|---|---|---|---:|---|
-| **Config** | ModelGenerationConfig | retrievalMaxChunks | (dein Wert) | Wie viele Chunks maximal ans LLM gehen (Output-Limit). |
-| **Config** | ModelGenerationConfig | retrievalVectorTopK | (dein Wert) | Wie viele Vector-Hits initial geholt werden (Recall-Breite). |
-| **Retriever** | NdjsonHybridRetriever | HARD_MAX_CHUNKS | 200 | Harte Obergrenze für retrievalMaxChunks (Safety-Limit). |
-| **Retriever** | NdjsonHybridRetriever | HARD_MAX_VECTORK | 200 | Harte Obergrenze für retrievalVectorTopK/topK (Safety-Limit). |
-| **Retriever** | NdjsonHybridRetriever | VECTOR_SCORE_THRESHOLD | 0.40 | Qualitäts-Gate: Vector-Treffer darunter werden verworfen (stärkster Präzisionshebel). |
-| **Retriever** | NdjsonHybridRetriever | List-Mode TopK | max(vectorTopKBase*3, 80) | Bei Listenfragen wird TopK stark erhöht für bessere Dokumentabdeckung. |
-| **Retriever** | NdjsonHybridRetriever | isListQuery() | Heuristik | Aktiviert Dokument-Ranking statt reinem Chunk-Ranking. |
-| **Retriever** | NdjsonHybridRetriever | Dedup-Normalisierung | whitespace-normalized | Entfernt Duplikate im finalen Chunk-Set. |
-| **Tags** | TagRoutingService | DEFAULT_TOPK | 8 | Anzahl der geprüften Tag-Vector-Hits. |
-| **Tags** | TagRoutingService | MIN_BEST_SCORE | 0.10 (empf. 0.25) | Ab welchem Tag-Score ein Bonus aktiviert wird. |
-| **Tags** | TagRoutingService | MAX_CANDIDATE_DOCS | 200 | Maximale Anzahl Dokumente, die als Tag-Kandidaten gelten dürfen. |
-| **Tags** | NdjsonHybridRetriever | TAG_SCORE_BONUS | z. B. 0.08 | Bonus auf Vector-Score bei Tag-Match (nur Ranking, kein Gate). |
-| **Query** | QueryCleaner | clean($prompt) | implizit | Beeinflusst Embedding stark (Token-Normalisierung/Entfernung). |
-| **Vector** | VectorSearchClient | search($query, topK) | implizit | Liefert Roh-Scores und Trefferverteilung (Basis des Rankings). |
-| **Tag Vector** | TagVectorSearchClient | search($query, DEFAULT_TOPK) | implizit | Bestimmt, ob und welche Tags matchen (Bonus-Aktivierung). |
+# Retrieval-Matrix: alle relevanten Parameter und ihr realer Einfluss
 
+## Zweck dieser Datei
 
-# Tabelle 2: Auswirkungen bei Änderung der Parameter
+Diese Datei beschreibt die **realen Retrieval-Parameter im aktuellen Code-Stand** von RetrieX auf Basis der aktuellen `rag.zip`.
+
+Wichtig:
+
+- Die Datei beschreibt **Code-Defaults, Hard Limits und effektive Laufzeitlogik**
+- Die **aktiven DB-Werte** der `ModelGenerationConfig` sind aus dem Repository allein **nicht sicher ableitbar**
+- Wo kein aktiver DB-Wert aus dem ZIP belegbar ist, wird zwischen **Code-Default**, **Admin-Default** und **effektivem Clamp** unterschieden
+
+---
+
+# 1. Die wichtigsten Hebel in Kurzform
+
+Die Retrieval-Qualität wird im aktuellen Stand vor allem durch diese Hebel bestimmt:
+
+1. **`retrievalMaxChunks`**  
+   bestimmt, wie viele finale Chunks maximal ans LLM gehen
+
+2. **`retrievalVectorTopK`**  
+   bestimmt, wie breit die initiale Vektorsuche sucht
+
+3. **effektiver Score-Threshold im Retriever**  
+   bestimmt, welche Vector-Hits überhaupt in die Fusion gelangen
+
+4. **Tag-Routing**  
+   bestimmt, ob zusätzlich eine dokumentgescopte Suche ausgeführt wird
+
+5. **List-Intent / Sales-Intent**  
+   verändert TopK, Auswahlmodus und Scoping-Verhalten
+
+6. **Selektionsregeln pro Dokument**  
+   begrenzen Redundanz und Nachbarschaft ähnlicher Chunks
+
+---
+
+# 2. Matrix der Retrieval-Parameter
+
+| Ebene | Ort | Parameter / Konstante | Aktueller Wert | Effektiver Einfluss |
+|---|---|---:|---:|---|
+| **DB / Config** | `ModelGenerationConfig` | `retrievalMaxChunks` | Constructor-Default: `25` | Maximalzahl finaler Chunks vor Retriever-internem Clamp |
+| **DB / Config** | `ModelGenerationConfig` | `retrievalVectorTopK` | Constructor-Default: `25` | Basisbreite der initialen Vektorsuche vor Retriever-internem Clamp |
+| **DB / Guardrail** | `ModelGenerationConfig` | `MAX_RETRIEVAL_CHUNKS` | `200` | Harte Obergrenze beim Setzen des DB-Werts |
+| **DB / Guardrail** | `ModelGenerationConfig` | `MAX_VECTOR_TOPK` | `200` | Harte Obergrenze beim Setzen des DB-Werts |
+| **Admin-Erzeugung** | `ModelGenerationConfigAdminService` | `retrieval_max_chunks` | Fallback: `25` | Standardwert beim Anlegen neuer Configs im Admin |
+| **Admin-Erzeugung** | `ModelGenerationConfigAdminService` | `retrieval_vector_top_k` | Fallback: `25` | Standardwert beim Anlegen neuer Configs im Admin |
+| **Fallback ohne aktive DB-Config** | `ModelGenerationConfigProvider` | `retrievalMaxChunks` | implizit `25` | Greift nur, wenn keine aktive Config existiert |
+| **Fallback ohne aktive DB-Config** | `ModelGenerationConfigProvider` | `retrievalVectorTopK` | implizit `25` | Greift nur, wenn keine aktive Config existiert |
+| **Retriever** | `NdjsonHybridRetriever` | `HARD_MAX_CHUNKS` | `90` | Zusätzlicher harter Retriever-Clamp für finale Chunk-Zahl |
+| **Retriever** | `NdjsonHybridRetriever` | `HARD_MAX_VECTORK` | `250` | Zusätzlicher harter Retriever-Clamp für TopK; effektiv meist unter DB-Clamp |
+| **Retriever** | `NdjsonHybridRetriever` | `VECTOR_SCORE_THRESHOLD` | `0.75` | Formale Basisschwelle vor zusätzlichem Floor/Ceil |
+| **Retriever** | `NdjsonHybridRetriever` | `THRESHOLD_FLOOR` | `0.83` | Effektive Mindestschwelle; dominiert aktuell den Basisschwellenwert |
+| **Retriever** | `NdjsonHybridRetriever` | `THRESHOLD_CEIL` | `0.92` | Effektive Maximalschwelle |
+| **Retriever** | `NdjsonHybridRetriever` | `LIST_BONUS` | `1.25` | Erhöht `topK` bei Listenfragen auf `round(base * 1.25)` |
+| **Retriever** | `NdjsonHybridRetriever` | `MAX_CHUNKS_PER_DOC` | `2` | Maximal zwei finale Chunks pro Dokument im Sales-Modus |
+| **Retriever** | `NdjsonHybridRetriever` | `MIN_CHUNK_DISTANCE` | `2.5` | Verhindert zu nahe Chunk-Nachbarn aus demselben Dokument |
+| **Retriever** | `NdjsonHybridRetriever` | `RRF_K` | `60` | Steuert die Reciprocal-Rank-Fusion |
+| **Retriever** | `NdjsonHybridRetriever` | Scoped RRF Boost | `1.2` | Scoped Hits werden nur in bestimmten Fällen stärker gewichtet |
+| **Retriever** | `NdjsonHybridRetriever` | `EMPTY_RRF_FALLBACK_TOPN` | `1` | Falls Fusion leer bleibt, wird maximal ein Top-Hit in Fallback-RRF überführt |
+| **Intent** | `IntentLite` | `LIST_THRESHOLD` | `4` | Ab Score 4 wird Listenmodus aktiviert |
+| **Intent** | `SalesIntentLite` | `MIN_SCORE_THRESHOLD` | `3` | Mindestscore, damit ein Nicht-Discovery-Intent akzeptiert wird |
+| **Intent** | `SalesIntentLite` | `DOMINANCE_DELTA` | `2` | Top-Intent muss den zweiten Intent um mindestens 2 Punkte schlagen |
+| **Vector Client** | `VectorSearchClient` | `MIN_SCORE` | `0.30` | Vorfilter im PHP-Client für Chunk-Vektortreffer |
+| **Vector Client** | `VectorSearchClient` | `MAX_LIMIT` | `200` | Hard Clamp für Anfragen an den Chunk-Vector-Service |
+| **Tag Vector Client** | `TagVectorSearchClient` | `MIN_SCORE` | `0.72` | Vorfilter für Tag-Vektortreffer |
+| **Tag Vector Client** | `TagVectorSearchClient` | `MAX_LIMIT` | `50` | Hard Clamp für Anfragen an den Tag-Vector-Service |
+| **Tag Routing** | `TagRoutingService` | `DEFAULT_TOPK` | `8` | Anzahl der Tag-Treffer, die initial geprüft werden |
+| **Tag Routing** | `TagRoutingService` | `MIN_BEST_SCORE` | `0.25` | Zusätzliche Gate-Schwelle nach Tag-Search; aktuell praktisch nicht limitierend |
+| **Tag Routing** | `TagRoutingService` | `MAX_CANDIDATE_DOCS` | `200` | Maximalzahl an Dokumenten, die aus Tags als Kandidatenmenge entstehen dürfen |
+| **Query-Aufbereitung** | `QueryCleaner` | Stopword-Filter | aktiv | Entfernt Stopwörter vor der Suche |
+| **Query-Aufbereitung** | `QueryCleaner` | Zahlen bleiben erhalten | aktiv | Zahlen werden nicht entfernt |
+| **Query-Aufbereitung** | `QueryCleaner` | Bindestrich/Slash-Splitting | aktiv | `-` und `/` werden als Worttrenner behandelt |
+| **Query-Aufbereitung** | `QueryEnricher` | Synonym-/Pseudonym-Anreicherung | Mapping-basiert | Hängt erkannte Pseudonyme als Zusatz an die Query |
+| **Auswahlmodus** | `NdjsonHybridRetriever` | `selectListChunkIds()` | dedup-basiert | Listenmodus dedupliziert Textfragmente statt hart pro Dokument zu begrenzen |
+| **Auswahlmodus** | `NdjsonHybridRetriever` | `selectSalesChunkIds()` | dokumentbegrenzt | Sales-/Normalmodus begrenzt pro Dokument und nach Chunk-Abstand |
+
+---
+
+# 3. Effektive Laufzeitlogik der wichtigsten Parameter
+
+## 3.1 `retrievalMaxChunks`
+
+Effektive Formel:
+```
+limit = min(activeConfig.retrievalMaxChunks, HARD_MAX_CHUNKS)
+```
+---
+
+# 4. Parameteränderungen und ihre typische Wirkung
 
 | Parameter | Wenn erhöht | Wenn gesenkt | Typischer Effekt / Risiko |
 |---|---|---|---|
-| retrievalMaxChunks | Mehr Kontext, höhere Antworttiefe | Kompaktere Antworten, evtl. Wissensverlust | Zu hoch → Token/Noise-Risiko |
-| HARD_MAX_CHUNKS | Erlaubt größere Kontexte | Strenger Kontext-Limit | Sicherheitsparameter |
-| retrievalVectorTopK | Mehr Recall, breitere Kandidatenbasis | Weniger Recall, präziser aber evtl. Lücken | Zu hoch → mehr Noise |
-| HARD_MAX_VECTORK | Größere Suchräume möglich | Strenger begrenzt | Sicherheitsparameter |
-| VECTOR_SCORE_THRESHOLD | Höhere Präzision, weniger schwache Treffer | Mehr Treffer, aber mehr Rauschen | Zu niedrig → Bonus wirkt stärker |
-| List-Mode TopK | Bessere Listenabdeckung | Listen evtl. unvollständig | Zu hoch → Noise |
-| isListQuery | Häufigerer Dokumentmodus | Seltener Dokumentmodus | Fehlklassifikation möglich |
-| QueryCleaner Aggressivität | Stabilere Suche, weniger Noise | Mehr Originalbegriffe | Zu aggressiv → Informationsverlust |
-| DEFAULT_TOPK (Tags) | Mehr Tag-Kandidaten | Weniger Tag-Kandidaten | Zu hoch → Bonus häufiger aktiv |
-| MIN_BEST_SCORE | Bonus seltener (nur starke Tag-Matches) | Bonus häufiger (auch schwache Matches) | Haupthebel gegen „Tags zu mächtig“ |
-| MAX_CANDIDATE_DOCS | Mehr Dokumente erhalten Bonus | Weniger Dokumente erhalten Bonus | Zu hoch → Bonus verwässert |
-| TAG_SCORE_BONUS | Tags pushen Ranking stärker | Tags pushen kaum | Zu hoch → Dominanz-Risiko |
-| Dedup-Normalisierung | Weniger Dopplungen | Mehr Redundanz | Beeinflusst Vielfalt, nicht Relevanz |
+| `retrievalMaxChunks` | mehr finaler Kontext | kompakterer Kontext | zu hoch: mehr Noise und Tokenverbrauch |
+| `retrievalVectorTopK` | breitere Kandidatenbasis | engere Kandidatenbasis | zu hoch: mehr Streuung, zu niedrig: Recall-Verlust |
+| effektiver Threshold | präzisere Treffer | mehr schwache Treffer | zu niedrig: Rauschen, zu hoch: Leertreffer |
+| `LIST_BONUS` | stärkere Listenabdeckung | schmalere Listenabdeckung | zu hoch: unnötig breite Listen-Suche |
+| `MAX_CHUNKS_PER_DOC` | mehr Tiefe je Dokument | mehr Diversität zwischen Dokumenten | zu hoch: Dominanz einzelner Dokumente |
+| `MIN_CHUNK_DISTANCE` | weniger Nachbarschaftsduplikate | mehr lokale Ballung | zu hoch: zusammenhängende Argumente können verloren gehen |
+| `RRF_K` | flachere Rangunterschiede | stärkere Dominanz der Top-Ränge | beeinflusst Fusionscharakter |
+| Scoped Boost `1.2` | stärkt Routing-Dokumente | schwächt Routing-Dokumente | zu hoch: Routing dominiert globale Suche |
+| Tag `DEFAULT_TOPK` | mehr Tag-Kandidaten | weniger Tag-Kandidaten | zu hoch: größere Kandidatenmengen |
+| `MAX_CANDIDATE_DOCS` | breiteres Tag-Scoping | engeres Tag-Scoping | zu hoch: Scoping verliert Fokus |
+| VectorClient `MIN_SCORE` | präzisere Rohhits | mehr Rohrauschen | Vorfilter vor Retriever-Fusion |
+| TagVectorClient `MIN_SCORE` | strengere Tag-Erkennung | großzügigere Tag-Erkennung | sehr sensibel für Routing-Verhalten |
+| `LIST_THRESHOLD` | Listenmodus seltener | Listenmodus häufiger | Fehlklassifikation möglich |
+| `MIN_SCORE_THRESHOLD` (`SalesIntent`) | Discovery häufiger | Spezial-Intents häufiger | beeinflusst Objection/Pricing-Steuerung |
+| `DOMINANCE_DELTA` | Intent muss klarer dominieren | Intent springt leichter um | beeinflusst Spezialisierung der Retrieval-Logik |
+
+# 5. Praktische Lesart für Tuning
+
+Wenn man im aktuellen Stand Retrieval-Tuning betreiben will, sind diese Hebel am wichtigsten:
+
+## Für mehr Recall
+
+- `retrievalVectorTopK` erhöhen
+- `QueryEnrichment` gezielt erweitern
+- Tag-Routing nicht zu streng machen
+- effektiven Threshold bewusst überprüfen
+
+## Für mehr Präzision
+
+- effektiven Threshold sauber justieren
+- `retrievalMaxChunks` nicht unnötig hoch setzen
+- `MAX_CHUNKS_PER_DOC` niedrig halten
+- Tag-Kandidatenmenge fokussiert halten
+
+## Für bessere Listenantworten
+
+- `LIST_THRESHOLD` und Listenheuristik prüfen
+- `LIST_BONUS` gezielt feinjustieren
+- dedup-basierte List-Auswahl beobachten
+
+## Für bessere Sales-/Beratungsantworten
+
+- `MAX_CHUNKS_PER_DOC`
+- `MIN_CHUNK_DISTANCE`
+- SalesIntent-Erkennung
+- Scoped-Boost-Logik