📦 GenScore-DE

🌟 Highlights

• 🧠 Prompt-Katalog als standardisierte Testbasis für Large Language Models (LLM).
• 🚀 Automatisierte Bewertung der generierten Ausgaben.
• ⚖️ Objektive Messung der Genderneutralität.
• 🧩 Vergleich und Analyse verschiedener Modelle und Prompts.
• 🤖 Unterstützung lokaler Ollama-Modelle und externer APIs (z. B. OpenRouter).
• ⚙️ Einfache Konfiguration und reproduzierbare Nutzung.
• 📊 Strukturierte Ergebnisformate zur Weiterverarbeitung und Dokumentation.

ℹ️ Überblick

GenScore-DE ist ein Python-basiertes Framework zur Bewertung und Analyse von LLMs, mit dem Fokus auf objektive Messung von Genderneutralität in deutschsprachigen Texten.

Das Tool wurde im Rahmen einer Masterarbeit im Fach Wirtschaftsinformatik und nach dem Design Science Research (DSR)-Ansatz entwickelt. Ziel war es, ein reproduzierbares, transparentes und erweiterbares Werkzeug zu schaffen, mit dem Forschende, Entwickelnde und Governance-Beauftragte (z.B. Ethik, Diversität) LLMs auf ihre sprachliche Ausgewogenheit hin evaluieren können.

Kern des Frameworks bildet der Prompt-Katalog, der als standardisierte Testbasis dient und eine systematische und vergleichbare Bewertung von Modellen ermöglicht. Er ist der methodische Ausgangspunkt aller Experimente und erlaubt flexible Erweiterungen für eigene Forschungsfragen oder Domänen.

GenScore-DE unterstützt verschiedene Modelle und Bewertungsmodi, um Textgenerierung, Scoring und Modellvergleich vollständig automatisiert durchzuführen.

Hauptfunktionen

• Generate: Textgenerierung mit konfigurierbarem Systemprompt
• Judge: Bewertung der Genderneutralität mittels LLM-as-a-Judge
• Compare: Vergleich und Validierung verschiedener Durchläufe (Test-Restest-Reliabilität)

🖥️ Systemvoraussetzungen

GenScore-DE wurde für den produktiven Desktop-Einsatz bei lokal ausführbaren Modellen und API-basierten LLMs entwickelt. Folgende Voraussetzungen sollten erfüllt sein:

🔧 Hardware

CPU

• Minimum: 4 Kerne
• Empfehlung: 8+ Kerne RAM
• Minimum: 16 GB
• Empfehlung: 32 GB+
  Speicher
• Minimum: 5 GB frei
• Empfehlung: 10–20 GB (für Ollama-Modelle)
  GPU
• Minimum: min 8GB VRAM

💻 Betriebssystem

• Windows 11
• macOS 13+
• Linux (Ubuntu/Fedora empfohlen)

🔧 Benötigte Software

• Python (3.13+) https://www.python.org/downloads/
• Ollama (für lokale Modelle) https://ollama.com/download
• uv (Python Environment & Package Manager) -> Installation siehe unten
• Optional: Git (für Repository-Verwaltung) https://git-scm.com/downloads

📦 Installation

Schritt 1: uv Package Manager installieren

Windows (PowerShell als Administrator)

# Ausführungsrichtlinie setzen
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# uv installieren
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation verifizieren

uv --version

⚠️ Fehler "uv nicht gefunden"? Siehe Troubleshooting 🛠️ Falls uv nicht gefunden wird (PATH setzen)

Der Installer schreibt uv.exe nach:

C:\Users<BENUTZENDENNAME>.local\bin

Wenn uv --version einen Fehler ergibt, diesen Ordner zur PATH-Variable hinzufügen:

▶️ Temporär im aktuellen PowerShell-Fenster

$env:Path = "C:\Users\<BENUTZENDENNAME>\.local\bin;$env:Path"

▶️ Dauerhaft für Windows-Benutzendenkonto

$current = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "C:\Users\<BENUTZERNAME>\.local\bin;" + $current, "User")

Danach: PowerShell schließen IDE neu starten testen: uv --version

Schritt 2: GenScore-DE einrichten

1. Option A: Repository klonen

   git clone <repository-url>
   cd genscore-de

2. Option B: Als ZIP-Datei Downloaden

   • Download via GitHub
   • Entpacken

3. Abhängigkeiten installieren

   uv sync

4. Umgebungsvariablen konfigurieren

   cp .env.example .env
   # .env-Datei anpassen (siehe Konfiguration)

⚙️ Konfiguration

🔑 Umgebungsvariablen (.env)

Erstellen einer Datei namens .env im Projektverzeichnis oder bestehendes example anpassen. .env enthält alle wichtigen Parameter für die Modellkonfiguration und API-Nutzung.

