Zjednotené dávkové úlohy prostredníctvom brány AI API: Odolné fronty, adaptéry poskytovateľa a fakturácia na úrovni nájomcu

Dávkové spracovanie by sa nemalo považovať za bočné dvere okolo brány AI API. Ak úlohy hodnotenia, obohatenia dokumentov, extrakcie, moderovania alebo vkladania opustia cestu synchrónnych požiadaviek, stále potrebujú kontroly nájomníkov, pripisovanie nákladov, opakované pokusy, auditovateľnosť a analýzu používania.

Vzorom implementácie je urobiť z dávkového vykonávania prvotriedny podsystém brány. Brána by mala odhaliť jednu zmluvu o úlohe neutrálnej voči poskytovateľovi a zároveň sa v zákulisí prispôsobovať dávkovým API OpenAI, Anthropic, Gemini a budúcim poskytovateľom.

Problém čitateľa: dávkové API majú podobný zámer, líšia sa v prevádzke

Pracovné zaťaženia tolerantné voči latencii sú prirodzene vhodné na dávkové vykonávanie. Najťažšie nie je rozhodnúť, či práca môže počkať. Najťažšou časťou je konzistentné prevádzkovanie dávkovej práce medzi poskytovateľmi.

Overené fakty: Rozhranie API OpenAI Batch je asynchrónne, číta požiadavky z nahraného súboru, zapisuje odpovede do výstupného súboru a momentálne používa 24-hodinové okno spracovania. OpenAI uvádza stavy ako overuje sa, neúspešné, prebieha, finalizuje sa, dokončené, vypršala, ruší a zrušené. Rozhranie API Anthropic's Message Batches spracováva veľa žiadostí správ asynchrónne, každú požiadavku spracováva nezávisle, vyžaduje prieskum a po ukončení spracovania vracia výsledky. Spoločnosť Antropic tiež odporúča zmysluplné hodnoty custom_id, pretože poradie výsledkov nie je zaručené. Gemini's Batch API odhaľuje dlhotrvajúce metódy v štýle operácií, ako sú metódy zoznamu, zrušenia, vymazania a aktualizácie, a jeho operácia zrušenia je opísaná ako najlepšia snaha.

Na týchto rozdieloch záleží, keď pridáte skutočné obchodné požiadavky:

• Ktorý nájomca, zákazník, projekt alebo kľúč API vlastní jednotlivé položky?
• Boli položky rozpočtu rezervované?
Ak zostala úloha dokončená? platnosť dávky vyprší alebo je zrušená?
• Ako sa opakujú čiastočné zlyhania bez duplikovania úspešnej práce?
• Ako dlho je možné načítať súbory s výsledkami a čo by mala brána uchovávať?
• Môže partner vytvoriť dávkové spracovanie na úrovni zákazníka bez odhalenia poverení poskytovateľa upstream?

Odpoveď nie je skryť všetky rozdiely medzi poskytovateľmi. Odpoveďou je normalizovať prevádzkovú zmluvu a zároveň zachovať natívne metadáta poskytovateľa na ladenie, zosúlaďovanie a podporu.

Odporúčané verejné rozhranie API: oddeľte dávkové úlohy od synchrónnych dokončení

Odporúčanie: vystavujte dávkové úlohy ako svoj vlastný povrch rozhrania API, nie ako špeciálny príznak pri dokončení četu. Synchrónna požiadavka a asynchrónna dávková úloha majú rôznu sémantiku životného cyklu, fakturácie, opakovania a získavania výsledkov.

Praktická zmluva o bráne zahŕňa tieto operácie:

• create_job: vytvorenie konceptu úlohy vlastnenej nájomníkom, projektom, kľúčom alebo partnerským zákazníkom.
• append_itcode> alebo
• append_itcode> so stabilnými identifikátormi položky.
• submit: overiť, rezervovať rozpočet, vybrať poskytovateľa, odoslať a uzamknúť odoslaný manifest.
• get_status: vrátiť normalizované počty úloh a položiek.
• list_results: prechádzať normalizovanými výsledkami položiek, chybami a sľubmi.>> okamžité
• request
• ukončenie.
• export_usage: export záznamov nákladov na úrovni úlohy a položky pre analytické alebo fakturačné systémy.

