Übersicht

Repository

Allgemeine Informationen

Die Evaluation ermöglicht es, Chatbots systematisch mithilfe von Large Language Models (LLMs) zu bewerten und deren Parameter gezielt zu optimieren. Das Framework unterstützt Entwicklerinnen und Entwickler bei der Auswahl geeigneter Sprachmodelle sowie beim Prompt Engineering.

Das Framework besteht aus den folgenden Services:

Synthetische Datensatzgenerierung: Ermöglicht die Erstellung use-case-spezifischer Datensätze, die eine gezielte und reproduzierbare Evaluation des Chatbots unterstützen.
Evaluation: Bindet den Chatbot ein und führt ihn auf den zuvor generierten Datensätzen aus. Die Ergebnisse werden anschließend anhand vordefinierter Kriterien durch das Evaluationsframework bewertet und durch geeignete Statistiken vergleichbar gemacht.

Konfigurationsdateien

create_dataset.yaml

create_dataset.yaml

# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

dataset_name: "gendering_example"
num_examples: "40"
description: "Geschlechtergerechte und barrierefreie Sprache"
criteria: |
  Nutzen Sie wenn möglich geschlechterneutrale Begriffe.
  Beispiel: „Ansprechpartner“ → „Ansprechperson“.
  Dabei kann es helfen, das Partizip oder verbale Formulierungen zu verwenden.
  Beispiele: „Arbeitnehmer“ → „Arbeitnehmende“, „Unsere Leserinnen und Leser überfliegen Texte zunächst.“ → „Wer heute Texte liest, überfliegt sie zunächst.“.
  Gibt es keine geeigneten neutralen oder partizipialen Begriffe, formulieren Sie konsequent beide Geschlechter vollständig aus – also weibliche und männliche Form.
  Beispiel: „Unternehmer“ → „Unternehmerin und Unternehmer“.
  Ersetzen Sie niemals geschlechtergerechte Formulierungen durch rein männliche Begriffe. Vermeiden Sie Verallgemeinerungen wie „der Unternehmer“, wenn mehrere Geschlechter gemeint sind.
  Beispiel: "Kunden" → „Kundinnen und Kunden“.
  Formulieren Sie inklusiv und vermeiden Sie stereotype oder diskriminierende Ausdrücke.
  Verzichten Sie auf Sonderzeichen wie *, :, /.
  Beispiel: "Unternehmer/-in" → „Unternehmer und Unternehmerin“.
llm_config:
  label: gpt-4o
  api:
    url: https://api.openai.com/v1
    auth:
      secret_path: ./secrets/llm_api.secret
system_prompt: |
  Du erstellst synthetische Datensätze für eine Textoptimierung. Der User gibt dir an, wie viele Beispiele generiert werden sollen.
  - Negativbeispiele sind Texte, die die vorgegebenen Kriterien **nicht erfüllen**.
  - Die Beispiele sollen realistisch, konsistent und vielfältig sein.
  - Die Antwort soll **parsebar** sein, ohne zusätzliche Texte oder Erklärungen.
user_prompt: |
  Erstelle bitte {num_examples} Negativbeispiele.
  Kontext:
  Beschreibung: {description}
  Kriterien:
  {criteria}
output_format: xlsx

evaluation.yaml

evaluation.yaml

# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

experiment_name: "example"
data_files:
  - example_data
replications: 3
csv_separator: ","
input_column_name: Original
output_column_name: Transformed
transformations:
  gpt_4_o:
    type: backend
    model_name: gpt_4_o
    label: GPT 4
  gemma_3_27b:
    type: backend
    model_name: gemma_3_27b
    label: Gemma 3

tasks:
  - Prägnanz und Einfachheit
  - Vermeidung des Konjunktivs
  - Inklusivität und diskriminierungsfreie Sprache
  - Lösungsorientierte und positive Sprache
indices:
  - LLM Hallucination
score_weighting:
  Prägnanz und Einfachheit: 2
  Vermeidung des Konjunktivs: 1
  Inklusivität und diskriminierungsfreie Sprache: 3
  Lösungsorientierte und positive Sprache: 1
  LLM Hallucination: 3
map:
  Prägnanz und Einfachheit: Prägnanz
  Vermeidung des Konjunktivs: Konjunktiv
  Inklusivität und diskriminierungsfreie Sprache: Inklusivität
  Lösungsorientierte und positive Sprache: Lösungsorientiert
  LLM Hallucination: Halluzinationen

