Унифицированные пакетные задания через шлюз AI API: устойчивые очереди, адаптеры поставщиков и выставление счетов на уровне арендатора

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

Шаблон реализации заключается в том, чтобы сделать пакетное выполнение первоклассной подсистемой шлюза. Шлюз должен предоставлять один независимый от поставщика контракт задания, одновременно адаптируясь к пакетным API OpenAI, Anthropic, Gemini и будущих поставщиков.

Проблема читателя: пакетные API схожи по замыслу, но различаются по работе

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

Подтвержденные факты: Пакетный API OpenAI является асинхронным, считывает запросы из загруженного файла, записывает ответы в выходной файл и в настоящее время использует 24-часовое окно обработки. OpenAI перечисляет такие статусы, как проверка, не удалось, in_progress, завершение, завершено, истёк, отмена и отменено. API пакетов сообщений Anthropic обрабатывает множество запросов сообщений асинхронно, обрабатывает каждый запрос независимо, требует опроса и возвращает результаты после завершения обработки. Anthropic также рекомендует осмысленные значения custom_id, поскольку порядок результатов не гарантируется. Пакетный API Gemini предоставляет методы долговременного операционного стиля, такие как методы списка, отмены, удаления и обновления, а его операция отмены описывается как оптимальная.

Эти различия имеют значение, когда вы добавляете реальные бизнес-требования:

• Какому арендатору, клиенту, проекту или ключу API принадлежит каждый элемент?
• Был ли зарезервирован бюджет до того, как задание покинуло шлюз?
• Какие завершенные элементы подлежат оплате, если срок действия пакета истекает или истекает отменены?
• Как повторяются частичные сбои без дублирования успешной работы?
• Как долго можно получать файлы результатов и что должен хранить шлюз?
• Может ли партнер создать пакетную обработку на уровне клиента, не раскрывая учетные данные вышестоящего поставщика?

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

Рекомендуемый общедоступный API: отделяйте пакетные задания от синхронных завершений

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

Практический шлюзовой контракт включает в себя следующие операции:

• create_job: создание чернового задания, принадлежащего арендатору, проекту, ключевому клиенту или партнеру-клиенту.
• append_items или upload_manifest: добавление отдельных запросов со стабильным элементом идентификаторы.
• submit: проверить, зарезервировать бюджет, выбрать поставщика, отправить и заблокировать отправленный манифест.
• get_status: вернуть нормализованное количество заданий и элементов.
• list_results: просмотреть нормализованные результаты элементов, ошибки и использование.
• отменить: запросить отмену, не обещая немедленного выполнения завершение.
• export_usage: экспорт записей затрат на уровне задания и элемента для аналитических или биллинговых систем.

