judge-mcp

English: README.en.md

Оценка качества текста по принципу LLM-as-Judge в виде MCP-сервера.

Оценивает пары «оригинал — исправленный текст» по многокритериальной взвешенной рубрике, проверяет модель-оценщика на золотом наборе с человеческими метками («проверка, а не обучение») и перекрёстно сверяет согласованность двух оценщиков. Всё это доступно через инструменты MCP, поэтому оценку можно запускать в диалоге из любого MCP-клиента — Claude Desktop, Claude Code и других.

Зачем это сделано

У правки, переписывания и суммаризации нет единственно верного ответа, поэтому всё больше команд используют LLM-оценщиков. Но непроверенный оценщик — это просто ещё одно мнение. Этот сервер обобщает в инструмент методологию, проверенную в проекте по анализу логов реального сервиса.

1. Многокритериальная взвешенная рубрика — сохранение смысла, естественность, наличие улучшения, сдержанность при чрезмерной правке. Вместо непрозрачной единой оценки — оценка по каждому критерию.

2. Проверка на золотом наборе — кандидат-оценщик проверяется на человеческих метках (хорошая правка / пропущенная правка / чрезмерная правка). Золотой набор никогда не используется для обучения, поэтому остаётся экзаменационным билетом и переиспользуется как регрессионный тест при каждом изменении рубрики.

3. Перекрёстная сверка двух оценщиков — один и тот же вопрос оценивается двумя оценщиками, измеряется согласованность, и эмпирически проверяется, устойчив ли вывод к выбору оценщика.

4. Детерминированный предварительный фильтр — пары без изменений оцениваются кодом, без LLM. Дёшево и всегда с одинаковым ответом.

Related MCP server: mcp-eval-harness

Инструменты

Встроен синтетический золотой набор из 24 вопросов по корейской правке (3 бакета); через golden_path можно подключить собственный золотой набор (JSONL: id, original, revised, label).

Установка и настройка

Работает с любым бэкендом, совместимым с OpenAI, — OpenAI, локальный 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

Пример настройки Claude Desktop — в examples/. После настройки можно спрашивать, например:

• «Оцени эту правку: оригинал "오늘 회의 몇시에 시작하나요", исправление "몇 시에 시작하나요?"»

• «Прогони золотой набор на gpt-4o-mini и покажи табель успеваемости»

• «Сравни, согласуются ли gpt-4o-mini и локальный Qwen как оценщики»

Реальные результаты

Результаты проверки встроенного золотого набора из 24 вопросов на Claude Sonnet (бэкенд claude-cli):

Воспроизведение: python scripts/run_golden.py --backend claude-cli (для API, совместимого с OpenAI, — --backend api).

Кейс-стади: золотой набор выявил дефект дизайна

Первый запуск дал 62.5% — бакет пропущенных правок 0/8. Причина была не в оценщике, а в дизайне вердикта. Пропущенная правка сохраняет смысл и не содержит чрезмерной правки, поэтому два критерия с большим весом (0.40+0.35) получают максимум, и даже при 1 балле за критерий улучшения итог составляет 8–9 баллов. Поймать пропущенную правку по итоговому баллу было математически невозможно.

Исправление: вердикт для бакета пропущенных правок изменён с итогового балла на критерий улучшения (improvement) ≤ 4. Повторная проверка: 62.5% → 83.3%, пропущенные правки 0/8 → 7/8. Именно для этого существует регрессионный цикл на золотом наборе — он эмпирически вскрыл тихо скрывавшийся дефект дизайна оценки, позволил его исправить и зафиксировать регрессионным тестом. (Оставшийся разрыв: в бакете чрезмерных правок наблюдается изменчивость LLM-оценки между запусками — кандидат на усиление few-shot якорями; улучшение можно проверить тем же регрессионным циклом.)

Заметки по дизайну

• Проверка оценщика — ключевое. Модели-оценщики в исходном состоянии имеют полярно противоположные склонности, поэтому выбор без проверки — это гадание. Точность определяется по направлению: хорошая правка оценивается высоко (≥7), пропущенная и чрезмерная — низко (≤5). Серая зона (5–7) намеренно считается ошибкой.

• Приоритет воспроизводимости. temperature 0, принудительный JSON-вывод + парсинг, устойчивый к код-фенсам и посторонним словам, клампинг диапазона баллов, а случаи, не требующие модели (без изменений), обрабатываются кодом.

• Действенные ошибки. При сбоях соединения или схемы возвращается не стектрейс, а сообщение о том, «что нужно исправить».

Тесты

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

Лицензия

MIT