Sjednocené dávkové úlohy prostřednictvím brány AI API: Odolné fronty, adaptéry poskytovatelů a fakturace na úrovni tenanta

Dávkové zpracování by nemělo být považováno za postranní dveře kolem vaší brány AI API. Pokud úlohy hodnocení, obohacování dokumentů, extrakce, moderování nebo vkládání opustí cestu synchronních požadavků, stále potřebují kontroly tenanta, přiřazování nákladů, opakování, auditovatelnost a analýzu využití.

Vzorem implementace je učinit z dávkového provádění prvotřídní podsystém brány. Brána by měla odhalit jednu zakázku neutrální vůči poskytovateli a zároveň se v zákulisí přizpůsobit dávkovým API OpenAI, Anthropic, Gemini a budoucím poskytovatelům.

Problém čtenáře: dávková rozhraní API mají podobný záměr, liší se v provozu

Úlohy s tolerancí latence jsou přirozené vhodné pro dávkové provádění. Nejtěžší není rozhodnout, zda práce může počkat. Nejtěžší částí je konzistentní provozování dávkové práce napříč poskytovateli.

Ověřená fakta: Batch API OpenAI je asynchronní, čte požadavky z nahraného souboru, zapisuje odpovědi do výstupního souboru a aktuálně používá 24hodinové okno pro zpracování. OpenAI uvádí stavy, jako je ověřování, neúspěšné, probíhá, dokončuje se, dokončeno, vypršelo, ruší a zrušeno. Antropic’s Message Batches API zpracovává mnoho požadavků Messages asynchronně, zpracovává každý požadavek nezávisle, vyžaduje dotazování a vrací výsledky po ukončení zpracování. Anthropic také doporučuje smysluplné hodnoty custom_id, protože pořadí výsledků není zaručeno. Gemini’s Batch API odhaluje dlouhotrvající metody ve stylu operací, jako je seznam, zrušení, odstranění a aktualizace, a jeho operace zrušení je popsána jako nejlepší úsilí.

Na těchto rozdílech záleží, jakmile přidáte skutečné obchodní požadavky:

• Který nájemce, zákazník, projekt nebo klíč API vlastní jednotlivé položky?
• Byly položky rozpočtu rezervovány? platnost dávky vyprší nebo je zrušena?
• Jak se opakují částečná selhání, aniž by se duplikovala úspěšná práce?
• Jak dlouho lze načítat soubory s výsledky a co by měla brána uchovávat?
• Může partner vytvořit dávkové zpracování na úrovni zákazníka, aniž by odhalil přihlašovací údaje poskytovatele upstream?

Odpovědí není skrýt všechny rozdíly mezi poskytovateli. Odpovědí je normalizovat provozní smlouvu a zároveň zachovat nativní metadata poskytovatele pro ladění, odsouhlasení a podporu.

Doporučené veřejné rozhraní API: oddělte dávkové úlohy od synchronních dokončení

Doporučení: vystavujte dávkové úlohy jako vlastní povrch rozhraní API, nikoli jako zvláštní příznak při dokončení chatu. Synchronní požadavek a asynchronní dávková úloha mají různou sémantiku životního cyklu, účtování, opakování a načítání výsledků.

Praktická smlouva brány zahrnuje tyto operace:

• create_job: vytvoření konceptu úlohy vlastněné tenantem, projektem, klíčem nebo partnerským zákazníkem.
• append_itcode>
• append_itcode> nebo se stabilními identifikátory položek.
• submit: ověřit, rezervovat rozpočet, vybrat poskytovatele, odeslat a uzamknout odeslaný manifest.
• get_status: vrátit normalizované počty úloh a položek.
• list_results: procházet normalizovanými výsledky položek, chybami a sliby>> okamžité
• request
• ukončení.
• export_usage: export záznamů nákladů na úrovni zakázky a položky pro analytické nebo fakturační systémy.

Příklad veřejného objektu zakázky:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "analýza-velká",
  "status": "běží",
  "počítá": {
    "odesláno": 50 000,
    "dokončeno": 31240,
    "neúspěšné": 180,
    "vypršelo": 0
  },
  "cena": {
    "odhad": "184,20",
    "rezervováno": "205,00",
    "vypořádáno": "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"
}

Ve výchozím nastavení by veřejný objekt neměl odhalovat ID souborů poskytovatele, názvy operací ani nezpracované chyby. Ty patří do metadat orientovaných na operátora.