llm_parameters.yaml

llm_parameters.yaml

# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

evaluation:
  label: gpt-4o
  api:
    url: https://api.openai.com/v1
    auth:
      secret_path: ./secrets/llm_api.secret
  inference:
    presence_penalty: 0.0
    frequency_penalty: 0.0
    temperature: 0.0
    top_p: 0.5
  prompt_yaml_file: config/llm_system_prompts.yaml

llm_system_prompts.yaml

llm_system_prompts.yaml

# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

system_prompts:
  evaluate_hallucination: |
    Du bist ein KI-Sprachmodell, dessen Aufgabe es ist, zwei Texte miteinander zu vergleichen.
    Dein Ziel ist es, zu überprüfen, ob die Inhalte der beiden Texte im Wesentlichen übereinstimmen,
    unabhängig von der Formulierung, der Wortwahl oder der Satzstruktur.

    Originaltext:
    {prompt_input}

    Arbeitsweise:

    1. Lies den Vergleichstext sorgfältig durch.
    2. Vergleiche den Inhalt dieses Textes mit dem Originaltext.
    3. Ignoriere Unterschiede in der Ausdrucksweise, der Wortwahl, der Satzstruktur, der Grammatik,
      der Zeitform oder der Verwendung von Synonymen, solange die wesentliche Bedeutung der Texte gleich bleibt.
    4. Überprüfe, ob im Vergleichstext keine signifikanten inhaltlichen Ergänzungen oder Kürzungen enthalten sind,
      die die Hauptaussage maßgeblich verändern.
    5. Gib „True“ aus, wenn die beiden Texte unter Berücksichtigung von 3. und 4. inhaltlich gleich sind.
      Gib „False“ aus, wenn es deutliche inhaltliche Unterschiede gibt, die die Hauptaussage maßgeblich verändern.

    Antworte ausschließlich mit „True“ oder „False“.
  evaluate_task_comparison: |
    Du bist ein Sprachmodell, das Texte basierend auf einem spezifischen Kriterium bewertet.
    Dein Ziel ist es, zu überprüfen, ob ein gegebener Text im Vergleich zum folgenden Originaltext
    das angegebene Kriterium erfüllt.

    Originaltext:
    {prompt_input_1}

    Kriterium:
    {prompt_input_2}

    Aufgabe:
    Lese den gegebenen Text und bewerte, ob er im Vergleich zum Originaltext das Kriterium erfüllt.
    Gib „True“ aus, wenn das Kriterium erfüllt wurde, und „False“, wenn es nicht erfüllt wurde.
    Deine Antwort sollte ausschließlich „True“ oder „False“ sein.

llm_tasks.yaml

llm_tasks.yaml

# SPDX-FileCopyrightText: 2025-present Bundesministerium für Arbeit und Soziales (BMAS) <info@denkfabrik-bmas.de>
#
# SPDX-License-Identifier: Apache-2.0

Prägnanz und Einfachheit: |
  Die Sprache ist klar und direkt, ohne unnötige oder überflüssige Wörter. Lange, umständliche Formulierungen oder komplexe Satzstrukturen werden vermieden, und die Botschaft wird in möglichst wenigen, einfachen Worten ausgedrückt.
  Bewertung: Prüfen, ob die Formulierung ohne Verlust an Bedeutung kürzer und direkter ausgedrückt werden kann.
Vermeidung des Konjunktivs: |
  Der Text verwendet keine unklaren oder hypothetischen Aussagen im Konjunktiv. Aussagen sind konkret formuliert, bleiben dabei jedoch in ihrer Tonalität freundlich.
  Bewertung: Prüfen, ob der Text unnötigen Konjunktiv verwendet und ob die Formulierungen klar, entschlossen und zugleich freundlich sind.
Inklusivität und diskriminierungsfreie Sprache: |
  Der Text vermeidet stereotype oder diskriminierende Begriffe. Er verwendet genderneutrale Ausdrücke oder nennt sowohl die männliche als auch die weibliche Version, spricht jedoch stets beide Geschlechter an. Der Text sollte alle Personen gleichermaßen ansprechen, ohne Vorurteile oder Ausschlüsse.
  Bewertung: Sicherstellen, dass keine diskriminierenden oder nicht-inklusive Begriffe verwendet werden und die Sprache neutral sowie respektvoll gegenüber allen Gruppen ist.
