ABLE - Chatbot-Evaluator

ABLE (Ableism Bias Language Evaluation)

Künstliche Intelligenz (KI) birgt großes Potenzial, um die Teilhabe von Menschen mit Behinderung zu verbessern. Allerdings hat sich gezeigt, dass KI-Systeme, insbesondere Sprachmodelle (Large Language Models, LLMs), diskriminierende Inhalte generieren und Vorurteile reproduzieren.

Das Projekt ABLE (Ableism Bias Language Evaluation) von Aktion Mensch in Zusammenarbeit mit der Hochschule Bielefeld setzt mit seiner Forschung hier an:

In enger Zusammenarbeit mit Menschen mit Behinderungserfahrung werden deutschsprachige Datensätze entwickelt, die Diskriminierung in KI-generierten Inhalten aufzeigen und für das Thema Ableismus sensibilisieren.

Weitere Infos zum Inhalt und Hintergrund des Projekts finden Sie hier: mehr zu ABLE

Neben einer Erläuterung des Projekts gibt es dort ein Tutorial, das die Einbindung des Tools für Entwickler*innen kurz erklärt.

ℹ️ Projektüberblick

Dieses Repository ist Teil des Projekts ABLE und enthält ein LLM-basiertes System zur automatisierten Evaluation von Chatbots auf ableistische Inhalte. Es besteht aus zwei zentralen Komponenten:

• ChatbotHandler: Diese Komponente setzt die Browserautomatisierung zur Interaktion mit Chatbots auf Webseiten um. Sie stellt Fragen an den Chatbot und empfängt dessen Antworten. Für jede Webseite wird ein spezifischer ChatbotHandler implementiert.
• ChatbotEvaluator: Diese Komponente erstellt gezielte (Folge-)Fragen auf Basis des bisherigen Gesprächsverlaufs sowie vordefinierter Kontextinformationen zur jeweiligen Webseite. Die Fragen werden über den ChatbotHandler an den Chatbot übermittelt. Im Anschluss wird die gesamte Konversation anhand eines detaillierten Kriterienkatalogs ausgewertet. Die Evaluationsergebnisse werden im JSON-Format gespeichert. Zum Einsatz kommen aktuelle OpenAI-Modelle, die über die Azure OpenAI-API verwendet werden.

🚀 Features

• Browserautomatisierung mit Selenium
• LLM-basierte Chatbot-Evaluation mit OpenAI-Modellen (Azure OpenAI-API)
• Automatisierte Generierung von PDF-Reports
• Web-App zur Visualisierung und Analyse der Evaluationsergebnisse

🗂️ Projektstruktur

able/
│
├── .vscode/                            # Konfiguration der empfohlenen VSCode-Erweiterungen
├── data/                               # Speicherort der Evaluationsergebnisse
├── src/                                # Sämtlicher Quellcode
│   │── able/
│   │   │── chatbot_handlers/           # ChatbotHandler-Klassen zur Browserautomatisierung
│   │   │── evaluator/                  # ChatbotEvaluator-Klasse
│   │   │── pdf_generator/              # PDFGenerator-Klasse
│   │   │── question_generator/         # QuestionCatalogGenerator-Klasse
│   │   └── __main__.py                 # Main-Datei der CLI-Anwendung (Command Line Interface)
│   │
│   └── frontend/                       # Quellcode der Web-App
│       │── index.html                  # Startseite der Web-App
│       │── script.js                   # JS-Script der Web-App
│       │── style.css                   # Styling der Web-App
│       └── web_app.py                  # Python-Skript zum Öffnen der Web-App im Browser
│
├── .env                                # Umgebungsvariablen (OpenAI-API-Schlüssel)
├── poetry.lock                         # Versionen der verwendeten Dependencies
└── pyproject.toml                      # Build- und Tool-Konfiguration

📦 Installation & Setup

1. Voraussetzungen

• Python 3.11
• Poetry installiert (Installationsanleitung)
  • Nach der Installation von Poetry sollte der folgende Befehl ausgeführt werden, damit in den nächsten Schritten die virtuelle Python-Umgebung innerhalb des Projektordners erzeugt wird: poetry config virtualenvs.in-project true
