97 lines
2.6 KiB
Markdown
97 lines
2.6 KiB
Markdown
# mindnet Retriever (WP-04 / Step 4a) – Kurz-Dokumentation
|
||
|
||
## 1. Überblick
|
||
|
||
Der Retriever besteht aus:
|
||
|
||
- **Semantic Retriever** (`semantic_retrieve`)
|
||
- **Hybrid Retriever** (`hybrid_retrieve`)
|
||
- Qdrant-Backend (`*_chunks`, `*_edges`)
|
||
- optionaler Edge-Expansion über `graph_adapter.expand`
|
||
|
||
Die API nutzt das bestehende `/query`-Endpoint (FastAPI), das `QueryRequest` und `QueryResponse` aus `app.models.dto` verwendet.
|
||
|
||
## 2. Scoring-Formel
|
||
|
||
Pro Treffer werden folgende Komponenten geführt:
|
||
|
||
- `semantic_score` – direkt aus Qdrant (Cosine/Euclidean, je nach Collection)
|
||
- `retriever_weight` – aus Chunk-Payload (`types.yaml` / Frontmatter)
|
||
- `edge_bonus` – Bonus aus dem Subgraph (z. B. Zahl der eingehenden/ausgehenden Edges, Beziehungstypen)
|
||
- `centrality_bonus` – Bonus aus einer einfachen Zentralitäts-Heuristik im Subgraph
|
||
|
||
Aktuelle Formel (Step 4a):
|
||
|
||
```text
|
||
total_score = semantic_score * max(retriever_weight, 0.0)
|
||
+ edge_bonus
|
||
+ centrality_bonus
|
||
```
|
||
|
||
Die Sortierung der Ergebnisse erfolgt absteigend nach `total_score`.
|
||
|
||
## 3. Modi
|
||
|
||
### 3.1 Semantic Mode
|
||
|
||
- Funktion: `semantic_retrieve`
|
||
- Request-Feld `mode = "semantic"`
|
||
- Keine Edge-Expansion, kein Graph-Call.
|
||
- Kandidaten nur aus Vektorsuche in `<prefix>_chunks`.
|
||
|
||
### 3.2 Hybrid Mode
|
||
|
||
- Funktion: `hybrid_retrieve`
|
||
- Request-Feld `mode = "hybrid"`
|
||
- Schritte:
|
||
1. Semantische Chunk-Suche wie im Semantic Mode
|
||
2. Falls `expand.depth > 0` gesetzt ist:
|
||
- Seeds = `chunk_id` (Fallback: `note_id`) der Treffer
|
||
- Aufruf `graph_adapter.expand(client, prefix, seed_ids, depth, edge_types)`
|
||
- Ergebnis-Subgraph liefert `edge_bonus` und `centrality_bonus` pro Node
|
||
3. Scores werden nach obiger Formel kombiniert.
|
||
|
||
## 4. Request-Struktur (JSON)
|
||
|
||
Beispiel-Hybrid-Request:
|
||
|
||
```json
|
||
{
|
||
"mode": "hybrid",
|
||
"query": "embeddings und qdrant",
|
||
"top_k": 10,
|
||
"expand": {
|
||
"depth": 1,
|
||
"edge_types": ["references", "depends_on"]
|
||
}
|
||
}
|
||
```
|
||
|
||
Minimaler Semantic-Request:
|
||
|
||
```json
|
||
{
|
||
"mode": "semantic",
|
||
"query": "karate trainingsplan",
|
||
"top_k": 5
|
||
}
|
||
```
|
||
|
||
## 5. Smoke-Test
|
||
|
||
Für einen schnellen End-to-End-Test kann folgendes Skript verwendet werden:
|
||
|
||
```bash
|
||
python scripts/test_retriever_smoke.py --query "karate" --mode hybrid --expand-depth 1 --top-k 5
|
||
```
|
||
|
||
Das Skript ruft `/query` auf, wertet Statuscode und JSON-Antwort aus und zeigt die Scores der Top-K-Treffer an.
|
||
|
||
## 6. Tests
|
||
|
||
Die wichtigsten Tests für den Retriever sind:
|
||
|
||
- `tests/test_retriever_basic.py` – Basisfunktion (Semantic + Hybrid)
|
||
- `tests/test_retriever_weight.py` – Einfluss von `retriever_weight` auf das Ranking
|
||
- `tests/test_retriever_edges.py` – Einfluss von Edge-/Centrality-Boni im Hybrid-Modus
|