Lösungsorientierte und positive Sprache: |
  Der Text betont Lösungen und positive Aspekte, anstatt Probleme hervorzuheben. Negative oder potenziell entmutigende Ausdrücke werden vermieden, und der Fokus liegt auf konstruktiven und hilfreichen Formulierungen.
  Bewertung: Überprüfen, ob der Text den Fokus auf Lösungen und positive Ansätze legt und negative Formulierungen vermieden werden.

Konfiguration

Um die Evaluation auszuführen, müssen zunächst einige Vorbereitungen getroffen werden. Dazu gehört insbesondere die Konfiguration der zu nutzenden Services und Sprachmodelle.

Die Konfiguration wird im Ordner config angelegt. Als Ausgangspunkt kann die Beispiel-Konfiguration im Ordner config.example verwendet werden, der mit dem folgenden Befehl kopiert werden kann:

cp -r config.example config

Konfiguration der Sprachmodelle

In der Evaluation nehmen Sprachmodelle zwei Positionen ein. Einerseits als zu testendes Sprachmodell ("Test-Modell"), andererseits zur Beurteilung der Ausgaben anhand unterschiedlicher Kriterien ("Judge"). Während das Test-Modell variieren kann, sollte zur Verbesserung der Vergleichbarkeit innerhalb eines Experiments immer derselbe Judge verwendet werden. Judge und Test-Modell können sich also unterscheiden.

Judge: Die Konfiguration des Sprachmodells, das als Judge dient, wird in der Datei config/llm_parameters.yaml vorgenommen. Dafür muss unter url die Adresse eines OpenAI-API-kompatiblen LLM-Providers für die jeweils genutzten Modelle hinterlegt werden. Falls der Provider ein Token benötigt, muss dieser in der Datei secrets/llm_api.secret abgelegt und in den entsprechenden YAML-Dateien im Abschnitt auth referenziert werden. Der Dateiname llm_api.secret ist frei wählbar, muss jedoch konsistent in den genannten YAML-Dateien angegeben werden.

Test-Modelle: Im Kontext von Behörden-KlarText werden die Texte von einem Backend verarbeitet. Es muss also das Backend so konfiguriert werden, dass es die gewünschten Sprachmodelle für die Textverarbeitung nutzt. Die Konfiguration der Sprachmodelle des Backends befindet sich in der Datei config/backend/llm_models.yaml. Wie zuvor muss unter url die Adresse eines OpenAI-API-kompatiblen LLM-Providers für die jeweils genutzten Modelle hinterlegt werden. Falls der Provider ein Token benötigt, muss dieser in der Datei secrets/llm_api.secret abgelegt und in den entsprechenden YAML-Dateien im Abschnitt auth referenziert werden. Der Dateiname llm_api.secret ist grundsätzlich frei wählbar, muss jedoch konsistent in allen relevanten YAML-Dateien (auch in compose.yaml) angegeben werden. Bei Problemen mit der Konfiguration kann möglicherweise auch die Dokumentation des Backends hilfreich sein. Wichtig: Um die Sprachmodelle zu aktivieren, müssen diese zusätzlich in der Datei config/backend/general.yml unter active_llms > behoerden_klartext aktiviert werden. Beispielsweise werden zwei Modell mit den Namen gpt_4_o und gemma_3_27b folgendermaßen eingetragen:

active_llms:
  behoerden_klartext: ["gpt_4_o", "gemma_3_27b"]

Sind alle Sprachmodelle wie gewünscht konfiguriert, kann der eigentlich interessante Teil beginnen.

Anwendung

In diesem Abschnitt werden die für die Evaluation erforderlichen Schritte in Form eines anwendungsbezogenen Tutorials dargestellt.

Beispiel-Texte erstellen

Zu Beginn steht die Frage, welches Ziel untersucht werden soll und welche Textbeispiele sich dafür eignen. Ein mögliches Ziel ist es beispielsweise, komplexe Texte zu vereinfachen, ohne ihre Bedeutung zu verändern. Um zu erfassen, wie gut ein Sprachmodell diese Aufgabe bewältigt, werden zunächst komplexe Ausgangstexte benötigt, die sich für eine Vereinfachung eignen.

Idealerweise können relevante Beispiele direkt aus dem Anwendungsbereich entnommen werden, in dem das Sprachmodell später eingesetzt werden soll. In diesem Fall wären das Texte aus dem relevanten Bereich, die als zu komplex und schwer verständlich wahrgenommen werden.

