Forenede batchjob gennem en AI API-gateway: Holdbare køer, udbyderadaptere og fakturering på lejerniveau

Batchbehandling bør ikke behandles som en sidedør omkring din AI API-gateway. Hvis evaler, dokumentberigelse, udtræk, modereringssweep eller indlejringsjob forlader den synkrone anmodningssti, har de stadig brug for lejerkontroller, omkostningstilskrivning, genforsøg, auditabilitet og brugsanalyse.

Implementeringsmønstret er at gøre batchudførelse til et førsteklasses gateway-undersystem. Gatewayen bør afsløre én udbyderneutral jobkontrakt, mens den tilpasser sig OpenAI, Anthropic, Gemini og fremtidige udbyders batch-API'er bag kulisserne.

Læserproblemet: batch-API'er er ens i hensigten, forskellige i drift

Latency-tolerante arbejdsbelastninger er en naturlig pasform til batchudførelse. Den svære del er ikke at beslutte, om et job kan vente. Den svære del er at drive batcharbejde konsekvent på tværs af udbydere.

Verificerede fakta: OpenAI's Batch API er asynkront, læser anmodninger fra en uploadet fil, skriver svar til en outputfil og bruger i øjeblikket et 24-timers behandlingsvindue. OpenAI viser statusser såsom validering, mislykkedes, i_gang, afslutter, afsluttet, udløbet, annullerer og annulleret. Anthropics Message Batches API behandler mange Messages-anmodninger asynkront, håndterer hver anmodning uafhængigt, kræver polling og returnerer resultater efter behandlingen er afsluttet. Anthropic anbefaler også meningsfulde custom_id-værdier, fordi resultatrækkefølgen ikke er garanteret. Gemini's Batch API afslører langvarige operations-metoder såsom liste, annullere, slette og opdatere metoder, og dens annullering beskrives som den bedste indsats.

Disse forskelle har betydning, når du tilføjer rigtige forretningskrav:

• Hvilken lejer, kunde, projekt eller API-nøgle ejer hver vare?
• Var opgaven fuldført, før opgaven blev afsluttet? er fakturerbare, hvis batchen udløber eller annulleres?
• Hvordan prøves delvise fejl igen uden at duplikere succesfuldt arbejde?
• Hvor længe kan resultatfiler hentes, og hvad skal gatewayen lagre?
• Kan en partner bygge kundebaseret batchbehandling uden at udsætte upstream-udbyderens legitimationsoplysninger for hid> Svaret er at normalisere driftskontrakten og samtidig bevare leverandør-native metadata til fejlfinding, afstemning og support.

  Anbefalet offentlig API: adskil batchjobs fra synkrone fuldførelser

  Anbefaling: eksponer batchjobs som deres egen API-overflade, ikke som et særligt flag på chat-afslutninger. En synkron anmodning og et asynkront batchjob har forskellige semantikker for livscyklus, fakturering, genforsøg og resultathentning.

  En praktisk gateway-kontrakt omfatter disse operationer:

  • create_job: opret et kladdejob, der ejes af en lejer, et projekt, en nøgle eller en partnerkunde.
  • app_encoded_coded_coded_code> tilføj individuelle anmodninger med stabile vare-id'er.
  • indsend: valider, reserver budget, vælg udbyder, afsend og lås det indsendte manifest.
  • get_status: returner normaliserede job- og vareantal.
  • list_results: blad gennem normaliserede vareresultater,
  • celle, og usage
  . lover øjeblikkelig opsigelse.
  • eksport_brug: eksporter omkostningsposter på jobniveau og vareniveau til analyse- eller faktureringssystemer.

  Eksempel på offentligt jobobjekt:

  {
    "job_id": "job_01j7...",
    "tenant_id": "tenant_acme",
    "customer_id": "cust_123",
    "endpoint": "chat.completions",
    "model": "analyse-stor",
    "status": "kører",
    "tæller": {
      "indsendt": 50000,
      "fuldført": 31240,
      "mislykkedes": 180,
      "udløbet": 0
    },
    "omkostning": {
      "estimeret": "184.20",
      "reserveret": "205.00",
      "afgjort": "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 offentlige objekt bør som standard ikke afsløre udbyderfil-id'er, operationsnavne eller rå upstream-fejl. De hører hjemme i metadata, der vender mod operatøren.

  Brug holdbare jobregistreringer som kilden til sandheden

  Et gateway-ejet batchlag skal have en holdbar tilstand, før noget sendes opstrøms. Stol ikke på udbyderens batch-registreringer som din eneste statslige butik. Udbyderregistreringer er nødvendige, men de kender ikke dit lejerhierarki, budgetreservationer, interne modelaliasser, partnerkunder eller analysekrav.

  Minimumsdatabasemodel

  Et nyttigt skema har tre niveauer:

  1. Batchjob

  batchjobs
  - job_id
  - lejer_id
  - projekt_id
  - kunde_id nullable- api_key_id
  - slutpunkt
  - requested_model
  - resolved_provider
  - resolved_provider_model
  - status
  - item_count
  - estimerede_input_tokens
  - estimerede_output_tokens
  - reserveret_beløb
  - afregnet_beløb
  - oprettet_kl
  - indsendt_kl
  - afsluttet_kl
  - udløber_kl
  - retrieval_deadline
  - cancellation_requested_at

  2. Batchvare

  batch_items
  - job_id
  - item_id
  - custom_id
  - idempotensnøgle
  - request_hash
  - status
  - provider_request_index nullable
  - estimerede_tokens
  - actual_input_tokens nullable
  - actual_output_tokens nullable
  - afregnet_beløb nullbar
  - result_pointer nullbar
  - fejlkode nullbar
  - Gentry_of_item_id nullable
  - oprettet_kl
  - settled_at

  3. Provider-metadata

  batch_provider_metadata
  - job_id
  - udbyder
  - provider_batch_id nullable
  - input_file_id nullable
  - output_file_id nullbar
  - error_file_id nullable
  - operationsnavn nullbar
  - slutpunkt
  - region nullable
  - native_status
  - native_request_counts jsonb
  - sidste_afstemning_kl
  - raw_error_pointer nullable

  Hvis udbyderens metadata holdes adskilt fra den offentlige jobkontrakt, kan gatewayen udvikle udbyderadaptere uden at bryde API'er, der vender mod lejeren.

  Kræv stabile vare-id'er før afsendelse

  Anbefaling kræve en _kode en gateway:: pr. vare custom_id eller idempotensnøgle før afsendelse. Afstem aldrig resultater efter ordre.

  Anthropic advarer eksplicit om, at resultatrækkefølge ikke er garanteret og anbefaler meningsfulde custom_id-værdier. Selv når en udbyder ser ud til at bevare orden, bør en gateway ikke være afhængig af den. Jobs bliver opdelt, prøvet igen, annulleret, delvist fuldført og genindtaget. Bestillingsantagelser mislykkes i sidste ende.

  Et sikkert vare-id-format er beskrivende, men ikke følsomt:

  tenantA.invoice_extraction.2026-08-19.row_000381

  Undgå at indsætte rå e-mails, navne, kunde-hemmelige titler eller kundenavne. Gem følsomme korrelationsdata i din egen lejerdatabase, ikke inde i udbyder-synlige id'er.

  Normaliser statusser uden at slette udbyderdetaljer

  Provider batch-API'er afslører forskellige livscyklusser. Gatewayen bør normalisere dem til en lille intern tilstandsmaskine, som dashboards, fakturering og automatisering kan forstå.

  Anbefalet normaliseret livscyklus:

  • draft: job eksisterer, men kan stadig redigeres.
  • validerer: gateway eller udbyder validering er ikke accepteret: >. endnu behandler.
  • kører: udbyder behandler elementer.
  • afslutter: udbyder er færdig med at beregne og forbereder resultatartefakter.
  • afsluttet: alle accepterede elementer nåede terminalsucces.
  • afsluttede_med_fejl og lykkedes med nogle elementer mislykkedes.
  • udløbet: udbydervinduet sluttede før alt arbejde var afsluttet.
  • cancel_requested: lejer bedt om at annullere, men det endelige fakturerbare arbejde er ikke afgjort.
  • annulleret: annullering afklaret.
  • mislykket
  job

  udført nyttigtp>. ikke skjule indfødte udbyderfejl til generiske etiketter for tidligt. Operatører har stadig brug for adgang til oprindelige statusser, valideringsfejl, anmodningstællinger, fil-id'er og operationsnavne ved fejlretning.

  Valider mod en funktionsmatrix før indsendelse

  Anbefaling: Kør preflight-validering før budgetreservation og udbyderafsendelse. Batch-tilstand er ikke kun synkron tilstand med en forsinkelse. Nogle modeller, endepunkter, anmodningsfunktioner, regioner og værktøjskonfigurationer understøttes muligvis ikke af en udbyders batch-API.

  Din interne kapacitetsmatrix bør kontrollere:

  • Understøttet slutpunkt: chat, meddelelser, indlejringer, moderering eller generering.
  • Modelberettigelse til batch-tilstand, maks. størrelse.
  • Uanset om streaming er forbudt.
  • Understøttelse af værktøjsbrug og funktionskald.
  • Understøttelse af struktureret output eller JSON-skema.
  • Billed-, lyd- eller multimodal input-understøttelse.
  • Regions- og opholdsbegrænsninger.
  • Udbyderfastholdelse og resultatindhentning begrænser hastigheden for udbyderen og søgningen af resultater. grænser.
  • Annulleringssemantik.

  Et godt preflight-svar er specifikt:

  {
    "error": "batch_capability_not_supported",
    "message": "Den valgte udbyder batch-adapter understøtter ikke streamingsvar. Fjern stream=true, eller vælg et synkront slutpunkt.",
    "field": "items[*].request.stream"}

  Dette er mere nyttigt end at acceptere jobbet og mislykkes efter et opstrøms valideringsbeløb.

  Reserver lejerbudget, og afgør derefter faktisk brug

  Batchudførelse komplicerer fakturering, fordi gatewayen kan miste synkron adgang til nøjagtig brug, indtil resultatfiler er tilgængelige. Det sikre mønster er tilbud, reserver, indsend, indtag, afregn og afstem.

  Bekræftede fakta: OpenAI angiver Batch API-priser tilbydes med rabat sammenlignet med synkrone API'er, og udløbne eller annullerede batches kan stadig returnere udført arbejde, der kan faktureres. Anthropic bemærker, at batchbehandling med høj gennemstrømning kan overskride en grænse for arbejdsområdets forbrug, hvilket gør reservation på gateway-siden og efterafregning vigtig.

  Anbefaling: reserver lejerbudget før indsendelse ved hjælp af estimerede tokens, udvalgte udbyderprisregler og en sikkerhedsmargin. Når resultaterne er indtaget, skal du afregne det faktiske forbrug på vareniveau. Hvis estimatet var for højt, frigiv den ubrugte reservation. Hvis det var for lavt, skal du anvende lejerens konfigurerede overskudspolitik.

  Praktiske finanshændelser:

  batch.estimated
  batch.reserveret
  batch.indsendt
  batch.vare.afgjort
  batch.vare.refunderes
  batch.cancel_requested
  batch.udløbetbatch.reconciled

  Rekontro på vareniveau er vigtig. Hvis 45.000 varer er færdige og 5.000 udløber, skal lejeren faktureres for afsluttet udbyderarbejde, ikke for det originale manifest som en enkelt udifferentieret klat.

  Byg udbyderadaptere som oversættere, ikke ejere af forretningslogik

  Hver udbyderadapter skal vide, hvordan man transformerer sub-gateway-opgaven, downloader dens gateway-status eller henter dens status. resultater, og kortlæg oprindelige resultater tilbage til normaliserede registreringer.

  Hold lejerpolitikken uden for adapteren. Adapteren bør ikke afgøre, om en kunde har tilstrækkeligt budget, om en partnerkunde er suspenderet, eller om prompter kan gemmes. Det er gateway-beslutninger.

  Adapteransvar

  • Gengiver udbyderspecifikke anmodningsmanifester.
  • Upload inputfiler eller opret udbyderhandlinger.
  • Gem udbyderidentifikatorer i metadata.
  • Kortlæg den oprindelige status til normaliseret status.
  • Hent output->
  • Returnering af indbyggede brugsregistreringer, når de er tilgængelige.
  • Gennemprøves i forhold til terminalfejl.

  Gateway-ansvar

  • Godkend lejer og API-nøgle.
  • Anvend team-, projekt- og kundekontroller.
  • Løs politikker for model
  • Løsning af model. batch-funktioner.
  • Reserver og afregn budget.
  • Bevar job- og varestatus.
  • Håndhæv fastholdelsespolitik.
  • Afslør analyser og eksporter.

  Denne adskillelse gør det nemmere at tilføje en ny udbyder uden at omskrive fakturering, analyser eller lejerstyring i første omgang.

  <2. indtagelse er, hvor mange batchsystemer ved et uheld duplikerer ladninger eller mister delvist arbejde. Behandl indtagelse som en gentagelig proces. Det burde være sikkert at downloade den samme outputfil to gange, behandle den samme udbyderoperation to gange eller genafspille den samme webhook-begivenhed to gange.

  Anbefaling: brug idempotensnøgler på vareniveau og begrænsninger for entydighed i hovedbog. Et resultat for job_id + custom_id bør afgøres nøjagtigt én gang, selvom indlæsning forsøges igen.

  Et robust indlæsningsflow:

  1. Hent en kortvarig lås for jobbet eller resultatartefakten.
  2. Hent udbyderoutput og fejlartefakter.
  Parse af postresultater for hvert element. custom_id eller gateway item ID.
  3. Skriv resultatmetadata og brug i en transaktion.
  4. Opret kun finansafregningshændelse, hvis en sådan ikke allerede eksisterer.
  5. Opdater joboptællinger fra varetilstande, ikke ud fra antagelser.
  6. Udgivne ubrugte budgetreservationer er kendte, når alle terminaltilstande er tilgængelige, når alle terminaltilstande er tilgængelige.
  > verificere signaturer og beskytte mod gentagelse. Hvis polling er påkrævet, skal du bruge adaptiv polling: polling ofte tæt på forventet afslutning, tilbage i længere perioder, og stop efter terminalafregning.

  Prøv elementer igen, ikke hele job

  Anbefaling: Prøv igen på vareniveau, når det er muligt. Genforsøg i hele job er enkle, men de øger risikoen for dobbeltarbejde og gør fakturering sværere.

  Klassificer fejl, før du prøver igen:

  • Valideringsfejl: er normalt afsluttet, indtil anmodningen er rettet.
  • Provider 5xx-fejl:kan ofte prøves igen med backoff->
  -fejl. efter kapacitet er tilgængelig.
  • Sikkerhedsblokke: prøv ikke blindt igen; vej til politikhåndtering.
  • Udløbne varer: kan prøves igen i et nyt job, hvis lejeren stadig ønsker, at arbejdet og budgettet tillader det.

  Et forsøg igen skulle oprette en ny vare knyttet til den originale:

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

  Indsend ikke afsluttede elementer igen, bare fordi de var en del af et job, der endte som afsluttet_med_fejl eller udløbet.

  Beslut hvad du vil gemme: rå resultater, pointere eller hashes

  Batchsystemer er fristende steder til at akkumulere output. Det kan være nyttigt til eksport og fejlretning, men det øger ansvaret for dataopbevaring.

  Anbefaling: gør lagerpolitikken lejer-konfigurerbar. For følsomme arbejdsbelastninger skal du gemme metadata, hashes, brugs- og resultatpointere i stedet for rå prompter og output.For mindre følsomme arbejdsbelastninger kan normaliseret resultatlagring være acceptabel, hvis opbevaringsvinduer, adgangskontroller og sletningsarbejdsgange er klare.

  Spor i det mindste:

  • Om rå input blev gemt.
  • Om råoutput blev gemt.
  • Hvor udbyderresultatartefakter lever.
  • Provider retefline.
  • sletningsfrist.
  • Hash af anmodning og svar til revision uden indholdseksponering.

  Bekræftet kendsgerning: Batchresultater fra antropiske tilstande er tilgængelige i 29 dage efter oprettelse og isoleret i arbejdsområdet. Denne form for udbyderspecifikt genfindingsvindue bør afspejles i gatewayens metadata og eksporter til lejer.

  Afslør analyser, der matcher, hvordan teams fungerer

  Batchanalyse bør eksistere på både job- og vareniveau. En produktejer ønsker at vide, om en natlig berigelse er gennemført. En økonomiadministrator ønsker omkostninger efter lejer, model og kunde. En tekniker ønsker at vide, hvilken fejlklasse der skal prøves igen.

  Nyttige målinger omfatter:

  • Indsendte, gennemførte, mislykkede, udløbne og annullerede vareantal.
  • Estimeret versus afregnet pris.
  • Reserveret budget er stadig indeholdt.
  • Input og output-tokener, hvor->< leverer input og output tokens. udbydere afslører dem.
  • Tæl igen og prøv succesrate igen.
  • Gennemsnitlig tid i kø-, kørende og afsluttende tilstande.
  • Top valideringsfejl efter endpoint og model.
  • Partnerkundetilskrivning.

  For Partner API-brugere, eksponer batch-jobressourcer som. Det gør det muligt for bureauer og SaaS-udviklere at tilbyde offline AI-behandling, samtidig med at de bibeholder opstrøms udbyderoplysninger, faktureringsafstemning og håndtering af hastighedsgrænser inde i gatewayen.

  Afvejninger, der skal gøres eksplicitte

  Gateway-abstraktion versus udbyderspecifik kapacitet:en ensartet funktion kan ikke give enhver kontrakt, men det forenkler udbyderen. Hold kapacitetsfejl eksplicitte.

  Budgetreservation versus estimatnøjagtighed: reservation beskytter lejere mod løbske job, men estimater kan være forkerte. Hovedbogen skal understøtte justeringer, refusioner og håndtering af overskud.

  Polling versus webhooks: polling er enkel og pålidelig, men kan spilde API-kald og forsinke færdiggørelsen. Webhooks er hurtigere, men kræver signaturbekræftelse, genafspilningsbeskyttelse og overvågning.

  Rå resultatlagring versus retentionsminimering: lagring af normaliserede resultater forbedrer eksport og analyser, men øger compliance-byrden. Følsomme lejere foretrækker måske pointere og hashes.

  Store batches versus chunked batches: enorme batches kan forbedre effektiviteten på udbydersiden, men mindre bidder reducerer sprængningsradius og gør genforsøg nemmere.

  Implementeringstjekliste

  • Opret en separat batch- og jobpostoverflade.
  indsendelse.
  • Kræv gateway-job-id'er og tilpassede id'er pr. vare.
  • Normaliser statusser, mens du gemmer native provider-metadata.
  • Byg en kapacitetsmatrix for hver udbyder-batchadapter.
  • Valider manifester, før du reserverer budget.
  • Reserver lejer-varebudget på S.
  efter faktisk afsendelse. indtagelse.
  • Gør resultatindtagelse idempotent.
  • Prøv mislykkede varer selektivt, ikke hele job blindt.
  • Spor udbyderens hentningsfrister og gateway-fastholdelsespolitik.
  • Udslæt job- og vareanalyse for lejere og partnerkunder.

  forudsigelser. overskrift

  Forudsigelse: batchudførelse bliver en normal del af AI-automatiseringsinfrastrukturen, ikke kun en rabatmekanisme. Efterhånden som teams kører flere evaler, dataoprydningsopgaver, sikkerhedsgennemgange og berigelsespipelines, vil de forvente, at asynkrone arbejdsbelastninger har samme styring som synkrone API-kald.

  Forudsigelse: udbyderbatch-API'er vil fortsætte med at adskille sig på nyttige måder. Nogle vil optimere til filer, andre til langvarige operationer og andre til administrerede datasæt eller tilbagekald af hændelser. Et gateway-adapterlag vil blive mere værdifuldt, ikke mindre, fordi den operationelle kontrakt over adapterne kan forblive stabil.

  Aktiv konklusion

  Batchbehandling må ikke boltes på en AI API-gateway som en udbyderspecifik escape hatch. Byg det som et holdbart undersystem med dets egne jobregistreringer, vareidentifikatorer, statusmodel, udbyderadaptere, budgetreservation, idempotent indtagelse og analyser.

  Det vigtigste designvalg er regnskab på vareniveau. Når hver anmodning inde i en batch har en stabil identitet, kan gatewayen afstemme uordnede resultater, prøve kun mislykket arbejde igen, kun fakturere udført udbyderarbejde og vise lejere, hvad der skete.Det er forskellen mellem at sende filer til en udbyder og at betjene en pålidelig multimodel-API til asynkrone arbejdsbelastninger.

  Relateret læsning

  • AI-quote, reconcile, settle, API mønster
  • brugsanalyse på gateway-niveau og token-ledger-design
  • når latencytolerante arbejdsbelastninger passer til batchbehandling