Príklad verejného objektu úlohy:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "analýza-veľká",
  "status": "beží",
  "counts": {
    "submitted": 50000,
    "dokončené": 31240,
    "nepodarilo sa": 180,
    "vypršala": 0
  },
  "cena": {
    "odhad": "184,20",
    "rezervované": "205,00",
    "vyrovnané": "117,43",
    "currency": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "submitted_at": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"
}

Verejný objekt by v predvolenom nastavení nemal odhaľovať ID súborov poskytovateľa, názvy operácií ani nespracované chyby. Tie patria do metadát pre operátora.

Používajte trvalé záznamy úloh ako zdroj pravdy

Vrstva dávky vlastnená bránou potrebuje trvalý stav predtým, ako sa čokoľvek odošle. Nespoliehajte sa na dávkové záznamy poskytovateľa ako na svoj jediný štátny sklad. Záznamy poskytovateľa sú nevyhnutné, ale nepoznajú vašu hierarchiu nájomníkov, rezervácie rozpočtu, aliasy interných modelov, zákazníkov partnerov ani požiadavky na analýzu.

Minimálny databázový model

Užitočná schéma má tri úrovne:

1. Dávková úloha

dávkové_úlohy
- job_id
- tenant_id
- project_id
- customer_id s nulovou hodnotou- api_key_id
- koncový bod
- požadovaný_model
- vyriešený_poskytovateľ
- vyriešený_model_poskytovateľa
- stav
- počet_položiek
- odhadované_vstupné_tokeny
- odhadované_výstupné_tokeny
- rezervovaná_suma
- zúčtovaná_suma
- vytvorený_at
- predložené_at
- dokončený_at
- expiruje_at
- uzávierka_získania
- cancel_requested_at

2. Batch item

batch_items
- job_id
- item_id
- custom_id
- idempotency_key
- request_hash
- stav
- provider_request_index s možnou hodnotou null
- odhadované_tokeny
- current_input_tokens s možnosťou null
- Skutočné_výstupné_tokensy s nulovou hodnotou
- zúčtovaná_suma s nulovou hodnotou
- ukazovateľ_výsledku môže mať hodnotu null
- kód chyby s nulovou hodnotou
- retry_of_item_id s možnou hodnotou null
- vytvorený_at
- usadený_at

3. Metadáta poskytovateľa

metadata_poskytovateľa dávky
- job_id
- poskytovateľ
- provider_batch_id s možnou hodnotou null
- input_file_id s nulovou hodnotou
- output_file_id s nulovou hodnotou
- error_file_id s nulovou hodnotou
- názov_operácie s možnou hodnotou null
- koncový bod
- oblasť neplatná
- pôvodný_stav
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Uchovávanie metadát poskytovateľa oddelene od zmluvy o verejnej úlohe umožňuje bráne vyvíjať adaptéry poskytovateľa bez narušenia rozhraní API pre nájomníkov.

Vyžadovať stabilné identifikátory položky pred odoslaním

Odporúčanie: vygenerovať bránu a vyžadovať_code -job_id custom_id alebo kľúč idempotency pred odoslaním. Nikdy nezoraďujte výsledky podľa poradia.

Anthropic výslovne varuje, že poradie výsledkov nie je zaručené, a odporúča zmysluplné hodnoty custom_id. Aj keď sa zdá, že poskytovateľ zachováva poriadok, brána by od neho nemala závisieť. Úlohy sú rozdelené, opakovane skúšané, zrušené, čiastočne dokončené a znovu prijímané. Predpoklady objednávania nakoniec zlyhajú.

Formát bezpečného identifikátora položky je popisný, ale nie citlivý:

tenantA.invoice_extraction.2026-08-19.row_000381

Neuvádzajte do identifikátorov nespracované e-maily, mená, názvy dokumentov alebo tajomstvá zákazníkov. Uchovávajte citlivé korelačné údaje vo svojej vlastnej databáze nájomníkov, nie v identifikátoroch viditeľných poskytovateľom.

