judge-mcp

English: README.en.md

LLM-as-Judge-Textqualitätsbewertung als MCP-Server.

Bewertet Paare aus Original- und überarbeitetem Text anhand einer mehrdimensionalen gewichteten Rubrik, testet Bewertungsmodelle mit einem Golden Set aus menschlichen Labels („Testen, nicht Trainieren") und validiert die Übereinstimmung zweier Bewerter kreuzweise. Alles wird über MCP-Tools bereitgestellt, sodass Bewertungen in jedem MCP-Client wie Claude Desktop oder Claude Code per Dialog ausgeführt werden können.

Warum

Für Korrektur, Rewriting und Zusammenfassung gibt es keine eindeutige richtige Antwort, weshalb immer mehr Teams LLM-Bewerter einsetzen. Doch ein unvalidierter Bewerter ist nur eine weitere Meinung. Dieser Server verallgemeinert eine Methodik, die in einem Projekt zur Analyse von Produktionslogs validiert wurde, zu einem Werkzeug.

1. Mehrdimensionale gewichtete Rubrik — Bedeutungserhalt, Natürlichkeit, Verbesserungsgrad, Zurückhaltung bei Überkorrektur. Statt einer undurchsichtigen Einzelpunktzahl wird pro Achse bewertet.

2. Golden-Set-Test — Bewerterkandidaten werden mit menschlichen Labels (gut korrigiert/übersehen/überkorrigiert) getestet. Sie werden niemals zum Training verwendet, sodass das Golden Set als Prüfungsbogen erhalten bleibt und bei jeder Rubrikänderung als Regressionstest wiederverwendet wird.

3. Kreuzvalidierung durch Doppelbewertung — Dieselben Fragen werden von zwei Bewertern bewertet, die Übereinstimmungsrate wird gemessen und empirisch geprüft, ob die Schlussfolgerung robust gegenüber der Bewerterwahl ist.

4. Deterministischer Pre-Filter — Unveränderte Paare werden ohne LLM vom Code bewertet. Günstig und immer dieselbe Antwort.

Related MCP server: mcp-eval-harness

Werkzeuge

Ein synthetisches Golden Set für koreanische Korrekturen mit 24 Fragen (3 Buckets) ist eingebaut; über golden_path kann ein eigenes Golden Set (JSONL: id, original, revised, label) verwendet werden.

Installation & Konfiguration

Jedes OpenAI-kompatible Backend funktioniert — OpenAI, lokales vLLM, Ollama, LM Studio.

pip install -e .

export JUDGE_API_BASE="https://api.openai.com/v1"   # vLLM이면 http://localhost:8000/v1
export JUDGE_API_KEY="sk-..."                        # 로컬 서버는 아무 값
export JUDGE_MODEL="gpt-4o-mini"                     # 또는 Qwen/Qwen2.5-7B-Instruct-AWQ

Ein Beispiel für die Claude-Desktop-Konfiguration finden Sie in examples/. Nach der Einrichtung können Sie zum Beispiel Folgendes fragen:

• „Bewerte diese Korrektur: Original ‚오늘 회의 몇시에 시작하나요', Überarbeitung ‚몇 시에 시작하나요?'"

• „Führe das Golden Set mit gpt-4o-mini aus und zeig mir die Leistungsübersicht"

• „Vergleiche, ob gpt-4o-mini und lokales Qwen als Bewerter übereinstimmen"

Gemessene Ergebnisse

Ergebnis des Tests des eingebauten Golden Sets mit 24 Fragen durch Claude Sonnet (claude-cli-Backend):

Selbst reproduzierbar: python scripts/run_golden.py --backend claude-cli (für OpenAI-kompatible APIs: --backend api).

Fallstudie: Das Golden Set deckte einen Designfehler auf

Der erste Lauf ergab 62,5 % — der Übersehen-Bucket lag bei 0/8. Die Ursache war nicht der Bewerter, sondern das Urteilsdesign. Übersehene Korrekturen erhalten bei Bedeutungserhalt und ohne Überkorrektur die volle Punktzahl auf den beiden stark gewichteten Achsen (0,40+0,35); selbst mit 1 Punkt auf der Verbesserungsachse ergibt sich eine Gesamtnote von 8–9. Übersehene Fälle über die Gesamtnote zu erkennen war mathematisch unmöglich.

Änderung: Das Urteil für den Übersehen-Bucket wurde von der Gesamtnote auf Verbesserungsachse ≤ 4 umgestellt. Der erneute Test ergab 62,5 % → 83,3 %, Übersehen 0/8 → 7/8. Genau dafür existiert die Golden-Set-Regressionsschleife — ein still versteckter Designfehler der Bewertung wurde durch Messung aufgedeckt, behoben und per Regressionstest abgesichert. (Verbleibende Lücke: Im Überkorrigiert-Bucket wurde Lauf-zu-Lauf-Varianz der LLM-Bewertung beobachtet — ein Kandidat für Few-Shot-Anker, deren Verbesserung mit derselben Regressionsschleife validiert werden kann.)

Designhinweise

• Die Validierung des Bewerters ist der Kern. Bewertermodelle haben im Ausgangszustand extrem gegensätzliche Tendenzen; ohne Test zu wählen ist Spekulation. Die Genauigkeit wird über die Richtung beurteilt — gut korrigierte Überarbeitungen werden hoch bewertet (≥7), übersehene und überkorrigierte niedrig (≤5). Die Grauzone (5–7) wird bewusst als falsch gewertet.

• Reproduzierbarkeit zuerst. Temperatur 0, erzwungene JSON-Ausgabe mit Parsing, das gegen Codefences und Geschwätz robust ist, Begrenzung des Punktzahlbereichs, und Fälle ohne Modellbedarf (unverändert) laufen über den Codepfad.

• Handlungsorientierte Fehler. Verbindungs- und Schemafehler liefern keine Stacktraces, sondern Nachrichten, die erklären, „was zu beheben ist".

Tests

pip install -e ".[dev]"
pytest   # 21건, 네트워크 불필요 (모의 LLM)

Lizenz

MIT