marek/MtoRagSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remove matrix params

Browse Source
This commit is contained in:
team 1
2026-05-04 19:29:09 +02:00
parent f149a61961
commit c5aeac397c
1 changed files with 0 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
MATRIX_PARAMS.md
View File

@@ -1,142 +0,0 @@
# 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