Normalizácia stavov bez vymazania podrobností poskytovateľa

Rozhrania API pre dávky poskytovateľov odhaľujú rôzne životné cykly. Brána by ich mala znormalizovať do malého interného stavového stroja, ktorému rozumejú riadiace panely, fakturácia a automatizácia.

Odporúčaný normalizovaný životný cyklus:

• návrh: úloha existuje, ale je stále upraviteľná.
• overuje sa: overenie brány alebo poskytovateľa ešte nie je spustené.
• ešte nie je spustené. spracováva sa.
• spustené: poskytovateľ spracováva položky.
• finalizuje sa: poskytovateľ dokončil výpočet a pripravuje artefakty výsledkov.
• completed: všetky prijaté položky dosiahli terminál úspešne.
• completed_with_errors: niektoré položky boli úspešné a niektoré okno prebehlo úspešne a niektoré zlyhali>
• cancel_requested: nájomca požiadaný o zrušenie, ale konečná fakturovateľná práca nie je vyrovnaná.
• zrušené: zrušenie sa vyriešilo.
• neúspešné: zlyhanie na úrovni úlohy zabránilo užitočnému vykonaniu.

Nezbaliť chyby natívneho poskytovateľa do všeobecných označení príliš skoro. Operátori stále potrebujú pri ladení prístup k natívnym stavom, chybám overenia, počtom požiadaviek, ID súborov a názvom operácií.

Pred odoslaním overte podľa matice schopností

Odporúčanie: pred rezerváciou rozpočtu a odoslaním poskytovateľa spustite overenie pred výstupom. Dávkový režim nie je len synchrónny režim s oneskorením. Niektoré modely, koncové body, funkcie požiadaviek, oblasti a konfigurácie nástrojov nemusia byť podporované dávkovým rozhraním API poskytovateľa.

Vaša interná matica schopností by mala kontrolovať:

• Podporovaný koncový bod: chat, správy, vkladanie, moderovanie alebo generovanie.
• Vhodnosť modelu pre dávkový režim.
• veľkosť súboru, počet položiek a maximálny počet úloh. veľkosť.
• Či je zakázané streamovanie.
• Podpora používania nástrojov a volania funkcií.
• Podpora štruktúrovaného výstupu alebo schémy JSON.
• Podpora obrazu, zvuku alebo multimodálneho vstupu.
• Obmedzenia regiónu a bydliska.
• Uchovanie a rýchlosť načítania výsledkov a obmedzenia podľa poskytovateľa
Batch. limity.
• Sémantika zrušenia.

Dobrá odozva pred výstupom je špecifická:

{
  "error": "batch_capability_not_supported",
  "message": "Vybratý dávkový adaptér poskytovateľa nepodporuje streamingové odpovede. Odstráňte stream=true alebo zvoľte synchrónny koncový bod.",
  "field": "items[*].request.stream"}

Je to užitočnejšie ako prijatie úlohy a jej zlyhanie po overení smerom hore.

Rezervujte si rozpočet nájomníka a potom vyrovnajte skutočné využitie

Dávkové spustenie komplikuje fakturáciu, pretože brána môže stratiť synchrónny prístup k presnému použitiu, kým nebudú k dispozícii výsledné súbory. Bezpečným vzorom je cenová ponuka, rezervácia, odoslanie, príjem, vyrovnanie a zosúladenie.

Overené fakty: OpenAI uvádza, že cena dávkového rozhrania API je ponúkaná so zľavou v porovnaní so synchrónnymi rozhraniami API a šarže s vypršanou platnosťou alebo zrušené môžu stále vrátiť dokončenú prácu, ktorá je fakturovateľná. Spoločnosť Antropic poznamenáva, že vysokovýkonné dávkové spracovanie môže mierne presiahnuť limit výdavkov na pracovný priestor, a preto je dôležitá rezervácia na strane brány a následné vysporiadanie.