Option A: Beispiel-Texte manuell erstellen

Um die Beispiele nutzen zu können, müssen sie in einer Tabellenspalte mit dem Namen Original abgelegt werden. Dies kann mit einem gängigen Tabellenkalkulationsprogramm erledigt werden. Die Datei kann dann entweder als Komma-separierte Datei (CSV-Datei, .csv) oder als Excel-Datei (.xlsx) im Ordner data abgelegt werden. Bei CSV-Dateien muss darauf geachtet werden, ob ein Komma oder ein Semikolon als Trennzeichen verwendet wird. Unter config/evaluation.yaml kann mit dem Eintrag csv_separator das Trennzeichen gegebenenfalls angepasst werden.

Option B: Synthetische Beispiel-Texte generieren

Falls keine geeigneten Beispieltexte vorliegen und eine manuelle Erstellung zu aufwendig ist, können auch automatisch generierte Beispiele eingesetzt werden. Ein Vorteil dieser Methodik besteht darin, dass thematisch fokussierte Datensätze erstellt werden können. Diese lassen sich gezielt auf bestimmte Funktionalitäten des zugrunde liegenden Sprachmodells sowie auf die Eigenschaften und Anforderungen des verwendeten Prompts ausrichten.

Mit der create_dataset-Funktionalität können synthetische Datensätze erstellt werden. Die Prompts für die Generierung und das genutzte Sprachmodell können dabei in config/create_dataset.yaml frei gewählt werden. Wichtig ist, dass eine Antwort generiert wird, aus der die Liste von Beispielen geparsed werden kann.

In der Beispielkonfiguration werden Negativbeispiele für ein Kriterium generiert. Dies können relevante Beispiele generiert werden, wenn das Ziel ist, ein bestimmtes Kriterium zu verbessern. Es wird eine einzige Abfrage an das Sprachmodell gestellt um den gesamten Datensatz zu generieren. Dadurch kann es zu leichten Abweichungen in der Anzahl der generierten Beispiele kommen.

In create_dataset.yaml müssen folgende Felder definiert werden:

dataset_name: Name des Datensatzes
num_examples: Anzahl der zu generierenden Beispiele
description: Kurze Beschreibung des Kriteriums
criteria: Regeln und Richtlinien, die bei der Textoptimierung berücksichtigt werden sollen.
llm_config: Die Konfiguration des zu nutzenden Sprachmodells
system_prompt: Der System-Prompt des zu nutzenden Sprachmodells
user_prompt: Das Template für den User-Prompt
(optional) output_format: Das Ausgabeformat, entweder csv oder xlsx

In der Beispielkonfiguration findet sich der Text für das Kriterium "korrektes Gendern".

Nach der Befüllung der genannten Felder kann das Programm zur Erstellung folgendermaßen ausgeführt werden:

mkdir -p ./data
CURRENT_UID=$(id -u):$(id -g) docker compose up --build create_dataset

Der Prefix CURRENT_UID=$(id -u):$(id -g) setzt dabei die Umgebungsvariable CURRENT_UID, die benötigt wird, um die generierten Daten mit den richtigen Berechtigungen zu speichern.

Der generierte Datensatz befindet sich dann im Ordner data/.

Um den Container im Anschluss herunterzufahren, ist ebenfalls die Angabe der Umgebungsvariable CURRENT_UID notwendig:

CURRENT_UID=$(id -u):$(id -g) docker compose down

Erstellen der Testkriterien

Tasks

Im nächsten Schritt werden die Anforderungen festgelegt, die das Sprachmodell bei der Transformation des Texts erfüllen soll. Es wird explizit geprüft, ob bestimmte Kriterien im Vergleich zum Originaltext erfüllt wurden. Alle Testkriterien sind binär aufgebaut: Für jedes Kriterium wird ausgegeben, ob es erfüllt wurde (1) oder nicht (0). Dazu wird ein Titel und die zugehörige Zielvorstellung formuliert. Diese werden dann in config/llm_tasks.yaml im YAML-Format abgelegt. Hier ist ein Beispiel für die Anforderung von einfacher Sprache. Bei der Formatierung ist der senkrechte Strich nach dem Titel sowie die Einrückung mit zwei Leerzeichen zu beachten.