Používejte trvalé záznamy úloh jako zdroj pravdy

Dávková vrstva vlastněná bránou potřebuje trvalý stav, než bude cokoli odesláno upstream. Nespoléhejte na dávkové záznamy poskytovatele jako na jediné úložiště stavu. Záznamy poskytovatelů jsou nezbytné, ale neznají vaši hierarchii nájemců, rezervace rozpočtu, aliasy interního modelu, partnerské zákazníky ani požadavky na analýzu.

Minimální databázový model

Užitečné schéma má tři úrovně:

1. Dávková úloha

dávkové_úlohy
- job_id
- tenant_id
- project_id
- customer_id s možnou hodnotou null- api_key_id
- koncový bod
- požadovaný_model
- vyřešený_poskytovatel
- resolved_provider_model
- stav
- počet_položek
- odhadované_vstupní_tokeny
- odhadované_výstupní_tokeny
- rezervovaná_částka
- vypořádaná_částka
- vytvořil_at
- předloženo_at
- dokončeno_v
- expiruje_at
- uzávěrka_získání
- 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žnou hodnotou null
- current_output_tokens s možnou hodnotou null
- vypořádaná_částka s možností null
- result_pointer s možnou hodnotou null
- error_code s možnou hodnotou null
- retry_of_item_id s možnou hodnotou null
- vytvořil_at
- vypořádáno

3. Metadata poskytovatele

batch_provider_metadata
- job_id
- poskytovatel
- provider_batch_id s možnou hodnotou null
- input_file_id s možnou hodnotou null
- output_file_id s možnou hodnotou null
- error_file_id s možnou hodnotou null
- název_operace s možnou hodnotou Null
- koncový bod
- oblast s nulovou hodnotou
- nativní_stav
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Uchování metadat poskytovatele odděleně od smlouvy o veřejné práci umožňuje bráně vyvinout adaptéry poskytovatele, aniž by narušila rozhraní API pro tenanty.

Vyžadovat stabilní identifikátory položek před odesláním

Doporučení: vygenerovat a vygenerovat bránu job_id custom_id nebo klíč idempotency před odesláním. Nikdy neslučujte výsledky podle pořadí.

Anthropic výslovně varuje, že pořadí výsledků není zaručeno, a doporučuje smysluplné hodnoty custom_id. I když se zdá, že poskytovatel zachovává objednávku, brána by na něm neměla záviset. Úlohy jsou rozděleny, opakovány, zrušeny, částečně dokončeny a znovu zpracovány. Předpoklady pro objednávání nakonec selžou.

Formát bezpečného identifikátoru položky je popisný, ale není citlivý:

tenantA.invoice_extraction.2026-08-19.row_000381

Nevkládejte do identifikátorů nezpracované e-maily, jména, názvy dokumentů nebo zákaznická tajemství. Uchovávejte citlivá korelační data ve své vlastní databázi tenantů, nikoli uvnitř ID viditelných poskytovatelem.

Normalizace stavů bez vymazání podrobností poskytovatele

Rozhraní API pro dávky poskytovatelů odhalují různé životní cykly. Brána by je měla normalizovat do malého interního stavového stroje, kterému porozumí řídicí panely, fakturace a automatizace.

Doporučený normalizovaný životní cyklus:

• návrh: úloha existuje, ale je stále upravitelná.
• ověření: ověření brány nebo poskytovatele zatím není spuštěno.
• zatím není spuštěno.
• draft. zpracovávání.
• spuštěno: poskytovatel zpracovává položky.
• finalizuje se: poskytovatel dokončil výpočet a připravuje artefakty výsledku.
• completed: všechny přijaté položky dosáhly úspěšného terminálu.
• completed_with_errors: některé položky byly úspěšné a některé okno selhalo poskytovatel selhal a některé se nezdařily. dokončeno.
• cancel_requested: nájemce požádán o zrušení, ale konečná fakturovatelná práce není vypořádána.
• zrušeno: zrušení vyřízeno.
• failed: selhání na úrovni úlohy zabránilo užitečnému provedení.

Nesbalujte chyby nativního poskytovatele do obecných štítků příliš brzy. Operátoři při ladění stále potřebují přístup k nativním stavům, chybám ověření, počtům požadavků, ID souborů a názvům operací.

Před odesláním ověřte podle matice schopností