Odporúčanie: rezervujte si rozpočet nájomcu pred odoslaním pomocou odhadovaných tokenov, pravidiel ceny vybraného poskytovateľa a bezpečnostnej marže. Po prijatí výsledkov nastavte skutočné využitie na úrovni položky. Ak bol odhad príliš vysoký, uvoľnite nevyužitú rezerváciu. Ak bola príliš nízka, použite nakonfigurovanú politiku prekročenia nájomníka.

Praktické udalosti účtovnej knihy:

batch.estimated
šarža.vyhradená
šarža.predložená
dávka.položka.vyrovnaná
dávka.položka.vrátená
batch.cancel_requested
šarža.vypršalabatch.reconciled

Hlavná kniha na úrovni položky je nevyhnutná. Ak je dokončených 45 000 položiek a uplynie platnosť 5 000 položiek, nájomníkovi by sa mala účtovať dokončená práca poskytovateľa, nie pôvodný manifest ako jeden nediferencovaný objekt blob.

Adaptéry poskytovateľa vytvárajte ako prekladatelia, nie ako vlastníci obchodnej logiky

Každý adaptér poskytovateľa by mal vedieť, ako transformovať natívny formát brány, odoslať výsledky, načítať stav mapy poskytovateľa a načítať dávku. výsledky späť do normalizovaných záznamov.

Ponechajte politiku nájomníka mimo adaptéra. Adaptér by nemal rozhodovať o tom, či má zákazník dostatočný rozpočet, či je partnerský zákazník pozastavený alebo či je možné uložiť výzvy. Toto sú rozhodnutia o bráne.

Zodpovednosti adaptéra

• Vykresľovanie manifestov požiadaviek špecifických pre poskytovateľa.
• Nahrávanie vstupných súborov alebo vytváranie operácií poskytovateľa.
• Ukladanie identifikátorov poskytovateľa do metadát.
• Mapovanie natívneho stavu na normalizovaný stav.
• Načítanie natívnych výstupov a artefaktov chýb.
Parse lilevel records.
• dostupné.
• Opakovateľné na povrchu verzus chyby terminálu.

Povinnosti brány

• Autentifikácia nájomníka a kľúč API.
• Použitie tímových, projektových a zákazníckych ovládacích prvkov.
• Vyriešenie aliasov modelov a smerovania poskytovateľov.
• Overenie možností dávkového servera a rozpočtuReattle Server. stav úlohy a položky.
• Presadzovať zásady uchovávania.
• Odhaliť analýzy a exporty.

Toto oddelenie uľahčuje pridanie nového poskytovateľa bez prepisovania fakturácie, analýzy alebo riadenia nájomníkov.

Výsledky príjmu idempotentne čiastočné

Prijímanie výsledkov je príčinou straty duplicitných pracovných dávkových systémov. Požitie berte ako opakovateľný proces. Malo by byť bezpečné stiahnuť ten istý výstupný súbor dvakrát, spracovať tú istú operáciu poskytovateľa dvakrát alebo prehrať tú istú udalosť webhooku dvakrát.

Odporúčanie: použite kľúče idempotencie na úrovni položky a obmedzenia jedinečnosti účtovnej knihy. Výsledok pre job_id + custom_id by sa mal ustáliť presne raz, aj keď sa príjem zopakuje.

Robustný tok príjmu:

1. Získajte krátkodobé uzamknutie pre úlohu alebo artefakt výsledku.
2. Načítajte výstup poskytovateľa a chybové artefakty.
3. Každý výsledok zaznamenávajte podľa záznamov.
4. Zaznamenajte každý výsledok podľa záznamov
5. Analyzujte záznamy do normalizovanej položky. custom_id alebo ID položky brány.
6. Zapíšte metadáta výsledkov a použitie v transakcii.
7. Vytvorte udalosť zúčtovania účtovnej knihy, iba ak ešte neexistuje.
8. Aktualizujte počty úloh zo stavov položiek, nie z predpokladov.
9. Uvoľnite nepoužitú rezerváciu rozpočtu, keď sú známe všetky stavy terminálu a
ak sú k dispozícii znova webhoplay, chrániť./ol. Ak sa vyžaduje hlasovanie, použite adaptívne hlasovanie: hlasujte často blízko očakávaného dokončenia, počas dlhotrvajúcich období ustúpte a zastavte sa po terminálnom vyrovnaní.