Prägnanz und Einfachheit: |
  Die Sprache ist klar und direkt, ohne unnötige oder überflüssige Wörter.
  Lange, umständliche Formulierungen oder komplexe Satzstrukturen werden vermieden, und die Botschaft wird in möglichst wenigen, einfachen Worten ausgedrückt.
  Bewertung: Prüfen, ob die Formulierung ohne Verlust an Bedeutung kürzer und direkter ausgedrückt werden kann.

Bevor ein Testkriterium für die eigentliche Evaluation eingesetzt wird, sollte es zunächst auf einem separaten, dafür vorgesehenen Testdatensatz geprüft werden. Dadurch wird sichergestellt, dass das Kriterium wie beabsichtigt funktioniert und die gewünschten Effekte erzielt. Zeigt sich dabei, dass die Bewertung uneindeutig, inkonsistent oder nicht zielgenau ausfällt, sollte der zugrunde liegende Prompt entsprechend überarbeitet und präzisiert werden. Dies kann mehrere Iterationen erfordern, bis das Testkriterium zuverlässig und reproduzierbar anwendbar ist.

Indizes

Neben den Tasks besteht die Möglichkeit, zusätzliche Indizes zu definieren oder auszuwählen. Aktuell ist nur der Index „LLM Hallucination“ verfügbar. Dieser prüft, ob der optimierte Text den Inhalt des Originaltexts verändert. Das Ergebnis ist binär: Eine Halluzination wird mit 0, das Ausbleiben einer Halluzination mit 1 gekennzeichnet.

Die Auswahl des Index erfolgt im Abschnitt Festlegen der Eigenschaften der Evaluation.

Weitere Informationen zur Definition zusätzlicher Indizes finden sich unter Architektur & Entwicklung.

Festlegen von Modellen und Prompts

Der Ordner config/backend enthält die Konfiguration des zu testenden Services und wird in den entsprechenden Container gemountet. Wie zuvor beschrieben, werden die Sprachmodelle in config/backend/llm_models.yml konfiguriert und anschließend in config/backend/general.yml der Liste der active_llms hinzugefügt werden.

Im vorliegenden Beispiel eines Backends zur Textoptimierung enthält der Ordner zusätzlich die Dateien config/backend/prompt_maps.yml (System- und User-Prompts) und config/backend/protected_words.yml. Diese Dateien müssen mit den zu testenden Prompts bzw. den Begriffen befüllt werden. Ziel ist es, einen Prompt zu entwickeln, mit dem das Sprachmodell die definierten Anforderungen möglichst gut erfüllt. Der Prompt in der Beispiel-Konfiguration bezieht sich auf ein bestimmtes Beispiel, kann aber auch für andere Probleme als Ausgangspunkt dienen.

Festlegen der Eigenschaften der Evaluation

Die Evaluation selbst wird in der Datei config/evaluation.yaml beschrieben. Die Konfiguration erfolgt wieder mit YAML, die Beispiel-Konfiguration kann als Orientierung dienen. Dabei müssen unter folgenden Einträgen Einstellungen vorgenommen werden:

experiment_name: Frei wählbarer Name des Experiments (ohne Sonderzeichen)
data_files: Die im Ordner data abgelegten Testdatensätze können unter data_files gewählt werden. Dabei wird die Endung nicht angegeben (also für "data.csv" wird nur "data" eingetragen). Mögliche Dateiformate sind CSV (.csv) und Excel (.xlsx). Es muss sichergestellt werden, dass die Datensätze im Ordner data existieren.
replications: Anzahl der Replikationen (identische Wiederholungen) des Experiments, angegeben als positive Ganzzahl. Mehrere Replikationen ermöglichen eine grobe Abschätzung, wie stark die Ergebnisse schwanken. Es werden drei Replikationen empfohlen.
input_column_name: Name der Spalte, die die Eingabetexte enthält. Unter output_column_name kann optional der Name der Spalte angegeben werden, in der die transformierten Texte gespeichert werden.
transformations: Die unterschiedlichen Sprachmodelle (oder optional manuell verbesserte Texte), mit denen der Text verarbeitet werden soll. Der Schlüssel ist jeweils ein Identifikator, die Werte unterscheiden sich nach Art der Verarbeitung. Jede Transformation hat mindestens einen Typ (type), der die Art der Transformation festlegt, und ein Label (label), das in der Auswertung als menschenlesbarer Bezeichner verwendet wird. Im Moment sind zwei Typen definiert, wobei vor allem ersterer relevant ist:
- type: backend für Sprachmodelle: Der zu testende Service wird aufgerufen, um den Text zu verarbeiten, bspw. um ihn zu vereinfachen. name gibt den Namen des zu nutzenden Sprachmodells an.
- type: manual für manuelle verbesserte Texte: Eine schon vorhandene Spalte wird als transfomierter Text genutzt. Die Spalte, die den manuell angepassten Text enhält, wird unter column angegeben. Dies kann nützlich sein, wenn man die Metriken von händischen Anpassungen mit automatischen Anpassungen vergleichen möchte.

