update

daten/RAG/evaluation.md

@@ -0,0 +1,100 @@
+<!-- titel -->
+Evaluation
+----------------------------------------
+<!-- art -->
+kern
+----------------------------------------
+<!-- ziel -->
+Führt Testläufe für AI-Agenten aus und liefert strukturierte Berichte
+----------------------------------------
+<!-- regeln -->
+- ROLE_KNOWLEDGE_ADMIN für alle Admin-Funktionen
+- CSRF-Token für alle POST-Operationen
+- Berichte als JSON-Dateien gespeichert
+- Exitcode FAILURE bei einem oder mehr Fehlern
+- Standardtyp retrieval ohne explizite Angabe
+- Parallele Ausführung als Child-Prozesse
+- Reportdateiname ist retrieval-last-run.json
+- Meta-Review-Signale werden als PASS+REVIEW angezeigt
+- json gibt den vollständigen Bericht als JSON aus
+- no-write unterdrückt das Schreiben der Reportdatei
+- list-cases listet Eval-Fälle ohne Ausführung
+- duration-profile zeigt Laufzeitprofil der langsamsten Fälle
+- jobs bestimmt die Anzahl paralleler Child-Prozesse
+- Report enthält scheduled_children und max_running_children
+- Report enthält wall_duration_ms und summed_case_duration_ms
+- Fail-Fast im Parallelmodus ist soft und sammelt laufende Prozesse
+----------------------------------------
+<!-- funktion -->
+Berichte bereinigen
+<!-- ziel -->
+Entfernt alte oder alle Testläufe aus dem Dateisystem, um Speicherplatz freizugeben
+<!-- regeln -->
+- Nur Admins mit ROLE_KNOWLEDGE_ADMIN
+- POST nur mit gültigem CSRF-Token
+- mode=trim löscht alle außer der letzten Konfiguration
+- mode=delete_all löscht alle historischen Testläufe
+- report_scope=all wirkt auf alle Bereiche
+<!-- testen -->
+- POST cleanup mit mode trim und CSRF-Token
+- Erfolg zeigt gelöschte Anzahl
+- POST cleanup mit mode delete_all
+- Löschung bestätigt
+----------------------------------------
+<!-- funktion -->
+Eval-Berichte anzeigen
+<!-- ziel -->
+Ermöglicht das Anzeigen von Eval-Berichten mit Vergleich und Übersicht
+<!-- regeln -->
+- ROLE_KNOWLEDGE_ADMIN erforderlich
+- type-Parameter bestimmt den Berichtstyp
+- scope und genre bestimmen den Eval-Kontext
+- compare_report zeigt Vergleichsbericht an
+<!-- testen -->
+- Admin-Bereich öffnen
+- GET admin evals aufrufen
+- Bericht wird mit Übersicht angezeigt
+----------------------------------------
+<!-- funktion -->
+Eval-Fälle ausführen
+<!-- ziel -->
+Führt Eval-Fälle für den RetrieX-Agenten aus und meldet Ergebnisse
+<!-- regeln -->
+- Selector enthält Typ und optional Ziel und Falltyp
+- case führt nur den Eval-Fall mit dieser ID aus
+- Report wird als JSON-Datei geschrieben
+- Exitcode ist FAILURE bei einem oder mehr fehlgeschlagenen Fällen
+<!-- testen -->
+- mto:agent:eval:run retrieval ausführen
+- Passende Eval-Fälle werden geladen
+- Jeder Fall zeigt PASS oder FAIL mit Dauer
+- Zusammenfassung zeigt total, passed, failed
+----------------------------------------
+<!-- funktion -->
+Eval-Fälle parallelisieren
+<!-- ziel -->
+Führt Eval-Fälle gleichzeitig in Child-Prozessen aus, um die Wandzeit zu verkürzen
+<!-- regeln -->
+- Erstellt einen Pool mit maximal --jobs Child-Prozessen
+- Terminiert überzählige Child-Prozesse bei Timeout
+- Fail-Fast bricht das Scheduling nach dem ersten Fehler ab
+- Ergebnisse werden in der ursprünglichen Reihenfolge zurückgegeben
+- Child-Prozesse werden nach Abschluss bereinigt
+<!-- testen -->
+- Kommando mit --jobs 4 ausführen
+- Läuft mit der angegebenen Anzahl paralleler Child-Prozesse
+- Alle Fälle werden ausgeführt und Ergebnisse gesammelt
+- Pool endet mit Ergebnissen in Eingabereihenfolge
+----------------------------------------
+<!-- funktion -->
+Evaluation ausführen
+<!-- ziel -->
+Führt Testsuite aus und zeigt das Ergebnis
+<!-- regeln -->
+- Erfordert Rolle ROLE_KNOWLEDGE_ADMIN
+- CSRF-Token erforderlich
+- Flash zeigt Zusammenfassung mit Bestehensrate
+<!-- testen -->
+- Als Admin Rolle an AdminEvalController senden
+- POST an Admin-Evals-Run mit gültigem _token
+- Flash-Meldung zeigt Testergebnis