Пример общедоступного объекта задания:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "модель": "большой анализ",
  "статус": "работает",
  "считается": {
    «отправлено»: 50000,
    "завершено": 31240,
    «не удалось»: 180,
    "истёк": 0
  },
  "стоимость": {
    "расчетный": "184,20",
    "зарезервировано": "205.00",
    "урегулировано": "117,43",
    "валюта": "доллар США"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "submit_at": "2026-08-19T10:05:00Z",
  "retrival_deadline": "2026-09-17T10:00:00Z"

По умолчанию общедоступный объект не должен раскрывать идентификаторы файлов поставщика, имена операций или необработанные ошибки восходящего потока. Они относятся к метаданным, доступным оператору.

Используйте надежные записи о заданиях в качестве источника достоверной информации.

Пакетному уровню, принадлежащему шлюзу, необходимо устойчивое состояние, прежде чем что-либо будет отправлено в восходящий поток. Не полагайтесь на пакетные записи поставщика как на единственное хранилище состояний. Записи о поставщиках необходимы, но они не знают вашей иерархии клиентов, резервирования бюджета, внутренних псевдонимов моделей, клиентов-партнеров или требований к аналитике.

Минимальная модель базы данных

Полезная схема имеет три уровня:

1. Пакетное задание

batch_jobs
- идентификатор вакансии
- идентификатор_арендатора
- идентификатор_проекта
- customer_id может быть нулевым- api_key_id
- конечная точка
- запрошенная_модель
- разрешенный_провайдер
-solved_provider_model
- статус
- количество_предметов
- оцененные_входные_токены
- оцененные_выходные_токены
- зарезервированная_сумма
- урегулированная_сумма
- создано_at
- submit_at
- завершено_at
- истекает_в
- поиск_дедлайн
- cancel_requested_at

2. Элемент пакета

batch_items
- идентификатор вакансии
- идентификатор элемента
- custom_id
- идемпотентный_ключ
- запрос_хэш
- статус
- провайдер_request_index имеет значение null
- оцененные_токены
- act_input_tokens имеет значение null
- act_output_tokens имеет значение null
- урегулированная_сумма, обнуляемая
- result_pointer может иметь значение null
- error_code имеет значение null
- retry_of_item_id может быть нулевым
- создано_at
- поселен_at

3. Метаданные поставщика

batch_provider_metadata
- идентификатор вакансии
- провайдер
- провайдер_batch_id может иметь значение null
- input_file_id может быть нулевым
- выходной_file_id может иметь значение null
- error_file_id может быть нулевым
- имя_операции, допускающее значение null
- конечная точка
- регион обнуляемый
- родной_статус
-native_request_counts jsonb
- последний_опрос_at
- raw_error_pointer nullable

Отделение метаданных поставщика от общедоступного контракта задания позволяет шлюзу развивать адаптеры поставщика, не нарушая API, ориентированные на клиента.

Требуйте стабильные идентификаторы элементов перед отправкой

Рекомендация: создайте шлюз job_id и перед отправкой запросите для каждого элемента custom_id или ключ идемпотентности. Никогда не согласовывайте результаты по порядку.

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

Формат безопасного идентификатора товара является описательным, но не конфиденциальным:

tenantA.invoice_extraction.2026-08-19.row_000381

Избегайте использования в идентификаторах необработанных адресов электронной почты, имен, названий документов или секретов клиентов. Храните конфиденциальные данные корреляции в собственной базе данных арендаторов, а не внутри идентификаторов, видимых поставщику.

Нормализация статусов без удаления сведений о поставщике

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

Рекомендуемый нормализованный жизненный цикл:

• черновик: задание существует, но его все еще можно редактировать.
• проверка: проверка шлюза или поставщика выполняется.
• в очереди: принято, но еще не завершено обработка.
• running: поставщик обрабатывает элементы.
• finalizing: поставщик завершил вычисления и подготавливает артефакты результатов.
• completed: все принятые элементы достигли конечного успеха.
• completed_with_errors: некоторые элементы завершились успешно, а некоторые не удалось.
• expired: окно поставщика завершилось до завершения всей работы завершено.
• cancel_requested: арендатор запросил отмену, но окончательная оплачиваемая работа не урегулирована.
• отменено: отмена решена.
• failed: сбой на уровне задания помешал полезному выполнению.

Не сворачивайте ошибки собственного поставщика в общие метки слишком рано. Операторам по-прежнему необходим доступ к собственным статусам, ошибкам проверки, количеству запросов, идентификаторам файлов и именам операций при отладке.

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

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

Ваша внутренняя матрица возможностей должна проверять:

• Поддерживаемая конечная точка: чат, сообщения, внедрения, модерация или генерация.
• Приемлемость модели для пакетного режима.
• Максимальный размер задания, количество элементов, размер запроса и размер загруженного файла.
• Подходит ли потоковая передача запрещена.
• Поддержка использования инструментов и вызова функций.
• Поддержка структурированного вывода или схемы JSON.
• Поддержка изображения, аудио или мультимодального ввода.
• Ограничения по региону и резидентности.
• Удержание поставщика и окна получения результатов.
• Ограничения скорости и ограничения очереди для конкретных пакетов.
• Семантика отмены.

Хорошо предполетный ответ конкретен:

{
  "error": "batch_capability_not_supported",
  "message": "Выбранный пакетный адаптер провайдера не поддерживает потоковую передачу ответов. Удалитеstream=true или выберите синхронную конечную точку.",
  "field": "items[*].request.stream"

Это более полезно, чем принять задание и отклонить его после прохождения восходящей проверки.

Зарезервируйте бюджет клиента, а затем определите фактическое использование

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

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

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

Практические события реестра:

batch.estimated
партия.зарезервировано
партия.отправлено
партия.предмет.урегулирована
пакет.предмет.возвращен
пакетный.cancel_requested
пакет.истёкBatch.reconciled

Регистр на уровне позиций имеет важное значение. Если 45 000 элементов выполнены, а срок действия 5 000 истек, арендатору следует выставить счет за выполненную работу поставщика, а не за исходный манифест в виде одного недифференцированного объекта.

Создавайте адаптеры поставщика в качестве переводчиков, а не владельцев бизнес-логики

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

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

Обязанности адаптера

• Отображение манифестов запросов для конкретного поставщика.
• Загрузка входных файлов или создание операций поставщика.
• Сохранение идентификаторов поставщика в метаданных.
• Сопоставление собственного статуса с нормализованным статусом.
• Извлечение выходных данных и артефактов ошибок.
• Анализ результатов на уровне элементов.
• Возврат собственных записей использования, когда доступно.
• Поверхностная повторная попытка и ошибки терминала.

Обязанности шлюза

• Аутентификация арендатора и ключа API.
• Применение элементов управления командой, проектом и клиентом.
• Разрешение псевдонимов модели и политика маршрутизации поставщика.
• Проверка пакетных возможностей.
• Резервирование и расчет бюджета.
• Сохранение задания и элемента состояние.
• Применять политику хранения.
• Открывать аналитику и экспорт.

Такое разделение упрощает добавление нового поставщика без переписывания выставления счетов, аналитики или управления арендаторами.

Идемпотентный прием результатов

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

Рекомендация: используйте ключи идемпотентности на уровне элементов и ограничения уникальности реестра. Результат для job_id + custom_id должен согласовываться ровно один раз, даже если попытка приема повторяется.

Надежный поток приема:

1. Получить кратковременную блокировку для задания или артефакта результата.
2. Извлечь выходные данные поставщика и артефакты ошибок.
3. Разобрать записи в нормализованные события результата элемента.
4. Сопоставить каждую запись по custom_id или шлюзу Идентификатор элемента.
5. Запишите метаданные результата и использование в транзакции.
6. Создайте событие расчета в бухгалтерской книге, только если оно еще не существует.
7. Обновите количество заданий на основе состояний элемента, а не на основе предположений.
8. Освободите неиспользованное резервирование бюджета, когда известны все состояния терминала.

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

Повторяйте элементы, а не все задания

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

Классифицируйте сбои перед повторной попыткой:

• Ошибки проверки: обычно завершаются до тех пор, пока запрос не будет исправлен.
• Ошибки поставщика 5xx: часто повторяются с откатом.
• Сбои с квотой или ограничением скорости: повторите попытку только после исчерпания емкости доступно.
• Блоки безопасности: не повторяйте попытку вслепую; маршрут к обработке политики.
• Элементы с истекшим сроком действия: можно повторить попытку в новом задании, если арендатор по-прежнему хочет, чтобы работа и бюджет позволяют.

Повторная попытка должна создать новый элемент, связанный с исходным:

{
  "item_id": "item_retry_002",
  "retry_of_item_id": "item_001",
  "custom_id": "tenantA.eval.row_901.retry_1"

Не отправляйте повторно завершенные элементы только потому, что они были частью задания, которое закончилось как completed_with_errors или expired.

Решите, что хранить: необработанные результаты, указатели или хэши

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

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

Отслеживайте как минимум:

• Сохранялись ли необработанные входные данные.
• Сохранялись ли необработанные выходные данные.
• Где находятся артефакты результатов поставщика.
• Срок получения поставщика.
• Срок удаления шлюза.
• Хэш запроса и ответ на аудит без раскрытия контента.

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

Предоставляйте аналитику, соответствующую тому, как работают команды

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

Полезные показатели включают в себя:

• Количество отправленных, завершенных, неудачных, истекших и отмененных элементов.
• Оценочная и расчетная стоимость.
• Зарезервированный бюджет все еще удерживается.
• Токены ввода и вывода по поставщику и модели.
• Индикаторы попадания в кэш, где их предоставляют поставщики.
• Повторить попытку доля успешных подсчетов и повторных попыток.
• Среднее время нахождения в очереди, выполнения и завершения.
• Основные ошибки проверки по конечной точке и модели.
• Атрибуция клиентов-партнеров.

Для пользователей Partner API предоставляйте пакетные задания как ресурсы на уровне клиента. Это позволяет агентствам и разработчикам SaaS предлагать автономную обработку ИИ, сохраняя при этом учетные данные вышестоящего поставщика, сверку счетов и обработку ограничений скорости внутри шлюза.

Компромиссы, которые необходимо сделать явными

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

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

Опрос в сравнении с веб-перехватчиками: опрос прост и надежен, но может привести к потере вызовов API и задержке завершения. Веб-перехватчики работают быстрее, но требуют проверки подписи, защиты от повторного воспроизведения и мониторинга.

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

Большие пакеты по сравнению с фрагментированными пакетами: большие пакеты могут повысить эффективность на стороне поставщика, но меньшие фрагменты уменьшают радиус взрыва и упрощают повторные попытки.

Контрольный список реализации

• Создайте отдельную поверхность API пакетного задания.
• Сохраняйте записи заданий и элементов перед отправкой поставщику.
• Требуйте идентификаторы заданий шлюза и пользовательские идентификаторы для каждого элемента.
• Нормализация статусов при сохранении метаданных собственного поставщика.
• Создание матрицы возможностей для каждого пакетного адаптера поставщика.
• Проверка манифестов перед резервированием бюджета.
• Зарезервируйте бюджет клиента перед отправкой.
• Определите фактическое использование на уровне элемента после приема.
• Сделайте прием результатов идемпотентным.
• Повторяйте неудачные элементы выборочно, а не все задания вслепую.
• Отслеживайте сроки получения данных поставщиками и политику сохранения шлюзов.
• Предоставляйте аналитику заданий и объектов арендаторам и клиентам-партнерам.

Прогнозы: куда движется эта закономерность

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

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

Практический вывод

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

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

Связанное чтение

• выставление цен, резервирование, расчет и сверка счетов AI API шаблон
• аналитика использования на уровне шлюза и дизайн реестра токенов
• когда рабочие нагрузки, устойчивые к задержкам, подходят для пакетной обработки