Движок разметки: CLI, REST API, инструменты MCP и SDK

Сервер разметки, командная строка, REST API, инструменты MCP и Python SDK управляют одним и тем же движком разметки через один и тот же файл engine.sqlite в каталоге задачи. Можно начать исследование из командной строки, выдавать запросы людям через сервер и сертифицировать из ноутбука.

Исследованием одновременно управляет только один процесс. Планировщик запущенного сервера держит блокировку записи исследования, и пока он её держит, potato label run, potato label certify и Study.run() отказываются работать и сообщают об этом. Вместо этого сертифицируйте через сервер, с помощью POST /api/engine/v1/certify или админ-страницы. Блокировка нужна потому, что два управляющих процесса отобрали бы две калибровочные выборки и сертифицировали бы по меткам друг друга. Блокировка снимается, когда её владелец завершается. Владельца, убитого на той же машине, сразу заменяют, а владельца на другой машине заменяют после двух минут без сигнала жизни. Команды только для чтения (status, certificate, calls, export) работают в любое время.

Командная строка

Каждая команда движка принимает файл конфигурации исследования:

potato label <command> <config.yaml> [options]

Девять команд покрывают исследование от первого вызова модели до экспортированного набора данных:

Проверка прогресса ничего не тратит, потому что status, certificate и админ-страница читают сохранённые результаты. Каждый новый тест, будь то certify на новых метках или certify --retest, тратит часть бюджета ошибки контракта.

Файлы, которые записывает экспорт

potato label export записывает в выходной каталог файлы четырёх видов:

Обычные экспортёры (python -m potato.export и экспорт из админ-панели) экспортируют разметку людей, а их список есть на странице форматов экспорта. Среди них формат labeling_engine записывает те же файлы, что и potato label export, и отказывается работать, если движок не включён. Когда движок включён, экспорт в CSV, Parquet и Hugging Face добавляет два столбца, которые говорят, на какой запрос движка отвечала каждая разметка. engine_purpose содержит цель, например calibration, а engine_request содержит JSON с целью, вероятностью включения, видимостью, частью выборки и id запроса. По этим столбцам слепую случайную выборку можно отделить от ответов на запросы проверки.

REST API

Все маршруты движка находятся под /api/engine/v1 и возвращают JSON. Аутентифицируйтесь ключом администратора в заголовке X-API-Key или сессией администратора. Для чтения нужно право на админ-панель, для certify и plan нужно управление распределением, а для сертификата нужно право на экспорт.

Маршруты отвечают 404, когда движок для исследования выключен. Они отвечают 400 с ошибкой в JSON на недопустимый параметр, например limit, который не является числом, неизвестные purpose или status либо format, отличный от json, md или html.

Например, этот запрос получает текущий сертификат в формате Markdown с сервера на порту 8000:

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

Инструменты MCP

MCP-сервер предоставляет пять инструментов движка с теми же правами, что и маршруты REST:

• engine_status
• engine_requests
• engine_run, который выполняет один проход планировщика
• engine_certify, который принимает retest
• engine_certificate в форматах json, md или html

Выдача этих инструментов при выключенном движке вызывает предупреждение валидации. Через potato mcp connect отклонённый вызов (нет права, неверный параметр) возвращается как ошибка инструмента с сообщением сервера. Выдача инструментов и подключение клиента описаны в документации MCP-сервера.

Python SDK

Класс Study управляет движком из Python, например в ноутбуке:

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

Каждый метод повторяет команду или маршрут:

Пример размечает каждый открытый запрос как «positive» только для того, чтобы показать вызовы. Метка, записанная через Study.label и не отвечающая ни на один запрос, сохраняется как органическая, а органические метки никогда не сертифицируют, поэтому скрипт, размечающий объекты, которые движок не запрашивал, добавляет метки, которые не читает ни один контракт.

Дополнительные материалы

• Движок разметки
• Конфигурация движка разметки
• Контракты движка разметки
• Админ-панель, которая ссылается на админ-страницу движка

Подробности реализации смотрите в исходной документации.