Последние
Разработка

Пакетная обработка запросов к ИИ: как подготовить batch и проверить результаты

Batch API подходит для больших несрочных серий запросов, но требует устойчивых идентификаторов, проверки каждой строки и отдельной обработки ошибок. Показываем воспроизводимый порядок от пробного запроса до сверки итогового файла.

В этом материале9 разделов
Batch: связываем запрос и результат. Не сопоставляйте результат со строкой только по позиции в файле.
Редакционная схема PENROUZ NEWS. Не сопоставляйте результат со строкой только по позиции в файле.

Сообщить об ошибке или предложить уточнение

Короткий ответ: пакетный режим нужен там, где ответ не требуется сразу

Пакетная обработка объединяет множество независимых запросов и передаёт их API как асинхронное задание. Приложение не ждёт каждый ответ в пользовательской сессии: оно создаёт batch, следит за статусом, а после завершения забирает результаты и ошибки. Такой режим подходит для массовой классификации, извлечения полей, расчёта embeddings и прогонов контрольного набора. Для чата, интерактивного поиска или операции, которую пользователь ожидает сейчас, нужен обычный синхронный запрос.

OpenAI, Gemini и Claude предоставляют собственные пакетные интерфейсы, но их форматы и ограничения различаются. Общая схема одинакова: подготовить записи, присвоить каждой устойчивый ключ, проверить небольшой образец, отправить пакет, дождаться конечного статуса и сопоставить каждый результат с исходной записью. Документация всех трёх платформ подчёркивает асинхронность; поэтому нельзя строить процесс так, будто пакет завершится к произвольной минуте.

Сначала отделите несрочную работу от интерактивной

Хороший кандидат не зависит от мгновенного ответа и может безопасно ждать. Например, ночью классифицировать каталог, подготовить черновые теги для архива или прогнать набор тестов после смены модели. Плохой кандидат — ответ в живом чате, подтверждение платежа, срочная модерация или шаг агента, от которого зависит следующее действие. Если часть процесса срочная, разделите его: минимальный ответ выполните синхронно, а необязательное обогащение перенесите в batch.

До подготовки файла оцените размер каждого входа и ожидаемого вывода. Материал про токены и контекстное окно помогает рассчитать объём без предположения, что символы равны токенам. Проверьте актуальные лимиты модели и batch-интерфейса в день запуска: допустимый размер файла, число записей, очередь токенов, срок обработки и хранения результатов относятся к конкретному поставщику и могут изменяться.

Каждой записи нужен собственный ключ

Порядок строк на выходе нельзя считать порядком входа. OpenAI рекомендует сопоставлять результаты через custom_id; Gemini возвращает пользовательский key; Claude требует уникальный custom_id внутри Message Batch. Создавайте ключ из внутреннего идентификатора задания и версии сценария, например `catalog-017-v2`. Не помещайте в ключ имя человека, электронную почту или иной закрытый реквизит. Таблица соответствий должна храниться в вашей системе, а не восстанавливаться по тексту ответа.

Ключ должен оставаться неизменным при повторном чтении результата, но новая попытка после исправления входа получает новый номер версии. Тогда журнал различает исходный запрос, повтор из-за временной ошибки и новую редакцию данных. Дубликаты ключей проверяйте до отправки. Если система поставщика отклоняет отдельную строку, журнал должен сохранить её статус и причину, не помечая весь набор как успешно обработанный.

Проверьте один запрос до массовой отправки

Возьмите одну типовую и одну пограничную запись, выполните их обычным поддерживаемым методом и убедитесь, что модель, параметры, схема ответа и лимит вывода работают. Anthropic прямо рекомендует dry run формы запроса перед большим batch. Эта проверка ловит неправильное имя модели, несовместимый параметр, слишком короткий max_tokens и ошибочную структуру до того, как в очередь попадут тысячи одинаково неверных строк.