Doporučení: před rezervací rozpočtu a odesláním poskytovatele spusťte ověření před výstupem. Dávkový režim není jen synchronní režim se zpožděním. Některé modely, koncové body, funkce požadavků, oblasti a konfigurace nástrojů nemusí dávkové rozhraní API poskytovatele podporovat.

Vaše interní matice schopností by měla kontrolovat:

• Podporovaný koncový bod: chat, zprávy, vkládání, moderování nebo generování.
• Vhodnost modelu pro dávkový režim.
• velikost souboru, počet položek a maximální počet nahrávek. velikost.
• Zda je zakázáno streamování.
• Podpora používání nástrojů a volání funkcí.
• Podpora strukturovaného výstupu nebo schématu JSON.
• Podpora obrazu, zvuku nebo multimodálního vstupu.
• Omezení regionu a bydliště.
• Omezení rychlosti uchovávání a načítání výsledků podle poskytovatele
windows. limity.
• Sémantika zrušení.

Dobrá odezva před výstupem je specifická:

{
  "error": "batch_capability_not_supported",
  "message": "Vybraný dávkový adaptér poskytovatele nepodporuje streamingové odpovědi. Odeberte stream=true nebo zvolte synchronní koncový bod.",
  "field": "items[*].request.stream"}

Toto je užitečnější než přijetí úlohy a její selhání po předchozím ověření.

Rezervujte rozpočet tenanta a poté vyrovnejte skutečné využití

Dávkové provádění komplikuje účtování, protože brána může ztratit synchronní přístup k přesnému využití, dokud nebudou k dispozici soubory výsledků. Bezpečným vzorem je nabídka, rezervace, odeslání, zpracování, vypořádání a odsouhlasení.

Ověřená fakta: OpenAI uvádí, že cena dávkového rozhraní API je nabízena se slevou ve srovnání se synchronními rozhraními API a dávky s vypršenou platností nebo zrušené mohou stále vrátit dokončenou práci, která je fakturovatelná. Antropic poznamenává, že vysokovýkonné dávkové zpracování může mírně překročit limit výdajů na pracovní prostor, takže rezervace na straně brány a následné vypořádání jsou důležité.

Doporučení: rezervujte si rozpočet nájemce před odesláním pomocí odhadovaných tokenů, cenových pravidel vybraných poskytovatelů a bezpečnostní marže. Po zpracování výsledků nastavte skutečné využití na úrovni položky. Pokud byl odhad příliš vysoký, uvolněte nevyužitou rezervaci. Pokud byla příliš nízká, použijte nakonfigurovanou zásadu přetížení tenanta.

Praktické události hlavní knihy:

batch.estimated
šarže.rezervováno
šarže.předložena
dávka.položka.vypořádána
dávka.položka.vrácena
batch.cancel_requested
šarže.vypršelabatch.reconciled

Hlavní kniha na úrovni položky je nezbytná. Pokud je dokončeno 45 000 položek a 5 000 vyprší, měla by být tenantovi účtována dokončená práce poskytovatele, nikoli původní manifest jako jeden nediferencovaný objekt blob.

Vytvářejte adaptéry poskytovatelů jako překladatele, nikoli jako vlastníky obchodní logiky

Každý adaptér poskytovatele by měl vědět, jak transformovat úlohu brány nativního formátu do formátu poskytovatele, načíst výsledky, načíst jej nahrát dávkově. výsledky zpět do normalizovaných záznamů.

Uchovávejte zásady tenanta mimo adaptér. Adaptér by neměl rozhodovat o tom, zda má zákazník dostatečný rozpočet, zda je partnerský zákazník pozastaven nebo zda lze uložit výzvy. To jsou rozhodnutí brány.

Odpovědnost adaptéru

• Vykreslování manifestů požadavků specifických pro poskytovatele.
• Nahrávání vstupních souborů nebo vytváření operací poskytovatele.
• Ukládání identifikátorů poskytovatelů do metadat.
• Mapování nativního stavu na normalizovaný stav.
• Načítání nativních výstupů a artefaktů chyb.
Parse lilevel records.
• k dispozici.
• Opakovatelné na povrchu versus chyby terminálu.

Odpovědnosti brány

• Ověření tenanta a klíče API.
• Použití týmových, projektových a zákaznických ovládacích prvků.
• Vyřešte aliasy modelů a zásady směrování poskytovatelů.
• Ověřte možnosti sestavení rozpočtu a serverů. stav úlohy a položky.
• Vynucovat zásady uchovávání.
• Odhalit analýzy a exporty.

