ABLE

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #golang #rust #deep-learning #linux #macos #java #awesome #awesome-list #pytorch #security

(★ 13)

Das Projekt ABLE (Ableism Bias Language Evaluation) ist eine Initiative von Aktion Mensch und der Hochschule Bielefeld, die erforscht, wie KI-Systeme diskriminierende Inhalte und Vorurteile reproduzieren.

ABLE Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://www.aktion-mensch.de/kuenstliche-intelligenz-und-inklusion/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.

![Architektur](https://raw.githubusercontent.com/aktionmensch/ABLE/master/images/architecture.png)

## 🚀 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

```zsh
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](https://python-poetry.org/docs/#installation))
  * 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](https://googlechromelabs.github.io/chrome-for-testing/#stable)
    * 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

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

### 4. Virtuelle Umgebung einrichten und Abhängigkeiten installieren

#### Option A: Mit Poetry (empfohlen)

```bash
# 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)

```bash
# 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

```bash
# 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)](#wichtige-hinweise) | Optional | `--questions "Frage 1" "Frage 2"` |
| `--questions-file` | Pfad zur Textdatei mit den initialen Fragen [(siehe Hinweise)](#wichtige-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)](#ausgabe-und-ergebnisse). | `False` | `--generate` |
| `--verbose` | Detaillierte Ausgabe aktivieren (nur für Debugging-Zwecke) | `False` | `--verbose` |

### Hilfe anzeigen

```bash
python -m able --help
```

Dies zeigt alle verfügbaren Parameter und Beispiele an.

### Beispiele für verschiedene Anwendungsfälle

#### 1. Evaluation mit eigenen Fragen

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

#### 2. Fragen aus Datei laden

```bash
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

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

#### 4. Normale (nicht-problematische) Fragen verwenden

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

#### 5. PDF-Reports generieren

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

#### 6. Kombination verschiedener Parameter

```bash
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`

```zsh
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

```bash
# 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

```bash
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` <br> 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

```bash
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:

```bash
python src/frontend/web_app.py
```

## ⚙️ Entwicklung & Konventionen

### Codequalität

* [Ruff](https://docs.astral.sh/ruff/): Linter & Formatter
* [Mypy](https://mypy-lang.org/): Statische Typprüfung
* [Pyright](https://github.com/microsoft/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.

ABLE

ABLE Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ABLE

ABLE Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README