Datensatz nutzen¶

Diese Seite richtet sich an Nutzer des Datensatzes, etwa um ein eigenes Modell zu evaluieren oder zu trainieren. Sie erklärt, was im Datensatz steckt, was man ausführt und wie man ein eigenes Modell anbindet.

Das Notebook benchmark/llm_benchmark_de.ipynb bietet einen einfachen Einstieg in die Nutzung vom Datensatz:

Datensatz beschaffen¶

Der Datensatz ist Teil des Repositorys unter benchmark/. Es ist kein separater Download nötig:

git clone https://github.com/dgaida/PyADM1ODE.git
cd PyADM1ODE

Die Umgebung mit PyADM1ODE wird für das Ausführen von Code benötigt (Conda-Umgebung biogas empfohlen). Reine Bewertung von Graphen (matcher.py) und der Viewer kommen ohne PyADM1ODE aus.

Was steckt drin?¶

benchmark/
  schema/    plant_datapoint.schema.json   JSON-Schema (Draft 2020-12) eines Datenpunkts
  dataset/   index.json                    Manifest aller Datenpunkte
             BGA1/ BGA2/ ...               je eine Anlage mit Input-Varianten + gold.py
  eval/      solve.py runner.py matcher.py batch.py make_index.py validate.py …
  viewer/    index.html                    interaktiver Datenpunkt-Viewer

Ein Ordner pro Anlage. Darin liegen alle Input-Varianten und eine gemeinsame Gold-Lösung gold.py (korrekter PyADM1ODE-Code).

Datei	Rolle
`BGAx_<variante>.json`	Aufgabe: Input (Text, Bild oder PDF) für das Modell und die Referenz-Anlage (typisierter Graph) zum Abgleich
`gold.py`	Gold-Lösung: bekannt korrekte Umsetzung, validiert den Harness und dient als Referenzcode

Varianten und Regime¶

Jede Anlage existiert in mehreren Varianten. Das Suffix _full markiert die Vollständigkeit:

fully_specified (_full): alle Angaben im Input – kein Oracle nötig.
underspecified (ohne _full): Werte fehlen – das Modell muss beim Oracle
nachfragen. Raten hilft nicht, dafür sind die Akzeptanzbänder zu eng.

Achse	Werte	Verteilung (24)
Anlage	BGA1, BGA2, BGA3	je 8
Vollständigkeit	fully_specified / underspecified	12 / 12
Modalität	text / image / hybrid / pdf	18 / 3 / 3 / 0
Sprache	de / en	18 / 6

Den genauen Aufbau eines einzelnen Datenpunkts beschreibt Ein Datenpunkt im Detail. Das maßgebliche Format steht im JSON-Schema unter benchmark/schema/plant_datapoint.schema.json.

Was man ausführt¶

Ziel	Befehl
Matcher-Selbsttest (ohne PyADM1ODE)	`python benchmark/eval/selftest.py`
Datenpunkte gegen das Schema prüfen	`python benchmark/eval/validate.py`
Baseline – alle Datenpunkte mit `gold.py`	`python benchmark/eval/batch.py`
Ein Datenpunkt: Code ausführen + bewerten	`python benchmark/eval/runner.py <datapoint.json> <code.py>`
Nur Graph bewerten (ohne Code-Lauf)	`python benchmark/eval/matcher.py <datapoint.json> <candidate.json>`
LLM-Evaluation	`python benchmark/eval/solve.py [Filter]`
Viewer/Index aktualisieren	`python benchmark/eval/make_index.py`

Beispiele:

# 1) Schneller Funktionscheck des Matchers (kein PyADM1ODE nötig)
python benchmark/eval/selftest.py

# 2) Baseline: alle 24 Datenpunkte gegen ihre gold.py bewerten
python benchmark/eval/batch.py

# 3) Einen einzelnen Datenpunkt mit der Gold-Lösung ausführen und bewerten
python benchmark/eval/runner.py \
    benchmark/dataset/BGA1/BGA1_text_de.json benchmark/dataset/BGA1/gold.py

batch.py schreibt benchmark/results.csv. solve.py legt CSV + den generierten Code je Datenpunkt unter benchmark/results/ ab.

Eigenes Modell anbinden oder trainieren¶

Die Eingabe liegt im Datenpunkt unter input (Felder modality, language, content, ggf. image_path oder document_path). Das Ziel ist lauffähiger PyADM1ODE-Code, der die Anlage baut. Die Referenz zum Abgleich steht unter reference (Bauteile + Verbindungen als typisierter Graph). gold.py zeigt je Anlage eine korrekte Umsetzung.

Am schnellsten geht es interaktiv im Notebook. Für automatisierte Läufe gibt es zwei Skript-Wege (A und B).

A) Offline Code erzeugen, dann bewerten¶

Lasse dein Modell pro Datenpunkt einen Python-Code erzeugen und speichere ihn als <datapoint-id>.py in einem Ordner. Danach:

python benchmark/eval/batch.py --candidates pfad/zu/modell_ausgaben

batch.py führt jeden Kandidaten isoliert aus und bewertet ihn.

B) Direkt über solve.py (API)¶

solve.py ist ein vollständiger Lauf inkl. Oracle-Runden. Standardmäßig nutzt es die Groq-API. Für ein eigenes Modell muss nur die Client-Sektion in solve.py angepasst werden, der restliche Ablauf (Prompt, Oracle, Bewertung) bleibt gleich.

```bash pip install -e ".[benchmark]" # groq + pypdf; bzw. eigene Client-Bibliothek export GROQ_API_KEY=... # bzw. eigener API-Key python benchmark/eval/solve.py --regime fully_specified # einfachster Einstieg

### Rückfragen bei unterspezifizierten Datenpunkten

Fehlt eine Angabe, darf das Modell zuerst fragen — als JSON-Block mit
`open_questions` (Format siehe `prompt.py`). `solve.py` reicht die Fragen an das
[Oracle](oracle.md) weiter und schickt die Antworten in einen zweiten Turn.

Die Rückfragen selbst werden **nicht** benotet. Bewertet wird nur die Anlage, die
am Ende dabei herauskommt: Wer nicht fragt und trotzdem plausible Werte trifft,
verliert nichts — wer nicht fragt und daneben liegt, verliert bei **Maße**.

## Programmatischer Zugriff

Das Manifest `dataset/index.json` listet alle Datenpunkte mit `id`, `path`,
`language`, `modality`, `regime`:

```python
import json
from pathlib import Path

root = Path("benchmark/dataset")
index = json.loads((root / "index.json").read_text(encoding="utf-8"))

for entry in index["datapoints"]:
    dp = json.loads((root / entry["path"]).read_text(encoding="utf-8"))
    task = dp["input"]["content"]        # Beschreibung für das Modell
    reference = dp["reference"]          # Soll-Anlage (Bauteile + Verbindungen)
    # ... eigenes Modell aufrufen, Code erzeugen, bewerten ...

Bewertung¶

Bewertet werden drei Scores, die bewusst disjunkt sind — jeder Fehler zählt genau einmal:

Vollständigkeit – sind alle Pflicht-Bauteile und Pflicht-Verbindungen da?
Maße – simulierte Parameter (V_liq, V_gas, T_ad, P_el_nom, …) im Akzeptanzband.
Keine Erfindungen – enthält die Anlage nur Bauteile und Verbindungen, die die Referenz kennt?

Wie daraus die Endbewertung entsteht, erklärt Bewertung & Ablauf. Den Datensatz visuell erkunden kannst du im Viewer.