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

Пакетната обработка не трябва да се третира като странична врата около вашия 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: прегледайте нормализирани резултати за артикули, грешки и използване.
• cancel: заявка за анулиране, без обещание за незабавно прекратяване.
• export_usage: експортиране на записи на ниво работа и на ниво артикул за системи за анализ или таксуване.

Примерен обществен обект за работа:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "крайна точка": "chat.completions",
  "модел": "голям анализ",
  "статус": "работи",
  "брои": {
    "изпратено": 50 000,
    "завършен": 31240,
    "неуспешно": 180,
    "изтекъл": 0
  },
  "цена": {
    "оценен": "184.20",
    "резервирано": "205.00",
    "уреден": "117.43",
    "валута": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "submitted_at": "2026-08-19T10:05:00Z",
  "краен_срок за извличане": "2026-09-17T10:00:00Z"
}

Публичният обект не трябва да разкрива идентификатори на файлове на доставчика, имена на операции или необработени грешки нагоре по подразбиране. Те принадлежат към метаданните, обърнати към оператора.

Използвайте трайни записи за работа като източник на истина

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

Минимален модел на база данни

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

1. Пакетна работа

batch_jobs
- job_id
- tenant_id
- project_id
- customer_id nullable- api_key_id
- крайна точка
- искан_модел
- resolved_provider
- разрешен_модел_доставчик
- състояние
- брой_артикули
- прогнозни_входни_токени
- оценени_изходни_токени
- резервирана_сума
- уредена_сума
- created_at
- изпратен_в
- завършен_в
- expires_at
- срок_за_извличане
- cancellation_requested_at

2. Партиден артикул

batch_items
- job_id
- item_id
- custom_id
- idempotency_key
- заявка_хеш
- състояние
- provider_request_index nullable
- приблизителни_токени
- действителни_входни_токени nullable
- действителни_изходни_токени nullable
- уредена_сума nullable
- указател_резултат nullable
- error_code nullable
- retry_of_item_id nullable
- created_at
- settled_at

3. Метаданни на доставчик

batch_provider_metadata
- job_id
- доставчик
- provider_batch_id nullable
- input_file_id nullable
- изходен_файл_id nullable
- error_file_id nullable
- име_на_операция nullable
- крайна точка
- регион nullable
- роден_статус
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Поддържането на метаданните на доставчика отделно от публичния договор за работа позволява на шлюза да развива адаптерите на доставчика, без да прекъсва API-тата, насочени към клиента.

Изисквайте стабилни идентификатори на артикул преди изпращане

Препоръка: генерирайте шлюз job_id и изисквайте за артикул custom_id или ключ за идемпотентност преди изпращане. Никога не съпоставяйте резултатите по ред.

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

Форматът на безопасен идентификатор на артикул е описателен, но не е чувствителен:

tenantA.invoice_extraction.2026-08-19.row_000381

Избягвайте да поставяте необработени имейли, имена, заглавия на документи или клиентски тайни в идентификаторите. Съхранявайте чувствителни данни за корелация във вашата собствена база данни на клиента, а не във видими от доставчика идентификационни номера.

Нормализирайте състоянията, без да изтривате подробностите за доставчика

Партидните API на доставчиците разкриват различни жизнени цикли. Шлюзът трябва да ги нормализира в малка вътрешна държавна машина, която таблата за управление, таксуването и автоматизацията могат да разберат.

Препоръчителен нормализиран жизнен цикъл:

• чернова: заданието съществува, но все още може да се редактира.
• валидиране: валидирането на шлюз или доставчик се изпълнява.
• на опашка: прието, но все още не обработване.
• работи: доставчикът обработва елементи.
• финализиране: доставчикът е завършил изчислението и подготвя артефакти с резултати.
• завършено: всички приети елементи достигнаха терминален успех.
• completed_with_errors: някои елементи бяха успешни и някои неуспешно.
• изтекъл: прозорецът на доставчика приключи, преди цялата работа да приключи.
• cancel_requested: наемателят е помолен да анулира, но окончателната таксувана работа не е уредена.
• отменено: анулирането е уредено.
• неуспешно: възпрепятстван отказ на ниво работа, полезно изпълнение.

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