Если результат должен быть JSON, сначала зафиксируйте схему и валидатор. Руководство про структурированный JSON от ИИ объясняет разницу между корректным синтаксисом и правильными значениями. Пакетный режим не усиливает достоверность модели: каждая строка всё равно может содержать отказ, обрыв, неверную категорию или формально допустимое, но выдуманное значение.

Рабочий пример: вымышленный каталог «Маяк»

У вымышленного магазина «Маяк» есть двадцать обезличенных карточек товаров без категорий. Для каждой записи известны внутренний код, название и краткое описание; цен, имён покупателей и закрытых данных нет. Задача модели — вернуть объект с полями `category`, `summary`, `needs_review` и `reason`. Допустимые категории заданы заранее, а сомнительные карточки должны получать `needs_review: true`, а не принудительно попадать в ближайший класс.

Сначала отправьте две карточки синхронно и проверьте схему. Затем создайте пакет из двадцати запросов с ключами `item-001-v1` — `item-020-v1`. Сохраните хеш инструкции, идентификатор модели и время отправки. После завершения загрузите результаты и для каждого ключа отметьте один из исходов: успех, ошибка API, отказ модели, неполный ответ, ошибка схемы или сомнительное значение. Отсутствующий ключ тоже является ошибкой полноты.

Для контрольной проверки заранее разметьте пять карточек человеком и не меняйте эталон после просмотра ответов. Сравните категорию, флаг ручной проверки и причину. Этот маленький пример не доказывает качество на всём каталоге, но показывает, что конвейер правильно связывает входы и выходы, распознаёт сбои и не теряет записи. После этого увеличивайте объём ступенчато, а не одним максимальным файлом.

Как читать статус и результаты

Статус пакетного задания и статус отдельной записи — разные уровни. Batch может завершиться, хотя часть запросов закончилась ошибкой, была отменена или истекла. Поэтому после конечного статуса считайте количество исходных ключей, полученных успешных результатов и всех остальных состояний. Итог должен сходиться до одной записи. Если числа не совпали, не запускайте автоматическое применение результата.

Скачанный файл обрабатывайте как недоверенный вход. Разбирайте строки независимо, проверяйте ключ, код ответа, структуру тела и бизнес-правила. Не полагайтесь на порядок. Неудачные записи складывайте в отдельную очередь с причиной. Автоматический повтор разрешайте только для временных технических ошибок; неверный формат, отказ или содержательная неопределённость требуют исправления запроса либо ручной проверки.

Стоимость и срок оцениваются по факту

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

Качество проверяйте отдельно от стоимости. Общий список из материала о проверке ответов ИИ применим и здесь: отделяйте подтверждённые данные от вывода модели, находите пропуски и не принимайте уверенный тон за доказательство. Дешёвый массовый запуск, который создаёт больше ручных исправлений или скрытых ошибок, не является эффективным.

Не забудьте о хранении и доступе

Асинхронная обработка требует, чтобы входы и результаты некоторое время хранились на стороне сервиса. Сроки доступности, изоляция по проекту или workspace и совместимость с режимами хранения различаются. Перед загрузкой проверьте политику конкретного batch-интерфейса, класс данных и права API-ключа. Не отправляйте персональные или закрытые сведения только потому, что пакет запускается в фоне.

Проверка результата

Пакетный процесс готов к ограниченному использованию, если пробные запросы проходят, все ключи уникальны, число результатов и ошибок сходится с числом входов, каждая строка валидируется независимо, а повторные попытки не создают скрытых дублей. Дополнительно сохранены версия инструкции, модель, параметры, время, метрики токенов и ручной эталон. Если хотя бы один из этих пунктов нельзя воспроизвести, сначала исправьте конвейер, а уже затем увеличивайте пакет.

Прозрачность

Источники и примечания

  1. Batch API | OpenAI API
  2. Batch API | Gemini API | Google AI for Developers
  3. Batch processing - Claude Platform Docs

В этом материале

На этом устройстве

Сохранённые материалы