Evaluation

URL: Evaluation-Daten werden ueber JSON-Endpoints bereitgestellt und auf der Dokumenten-Seite sowie im Dashboard angezeigt. Mindest-Rolle: avs-editor (fuer manuelle Ausloesung)

Was ist die Evaluation?

Die Evaluation prueft automatisch die Qualitaet der Suchpipeline (Retrieval). Sie vergleicht die Ergebnisse der RAG-Pipeline gegen einen definierten Satz von Testfragen mit bekannten korrekten Antworten (Ground Truth).

Die Evaluation nutzt direkt die geladenen Haystack-Pipeline-Komponenten (Text-Embedder, Retriever, Ranker) und benoetigt keine GPU-basierte Textgenerierung. Ein Durchlauf dauert typischerweise 10-30 Sekunden.

Testfragen

Die Testfragen werden aus zwei Quellen geladen:

1. Datenbank: Aktive Fragen aus der Tabelle evaluation_questions (pro Produkt)
2. Fallback-Dateien: resources/eval_questions.json (Docker-Image) oder tests/evaluation/test_questions.json (Entwicklung)

Jede Testfrage besteht aus einer Frage, den erwarteten relevanten Dokumenten/Chunks und optional einer Referenzantwort.

Verwaltung der Testfragen

Die Testfragen werden in der PostgreSQL-Tabelle evaluation_questions gespeichert und pro Produkt gefiltert. Aktuell erfolgt die Verwaltung (Hinzufuegen, Aendern, Loeschen neuer Fragen) direkt ueber die Datenbank durch den Entwickler.

Geplante Erweiterung

Eine Self-Service-Oberflaeche im Admin-Panel ist geplant, ueber die AVS-IT die Testfragen eigenstaendig pflegen kann. In der SaaS-Loesung soll jeder Kunde die Testfragen fuer seine Instanz selbst verwalten koennen.

Metriken

Metrik	Beschreibung
Recall@5	Anteil der Testfragen, bei denen das relevante Dokument in den Top-5-Ergebnissen enthalten ist
MRR (Mean Reciprocal Rank)	Durchschnitt des Kehrwerts des Rangs des ersten relevanten Treffers

Automatische Ausloesung

Wenn die Einstellung eval_auto_after_upload aktiviert ist (Standard: ja), wird nach jedem Dokument-Upload automatisch eine Evaluation gestartet. Dies stellt sicher, dass Qualitaetseinbrueche sofort auffallen.

Die Einstellung kann unter Einstellungen geaendert werden.

Manuelle Ausloesung

Ueber den Button "Evaluation starten" kann eine Evaluation manuell ausgeloest werden. Optional kann auch eine Generation-Evaluation (mit LLM) eingeschlossen werden.

Endpoint: POST /admin/evaluation/run

Gleichzeitige Laeufe

Es kann nur eine Evaluation gleichzeitig laufen. Bei einem Versuch, eine zweite zu starten, wird HTTP 409 zurueckgegeben.

Trend-Diagramm

Ein Diagramm zeigt die Entwicklung von Recall@5 und MRR ueber die letzten Evaluationslaeufe (max. 20).

Endpoint: GET /admin/evaluation/trend?limit=20

Qualitaets-Alerts

Basierend auf konfigurierbaren Schwellenwerten werden automatisch Alerts ausgeloest:

Recall@5-Schwellenwerte

Level	Einstellung	Standard
Warnung	eval_recall_warning_threshold	0.85
Kritisch	eval_recall_critical_threshold	0.70

MRR-Schwellenwerte

Level	Einstellung	Standard
Warnung	eval_mrr_warning_threshold	0.60
Kritisch	eval_mrr_critical_threshold	0.40

Die Schwellenwerte lassen sich unter Einstellungen anpassen.

Ein Prometheus-Gauge (avs_evaluation_quality_alert) wird entsprechend gesetzt: 0 = OK, 1 = Warnung, 2 = Kritisch.

API-Endpoints

Methode	Endpoint	Beschreibung
POST	/admin/evaluation/run	Evaluation starten
GET	/admin/evaluation/status/{run_id}	Status eines Laufs abfragen
GET	/admin/evaluation/latest	Letzter abgeschlossener Lauf
GET	/admin/evaluation/trend	Trend der letzten Laeufe