• Google Chrome Browser installiert

2. Installation des ChromeDrivers zur Browserautomatisierung

1. Chrome-Version in den Chrome-Einstellungen ermitteln: Einstellungen -> Hilfe --> Über Google Chrome
2. ChromeDriver für die passende Chrome-Version herunterladen
   • ChromeDriver Download-Seite
   • Passenden ChromeDriver auswählen und URL aufrufen
3. Die Installation des ChromeDrivers hängt vom verwendeten Betriebssystem ab:
   • Für MacOS:
     • .zip-Ordner entpacken: unzip ~/Downloads/mac-arm64.zip
     • ChromeDriver in den bin-Ordner verschieben: sudo mv ~/Downloads/chromedriver-mac-arm64/chromedriver /usr/local/bin/
     • Rechte anpassen: sudo chmod +x /usr/local/bin/chromedriver
     • Befehl chromedriver --version ausführen
     • Falls Befehl fehlschlägt: Unter Systemeinstellungen -> Datenschutz & Sicherheit -> Sicherheit die App erlauben.
     • Nun sollte nach der erneuten Ausführung des chromedriver --version Befehls die ChromeDriver-Version zu sehen sein.
   • Für Windows:
     • .zip-Ordner entpacken
     • chromedriver.exe in einen beliebigen Ordner verschieben
     • Pfad zum ChromeDriver zur Path-Systemvariable hinzufügen

3. Projekt klonen und initialisieren

git clone https://github.com/aktionmensch/able.git
cd able

4. Virtuelle Umgebung einrichten und Abhängigkeiten installieren

Option A: Mit Poetry (empfohlen)

# Abhängigkeiten installieren (erstellt automatisch .venv)
poetry install

# Virtuelle Umgebung aktivieren
# MacOS/Linux
source .venv/bin/activate

# Windows Powershell
.\.venv\Scripts\activate.ps1

# Windows CMD
.\.venv\Scripts\activate.bat

Option B: Mit pip und venv (Alternative, falls es auf Windows zu Problemen mit Poetry kommen sollte)

# Virtuelle Umgebung erstellen und aktivieren
python -m venv .venv

# MacOS/Linux
source .venv/bin/activate

# Windows Powershell
.\.venv\Scripts\activate.ps1

# Windows CMD
.\.venv\Scripts\activate.bat

# Abhängigkeiten installieren
pip install -r requirements.txt

5. API-Schlüssel konfigurieren

1. Eine neue .env-Datei erstellen
2. Inhalt der .env.example-Datei kopieren und die Platzhalter durch die entsprechenden Werte ersetzen.
   • Hinweis: AZURE_OPENAI_DEPLOYMENT_NAME und AZURE_OPENAI_REASONING_DEPLOYMENT_NAME legen die Sprachmodelle fest, die für den ChatbotEvaluator verwendet werden. Während der Entwicklung kamen hierbei gpt-4.1 als LLM bzw. o3-mini als Reasoning LLM zum Einsatz.
3. Konfiguration testen (Optional): Die Verbindung zu den Azure OpenAI Modellen kann mit python src/scripts/model_health_check.py getestet werden.

▶️ Chatbot-Evaluator über die Kommandozeile ausführen

Der Chatbot-Evaluator kann über die Kommandozeile mit verschiedenen Optionen ausgeführt werden:

Grundlegende Nutzung

# Falls die Abhängigkeiten mit pip und venv installiert wurden: 
# Wechseln Sie in das src-Verzeichnis
cd src

# Einfache Evaluation mit Standardeinstellungen (1 Evaluation, 3 Durchgänge)
python -m able

# Mehrere Evaluationen ausführen
python -m able --evaluations 3 --conversations 3 --follow-ups 5

Verfügbare Parameter

