diff --git a/patch_history/RETRIEX_PATCH_101B_ADMIN_EVAL_CASE_HELP_TEXTS_README.md b/patch_history/RETRIEX_PATCH_101B_ADMIN_EVAL_CASE_HELP_TEXTS_README.md new file mode 100644 index 0000000..4993ce1 --- /dev/null +++ b/patch_history/RETRIEX_PATCH_101B_ADMIN_EVAL_CASE_HELP_TEXTS_README.md @@ -0,0 +1,52 @@ +# RetrieX Patch p101b - Admin Eval Case Help Texts + +## Ziel + +Verbessert die Hilfetexte auf der Admin-Seite zum Erstellen neuer Eval-Cases, damit auch weniger technische Nutzer verstehen, welche Werte in welche Felder gehören. + +## Scope + +Geändert: + +- `templates/admin/evals/case_new.html.twig` + +Neu: + +- `patch_history/RETRIEX_PATCH_101B_ADMIN_EVAL_CASE_HELP_TEXTS_README.md` + +## Änderungen + +- Ausführlichere Beschreibungen unter allen Eingabefeldern +- Laienfreundliche Erklärung der Eval-Typen +- Beispiele für gute Case-IDs +- Klarere Erklärung für Prompt vs. erwartete Antwort +- Copy-Paste-Beispiele für Assert-JSON +- Erklärung, wann History-JSON benötigt wird +- Hinweis, dass Request Context Hint fast immer leer bleiben kann +- Zusätzliche Checkliste vor dem Speichern + +## Nicht geändert + +- Keine Eval-Logik +- Keine Retrieval-Logik +- Keine Shopquery-Logik +- Keine Follow-up-Logik +- Keine Answer-Guard-Logik +- Keine bestehenden Eval-Cases +- Keine YAML- oder Parameteränderung +- Keine Migration + +## Prüfung + +Nach Einspielen: + +```bash +php bin/console mto:agent:config:validate +``` + +Dann im Admin prüfen: + +- `/admin/evals/cases/new` +- Hilfetexte unter allen Feldern sichtbar +- Vorlage aus Report-Result weiterhin nutzbar +- Case speichern weiterhin möglich diff --git a/templates/admin/evals/case_new.html.twig b/templates/admin/evals/case_new.html.twig index f38084d..64f4e5a 100644 --- a/templates/admin/evals/case_new.html.twig +++ b/templates/admin/evals/case_new.html.twig @@ -37,6 +37,17 @@ {% endif %} +
+
+ Kurz erklärt +
+
+ Ein Eval-Case ist ein wiederholbarer Test. Du trägst ein, was der Nutzer fragt + und woran RetrieX gemessen werden soll. Der Test verändert keine Daten im Shop oder im RAG-Wissen, + sondern prüft nur, ob ein bekannter Fall weiterhin richtig läuft. +
+
+
@@ -48,7 +59,7 @@
-
+
- Der Typ entscheidet, in welche Datei geschrieben wird: tests/evals/cases/<type>.ndjson. + Wähle zuerst, was genau geprüft werden soll. Der Typ entscheidet auch, + in welche Datei der Case geschrieben wird: tests/evals/cases/<type>.ndjson. +
+
+
retrieval: prüft, ob die richtige Wissensquelle oder das richtige Dokument gefunden wird.
+
shop_query: prüft, welche Suchquery an den Shop geschickt würde.
+
followup: prüft eine Folgefrage, die den vorherigen Chatverlauf braucht.
+
answer_guard: prüft, dass RetrieX bei Unsinn oder fehlender Evidenz nichts erfindet.
-
+
- Eindeutig über alle Eval-Typen. Erlaubt: Buchstaben, Zahlen, _ und -. + Das ist der interne Name des Tests. Er erscheint später in der Eval-Auswertung, + damit du den Fall wiedererkennst. Verwende keine Leerzeichen. Erlaubt sind Buchstaben, Zahlen, _ und -. +
+
+ Gute Beispiele: retrieval_lieferbedingungen_versand_001, + shop_query_testomat808_indikator300_001, + followup_testomat808_device_price_001.
+ Faustregel: typ_thema_ziel_nummer.
-
+
- Exakt der Nutzerprompt, der abgesichert werden soll. Tippfehler bewusst so eintragen, wenn sie Teil des Tests sind. + Hier kommt genau die Nutzerfrage hinein, die getestet werden soll. + Nicht die erwartete Antwort eintragen, sondern den Satz, den ein Nutzer in den Chat schreiben würde. +
+
+ Tippfehler dürfen bewusst drin bleiben, wenn genau dieser Tippfehler abgesichert werden soll. + Beispiel: ich würde gern chlor im schwinnbad messen prüft dann auch die Korrektur Richtung schwimmbad.
-
+
- Muss ein gültiges JSON-Objekt sein. Beispiel: {"expected_query":"testomat 808"}. + Hier steht, was der Test erwarten soll. Das Feld muss gültiges JSON sein, + also mit { anfangen und mit } enden. Keine Kommentare und kein Komma nach dem letzten Eintrag. +
+
+
Wenn eine Shopquery exakt stimmen soll:
+ 
{
+  "expected_query": "testomat 808"
+}
+
Wenn bestimmte Wörter enthalten sein müssen:
+ 
{
+  "must_include_terms": [
+    "testomat",
+    "808"
+  ]
+}
+
Wenn ein Dokument gefunden werden muss:
+ 
{
+  "min_results": 1,
+  "must_include_one_of_document_ids": [
+    "DOKUMENT-ID"
+  ]
+}
-
+
- Für Follow-up-Cases empfohlen. Muss eine JSON-Liste sein. Leer lassen für direkte Prompts. + Nur ausfüllen, wenn die aktuelle Frage den vorherigen Chatverlauf braucht. + Für direkte Einzelprompts leer lassen. Das Feld muss eine JSON-Liste sein, also mit [ anfangen und mit ] enden. +
+
+ Typischer Einsatz: Der Nutzer fragt zuerst nach dem niedrigsten Grenzwert, danach nach dem Indikator + und anschließend was kostet der indikator. Dann braucht der Test die vorherigen Fragen und Antworten als History. + 
[
+  {
+    "prompt": "mit welchem indikator",
+    "answer": "Der Wert 0,02 °dH wird beim Testomat 808 mit Indikatortyp 300 gemessen."
+  }
+]
@@ -117,7 +179,12 @@ class="form-control bg-dark text-light border-secondary" placeholder="Nur für Spezialfälle, wenn History nicht ausreicht.">{{ case_draft.request_context_hint|default('') }}
- Normalerweise leer lassen. Für reguläre Regressionen lieber History-JSON verwenden. + Dieses Feld kannst du fast immer leer lassen. Es ist nur für Sonderfälle gedacht, + wenn der Test Zusatzkontext braucht, der nicht sauber als History darstellbar ist. +
+
+ Beispiel für einen Sonderfall: Im vorherigen Ergebnis waren mehrere Shop-Produkte sichtbar, aber keine normale Chatantwort. + Für normale Regressionen ist History-JSON die bessere Wahl.
@@ -139,14 +206,26 @@
- Feld-Checkliste + Welcher Typ ist richtig?
-
    -
  • retrieval: richtiges Dokument / richtige Chunks prüfen.
    • -
  • shop_query: direkte Shopquery prüfen.
    • -
  • followup: Prompt plus History prüfen.
    • -
  • answer_guard: No-Answer- oder Evidenzfälle prüfen.
    • -
