MtoRagSystem/MATRIX_PARAMS.md

MATRIX_PARAMS.md

Retrieval-Matrix: alle relevanten Parameter und ihr realer Einfluss

Zweck dieser Datei

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 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