Валидирайте спрямо матрица на възможностите преди изпращане

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

Вашата вътрешна матрица на възможности трябва да проверява:

• Поддържана крайна точка: чат, съобщения, вграждания, модериране или генериране.
• Допустимост на модела за пакетен режим.
• Максимален размер на заданието, брой елементи, размер на заявката, и размер на качен файл.
• Дали стриймингът е забранен.
• Използване на инструмент и поддръжка за извикване на функции.
• Поддръжка на структуриран изход или JSON схема.
• Поддръжка на изображение, аудио или мултимодален вход.
• Ограничения за регион и пребиваване.
• Запазване на доставчика и извличане на резултати прозорци.
• Специфични за пакета ограничения на скоростта и ограничения на опашката.
• Семантика на анулиране.

Добрият отговор преди полет е специфичен:

{
  "грешка": "batch_capability_not_supported",
  "message": "Избраният пакетен адаптер на доставчик не поддържа поточни отговори. Премахнете stream=true или изберете синхронна крайна точка.",
  "поле": "елементи [*].request.stream"}

Това е по-полезно, отколкото да приемете заданието и да го провалите след преминаване на валидиране нагоре.

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

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

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

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

Практически събития в книгата:

batch.estimated
партида.запазено
партида.подадена
партида.артикул.уреден
batch.item.refunded
batch.cancel_requested
партида.изтекълbatch.reconciled

Главната книга на ниво артикул е от съществено значение. Ако 45 000 елемента са завършени и 5000 изтекат, наемателят трябва да бъде таксуван за завършена работа на доставчика, а не за оригиналния манифест като единичен недиференциран петно.

Изградете адаптери на доставчик като преводачи, а не собственици на бизнес логика

Всеки адаптер на доставчик трябва да знае как да трансформира заданието на шлюза в пакетния формат на доставчика, да го изпрати, да анкетира или извлече състояние, изтегляне на резултатите и картографиране на естествените резултати обратно към нормализирани записи.

Поддържайте политиката на клиента извън адаптера. Адаптерът не трябва да решава дали даден клиент има достатъчен бюджет, дали партньорски клиент е спрян или дали подканите могат да се съхраняват. Това са решения за шлюз.

Отговорности на адаптера

• Изобразяване на манифести на заявка, специфични за доставчика.
• Качване на входни файлове или създаване на операции на доставчика.
• Съхраняване на идентификаторите на доставчика в метаданни.
• Съпоставяне на естественото състояние към нормализирано състояние.
• Извличане на изходни данни и артефакти за грешки.
• Разбиране резултати на ниво артикул.
• Връщане на собствени записи за използване, когато има такива.
• Повърхностни повторни опити срещу грешки на терминал.

Отговорности на шлюза

• Удостоверяване на клиент и API ключ.
• Прилагане на екипни, проектни и клиентски контроли.
• Разрешаване на псевдоними на модела и маршрутизиране на доставчик политика.
• Проверка на пакетните възможности.
• Резервиране и уреждане на бюджет.
• Постоянство на заданието и състоянието на артикула.
• Прилагане на политика за задържане.
• Показване на анализи и експорти.

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

Поглъщане на резултати идемпотентно

Поглъщането на резултат е мястото, където много партидни системи случайно дублират такси или губят частична работа. Отнасяйте се към поглъщането като към повтарящ се процес. Би трябвало да е безопасно да изтеглите един и същ изходен файл два пъти, да обработите една и съща операция на доставчик два пъти или да повторите едно и също събитие на webhook два пъти.

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

Стабилен поток на приемане:

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

Ако налични са webhooks, проверяват подписи и защитават срещу повторно възпроизвеждане. Ако се изисква запитване, използвайте адаптивно анкетиране: анкетирайте често близо до очакваното завършване, отдръпнете се по време на дълги периоди и спрете след крайно уреждане.

Опитайте отново елементи, не цели задачи

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

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

• Грешки при потвърждение: обикновено завършват, докато заявката не бъде коригирана.
• Грешки на доставчика 5xx: често могат да се правят повторни опити с отлагане.
• Квота или лимит на скоростта грешки: опитайте отново само след като капацитетът е наличен.
• Блокове за безопасност: не опитвайте сляпо отново; път към обработка на правилата.
• Изтекли артикули: може да се опитат отново в нова работа, ако наемателят все още иска работата и бюджетът позволява.