+
+
+ Du willst prüfen, ob das richtige Dokument gefunden wird?
+ Dann nimm retrieval. +
+
+ Du willst prüfen, welche Suchwörter an den Shop gehen?
+ Dann nimm shop_query. +
+
+ Die Frage bezieht sich auf die vorherige Antwort?
+ Dann nimm followup und fülle History-JSON aus. +
+
+ RetrieX soll bei Unsinn nichts erfinden?
+ Dann nimm answer_guard. +
+
@@ -168,6 +247,14 @@ ] } +
Begriffe dürfen nicht enthalten sein:
+ 
{
+  "must_not_include_terms": [
+    "indikator",
+    "300"
+  ]
+}
+
Dokument muss enthalten sein:
{
   "min_results": 1,
@@ -178,6 +265,21 @@
+
+
+
+ Vor dem Speichern prüfen +
+
    +
  • Prüft der Case genau einen Zweck?
    • +
  • Ist die Case-ID eindeutig und ohne Leerzeichen?
    • +
  • Ist der Prompt eine echte Nutzerfrage?
    • +
  • Ist Assert-JSON gültiges JSON?
    • +
  • Ist History nur bei echten Folgefragen gefüllt?
    • +
+
+
+
@@ -185,6 +287,8 @@

Ein guter Eval-Case prüft genau einen Zweck. Lieber mehrere kleine Cases anlegen als einen großen, empfindlichen Case. + Wenn du unsicher bist, starte mit expected_query bei Shop-/Follow-up-Fällen oder mit + must_include_one_of_document_ids bei Retrieval-Fällen.