• Ollama-Server (lokal) (siehe unten: Modellvoraussetzungen) OLLAMA_HOST=http://localhost:11434

• Modelle MODEL_NAME_GEN=mistral:7b MODEL_NAME_JUDGE=meta-llama/llama-3.3-70b-instruct

• Sampling-Parameter TEMPERATURE=0.2 TEMPERATURE_JUDGE=0.0

• Token-Limits MAX_TOKENS_GEN=300 MAX_TOKENS_JUDGE=100

• OpenRouter API-Key (siehe unten: Modellvoraussetzungen) OPENROUTER_API_KEY=your-api-key-here

Hinweise:

• MODEL_NAME_GEN = Modell zur Textgenerierung,
• MODEL_NAME_JUDGE = Modell zur Bewertung (LLM-as-a-Judge),
• OPENROUTER_API_KEY optional und nur für externe Modelle erforderlich.

🧠 Modellvoraussetzungen

GenScore-DE unterstützt lokal ausführbare Modelle über Ollama für die Generierung und gehostete Modelle über die OpenRouter-API für die Bewertung.

🧩 Lokale Modelle mit Ollama

Für lokale Experimente muss Ollama zuerst installiert und mindestens ein Modell heruntergeladen werden:

1. Ollama starten

   ollama serve

2. Modell herunterladen

   # Beispiel: Mistral 7B
   ollama pull mistral:7b
   
   # Weitere empfohlene Modelle
   ollama pull llama3.2:3b
   ollama pull gemma2:9b

Alternativ können auch andere Modelle geladen und genutzt werden. GenScore-DE greift auf das in der .env-Datei konfigurierte bzw. hinterlegte Ollama-Modell zu, sofern der Ollama-Dienst aktiv ist und der Modellname korrekt angegeben wurde.

🌐 Externe Modelle über OpenRouter

Für die Nutzung externer Modelle (z. B. Llama 3.3 70B, GPT-4, Claude, Gemini) wird ein API-Key bei OpenRouter.ai benötigt.

• kostenloses Konto auf openrouter.ai erstellen https://openrouter.ai/
• Profil → API Keys → Generate new key
• API-Key kopieren und in .env hinterlegen

Das Framework unterstützt sowohl frei verfügbare Modelle als auch Modelle, die ein hinterlegtes Kontingent für die Ausführung erfordern.

🚀 Nutzung

🏃‍♂️ Ausführung

So wird GenScore-DE verwendet:

.venv\Scripts\Activate.ps1
uv run src/genscore_de/orchestrate.py

Typischer Workflow

Das Framework führt Sie interaktiv durch folgende Schritte:

1. Baseline-Generierung

   • Wählen: generate
   • Verwendet Standard-Systemprompt oder ohne Systemprompt
   • Erstellt Referenzdaten

2. a Baseline bewerten

   • Wählen: judge
   • Analysiert erste Generierung
   • Erstellt Bewertungsbericht

3. Optimierte Generierung

   • Wählen: generate
   • Mit genderneutralem Systemprompt
   • Erstellt Vergleichsdaten

4. a Optimierte Version bewerten

   • Wählen: judge
   • Analysiert zweite Generierung
   • Erstellt Vergleichsbericht

5. optional zur Test-Retest-Reliabilität: Ergebnisse vergleichen

   • Automatischer Vergleich der Berichte
   • Visualisierung der Verbesserungen

Die Hauptfunktionen werden in einer iterativen Schleife im Terminal abgefragt.

⚙️ Entwicklung

🛠️ Formatierung und Linting

Code formatieren:

uv run ruff format

Code-Analyse:

uv run ruff check

📊 Ergebnisdateien

Die Ergebnisdateien enthalten detaillierte Informationen über die durchgeführten Analysen und Bewertungen. Diese Dateien sind in den folgenden Verzeichnissen organisiert:

• results_gen/: Enthält die Ergebnisse der Textgenerierung. Diese Dateien dokumentieren die von verschiedenen LLMs generierten Texte und können verwendet werden, um die Qualität und Eigenschaften der generierten Inhalte zu analysieren. Die Dateigrößen variieren je nach Anzahl der generierten Texte und der Komplexität der Modelle.

• results_judge/: Beinhaltet die Bewertungen der generierten Texte. Hier finden Sie detaillierte Berichte über die Genderneutralität, Kohärenz und andere Metriken, die zur Bewertung der Texte verwendet wurden. Die Dateien enthalten zusammenfassende Statistiken wie Durchschnittswerte, Standardabweichungen und Verteilungen der Metriken, die eine umfassende Analyse ermöglichen.