Parameter	Beschreibung	Standard	Beispiel
--handler	Auswahl des ChatbotHandlers. Derzeit ist nur der Handler für den Familienratgeber Chatbot vorhanden.	familienratgeber	--handler familienratgeber
--headless	Bei Verwendung dieses Parameters öffnet sich kein Chrome-Browser-Fenster für die Automatisierung.	False	--headless
--evaluations	Anzahl der Evaluationen	1	--evaluations 3
--conversations	Anzahl der Initialfragen pro Evaluation	3	--conversations 3
--follow-ups	Anzahl der generierten Folgefragen pro Konversation	3	--follow-ups 3
--question-type	Art der Fragen (problematic oder normal)	problematic	--question-type normal
--questions	Liste von initialen Fragen (siehe Hinweise)	Optional	--questions "Frage 1" "Frage 2"
--questions-file	Pfad zur Textdatei mit den initialen Fragen (siehe Hinweise)	Optional	--questions-file questions.txt
--output-folder	Ausgabeordner für Ergebnisse (optional)	Optional	--output-folder familienratgeber
--generate-pdf	Bei Verwendung dieses Parameters wird für jede Evaluation ein PDF-Report erzeugt (siehe Ausgabe und Ergebnisse).	False	--generate
--verbose	Detaillierte Ausgabe aktivieren (nur für Debugging-Zwecke)	False	--verbose

Hilfe anzeigen

python -m able --help

Dies zeigt alle verfügbaren Parameter und Beispiele an.

Beispiele für verschiedene Anwendungsfälle

1. Evaluation mit eigenen Fragen

python -m able --questions "Wie funktioniert Inklusion?" "Was ist Barrierefreiheit?" --conversations 2

2. Fragen aus Datei laden

python -m able --questions-file questions.txt --conversations 3

In den Dateien questions_example_kommune.txt und questions_example_veranstaltung.txt finden sich mögliche erste Fragen, die mit ableistischen Mustern und in durchaus provozierenden Formulierungen den Service-Chat hinsichtlich möglichst sensibler Antworten herausfordern sollen. Es handelt sich bei den provokanten Beispielen um Anregungen, die für den jeweiligen Service-Chat angepasst werden sollten.

3. Mehrere Evaluationen im Headless-Modus

python -m able --evaluations 10 --conversations 5 --headless --output-folder results

4. Normale (nicht-problematische) Fragen verwenden

python -m able --question-type normal --evaluations 3 --verbose

5. PDF-Reports generieren

python -m able --evaluations 5 --conversations 3 --generate-pdf

6. Kombination verschiedener Parameter

python -m able \
  --handler familienratgeber \
  --evaluations 5 \
  --conversations 6 \
  --follow-ups 3 \
  --question-type problematic \
  --headless \
  --output-folder evaluation_results \
  --verbose

Ausgabe und Ergebnisse

Evaluationsergebnisse

Der Evaluator erstellt für jede Evaluation eine JSON-Datei und speichert diese automatisch im data-Ordner. Wird ein --output-folder angegeben, so wird dieser im data-Ordner angelegt. Wird kein --output-folder, so wird automatisch ein Unterordner bestehend aus dem Namen des ChatbotHandlers (z. B. familienratgeber) und dem aktuellen Zeitstempel erzeugt.

Beispiel: --output-folder results

data/
  └──familienratgeber_20250811_161545     # Automatisch generierter Ordner aus einem früheren Durchlauf 
  └──results/                             # Neuer Ordner
    ├── evaluation_001.json
    ├── evaluation_002.json
    └── evaluation_003.json

PDF-Reports

Die PDF-Reports werden innerhalb des Zielordners in einem Unterordner pdf_reports gespeichert.

Wichtige Hinweise

• Initiale Fragen: Bitte geben Sie die initialen Fragen entweder über die Kommandozeile ein (Parameter --questions) oder in Form einer Textdatei (Parameter --questions-file). Werden diese beiden Parameter nicht verwendet, werden die Fragen automatisch generiert.
• Fragen-Datei Format: Textdateien (.txt) mit einer Frage pro Zeile
• Konversationen vs. Anzahl Fragen: Werden mehr Fragen angegeben als durch --conversations X vorgesehen, werden nur die ersten X Fragen gestellt. Ist --conversations größer als die Anzahl der angegebenen Fragen, werden in den übrigen Runden zusätzliche Fragen automatisch generiert.
• PDF-Generierung: Die PDF-Reports werden innerhalb des Zielordners in einem Unterordner pdf_reports gespeichert.

