Enade batchjobb genom en AI API-gateway: hållbara köer, leverantörsadaptrar och fakturering på hyresnivå

Batchbearbetning ska inte behandlas som en sidodörr runt din AI API-gateway. Om evaler, dokumentberikning, extrahering, modereringssvep eller inbäddningsjobb lämnar den synkrona begäranden, behöver de fortfarande kontroll av hyresgäster, kostnadstillskrivning, omförsök, granskningsbarhet och användningsanalys.

Implementeringsmönstret är att göra batchexekvering till ett förstklassigt gateway-undersystem. Gatewayen bör avslöja ett leverantörsneutralt jobbkontrakt samtidigt som den anpassar sig till OpenAI, Anthropic, Gemini och framtida leverantörs batch-API:er bakom kulisserna.

Läsarproblemet: batch-API:er är lika i avsikt, olika i drift

Latens-toleranta arbetsbelastningar är en naturlig passform för batchexekvering. Det svåra är att inte bestämma sig för om ett jobb kan vänta. Det svåra är att driva batcharbete konsekvent mellan leverantörer.

Verifierade fakta: OpenAI:s Batch API är asynkront, läser förfrågningar från en uppladdad fil, skriver svar till en utdatafil och använder för närvarande ett 24-timmars bearbetningsfönster. OpenAI listar statusar som validerar, misslyckades, pågår, slutför, slutförd, förfallit, avbryter och avbryts. Anthropics Message Batches API behandlar många meddelandeförfrågningar asynkront, hanterar varje begäran oberoende, kräver polling och returnerar resultat efter att behandlingen är slut. Anthropic rekommenderar också meningsfulla custom_id-värden eftersom resultatordningen inte är garanterad. Gemini's Batch API avslöjar långvariga operationsstilsmetoder som lista, avbryt, ta bort och uppdatera metoder, och dess avbrytningsoperation beskrivs som bästa möjliga.

Dessa skillnader spelar roll när du väl lägger till verkliga affärskrav:

• Vilken hyresgäst, kund, projekt eller API-nyckel äger varje artikel?
• Vilken var budgeten reserverad >
• Vad budgeten var reserverad >
• är fakturerbara om batchen löper ut eller avbryts?
• Hur görs om partiella misslyckanden utan att duplicera framgångsrikt arbete?
• Hur länge kan resultatfiler hämtas, och vad ska gatewayen lagra?
• Kan en partner bygga kundanpassad batchbearbetning utan att exponera uppströmsleverantörens referenser/uppgifter för hi