Beide Typen können mehrfach vorkommen. Die Reihenfolge in Grafiken und Tabellen entspricht der Reihenfolge der Konfiguration.

tasks: Liste der Titel/Bezeichner der Kriterien, die getestet werden sollen. Es muss sichergestellt werden, dass die gewählten Kriterien in config/llm_tasks.yaml definiert sind.
indices: Liste der Indizes. Indizes sind andere relevante Größen, die nicht dem Schema der Kriterien folgen. Aktuell ist nur "LLM Hallucination" als Index verfügbar.
score_weighting (optional): Gewichte für einen gewichteten Mittelwert der Kriterien und Indizes. Damit kann aus den unterschiedlichen Werten ein Gesamtergebnis berechnet werden, das die Qualität der Transformation in einer Zahl beschreibt. Dieses wird in der Spalte "Score" gespeichert.
map: Umbenennungen der Kriterien und Indizes für die Anzeige. Hier können beispielsweise übermäßig lange Bezeichner gekürzt werden.

Mit diesen Einträgen wird festgelegt, welche Test-Modelle (transformations) auf welchen Datensätzen (data_files) unter welchen Kriterien (tasks) getestet wird.

Ausführen der Evaluation

Um Backend und Evaluation gemeinsam starten zu können, wird Docker mit Docker Compose verwendet. Die Evaluation kann damit wie folgt ausgeführt werden.

mkdir -p ./results  # Ergebnisordner erstellen
CURRENT_UID=$(id -u):$(id -g) docker compose up backend -d
CURRENT_UID=$(id -u):$(id -g) docker compose build evaluation
CURRENT_UID=$(id -u):$(id -g) docker compose run --rm -it evaluation

Der Prefix CURRENT_UID=$(id -u):$(id -g) setzt dabei die Umgebungsvariable CURRENT_UID, die benötigt wird, um die Ergebnisdateien mit den richtigen Berechtigungen zu speichern.

Die Ergebnisse der Evaluation sind im Ordner results/<experiment_name>__<zeitstempel> einsehbar. Tabellen werden sowohl als CSV als auch als Excel-Dateien bereitgestellt, da es beim Öffnen von CSV-Dateien in Excel zu Darstellungsfehlern kommen kann. Die folgenden Ergebnisse werden standardmäßig erzeugt:

detailed_results.csv/.xlsx: Alle transformierten Texte (für alle Modelle und Datensätze) mit den zugehörigen Kriterien.
summary.md: Die berechneten Kriterien mit Mittel-, Minimal- und Maximalwert über die Replikationen als Markdown-Text.
summary.csv/.xlsx: Die Mittelwerte der berechneten Kriterien als Tabelle.
summary.png: Die berechneten Kriterien mit Mittel-, Minimal- und Maximalwert über die Replikationen als Balkendiagramm.
summary_statistics_replications.csv/.xlsx: Erweiterte Statistiken der berechneten Kriterien über die Replikationen.

Um die Container im Anschluss herunterzufahren, ist ebenfalls die Angabe der Umgebungsvariable CURRENT_UID notwendig:

CURRENT_UID=$(id -u):$(id -g) docker compose down

Mehrere Experimente vergleichen

Beim Erstellen neuer Prompts ist ein schrittweises Vorgehen üblich. Um die Ergebnisse der unterschiedlichen Experimente besser vergleichen zu können, erlaubt die combine_experiments-Funktionalität, diese in einer Tabelle zusammenzufassen.

Wichtig: Die Einstellungen in evaluation.yaml sollten dabei möglichst ähnlich sein, insbesondere dürfen input_column_name und output_column_name sich nicht unterscheiden.

Um alle Experimente im Ordner results zusammenfassen, kann der folgende Befehl verwendet werden. Experimente, die nicht in der Zusammenfassung enthalten sollen sein, können solange in einem anderen Ordner außerhalb von results abgelegt werden.