Повторният опит трябва да създаде нов артикул, свързан с оригинала:

{
  "item_id": "item_retry_002",
  "retry_of_item_id": "артикул_001",
  "custom_id": "tenantA.eval.row_901.retry_1"
}

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

Решете какво да съхранявате: необработени резултати, указатели или хешове

Пакетните системи са изкушаващи места за натрупване на подкани и изходи. Това може да е полезно за експортиране и отстраняване на грешки, но увеличава отговорността за задържане на данни.

Препоръка: направете политиката за съхранение конфигурируема за наемател. За чувствителни работни натоварвания съхранявайте метаданни, хешове, използване и указатели за резултати, а не необработени подкани и изходи.За по-малко чувствителни работни натоварвания нормализираното съхранение на резултати може да е приемливо, ако прозорците за задържане, контролите за достъп и работните потоци за изтриване са ясни.

Проследете поне:

• Дали необработеният вход е бил съхранен.
• Дали необработеният изход е бил съхранен.
• Къде са активни артефактите на резултатите от доставчика.
• Извличане на доставчика краен срок.
• Краен срок за изтриване на шлюза.
• Хеш на заявка и отговор за одит без излагане на съдържание.

Проверен факт: Резултатите от антропните състояния са налични за 29 дни след създаването и са изолирани в работното пространство. Този вид специфичен за доставчика прозорец за извличане трябва да бъде отразен в метаданните на шлюза и експортирания към клиента.

Излагане на анализи, които съответстват на начина, по който работят екипите

Пакетният анализ трябва да съществува както на ниво задание, така и на ниво елемент. Собственик на продукт иска да знае дали е приключило нощното обогатяване. Финансовият администратор иска цена по наемател, модел и клиент. Инженер иска да знае кой клас на неуспех да опита отново.

Полезните показатели включват:

• Изпратени, завършени, неуспешни, изтекли и отменени артикули. индикатори, при които доставчиците ги разкриват.
• Брой на повторните опити и процент на успеваемост на повторните опити.
• Средно време в състояния на опашка, изпълнение и финализиране.
• Най-често срещани грешки при валидиране по крайна точка и модел.
• Приписване на клиенти на партньори.

За потребители на API на партньори излагайте пакетни задания като ресурси с обхват на клиента. Това позволява на агенциите и създателите на SaaS да предлагат офлайн обработка с изкуствен интелект, като същевременно запазват идентификационните данни на доставчика нагоре по веригата, съгласуването на таксуването и обработката на лимита на скоростта вътре в шлюза.

Компромиси, за да се направи изрично

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

Бюджетна резервация срещу точност на прогнозата: резервацията предпазва наемателите от бягащи работни места, но прогнозите може да са грешни. Книгата трябва да поддържа корекции, възстановяване на суми и обработка на излишък.

Проучване срещу уебкукички: анкетирането е просто и надеждно, но може да напразни извиквания на API и да забави завършването. Уеб кукичките са по-бързи, но изискват проверка на подписа, защита при повторно възпроизвеждане и наблюдение.

Съхранение на необработени резултати срещу минимизиране на задържането: съхраняването на нормализирани резултати подобрява експортирането и анализа, но увеличава тежестта на съответствието. Чувствителните наематели може да предпочетат указатели и хешове.

Големи партиди срещу групирани партиди: огромните партиди могат да подобрят ефективността от страна на доставчика, но по-малките парчета намаляват радиуса на взрив и улесняват повторните опити.

Контролен списък за внедряване

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

Прогнози: къде е този модел заглавие

Прогноза: пакетното изпълнение ще стане нормална част от инфраструктурата за автоматизация на AI, а не само механизъм за отстъпка. Тъй като екипите изпълняват повече оценки, задачи за почистване на данни, прегледи на безопасността и тръбопроводи за обогатяване, те ще очакват асинхронните работни натоварвания да имат същото управление като синхронните извиквания на API.

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

Приложимо заключение

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

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

Свързано четене

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