• Rekommenderat offentligt API: separera batchjobb från synkrona slutföranden

  Rekommendation: exponera batchjobb som sin egen API-yta, inte som en speciell flagga på chattkompletteringar. En synkron begäran och ett asynkront batchjobb har olika semantik för livscykel, fakturering, återförsök och resultathämtning.

  Ett praktiskt gatewaykontrakt inkluderar dessa operationer:

  • create_job: skapa ett utkast till jobb som ägs av en hyresgäst, ett projekt, en nyckel eller en partnerkund.
  • app_en_coded_coded_coded_code: lägg till individuella förfrågningar med stabila artikelidentifierare.
  • skicka: validera, reservera budget, välj leverantör, skicka och lås det inlämnade manifestet.
  • get_status: returnera normaliserade jobb- och artikelantal.
  • list_results: bläddra igenom normaliserade artikelresultat, förfrågningar och usage:
  cancel: lovar omedelbar uppsägning.
  • export_användning: exportera kostnadsposter på jobbnivå och artikelnivå för analys- eller faktureringssystem.

  Exempel på offentligt jobbobjekt:

  {
    "job_id": "job_01j7...",
    "tenant_id": "tenant_acme",
    "customer_id": "cust_123",
    "endpoint": "chat.completions",
    "model": "analys-stor",
    "status": "kör",
    "counts": {
      "skickat": 50 000,
      "avslutad": 31240,
      "misslyckades": 180,
      "förfallit": 0
    },
    "kostnad": {
      "estimated": "184.20",
      "reserved": "205.00",
      "settled": "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"
  }

  Det offentliga objektet ska inte avslöja leverantörsfil-ID:n, operationsnamn eller råa uppströmsfel som standard. De hör hemma i operatörens metadata.

  Använd hållbara jobbposter som källan till sanningen

  Ett gatewayägt batchlager behöver ett hållbart tillstånd innan något skickas uppströms. Lita inte på leverantörsbatchposter som din enda statliga butik. Leverantörsposter är nödvändiga, men de känner inte till din hyresgästhierarki, budgetreservationer, interna modellalias, partnerkunder eller analyskrav.

  Minsta databasmodell

  Ett användbart schema har tre nivåer:

  1. Batchjobb

  batch_jobs
  - jobb_id
  - tenant_id
  - projekt_id
  - customer_id nullbar- api_key_id
  - slutpunkt
  - begärd_modell
  - resolved_provider
  - resolved_provider_model
  - status
  - item_count
  - estimated_input_tokens
  - estimated_output_tokens
  - reserverat_belopp
  - avräknat_belopp
  - skapad_at
  - inlämnat_at
  - avslutad_kl
  - går ut_kl
  - retrieval_deadline
  - cancellation_requested_at

  2. Batchobjekt

  batch_items
  - jobb_id
  - artikel-id
  - custom_id
  - idempotency_key
  - request_hash
  - status
  - provider_request_index nullbar
  - uppskattade_tokens
  - actual_input_tokens nullbar
  - actual_output_tokens nullbar
  - settled_amount nullbar
  - result_pointer nullbar
  - felkod nullbar
  - retry_of_item_id nullbar
  - skapad_at
  - settled_at

  3. Leverantörsmetadata

  batch_provider_metadata
  - jobb_id
  - leverantör
  - provider_batch_id nullbar
  - input_file_id nullbar
  - output_file_id nullbar
  - error_file_id nullbar
  - operationsname nullbar
  - slutpunkt
  - region nullbar
  - native_status
  - native_request_counts jsonb
  - senast_omröstning_kl
  - raw_error_pointer nullable

  Att hålla leverantörens metadata åtskild från det offentliga jobbkontraktet gör att gatewayen kan utveckla leverantörsadaptrar utan att bryta API:er som vänder sig till klienten.

  Kräv stabila artikelidentifierare innan avsändning

  Rekommendation generera en _gateway ajo:kod: per artikel custom_id eller idempotensnyckel före avsändning. Avstäm aldrig resultat efter beställning.

  Anthropic varnar uttryckligen för att resultatordning inte är garanterad och rekommenderar meningsfulla custom_id-värden. Även när en leverantör verkar bevara ordningen bör en gateway inte vara beroende av den. Jobb blir bitar, prövas igen, avbryts, slutförs delvis och tas in igen. Beställningsantaganden misslyckas så småningom.

  Ett format för säker artikelidentifierare är beskrivande men inte känsligt:

  tenantA.invoice_extraction.2026-08-19.row_000381

  Undvik att sätta in obearbetade e-postmeddelanden, namn, kundidentifierare, dokumenthemliga namn. Lagra känsliga korrelationsdata i din egen klientdatabas, inte i leverantörssynliga ID:n.

  Normalisera statusar utan att radera leverantörsdetaljer

  Provider batch-API:er avslöjar olika livscykler. Gatewayen bör normalisera dem till en liten intern tillståndsmaskin som instrumentpaneler, fakturering och automatisering kan förstå.

  Rekommenderad normaliserad livscykel:

  • utkast: jobbet finns men är fortfarande redigerbart.
  • validerar: gateway eller leverantörsvalidering är inte igång, > är inte godkänd. ännu bearbetas.
  • kör: leverantören bearbetar objekt.
  • slutför: leverantören har slutfört beräkningen och förbereder resultatartefakter.
  • slutförd: alla accepterade objekt nådde terminal framgång.
  • slutförde_med_fel och vissa artiklar lyckades
  • misslyckades.
  • upphört: leverantörsfönstret avslutades innan allt arbete slutförts.
  • cancel_requested: hyresgästen ombedd att avbryta, men det slutliga fakturerbara arbetet är inte löst.
  • avbrutit: annulleringen avklarad.
  • misslyckades
  • misslyckades
  jobbet misslyckades. inte kollapsa inbyggda leverantörsfel till generiska etiketter för tidigt. Operatörer behöver fortfarande åtkomst till inbyggda statusar, valideringsfel, antal begäranden, fil-ID:n och operationsnamn vid felsökning.

  Validera mot en kapacitetsmatris före inlämning

  Rekommendation: kör preflight-validering innan budgetreservation och leverantörsutskick. Batch-läge är inte bara synkront läge med fördröjning. Vissa modeller, slutpunkter, förfrågningsfunktioner, regioner och verktygskonfigurationer kanske inte stöds av en leverantörs batch-API.

  Din interna kapacitetsmatris bör kontrollera:

  • Slutpunkt som stöds: chatt, meddelanden, inbäddningar, moderering eller generering.
  • Modelbehörighet för batchläge, poststorlek, poststorlek, uppladdningsstorlek och filstorlek.
  storlek.
  • Oavsett om strömning är förbjuden.
  • Stöd för verktygsanvändning och funktionsanrop.
  • Stöd för strukturerad utdata eller JSON-schema.
  • Stöd för bild, ljud eller multimodal ingång.
  • Regions- och uppehållsbegränsningar.
  • Providerretention och resultathämtning begränsar gränsvärden för leverantörer och hämtning av resultatB.
  • Annulleringssemantik.

  Ett bra preflight-svar är specifikt:

  {
    "error": "batch_capability_not_supported",
    "message": "Den valda leverantörens batchadapter stöder inte streamingsvar. Ta bort stream=true eller välj en synkron slutpunkt.",
    "field": "items[*].request.stream"}

  Detta är mer användbart än att acceptera jobbet och misslyckas med det efter ett uppströms valideringspass.

  Reservera hyresgästbudget och bestäm sedan faktisk användning

  Batchkörning komplicerar fakturering eftersom gatewayen kan förlora synkron åtkomst till exakt användning tills resultatfiler är tillgängliga. Det säkra mönstret är offert, reservera, skicka, inta, kvittera och stämma av.

  Verifierade fakta: OpenAI anger att Batch API-priser erbjuds till en rabatt jämfört med synkrona API:er, och utgångna eller avbrutna batcher kan fortfarande returnera färdigt arbete som är fakturerbart. Anthropic noterar att batchbearbetning med hög genomströmning något kan överskrida en utgiftsgräns för arbetsytan, vilket gör bokning på gatewaysidan och efter avveckling viktiga.

  Rekommendation: reservera hyresgästbudget före inlämning med hjälp av uppskattade tokens, utvalda leverantörsprisregler och en säkerhetsmarginal. När resultaten har intagits, avgör den faktiska användningen på artikelnivå. Om uppskattningen var för hög, släpp den oanvända reservationen. Om den var för låg tillämpar du hyresgästens konfigurerade överskottspolicy.

  Praktiska redovisningshändelser:

  batch.estimated
  parti.reserverad
  batch.inlämnad
  batch.artikel.avgjord
  batch.artikel.återbetalas
  batch.cancel_requested
  batch.expiredbatch.reconciled

  Rekontran på artikelnivå är viktig. Om 45 000 artiklar slutförs och 5 000 löper ut, ska hyresgästen faktureras för utfört leverantörsarbete, inte för det ursprungliga manifestet som en enda odifferentierad blob.

  Bygg leverantörsadaptrar som översättare, inte affärslogikägare

  Varje leverantörsadapter bör veta hur man omvandlar gateway-adaptern, laddar ner gateway-jobbet, laddar ner dets batch-format eller hämtar det. resultat och kartlägga inbyggda resultat tillbaka till normaliserade poster.

  Håll hyresgästpolicyn utanför adaptern. Adaptern ska inte avgöra om en kund har tillräckligt med budget, om en partnerkund är avstängd eller om uppmaningar kan lagras. Det är gateway-beslut.

  Anpassaransvar

  • Gör leverantörsspecifika begärandemanifest.
  • Ladda upp indatafiler eller skapa leverantörsoperationer.
  • Lagra leverantörsidentifierare i metadata.
  • Kappa ursprunglig status till normaliserad status.
  • Hämta objekt->
  • Returnera inbyggda användningsposter när det är tillgängligt.
  • Utförsökbara ytor mot terminalfel.

  Gateway-ansvar

  • Autentisera klienten och API-nyckeln.
  • Tillämpa team-, projekt- och kundkontroller.
  • Lösa modell
  roualiases. batch-funktioner.
  • Reservera och reglera budget.
  • Bevara jobb- och artikelstatus.
  • Tillämpa retentionspolicy.
  • Exponera analyser och exporter.

  Denna separation gör det enklare att lägga till en ny leverantör utan att skriva om fakturering, analys eller hyresgäststyrning i första hand.

  <2resultat idem>.
  <2. intag är där många batchsystem av misstag duplicerar laddningar eller förlorar partiellt arbete. Behandla intag som en repeterbar process. Det bör vara säkert att ladda ner samma utdatafil två gånger, bearbeta samma leverantörsoperation två gånger eller spela upp samma webhook-händelse två gånger.

  Rekommendation: använd idempotensnycklar på artikelnivå och begränsningar för reskontras unikhet. Ett resultat för job_id + custom_id bör avgöras exakt en gång, även om inmatning görs om.

  Ett robust inmatningsflöde:

  1. Få ett kortlivat lås för jobbet eller resultatartefakten.
  2. Hämta leverantörsutdata och felartefakter.
  3. Parse artikelresultathändelser i normaliserade objekt efter poster. custom_id eller gateway-artikel-ID.
  4. Skriv resultatmetadata och användning i en transaktion.
  5. Skapa reskontraavräkningshändelse endast om en sådan inte redan finns.
  6. Uppdatera jobbantal från artikeltillstånd, inte från antaganden.
  7. Release oanvända budgetreservationer är kända när alla terminaltillstånd är tillgängliga.

  Försök objekt igen, inte hela jobb

  Rekommendation: Försök igen på objektnivå när det är möjligt. Omförsök med hela jobb är enkla, men de ökar risken för dubbelarbete och gör faktureringen svårare.

  Klassificera misslyckanden innan du försöker igen:

  • Valideringsfel: vanligtvis slutar tills begäran är åtgärdad.
  • Provider 5xx-fel:kan ofta återförsökas med backoff>
  endast med backoff-limits: efter att kapaciteten är tillgänglig.
  • Säkerhetsblockeringar: försök inte blint igen; väg till policyhantering.
  • Utgångna objekt: kan prövas på nytt i ett nytt jobb om hyresgästen fortfarande vill att arbetet och budgeten tillåter.

  Ett nytt försök bör skapa ett nytt objekt kopplat till originalet:

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

  Skicka inte om slutförda objekt bara för att de ingick i ett jobb som slutade som completed_with_errors eller expired.

  Bestämma vad som ska lagras: råresultat, pekare eller hash

  Batchsystem är frestande ställen att ackumulera och utdata. Det kan vara användbart för export och felsökning, men det ökar ansvaret för datalagring.

  Rekommendation: gör lagringspolicyn konfigurerbar för klienten. För känsliga arbetsbelastningar, lagra metadata, hash-, användnings- och resultatpekare snarare än råa uppmaningar och utdata.För mindre känsliga arbetsbelastningar kan normaliserad resultatlagring vara acceptabel om lagringsfönster, åtkomstkontroller och borttagningsarbetsflöden är tydliga.

  Spåra åtminstone:

  • Om råindata lagrades.
  • Om råutdata lagrades.
  • Där leverantörsresultatartefakter lever.
  • Provider retire.
  • raderingsfrist.
  • Hash av begäran och svar för granskning utan innehållsexponering.

  Verifierat faktum: Antropiska tillstånds batchresultat är tillgängliga i 29 dagar efter skapande och isolerade inom arbetsytan. Den här typen av leverantörsspecifika hämtningsfönster bör återspeglas i gatewayens metadata och exporter som vänder sig till klienter.

  Exponera analyser som matchar hur team fungerar

  Batchanalys bör finnas på både jobb- och artikelnivå. En produktägare vill veta om en nattlig berikning har slutförts. En finansadministratör vill ha kostnad per hyresgäst, modell och kund. En ingenjör vill veta vilken misslyckandeklass som ska försökas igen.

  Användbara mätvärden inkluderar:

  • Inskickade, slutförda, misslyckade, utgångna och avbrutna artiklar.
  • Uppskattad kontra fast kostnad.
  • Reserverad budget kvarstår.
  • Input och output tokens in-> leverantörer avslöjar dem.
  • Räkna om och försök igen.
  • Genomsnittlig tid i kö, körning och slutförande.
  • De vanligaste valideringsfelen efter slutpunkt och modell.
  • Partnerkundtillskrivning.

  För Partner API-användare, exponera batch-jobbresurser som kundanvändare. Det gör det möjligt för byråer och SaaS-byggare att erbjuda offline AI-bearbetning samtidigt som de bibehåller uppströms leverantörsuppgifter, faktureringsavstämning och hantering av taxegränser inom gatewayen.

  Avvägningar för att göra explicita

  Gateway-abstraktion kontra leverantörsspecifik förmåga: en enhetlig kontraktsintegrering förenklar det för operatören. Håll kapacitetsfel explicita.

  Budgetreservation kontra uppskattningsnoggrannhet: reservation skyddar hyresgäster från skenande jobb, men uppskattningar kan vara felaktiga. Huvudboken måste stödja justeringar, återbetalningar och hantering av överskott.

  Polling kontra webhooks: polling är enkel och pålitlig, men kan slösa API-anrop och försena slutförandet. Webhooks är snabbare, men kräver signaturverifiering, uppspelningsskydd och övervakning.

  Lagring av råresultat kontra retentionsminimering: Att lagra normaliserade resultat förbättrar export och analyser, men ökar efterlevnadsbördan. Känsliga hyresgäster kanske föredrar pekare och hash.

  Stora partier kontra klumpar: enorma partier kan förbättra effektiviteten på leverantörssidan, men mindre bitar minskar sprängradien och gör omförsök enklare.

  Implementeringschecklista

  • Skapa en separat sats för jobbposter och API-poster.
  inlämning.
  • Kräv gateway-jobb-ID:n och anpassade ID:n per artikel.
  • Normalisera statusar samtidigt som du lagrar inbyggd leverantörsmetadata.
  • Skapa en kapacitetsmatris för varje leverantörs batchadapter.
  • Validera manifest innan du bokar budget.
  • Reservera hyresgästbudget på S.
  efter faktisk utskick. intag.
  • Gör resultatintag idempotent.
  • Försök misslyckade objekt igen selektivt, inte hela jobb i blindo.
  • Spåra leverantörshämtningsfrister och gateway-retentionspolicy.
  • Exponera jobb- och objektanalys för hyresgäster och partnerkunder.

  förutsägelser: där detta mönster är förutsägelser: rubrik

  Prognos: batchexekvering kommer att bli en normal del av AI-automatiseringsinfrastrukturen, inte bara en rabattmekanism. När team kör fler evaler, uppgifter för att städa data, säkerhetsgranskningar och anrikningspipelines kommer de att förvänta sig att asynkrona arbetsbelastningar har samma styrning som synkrona API-anrop.

  Förutsägelse: Providers batch-API:er kommer att fortsätta att skilja sig åt på användbara sätt. Vissa kommer att optimera för filer, andra för långvariga operationer och andra för hanterade datamängder eller återuppringningar av händelser. Ett gateway-adapterlager kommer att bli mer värdefullt, inte mindre, eftersom det operativa kontraktet ovanför adaptrarna kan förbli stabilt.

  Aktiveringsbar slutsats

  Skruva inte fast batchbearbetning på en AI API-gateway som en leverantörsspecifik utrymningslucka. Bygg det som ett hållbart delsystem med egna jobbposter, artikelidentifierare, statusmodell, leverantörsadaptrar, budgetreservation, idempotent intag och analyser.

  Det viktigaste designvalet är redovisning på artikelnivå. När varje begäran i en batch har en stabil identitet, kan gatewayen stämma av oordnade resultat, bara försöka igen, endast misslyckat arbete, fakturera endast utfört leverantörsarbete och visa hyresgästerna vad som hände.Det är skillnaden mellan att skicka filer till en leverantör och att använda ett pålitligt multimodell-API för asynkrona arbetsbelastningar.

  Relaterad läsning

  • AI-kvotering, avstämning, avstämning, avstämning av AI mönster
  • användningsanalys och tokenreskontradesign på gatewaynivå
  • när latencytoleranta arbetsbelastningar passar batchbearbetning