Znova skúste položky, nie celé úlohy

Odporúčanie: skúste to znova na úrovni položky, kedykoľvek je to možné. Opakované pokusy o vykonanie celej úlohy sú jednoduché, ale zvyšujú riziko duplicitnej práce a sťažujú fakturáciu.

Klasifikácia zlyhaní pred opätovným pokusom:

• Chyby overenia: zvyčajne koncové, kým sa žiadosť nevyrieši.
• Chyby poskytovateľa 5xx: často je možné opakovať pokus . až po uvoľnení kapacity.
• Bezpečnostné bloky:nepokúšajte sa naslepo; trasa k spracovaniu pravidiel.
• Položky s uplynutou platnosťou: môžu byť opakovane vyskúšané v novej úlohe, ak nájomca stále chce prácu a rozpočet mu to dovoľuje.

Opätovným pokusom by sa mala vytvoriť nová položka prepojená s originálom:

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

Neodosielajte dokončené položky len preto, že boli súčasťou úlohy, ktorá skončila ako completed_with_errors alebo vypršaná.

Rozhodnite sa, čo uložiť: nespracované výsledky, ukazovatele alebo hash

Dávkové systémy sú lákavé miesta na hromadenie výziev a výstupov To môže byť užitočné pri exportoch a ladení, ale zvyšuje to zodpovednosť za uchovávanie údajov.

Odporúčanie: nastavte politiku úložiska tak, aby bola konfigurovateľná pre nájomníka. V prípade citlivých úloh ukladajte metaúdaje, hodnoty hash, použitie a ukazovatele výsledkov namiesto nespracovaných výziev a výstupov.V prípade menej citlivých úloh môže byť prijateľné ukladanie normalizovaných výsledkov, ak sú okná uchovávania, ovládacie prvky prístupu a pracovné postupy odstraňovania jasné.

Sledovať aspoň:

• Či bol uložený nespracovaný vstup.
• Či bol uložený nespracovaný výstup.
• Kde sa nachádzajú artefakty výsledkov poskytovateľa.
• Uzávierka načítania žiadosti poskytovateľa
Gashli> Termín G. a odpoveď na audit bez vystavenia obsahu.

Overený fakt: Dávkové výsledky antropických stavov sú dostupné 29 dní po vytvorení a izolované v rámci pracovného priestoru. Tento druh okna získavania špecifického pre poskytovateľa by sa mal prejaviť v metadátach brány a exportoch pre nájomníkov.

Poskytnite analýzy, ktoré zodpovedajú tomu, ako fungujú tímy

Dávkové analýzy by mali existovať na úrovni úlohy aj položky. Vlastník produktu chce vedieť, či bolo nočné obohatenie dokončené. Finančný správca chce náklady podľa nájomníka, modelu a zákazníka. Technik chce vedieť, ktorú triedu zlyhania má zopakovať.

Užitočné metriky zahŕňajú:

• Počet odoslaných, dokončených, neúspešných, vypršaných a zrušených položiek.
• Odhadované verzus zúčtované náklady.
• Rezervovaný rozpočet je stále zachovaný.
• Vstupné a výstupné tokeny podľa poskytovateľa a modelu.
Cache-h>Cache-h>< ich.
• Počet opakovaných pokusov a miera úspešnosti opakovania.
• Priemerný čas vo fronte, spustení a dokončovaní.
• Najčastejšie chyby overenia podľa koncového bodu a modelu.
• Priradenie partnera partnera.

Používatelia rozhrania Partner API vystavia dávkové úlohy ako zdroje v rozsahu zákazníka. To umožňuje agentúram a tvorcom SaaS ponúkať offline spracovanie AI a zároveň zachovať prihlasovacie údaje poskytovateľa, odsúhlasenie fakturácie a manipuláciu s limitmi sadzieb v bráne.

Výrazné kompromisy

