From 413dca770c77333baece140811320fb10b1776b9 Mon Sep 17 00:00:00 2001 From: Lars Date: Thu, 4 Dec 2025 20:38:00 +0100 Subject: [PATCH] =?UTF-8?q?docs/wp04=5Fretriever=5Fscoring.md=20hinzugef?= =?UTF-8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/wp04_retriever_scoring.md | 260 +++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/wp04_retriever_scoring.md diff --git a/docs/wp04_retriever_scoring.md b/docs/wp04_retriever_scoring.md new file mode 100644 index 0000000..a3af4c1 --- /dev/null +++ b/docs/wp04_retriever_scoring.md @@ -0,0 +1,260 @@ +# WP-04 / Step 4a – Retriever Scoring & Konfiguration + +Dieses Dokument beschreibt den aktuellen Stand (2025-11-30) der Scoring-Logik des mindnet-Retrievers in WP-04 / Step 4a. +Es dient als Referenz für: + +- Nachvollziehbarkeit des Rankings +- Konfiguration und Feintuning (ohne Codeänderungen) +- spätere Automatisierung / „Selbstjustierung“ des Retrievers + +--- + +## 1. Überblick + +Der Retriever kombiniert drei Signalquellen zu einem einheitlichen Score: + +1. **Semantik** – Vektorsuche über `mindnet_chunks` +2. **Typ-Gewichtung** – `retriever_weight` pro Note/Chunk (aus `types.yaml`) +3. **Graph-Boni** – `edge_bonus` und `centrality_bonus` aus dem Subgraph (Edges) + +Die Berechnung erfolgt in `app/core/retriever.py` und ist über `config/retriever.yaml` konfigurierbar. +Die API stellt die Funktionalität über den `/query`-Endpoint (FastAPI) bereit. + +--- + +## 2. Datenbasis (Kurzüberblick) + +### 2.1 Notes (`_notes`) + +Relevante Felder: + + - note_id: keyword + - title: text + - type: keyword + - retriever_weight: float + - chunk_profile: keyword + - edge_defaults: keyword[] + - tags: keyword[] + - path: text + - fulltext: text + +### 2.2 Chunks (`_chunks`) + +Relevante Felder: + + - note_id: keyword + - chunk_id: keyword + - text: text + - window: text + - retriever_weight: float + - type: keyword + - path: text + - section: text + - neighbors_prev / neighbors_next + - chunk_profile: keyword + +### 2.3 Edges (`_edges`) + +Relevante Felder: + + - kind: keyword + - source_id: keyword + - target_id: keyword + - note_id: keyword + - confidence: float + - rule_id, provenance, edge_id, scope, relation, ref_text + +Edges stammen stets aus der Import-/Edge-Pipeline (WP-03) und bilden die graphbasierte Grundlage des Retrievers. + +--- + +## 3. Scoring-Formel (Retriever) + +### 3.1 Eingangsgrößen + +Für jeden Treffer gelten: + + semantic_score – aus der Vektorsuche (Qdrant) + retriever_weight – typabhängiges Gewicht (aus types.yaml) + edge_bonus – aggregierter Graph-Bonus + centrality_bonus – Zentralitätsbonus aus dem Subgraph + +### 3.2 Globale Gewichte (aus retriever.yaml) + +Datei: `config/retriever.yaml` +Beispiel: + + version: 1.0 + + scoring: + semantic_weight: 1.0 # W_sem + edge_weight: 0.7 # W_edge + centrality_weight: 0.5 # W_cent + +Falls diese Datei fehlt, greifen ENV-basierte Defaults (`RETRIEVER_W_*`). + +### 3.3 Formel + + total_score = + W_sem * semantic_score * max(retriever_weight, 0.0) + + W_edge * edge_bonus + + W_cent * centrality_bonus + +Bemerkungen: + +- Negative `retriever_weight` werden abgefangen. +- Die rohen `edge_bonus` und `centrality_bonus` werden im API-/Smoke-Output angezeigt. +- Die Gewichte aus `retriever.yaml` beeinflussen **nur den total_score**, nicht die Anzeige. + +--- + +## 4. Konfigurationsdateien + +### 4.1 Typen-Registry (`types.yaml`) + +Beispielauszug: + + defaults: + retriever_weight: 1.0 + chunk_profile: default + + types: + types: + concept: + retriever_weight: 0.60 + edge_defaults: ["references", "related_to"] + + project: + retriever_weight: 0.97 + edge_defaults: ["references", "depends_on"] + + journal: + retriever_weight: 0.80 + edge_defaults: ["references", "related_to"] + + source: + retriever_weight: 0.50 + edge_defaults: [] + +Diese Werte bestimmen, wie wichtig eine Note/Chunk **prinzipiell** für den Retriever ist. + +### 4.2 Retriever-Konfiguration (`retriever.yaml`) + +Beispiel: + + version: 1.0 + + scoring: + semantic_weight: 1.0 + edge_weight: 0.7 + centrality_weight: 0.5 + + # Blueprint für spätere Edge-Feinsteuerung: + edge_types: + references: 0.20 + depends_on: 0.18 + related_to: 0.15 + similar_to: 0.12 + belongs_to: 0.10 + next: 0.06 + prev: 0.06 + +Die Datei befindet sich standardmäßig unter `config/retriever.yaml`. +Override per ENV: + + MINDNET_RETRIEVER_CONFIG=/pfad/zur/datei.yaml + +### 4.3 Aktive Gewichte auslesen + + python - << 'PY' + from app.core.retriever import _get_scoring_weights + print(_get_scoring_weights()) + PY + +Beispielausgabe: + + (1.0, 0.7, 0.5) + +--- + +## 5. Betriebsmodi + +### 5.1 Semantikmodus (semantic) + +Ablauf: + + - Query-Vektor über embed_text() + - Qdrant-Suche über mindnet_chunks + - kein Subgraph → edge_bonus = centrality = 0 + - total_score = W_sem * semantic_score * retriever_weight + +### 5.2 Hybridmodus (hybrid) + +Ablauf: + + - Semantik wie oben + - falls expand.depth > 0: + - Subgraph-Berechnung über ga.expand() + - Ermittlung von edge_bonus und centrality_bonus + - total_score = kombinierte Formel aus Semantik + Graph + +--- + +## 6. Tests + +### Ausführung (Unit & Integration) + + pytest tests/test_retriever_basic.py \ + tests/test_retriever_weight.py \ + tests/test_retriever_edges.py + + pytest tests/test_query_unit.py \ + tests/test_query_text_embed_unit.py + +Tests decken ab: + + - Semantiktreffer + - Typ-Gewichte + - Edge-Boni + - Hybridmodus / FastAPI-Endpunkt + +### Smoke-Test + + python tests/test_retriever_smoke.py \ + --url "http://127.0.0.1:8001/query" \ + --query "embeddings" \ + --mode hybrid \ + --expand-depth 1 \ + --top-k 5 + +Beispielausgabe: + + [1] note_id=...retriever-design + total=1.5054 (semantic=0.4038 edge=1.5910 centrality=0.0000) + +Interpretation: + +- `semantic`, `edge`, `centrality` = Rohwerte +- `total` = skaliert mit `retriever.yaml` + +--- + +## 7. Betriebs-Hinweise + +### 7.1 Änderung der Gewichte + + - retriever.yaml anpassen + - FastAPI/uvicorn neu starten + - Smoke-Test prüfen + +### 7.2 Zielbild WP-04 + +Der jetzige Stand ermöglicht: + + - transparente, konfigurierbare Score-Berechnung + - Kombination aus Semantik, Typwissen und Graphstruktur + - spätere agentenbasierte Selbstjustierung + - alternative Profile (z. B. „mehr Semantik“, „mehr Graph“) + +Dieses Dokument dient als stabile Referenz für Entwickler, Tests und spätere Automatisierungsschritte. +