Toto oddělení usnadňuje přidání nového poskytovatele, aniž by bylo nutné přepisovat fakturaci, analytiku nebo správu tenantů.

Výsledky příjmu idempotentně částečné

Při přijímání výsledků dochází ke ztrátě systému zdvojení dávky nebo ke ztrátě pracovních dávek. Považujte požití za opakovatelný proces. Mělo by být bezpečné stáhnout dvakrát stejný výstupní soubor, dvakrát zpracovat stejnou operaci poskytovatele nebo dvakrát přehrát stejnou událost webhooku.

Doporučení: použijte klíče idempotence na úrovni položky a omezení jedinečnosti účetní knihy. Výsledek pro job_id + custom_id by se měl ustálit přesně jednou, i když se zpracování zopakuje.

Robustní tok příjmu:

1. Získejte krátkodobý zámek pro úlohu nebo artefakt výsledku.
2. Načtěte výstup poskytovatele a chybové artefakty.
3. Každý výsledek zaznamenávejte pomocí záznamů>Matlich> normalizovaná položka. custom_id nebo ID položky brány.
4. Zapište metadata výsledku a použití v transakci.
5. Vytvořte událost vypořádání hlavní knihy pouze v případě, že ještě neexistuje.
6. Aktualizujte počty úloh ze stavů položek, nikoli z předpokladů.
7. Uvolněte nepoužitou rezervaci rozpočtu, když jsou známy všechny stavy terminálu.
Pokud jsou k dispozici všechny stavy terminálu,

Zkuste znovu položky, ne celé úlohy

Doporučení: opakujte to na úrovni položky, kdykoli je to možné. Opakování celé úlohy je jednoduché, ale zvyšuje riziko duplicitní práce a ztěžuje fakturaci.

Klasifikujte selhání před opakováním:

• Chyby ověření: obvykle končí, dokud není požadavek vyřešen.
• Chyby poskytovatele 5xx: často lze opakovat>. až po uvolnění kapacity.
• Bezpečnostní bloky:nepokoušejte se naslepo; trasa ke zpracování zásad.
• Položky s prošlou platností: lze zopakovat v nové zakázce, pokud nájemce stále chce práci a rozpočet dovoluje.

Opakováním by se měla vytvořit nová položka propojená s původní:

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

Neodesílejte znovu dokončené položky jen proto, že byly součástí úlohy, která skončila jako completed_with_errors nebo vypršela.

Rozhodněte se, co uložit: nezpracované výsledky, ukazatele nebo hodnoty hash

Dávkové systémy jsou lákavá místa pro hromadění výzev a výstupů. To může být užitečné pro exporty a ladění, ale zvyšuje to odpovědnost za uchovávání dat.

Doporučení: nastavte zásady úložiště tak, aby se daly konfigurovat tenantem. U citlivých úloh ukládejte spíše metadata, hash, použití a ukazatele výsledků než nezpracované výzvy a výstupy.U méně citlivých úloh může být přijatelné normalizované ukládání výsledků, pokud jsou okna uchování, řízení přístupu a pracovní postupy mazání jasné.

Sledujte alespoň:

• Zda byl uložen nezpracovaný vstup.
• Zda byl uložen nezpracovaný výstup.
• Kde jsou artefakty výsledků poskytovatele aktivní.
• Lhůta pro načtení poskytovatele
Gashli> Lhůta. a odpověď na audit bez vystavení obsahu.

Ověřený fakt: Dávkové výsledky antropických stavů jsou k dispozici 29 dní po vytvoření a izolovány v rámci pracovního prostoru. Tento druh okna vyhledávání specifického pro poskytovatele by se měl odrazit v metadatech brány a exportech pro tenanty.

Vystavte analýzy, které odpovídají fungování týmů

Dávkové analýzy by měly existovat na úrovni úlohy i položky. Vlastník produktu chce vědět, zda bylo noční obohacení dokončeno. Finanční správce požaduje náklady podle nájemce, modelu a zákazníka. Technik chce vědět, kterou třídu selhání má zkusit znovu.

Užitečné metriky zahrnují:

• Počet odeslaných, dokončených, neúspěšných, vypršených a zrušených položek.
• Odhadované versus uhrazené náklady.
• Rezervovaný rozpočet je stále zachován.
• Indikátory vstupu a výstupu podle poskytovatele a modelu.
Cache-hits>Cache-hits>Odhadované versus uhrazené náklady. je.
• Počet opakování a úspěšnost opakování.
• Průměrná doba ve frontě, spuštění a dokončení.
• Nejčastější chyby ověření podle koncového bodu a modelu.
• Přiřazení partnerských zákazníků.

Pro uživatele Partner API vystavte dávkové úlohy jako zdroje pro zákazníka. To umožňuje agenturám a tvůrcům SaaS nabízet offline zpracování umělé inteligence při zachování přihlašovacích údajů poskytovatele, odsouhlasení fakturace a zpracování limitů sazeb v bráně.

Konkrétní kompromisy

Abstrakce brány versus možnosti specifické pro poskytovatele: Jednotná smlouva zjednodušuje integraci všech poskytovatelů, ale nemůže zajistit, aby všichni poskytovatelé měli integraci. Udržujte chyby funkcí explicitní.

Rezervace rozpočtu versus přesnost odhadu: Rezervace chrání nájemníky před neúspěchem úloh, ale odhady mohou být chybné. Kniha musí podporovat úpravy, vracení peněz a zpracování nadměrného množství.

Dotazování versus webhooky: Dotazování je jednoduché a spolehlivé, ale může plýtvat voláními API a zdržovat dokončení. Webhooky jsou rychlejší, ale vyžadují ověření podpisu, ochranu před přehráním a monitorování.

Ukládání nezpracovaných výsledků versus minimalizace uchovávání: ukládání normalizovaných výsledků zlepšuje exporty a analýzy, ale zvyšuje zátěž související s dodržováním předpisů. Citliví nájemci mohou upřednostňovat ukazatele a hash.

Velké dávky versus blokové dávky: velké dávky mohou zlepšit efektivitu na straně poskytovatele, ale menší bloky zmenšují rádius výbuchu a usnadňují opakování.

Kontrolní seznam implementace

• Vytvořte samostatnou úlohu hromadného odesílání. ID úlohy brány a vlastní ID pro jednotlivé položky.
• Normalizujte stavy při ukládání metadat nativního poskytovatele.
• Vytvořte matici schopností pro každý dávkový adaptér poskytovatele.
• Ověřte manifesty před rezervací rozpočtu.
• Rezervujte rozpočet tenanta před odesláním.
• Urovnejte skutečné využití na úrovni položky.
• Urovnejte skutečné využití na úrovni položky. idempotent.
• Opakujte neúspěšné položky selektivně, ne celé úlohy naslepo.
• Sledujte termíny načítání poskytovatelů a zásady uchovávání brány.
• Představte analýzu úloh a položek nájemcům a partnerským zákazníkům.

Předpovědi: kam tento vzor směřuje

Předpověď: AI se nestane jen běžným mechanismem hromadného spouštění. Jak týmy spouštějí více hodnocení, úkolů čištění dat, bezpečnostních kontrol a kanálů obohacení, budou očekávat, že asynchronní pracovní zátěže budou mít stejné řízení jako synchronní volání API.

Předpověď: Dávková rozhraní API poskytovatelů se budou nadále v užitečných směrech lišit. Některé se budou optimalizovat pro soubory, jiné pro dlouhotrvající operace a další pro spravované datové sady nebo zpětná volání událostí. Vrstva adaptéru brány se stane cennější, ne méně, protože provozní smlouva nad adaptéry může zůstat stabilní.

Akční závěr

Nepřipojujte dávkové zpracování na bránu AI API jako únikový poklop specifický pro poskytovatele. Vybudujte jej jako odolný subsystém s vlastními záznamy úloh, identifikátory položek, modelem stavu, adaptéry poskytovatelů, rezervací rozpočtu, idempotentním zpracováním a analýzou.

Nejdůležitější volbou návrhu je účetnictví na úrovni položek. Jakmile má každý požadavek v dávce stabilní identitu, může brána sladit neuspořádané výsledky, opakovat pouze neúspěšnou práci, účtovat pouze dokončenou práci poskytovatele a ukázat nájemcům, co se stalo.To je rozdíl mezi odesíláním souborů poskytovateli a provozováním spolehlivého multimodelového API pro asynchronní pracovní zátěže.

Související čtení

• citovat a vyúčtovat AI účet, vypořádání API vzor
• analytika využití na úrovni brány a návrh účetní knihy tokenů
• když se zátěže odolné vůči latenci hodí pro dávkové zpracování