Abstrakcia brány verzus schopnosť špecifická pre poskytovateľa: Jednotná zmluva zjednodušuje integráciu všetkých poskytovateľov, ale nemôže zabezpečiť, aby každý poskytovateľ bol schopný jasne. Udržiavajte chyby funkcií explicitné.

Rezervácia rozpočtu verzus presnosť odhadu: Rezervácia chráni nájomníkov pred neúspechom úloh, ale odhady môžu byť nesprávne. Kniha musí podporovať úpravy, vrátenia peňazí a spracovanie nadmerného množstva.

Výzvy verzus webhooky: Výzvy sú jednoduché a spoľahlivé, ale môžu plytvať volaniami API a oneskorovať dokončenie. Webhooky sú rýchlejšie, ale vyžadujú overenie podpisu, ochranu pred prehrávaním a monitorovanie.

Ukladanie nespracovaných výsledkov verzus minimalizácia uchovávania:ukladanie normalizovaných výsledkov zlepšuje exporty a analýzy, ale zvyšuje zaťaženie súladu. Citliví nájomníci môžu uprednostňovať ukazovatele a hodnoty hash.

Veľké dávky verzus skupinové dávky: obrovské dávky môžu zlepšiť efektivitu na strane poskytovateľa, ale menšie kusy zmenšia rádius výbuchu a uľahčia opakované pokusy.

Kontrolný zoznam implementácie

• Vytvorte samostatnú úlohu odosielania hromadnej úlohy
Položka poskytovateľa API ID úlohy brány a vlastné ID podľa položky.
• Normalizácia stavov pri ukladaní metadát natívneho poskytovateľa.
• Vytvorte maticu schopností pre každý dávkový adaptér poskytovateľa.
• Overte manifesty pred rezerváciou rozpočtu.
• Rezervujte rozpočet nájomníka pred odoslaním.
• Urovnajte skutočné využitie na úrovni položky po výsledku. idempotent.
• Sledujte neúspešné položky selektívne, nie celé úlohy naslepo.
• Sledujte termíny načítania poskytovateľa a politiku uchovávania brány.
• Poskytnite analýzu úloh a položiek nájomníkom a partnerským zákazníkom.

Predpovede: kam smeruje tento vzor

Predpoveď: AI sa nestane len bežným mechanizmom hromadného vykonávania. Keďže tímy spúšťajú viac hodnotení, úloh čistenia údajov, bezpečnostných kontrol a kanálov obohatenia, budú očakávať, že asynchrónne pracovné zaťaženia budú mať rovnaké riadenie ako synchrónne volania API.

Predpoveď: Rozhrania API pre dávky poskytovateľov sa budú naďalej užitočným spôsobom líšiť. Niektoré sa budú optimalizovať pre súbory, iné pre dlhotrvajúce operácie a ďalšie pre spravované množiny údajov alebo spätné volania udalostí. Vrstva adaptéra brány sa stane cennejšou, nie menšou, pretože prevádzková zmluva nad adaptérmi môže zostať stabilná.

Uplatniteľný záver

Nepripájajte dávkové spracovanie na bránu AI API ako únikový poklop špecifický pre poskytovateľa. Zostavte ho ako odolný subsystém s vlastnými záznamami úloh, identifikátormi položiek, modelom stavu, adaptérmi poskytovateľa, rezerváciou rozpočtu, idempotentným prijímaním a analýzou.

Najdôležitejšou voľbou návrhu je účtovníctvo na úrovni položiek. Keď má každá požiadavka v dávke stabilnú identitu, brána môže zosúladiť neusporiadané výsledky, zopakovať iba neúspešnú prácu, účtovať iba dokončenú prácu poskytovateľa a ukázať nájomcom, čo sa stalo.To je rozdiel medzi odosielaním súborov poskytovateľovi a prevádzkovaním spoľahlivého multimodelového API pre asynchrónne pracovné zaťaženia.

Súvisiace čítanie

• citovať a zúčtovať účet, rezervovať API, zúčtovanie API vzor
• analytika používania na úrovni brány a návrh účtovnej knihy tokenov
• keď pracovné zaťaženie odolné voči latencii vyhovuje dávkovému spracovaniu