CURRENT_UID=$(id -u):$(id -g) docker compose up --build combine_experiments

Es wird dann ein Ordner results/combined_experiments/<zeitstempel> erstellt, der die zusammengefassten Ergebnisse enthält. Die Ausgabedateien entsprechen dabei im Wesentlichen der eines einzelnen Experiments, wie sie oben beschrieben wurden.

Statt alle irrelevanten Experimente aus dem results-Ordner zu entfernen können auch einzelne Experimente ausgewählt werden. Dazu kann man das Skript folgendermaßen aufrufen. Dabei müssen relative Pfade verwendet werden.

CURRENT_UID=$(id -u):$(id -g) docker compose build combine_experiments
CURRENT_UID=$(id -u):$(id -g) docker compose run --rm -it combine_experiments "python3 main.py combine-experiments results/<experiment_name__timestamp_1> results/<experiment_name__timestamp_02> ..."

Um die Container im Anschluss herunterzufahren, ist kann wieder das folgende Kommando verwendet werden:

CURRENT_UID=$(id -u):$(id -g) docker compose down

Zusammenfassung

Wenn bis zu diesem Punkt alle Schritte erfolgreich durchgeführt wurden, können nun neue Prompt-Varianten und Modelle mit bestehenden verglichen werden. Das kann neben der manuellen Beurteilung ein weiterer Indikator sein, ob sich eine Änderung positiv auswirkt. Gerade bei Projekten mit mehreren Anforderungen kann dies hilfreich zu sein. Versucht man einen Bereich zu verbessern, können dadurch verursachte Verschlechterungen in anderen Bereichen leicht untergehen. Gibt es Kriterien, die alle relevanten Bereiche abdecken, können solche Verschlechterungen bemerkt und (hoffentlich) behoben werden.

Entwicklung

Abhängigkeiten

Dieses Projekt verwendet pip-tools, um die requirements.txt zu generieren. In einer virtuellen Umgebung kann mittels pip-sync die aktuelle requirements.txt geladen werden. Mit pip-compile --upgrade können die Abhängigkeiten aktualisiert werden.

Struktur

Die Evaluation gliedert sich in drei Phasen.

Transformation (src/transformation.py): Der Eingabetext wird verarbeitet. Für jede angegebene Transformation wird ein Ordner mit dem entsprechenden Namen angelegt. Der verarbeitete Text wird zur Eingabedatei hinzugefügt und wieder als CSV-Datei gespeichert.
Evaluation (src/evaluation.py): Die verarbeiteten Texte werden eingelesen, Metriken bestimmt und diese wiederum zur CSV-Datei hinzugefügt.
Zusammenfassung (src/summarize.py): Die Evaluation liegt zunächst für jede Transformation separat vor. Hier werden sie eingelesen, gemittelt und die zusammengefassten Werte ausgegeben.

Soll nur die Transformation durchgeführt werden (beispielsweise um die Funktionalität des Backends zu testen), kann das --only-transform Flag gesetzt werden:

CURRENT_UID=$(id -u):$(id -g) docker compose up backend -d
CURRENT_UID=$(id -u):$(id -g) docker compose build evaluation
CURRENT_UID=$(id -u):$(id -g) docker compose run --rm -it evaluation "python3 main.py --only-transform"

Der Code für die Datensatzgenerierung liegt primär in src/create_dataset.py.

Erweiterung & Anpassung

Transformationen

Transformationen sind in src/transform.py definiert und können dem match-case in der Funktion transform() hinzugefügt werden. Eine mögliche Erweiterung ist die Transformation mit einem beliebigen Modell statt des hier genutzten Backends.

Indizes

Die Indizes sind in src/indices.py definiert und können dort erweitert und ausgetauscht werden. Um einen neuen Index hinzuzufügen muss zunächst eine Funktion mit der Signatur fn(original_text: str, transformed_text: str) -> float implementiert werden. Die Funktion example_index in src/indices.py kann hier als Beispiel dienen. Anschließend muss die Funktion zum Dictionary INDEX_FUNCTIONS am Ende von src/indices.py hinzugefügt werden. Der Key muss hierbei ein String sein, der dann in der Konfiguration config/evaluation.yaml unter indices verwendet wird, um den Index zu aktivieren.

Zusammengefasst:

Funktion definieren
Funktion in src/indices.py zu INDEX_FUNCTIONS hinzufügen
Index in config/evaluation.yaml unter indices aktivieren