eval-harness: персонализированные оценки для локальных моделей и агентов — инструкция по применению

Запустить модель локально — полдела. Понять, работает ли она в реальных условиях — вот где начинается ад. Бенчмарки вроде MMLU или HumanEval показывают одно, а когда ты подсовываешь модели свой корпоративный датасет с диалогами поддержки — она сыпется. Или агент, который в тестах на python-коде блещет, а при вызове API начинает галлюцинировать tool calls.

Есть инструмент, который закрывает эту боль — eval-harness. Не путать с lm-evaluation-harness от EleutherAI. Речь о более гибкой, форкабельной утилите, заточенной под кастомные сценарии и агентов. На момент июля 2026 последний стабильный релиз — v2.4.1, с нативной поддержкой OpenAI-совместимых API, локальных раннеров (llama.cpp, vLLM, Ollama) и даже агентных циклов.

Что под капотом и зачем это нужно

Ты даешь eval-harness три вещи:

• модель (или endpoint);
• набор промптов + ожидаемых ответов (датасет);
• метрику (exact match, F1, BLEU, LLM-as-judge, callback).

Он гоняет пайплайн, собирает логи и отдает табличку с результатами. Звучит банально, но дьявол в деталях. Большинство тулов для оценки либо завязаны на облачные API (OpenAI Evals), либо требуют писать тонны boilerplate (Hugging Face evaluate). Eval-harness — это CLI-подход: eval-harness run --model ./model.gguf --dataset my_tasks.jsonl --metric exact_match. Никаких питонских ноутбуков, все конфиги в YAML.

Сравнение с альтернативами: кто кого

LangSmith — хорош для production-мониторинга, но если нужно быстро прогнать 50 кейсов локально без интернета — eval-harness удобнее. А про фреймворк Amazon для оценки агентов мы уже писали — там другая философия, больше про метрики бизнеса.

Как это выглядит на деле: два примера

1 Оценка суммаризации на локальной модели

Допустим, ты поднял LLaMA-3.2-8B через Ollama. Хочешь понять, насколько хорошо она суммаризирует чаты поддержки. Создаешь датасет в JSONL:

{"prompt": "Суммаризируй диалог: ...", "reference": "Клиент не смог войти, проблема решена сбросом пароля"}

Запускаешь:

eval-harness run \
  --model "ollama:llama3.2-8b" \
  --dataset summaries.jsonl \
  --metric rouge-l \
  --output results.json

На выходе — ROUGE-L по каждому примеру и среднее. Можно добавить LLM-as-judge (--judge gpt-4o-mini, если есть доступ). Результаты — в консоль и JSON. Легко автоматизировать в CI.

2 Агент: калькулятор и поиск

Классический сценарий: модель должна решить, вызвать ли tool calculator или search, и передать правильные аргументы. Eval-harness умеет симулировать окружение с инструментами. Конфиг YAML:

tasks:
  - name: "calculator addition"
    prompt: "сколько будет 2+2?"
    expected_tool: "calculator"
    expected_args: {"a": 2, "b": 2}

Запускаем с флагом --agent:

eval-harness run --model "llama.cpp:Qwen2.5-7B-Instruct-Q4_K_M.gguf" \
  --dataset agent_tasks.yaml --agent --tools calculator,search \
  --metric tool_call_accuracy

Инструмент смотрит: выбрал ли LLM правильный tool, не перепутал ли аргументы, вызвал ли в нужном порядке. Результат — процент успешных вызовов. Для глубокого разбора можно добавить --trace — получите лог каждого шага агента.

Тонкий момент: маленькие модели (<7B) часто пытаются вызвать несуществующие функции или забывают аргументы. Мы подробно разбирали эту проблему в статье про agent harness для локальных моделей. Совет: используйте формат tool calls как JSON в system prompt, а не в виде Python-функций.

Кому eval-harness реально упростит жизнь

• Разработчикам локальных LLM — тем, кто квантует, обрезает, дообучает. Вместо того чтобы писать eval скрипты каждый раз, бросаете датасет в harness и смотрите, не упала ли метрика после изменения.
• Инженерам агентных систем — особенно если вы экспериментируете с разными промптами для tool calls. Можно настроить регрессионные тесты: прогнать 100 кейсов до и после изменения промпта.
• Тем, кто устал от вендор-лока — если вы используете LocalAI, Ollama или собственный эндпоинт, eval-harness агностичен к бэкенду. Просто укажите --base-url http://localhost:8080.

Не подойдет, если вам нужны визуальные дашборды и сравнение моделей с красивыми графиками — тогда смотрите в сторону LangSmith или community evals на Hugging Face. Но для автоматизации и кастомных чеков — самое то.

Подводные камни, которые лучше знать заранее

Главная боль — кастомные метрики. Встроенных мало: exact_match, f1, rouge, bleu, tool_call_accuracy, llm_judge. Если нужно что-то свое (например, semantic similarity через embedding), придется писать Python-скрипт и регистрировать его через плагин. Документация по плагинам скудная — придется читать исходники. Но для 80% случаев хватает.

Вторая проблема — агентный режим сыроват. На маленьких моделях tool calls могут крашить пайплайн, если возвращаемое значение не парсится. В версии 2.4 добавили fallback: если модель вернула не JSON, а текст — eval-harness пытается вытащить tool call регуляркой. Спасает, но не всегда.

И последнее: на больших датасетах (10k+ примеров) логирование в JSON может сожрать гигабайты. Используйте --output sqlite://results.db — есть экспериментальная поддержка. Или пишите свой обработчик.

Зато ценник — ноль рублей. Репозиторий живой, коммиты регулярные. В отличие от той же lm-evaluation-harness от EleutherAI, где ментейнеры забили на локальные бэкенды и агентов, здесь чувствуется, что разработчики сами мучаются с локальными моделями.

Напоследок совет из практики: не пытайтесь засунуть в один eval всё сразу. Делайте по одному сценарию на задачу. И используйте --seed для воспроизводимости — иначе при каждом запуске будете получать разные цифры из-за семплинга. Агенты без seed — это лотерея, особенно на температуре >0.7.

Подписаться на канал