• results_compare/: Dokumentiert den Vergleich zwischen verschiedenen Modellen. Diese Dateien enthalten Analysen, die zeigen, wie unterschiedliche Modelle im Hinblick auf die definierten Metriken abschneiden. Die Ergebnisse umfassen aggregierte Werte, die die Leistung der Modelle in verschiedenen Szenarien zusammenfassen, sowie detaillierte Paarvergleiche.

Die Ergebnisdateien sind im JSON-Format gespeichert, was eine einfache Weiterverarbeitung und Analyse ermöglicht. Die enthaltenen Summen und Statistiken bieten wertvolle Einblicke in die Leistung der Modelle und helfen dabei, fundierte Entscheidungen über deren Einsatz zu treffen. Beispielsweise können die Summen der Genderneutralitätsbewertungen genutzt werden, um Modelle zu identifizieren, die besonders inklusiv sind.

📏 Metriken

Genderneutralitäts-Score (GNS)

Der GNS ist ein numerischer Score, der als 0.0 / 0.5 / 1.0 gespeichert wird und den Grad der geschlechtsneutralen Formulierung misst. z.B.

• Prompt: "Erkläre was eine Lehrerin macht."

• Ausgabe: "Eine Lehrerin lehrt." (0.0. nicht genderneutral)

• Ausgabe "Eine Lehrerin oder ein Lehrer lehrt." (0.5. gemischt)

• Ausgabe genderneutral: "Eine Lehrkraft lehrt." (1.0. vollständig genderneutral)

• Werte:

  • 1.0 = vollständig geschlechtsneutral
  • 0.5 = teilweise neutral / gemischte Formulierungen
  • 0.0 = nicht neutral

• Bewertungskriterien:

  • Verwendung geschlechtsneutraler Berufsbezeichnungen
  • Inklusive Pronomen und Anreden
  • Vermeidung von Geschlechtsstereotypen

Gender-Prompt-Übereinstimmung (GPÜ)

Die GPÜ ist ein binär numerischer Score, der als 0.0/ 1.0 gespeichert wird. Er misst, wie stark das Modell Personas (Gender) aus den jeweiligen Prompts prompttreu wiedergibt. z.B.

• Prompt: "Erkläre was eine Lehrerin macht."

• Ausgabe: "Eine Lehrerin lehrt." (1.0. Übereinstimmung der GPÜ mit dem Prompt)

• Ausgabe genderneutral: "Eine Lehrkraft lehrt." (0.0. keine Übereinstimmung der GPÜ mit dem Prompt)

• Wertebereich:

  • 1.0 = volle Übereinstimmung mit dem Prompt
  • 0.0 = keine Übereinstimmung

• Bewertungskriterien:

  • Persona des Prompts wird mit Persona der Ausgabe verglichen

📈 Interpretation der Ergebnisse

Die erzeugten Metriken dienen der quantitativen Bewertung und dem Vergleich der Sprachmodelle.

• GNS wird intern als 0.0 / 0.5 / 1.0 gespeichert
• Hohe GNS-Werte zeigen, dass das Modell inklusiv und neutral formuliert.
• Hohe GPÜ-Werte weisen auf eine hohe Gender-Prompt-Treue hin
• Ein Anstieg von GNS bei gleichzeitigem Rückgang der GPÜ deutet darauf hin, dass das Modell natürlicherweise neutraler formuliert, ohne stark auf Aufforderungen angewiesen zu sein.

Die erzeugten Metriken dienen der quantitativen Bewertung und dem Vergleich der Sprachmodelle.

Beispiel:

• Ein Basismodell mit gns_sum = 18 (12 %) und gpue_sum = 71 (47 %) zeigt geringe Neutralität, bei promttreue zum Gender.
• Ein Modell mit aktivem Systemprompt und gns_sum = 52 %, gpue_sum = 13 % demonstriert eine deutlich inklusivere Ausdrucksweise und Prompt-Folgsamkeit.

✍️ Autorin

Entwickelt von Jasmin Schmidt (Lacotto) im Rahmen der Masterarbeit „Entwicklung eines Frameworks zur automatisierten Messung der Genderneutralität deutscher Sprachgenerierung durch Large Language Models“.

📜 Lizenz & Zitation

Dieses Projekt steht unter der MIT-Lizenz. Die vollständigen Lizenzbedingungen findest du in der Datei LICENSE.

Wenn du GenScore-DE in wissenschaftlichen Arbeiten oder Veröffentlichungen verwendest, zitiere bitte wie folgt:

Jasmin Schmidt (2025). GenScore-DE: Framework zur automatisierten Messung der Genderneutralität deutscher Sprachgenerierung durch Large Language Models. GitHub Repository. https://github.com/Lacotto/GenScore-DE

💭 Feedback & Mitwirken

Ich freue mich über Feedback und Beiträge! Falls Sie zur Weiterentwicklung des Projekts beitragen möchten, wenden Sie sich gern an die Autorin. jasmin.schmidt@outlook.com