▶️ QuestionCatalogGenerator zur Generierung von Fragenkatalogen

Mithilfe des QuestionCatalogGenerators können Fragenkataloge für bestimmte Bewertungskategorien generiert werden. Der QuestionCatalogGenerator kann über die Kommandozeile mit verschiedenen Optionen ausgeführt werden:

Wichtig: Ersetzen Sie in der .env-Datei den Platzhalter der Variable AZURE_OPENAI_QUESTION_GEN_MODEL_DEPLOYMENT_NAME mit dem Namen des Modells, das Sie für die Fragengenerierung verwenden möchten!

Grundlegende Nutzung des QuestionCatalogGenerators

# Falls die Abhängigkeiten mit pip und venv installiert wurden: 
# Wechseln Sie in das src-Verzeichnis
cd src

# Die Parameter --num-question und --category sind zwingend erforderlich!
python -m able.question_generator --num-question 20 --category sprache

Alle verfügbaren Kategorien anzeigen lassen

python -m able.question_generator --list-categories

Folgende Kategorie sind verfügbar:

1. sprache
2. stereotype
3. fokus-norm-und-abweichung
4. verweis-sondersysteme
5. verhaeltnis-behinderungserfahrungen
6. behinderung-im-vordergrund
7. faktencheck
8. zentrierung-auf-ausschluss

Verfügbare Parameter des QuestionCatalogGenerators

Parameter	Beschreibung	Standard	Beispiel
--num-questions	Anzahl der zu generierenden Fragen (erforderlich).	Zwingend erforderlich	--num-questions 20
--category	Bewertungskategorie, auf die die generierten Fragen abzielen sollen.	Zwingend erforderlich	--category sprache
--context-file	Pfad zu einer Textdatei mit Kontextinformationen zum Chatbo (.txt).	Optional	--context-file context.txt
--examples-file	Pfad zu einer Textdatei mit Beispielfragen (.txt).	Optional	--examples-file examples.txt
--output-file	Pfad zu einer Ausgabedatei (.txt). Wird ein relativer Pfad angegeben, wird er unterhalb des Projekt-data Ordners erstellt. Falls nichts angegeben wird, wird ein Standardname verwendet und die Datei im data-Ordner gespeichert.	Optional	--output-file fragenkatalog.txt
--max-chars-per-question	Maximale Zeichenanzahl pro Frage	200	--max-chars-per-question 300
--batch-size	Batchgröße für die Generierung. Bestimmt, wie viele Fragen pro API-Aufruf generiert werden.	10	--batch-size 20
--temperature	Beeinflusst die Kreativität des Modells bei der Fragengenerierung.	Default: 0.8 Muss ein Wert zwischen 0.0 - 2.0 sein.	--temperature 0.8
--max-tokens	Maximale Anzahl an Completion-Tokens pro API-Aufruf. Kann erhöht werden, wenn eine hohe Batch-Size verwendet wird.	2000	--max-tokens 2000
--verbose	Detaillierte Ausgabe aktivieren (nur für Debugging-Zwecke)	False	--verbose

Hilfe zum QuestionCatalogGenerator anzeigen

python -m able.question_generator --help

🖥️ Web-App

Die Web-App ermöglicht die Visualierung der Evaluationsergebnisse. Hierzu kann ein Ordner mit den Evaluationsergebnissen mithilfe des Buttons 📁 Ordner auswählen hochgeladen werden.

Öffnen Sie die Datei src/frontend/index.html in einem Browser, um die Web-App zu starten.

Alternativ kann die Web-App mit dem folgenden Befehl gestartet werden:

python src/frontend/web_app.py

⚙️ Entwicklung & Konventionen

Codequalität

• Ruff: Linter & Formatter
• Mypy: Statische Typprüfung
• Pyright: Weitere Typprüfung (nur in VSCode genutzt)

Die Konfiguration erfolgt über die pyproject.toml. Nutzer von VSCode sollten die empfohlenen Erweiterungen installieren. Diese werden durch die .vscode/settings.json vorkonfiguriert, sodass linting, formatting etc. korrekt funktionieren.