Samlede batchjobber gjennom en AI API-gateway: holdbare køer, leverandøradaptere og fakturering på leietakernivå

Batchbehandling bør ikke behandles som en sidedør rundt AI API-gatewayen din. Hvis evaler, dokumentanriking, utvinning, moderasjonssveip eller innebyggingsjobber forlater den synkrone forespørselsbanen, trenger de fortsatt leietakerkontroller, kostnadsattribusjon, gjenforsøk, revisjonerbarhet og bruksanalyse.

Implementeringsmønsteret er å gjøre batchkjøring til et førsteklasses gateway-undersystem. Gatewayen bør avsløre én leverandørnøytral jobbkontrakt mens den tilpasser seg OpenAI, Anthropic, Gemini og fremtidige leverandør-batch-API-er bak kulissene.

Leserproblemet: batch-API-er er like i intensjoner, forskjellige i drift

Latens-tolerante arbeidsbelastninger er en naturlig tilpasning for batch-utførelse. Det vanskelige er ikke å bestemme seg for om en jobb kan vente. Den vanskelige delen er å drive batcharbeid konsekvent på tvers av leverandører.

Verifiserte fakta: OpenAIs Batch API er asynkron, leser forespørsler fra en opplastet fil, skriver svar til en utdatafil og bruker for øyeblikket et 24-timers behandlingsvindu. OpenAI viser statuser som validering, mislyktes, i_progress, finalizing, fullført, utløpt, avbryter og avbrutt. Anthropics Message Batches API behandler mange meldingsforespørsler asynkront, håndterer hver forespørsel uavhengig, krever polling og returnerer resultater etter at behandlingen er avsluttet. Anthropic anbefaler også meningsfulle custom_id-verdier fordi resultatrekkefølgen ikke er garantert. Geminis Batch API avslører langvarige operasjonsstilsmetoder som liste, avbryt, slett og oppdater metoder, og kanselleringsoperasjonen beskrives som beste innsats.

Disse forskjellene er viktige når du legger til reelle forretningskrav:

• Hvilken leietaker, kunde, prosjekt eller API-nøkkel eier hver vare?
• Var jobben reservert før budsjettet var reservert >
• er fakturerbare hvis batchen utløper eller kanselleres?
• Hvordan prøves delvise feil på nytt uten å duplisere vellykket arbeid?
• Hvor lenge kan resultatfiler hentes, og hva bør gatewayen lagre?
• Kan en partner bygge kundeomfanget batchbehandling uten å eksponere oppstrømsleverandørens legitimasjon for hi

• Anbefalt offentlig API: skille batchjobber fra synkrone fullføringer

  Anbefaling: eksponer batchjobber som deres egen API-overflate, ikke som et spesielt flagg på chatfullføringer. En synkron forespørsel og en asynkron batchjobb har forskjellig livssyklus-, fakturerings-, prøve- og resultathentingssemantikk.

  En praktisk gateway-kontrakt inkluderer disse operasjonene:

  • create_job: opprett et utkast til en jobb som eies av en leietaker, et prosjekt, en nøkkel eller en partnerkunde.
  • app_en_coded_coded_code: legg til individuelle forespørsler med stabile vareidentifikatorer.
  • send inn: valider, reserver budsjett, velg leverandør, send og lås det innsendte manifestet.
  • get_status: returner normalisert jobb- og varetall.
  • listeresultater: blad gjennom normaliserte vareresultater, forespørsler og . lover umiddelbar avslutning.
  • eksportbruk: eksporter kostnadsposter på jobbnivå og varenivå for analyse- eller faktureringssystemer.

  Eksempel på offentlig jobbobjekt:

  {
    "job_id": "job_01j7...",
    "tenant_id": "tenant_acme",
    "customer_id": "cust_123",
    "endpoint": "chat.completions",
    "model": "analyse-stor",
    "status": "løper",
    "teller": {
      "innsendt": 50 000,
      "fullført": 31240,
      "mislyktes": 180,
      "utløpt": 0
    },
    "kostnad": {
      "estimert": "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 offentlige objektet skal ikke avsløre leverandørfil-IDer, operasjonsnavn eller rå oppstrømsfeil som standard. De hører hjemme i operatørvendte metadata.

  Bruk holdbare jobbposter som kilden til sannhet

  Et gateway-eid batchlag trenger en varig tilstand før noe sendes oppstrøms. Ikke stol på leverandørbatch-poster som din eneste statlige butikk. Leverandøroppføringer er nødvendige, men de kjenner ikke leietakerhierarkiet ditt, budsjettreservasjoner, interne modellaliaser, partnerkunder eller analysekrav.

  Minimumsdatabasemodell

  Et nyttig skjema har tre nivåer:

  1. Batchjobb

  batch_jobs
  - jobb_id
  - leietaker-id
  - prosjekt_id
  - kunde_id nullbar- api_key_id
  - endepunkt
  - forespurt_modell
  - resolved_provider
  - resolved_provider_model
  - status
  - item_count
  - estimerte_input_tokens
  - estimerte_output_tokens
  - reservert_beløp
  - avgjort_beløp
  - opprettet_at
  - sendt_at
  - fullført_kl
  - utløper_kl
  - henting_frist
  - cancellation_requested_at

  2. Batch element

  batch_items
  - jobb_id
  - item_id
  - custom_id
  - idempotensnøkkel
  - request_hash
  - status
  - provider_request_index nullbar
  - estimerte_tokens
  - actual_input_tokens nullbar
  - faktisk_utgang_tokens nullbar
  - settled_amount nullbar
  - resultatpeker nullbar
  - error_code nullbar
  - retry_of_item_id nullbar
  - opprettet_at
  - settled_at

  3. Leverandørmetadata

  batch_provider_metadata
  - jobb_id
  - leverandør
  - provider_batch_id nullbar
  - input_file_id nullbar
  - output_file_id nullbar
  - error_file_id nullbar
  - operasjonsnavn nullbar
  - endepunkt
  - region nullbar
  - native_status
  - native_request_counts jsonb
  - siste_avstemning_kl
  - raw_error_pointer nullable

  Ved å holde leverandørens metadata atskilt fra den offentlige jobbkontrakten lar gatewayen utvikle leverandøradaptere uten å bryte API-er som vender mot leietaker.

  Krev stabile vareidentifikatorer før utsendelse

  Anbefaling: generer en _portkode og gateway: per-element custom_id eller idempotensnøkkel før utsendelse. Avstem aldri resultater etter ordre.

  Anthropic advarer eksplisitt om at resultatrekkefølge ikke er garantert og anbefaler meningsfulle custom_id-verdier. Selv når en leverandør ser ut til å opprettholde orden, bør en gateway ikke være avhengig av den. Jobber blir delt opp, forsøkt på nytt, kansellert, delvis fullført og inntatt på nytt. Bestillingsforutsetninger mislykkes til slutt.

  Et sikkert vareidentifikatorformat er beskrivende, men ikke sensitivt:

  tenantA.invoice_extraction.2026-08-19.row_000381

  Unngå å legge inn rå e-poster, navn, kundehemmelige identifikatorer. Lagre sensitive korrelasjonsdata i din egen leietakerdatabase, ikke inne i ID-er som er synlige for leverandøren.

  Normaliser statuser uten å slette leverandørdetaljer

  Provider batch-APIer avslører ulike livssykluser. Gatewayen bør normalisere dem til en liten intern tilstandsmaskin som dashbord, fakturering og automatisering kan forstå.

  Anbefalt normalisert livssyklus:

  • utkast: jobben eksisterer, men kan fortsatt redigeres.
  • validerer: gateway eller leverandør er ikke godkjent, men validerer ikke. ennå behandles.
  • kjører: leverandøren behandler elementer.
  • sluttgjør: leverandøren har fullført beregningen og forbereder resultatartefakter.
  • fullførte: alle aksepterte elementer nådde terminalsuksess.
  • fullførte_med_feil og noen elementer fullført
  • mislyktes.
  • utløpt: leverandørvinduet ble avsluttet før alt arbeid ble fullført.
  • cancel_requested: leietaker bedt om å avbryte, men endelig fakturerbart arbeid er ikke avgjort.
  • kansellert: kansellering avgjort.
  • mislykket
  • utførelse svikt
  . ikke skjule innfødte leverandørfeil til generiske etiketter for tidlig. Operatører trenger fortsatt tilgang til opprinnelige statuser, valideringsfeil, forespørselstall, fil-ID-er og operasjonsnavn ved feilsøking.

  Valider mot en funksjonsmatrise før innsending

  Anbefaling: kjør forhåndskontroll før budsjettreservasjon og leverandørutsendelse. Batch-modus er ikke bare synkron modus med forsinkelse. Enkelte modeller, endepunkter, forespørselsfunksjoner, regioner og verktøykonfigurasjoner støttes kanskje ikke av en leverandørs batch-API.

  Din interne kapasitetsmatrise bør sjekke:

  • Støttet endepunkt: chat, meldinger, innebygginger, moderering eller generering.
  • Kvalifisering for modell for batch-modus, opplastingsmodus, varestørrelse og filstørrelse.
  størrelse.
  • Hvorvidt strømming er forbudt.
  • Støtte for verktøybruk og funksjonsanrop.
  • Støtte for strukturert utgang eller JSON-skjema.
  • Støtte for bilde, lyd eller multimodal inngang.
  • Region- og bostedsbegrensninger.
  • Tilbyderoppbevaring og resultatinnhentingshastighet B.>
  • spesifikke vinduer for oppbevaring og resultatinnhenting. grenser.
  • Kanselleringssemantikk.

  En god forhåndskontroll er spesifikk:

  {
    "error": "batch_capability_not_supported",
    "message": "Den valgte leverandørens batchadapter støtter ikke strømmesvar. Fjern stream=true eller velg et synkront endepunkt.",
    "field": "items[*].request.stream"}

  Dette er mer nyttig enn å godta jobben og mislykkes etter et oppstrøms valideringspass.

  Reserver leietakerbudsjett, og avgjør deretter faktisk bruk

  Batchkjøring kompliserer fakturering fordi gatewayen kan miste synkron tilgang til eksakt bruk til resultatfiler er tilgjengelige. Det sikre mønsteret er tilbud, reserver, send inn, inntak, avgjør og avstem.

  Verifiserte fakta: OpenAI oppgir at Batch API-priser tilbys med rabatt sammenlignet med synkrone APIer, og utløpte eller kansellerte batcher kan fortsatt returnere fullført arbeid som er fakturerbart. Anthropic bemerker at batchbehandling med høy gjennomstrømning kan overskride en grense for forbruk på arbeidsområdet, noe som gjør reservasjon på gatewaysiden og etteroppgjør viktig.

  Anbefaling: reserver leietakerbudsjett før innsending ved å bruke estimerte tokens, utvalgte leverandørprisregler og en sikkerhetsmargin. Etter at resultatene er inntatt, avgjør faktisk bruk på varenivå. Hvis anslaget var for høyt, frigi den ubrukte reservasjonen. Hvis den var for lav, bruk leietakerens konfigurerte overskuddspolicy.

  Praktiske finanshendelser:

  batch.estimated
  batch.reservert
  batch.innsendt
  batch.vare.avgjort
  batch.item.refunded
  batch.cancel_requested
  batch.utløptbatch.reconciled

  Rekontro på varenivå er viktig. Hvis 45 000 varer fullføres og 5 000 utløper, skal leietakeren faktureres for fullført leverandørarbeid, ikke for det originale manifestet som en enkelt udifferensiert blob.

  Bygg leverandøradaptere som oversettere, ikke eiere av forretningslogikk

  Hver leverandøradapter skal vite hvordan man transformerer gateway-jobben til undergrunnsstasjon, henter dens batch-format eller henter den. resultater, og kartlegg opprinnelige resultater tilbake til normaliserte poster.

  Hold leietakerpolicy utenfor adapteren. Adapteren skal ikke bestemme om en kunde har nok budsjett, om en partnerkunde er suspendert eller om forespørsler kan lagres. Dette er gateway-beslutninger.

  Adapteransvar

  • Gengi leverandørspesifikke forespørselsmanifester.
  • Last opp inndatafiler eller opprett leverandøroperasjoner.
  • Lagre leverandøridentifikatorer i metadata.
  • Kartlegg native status til normalisert status.
  • Hent vareutdata og
  • Returner opprinnelige bruksposter når de er tilgjengelige.
  • Tilgjengelig på nytt i forhold til terminalfeil.

  Gatewayansvar

  • Autentiser leietaker og API-nøkkel.
  • Bruk team-, prosjekt- og kundekontroller.
  • Løs retningslinjer for modell
  • Løsing av modeller. batch-funksjoner.
  • Reserver og avgjør budsjett.
  • Fortsett jobb- og varestatus.
  • Håndhev oppbevaringspolicy.
  • Utslør analyser og eksporter.

  Denne separasjonen gjør det enklere å legge til en ny leverandør uten å omskrive fakturering, analyser eller leietakerstyring.

  Anbefaling: bruk idempotensnøkler på varenivå og begrensninger for reskontroens unikhet. Et resultat for job_id + custom_id bør avgjøres nøyaktig én gang, selv om innføring prøves på nytt.

  En robust innføringsflyt:

  1. Få en kortvarig lås for jobben eller resultatartefakten.
  2. Hent leverandørutdata og feilartefakter.
  3. Parse posted item-resultater i hver post. custom_id eller gateway item ID.
  4. Skriv resultatmetadata og bruk i en transaksjon.
  5. Opprett reskontroavregningshendelse bare hvis en ikke allerede eksisterer.
  6. Oppdater jobbtellinger fra varetilstander, ikke fra forutsetninger.
  7. Skriv ubrukt budsjettreservasjon er kjent når alle terminaltilstander er tilgjengelige.
  verifisere signaturer og beskytte mot gjenspilling. Hvis polling er nødvendig, bruk adaptiv polling: polling ofte nær forventet fullføring, trekk tilbake i langvarige perioder, og stopp etter terminaloppgjør.

  Prøv elementer på nytt, ikke hele jobber

  Anbefaling: Prøv på nytt på varenivå når det er mulig. Hele jobbforsøk er enkle, men de øker risikoen for duplikatarbeid og gjør fakturering vanskeligere.

  Klassifiser feil før du prøver på nytt:

  • Valideringsfeil: vanligvis terminal inntil forespørselen er løst.
  • Provider 5xx-feil:kan ofte prøves på nytt med backoff->
  etter at kapasitet er tilgjengelig.
  • Sikkerhetsblokker: ikke blindt prøv på nytt; vei til policyhåndtering.
  • Utløpte varer: kan prøves på nytt i en ny jobb hvis leietaker fortsatt ønsker at arbeidet og budsjettet tillater det.

  Et nytt forsøk bør opprette en ny vare knyttet til originalen:

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

  Ikke send inn fullførte elementer på nytt bare fordi de var en del av en jobb som endte som completed_with_errors eller utløpt.

  Beslutt hva du vil lagre: råresultater, pekere eller hashes

  Batchsystemer er fristende steder for å akkumulere utdata. Det kan være nyttig for eksport og feilsøking, men det øker ansvaret for dataoppbevaring.

  Anbefaling: gjør lagringspolicyen leietakerkonfigurerbar. For sensitive arbeidsbelastninger, lagre metadata, hasher, bruk og resultatpekere i stedet for rå meldinger og utdata.For mindre sensitive arbeidsbelastninger kan normalisert resultatlagring være akseptabelt hvis oppbevaringsvinduer, tilgangskontroller og slettingsarbeidsflyter er klare.

  Spor i det minste:

  • Om råinndata ble lagret.
  • Om råutdata ble lagret.
  • Hvor leverandørresultatartefakter lever.
  • Provider retire.
  • slettingsfrist.
  • Hash av forespørsel og svar for revisjon uten innholdseksponering.

  Bekreftet faktum: Antropiske staters batchresultater er tilgjengelige i 29 dager etter opprettelse og isolert innenfor arbeidsområdet. Denne typen leverandørspesifikt innhentingsvindu bør gjenspeiles i gatewayens metadata og eksporter mot leietaker.

  Avslør analyser som samsvarer med hvordan teamene fungerer

  Batchanalyse bør eksistere på både jobb- og varenivå. En produkteier ønsker å vite om en nattlig berikelse ble fullført. En økonomiadministrator ønsker kostnad etter leietaker, modell og kunde. En ingeniør ønsker å vite hvilken feilklasse som skal prøves på nytt.

  Nyttige beregninger inkluderer:

  • Innsendte, fullførte, mislykkede, utløpte og kansellerte vareteller.
  • Estimert kontra avgjort kostnad.
  • Reservert budsjett fortsatt holdt.
  • Input and output tokens in->
  • Input and output tokens. leverandørene avslører dem.
  • Tell på nytt og forsøk suksessrate på nytt.
  • Gjennomsnittlig tid i kø-, kjøre- og ferdigstillelsestilstander.
  • De beste valideringsfeilene etter endepunkt og modell.
  • Partnerkundeattribusjon.

  For Partner API-brukere, eksponer batchjobbressurser som. Dette gjør at byråer og SaaS-byggere kan tilby offline AI-behandling samtidig som de beholder oppstrøms leverandørlegitimasjon, faktureringsavstemming og takstgrensehåndtering inne i gatewayen.

  Avveininger for å gjøre eksplisitt

  Gateway-abstraksjon kontra leverandørspesifikk funksjon: en enhetlig integrasjon forenkler ikke alle kontrakter, men det forenkler. Hold funksjonsfeil eksplisitte.

  Budsjettreservasjon versus estimatnøyaktighet: reservasjon beskytter leietakere mot løpske jobber, men estimater kan være feil. Hovedboken må støtte justeringer, refusjoner og håndtering av overskudd.

  Polling versus webhooks: polling er enkelt og pålitelig, men kan kaste bort API-kall og forsinke fullføring. Webhooks er raskere, men krever signaturverifisering, avspillingsbeskyttelse og overvåking.

  Rå resultatlagring kontra retentionsminimering: lagring av normaliserte resultater forbedrer eksport og analyser, men øker compliance-byrden. Sensitive leietakere foretrekker kanskje pekepinner og hashes.

  Store batcher versus chunked batcher: enorme batcher kan forbedre effektiviteten på leverandørsiden, men mindre deler reduserer sprengningsradius og gjør gjenforsøk enklere.

  Implementeringssjekkliste

  • Lag en separat jobbpostoverflate.
  APIer-jobbelementer. innsending.
  • Krev gateway-jobb-ID-er og egendefinerte ID-er per vare.
  • Normaliser statuser mens du lagrer opprinnelige leverandørmetadata.
  • Bygg en kapasitetsmatrise for hver leverandørbatchadapter.
  • Valider manifester før du reserverer budsjett.
  • Reserver leietaker-varebudsjett på S.
  etter faktisk utsendelse. inntak.
  • Gjør inntak av resultat idempotent.
  • Prøv mislykkede elementer selektivt, ikke hele jobber blindt.
  • Spor leverandørens hentingsfrister og retningslinjer for oppbevaring av gateway.
  • Utsett jobb- og vareanalyse for leietakere og partnerkunder.

  forutsigelser. overskrift

  Prediksjon: batchutførelse vil bli en normal del av AI-automasjonsinfrastrukturen, ikke bare en rabattmekanisme. Etter hvert som team kjører flere evaler, dataoppryddingsoppgaver, sikkerhetsgjennomganger og berikelsespipelines, vil de forvente at asynkrone arbeidsbelastninger har samme styring som synkrone API-kall.

  Forutsigelse: leverandørbatch-API-er vil fortsette å variere på nyttige måter. Noen vil optimalisere for filer, andre for langvarige operasjoner, og andre for administrerte datasett eller tilbakeringing av hendelser. Et gateway-adapterlag vil bli mer verdifullt, ikke mindre, fordi driftskontrakten over adapterene kan forbli stabil.

  Aktiv konklusjon

  Ikke fest batchbehandling på en AI API-gateway som en leverandørspesifikk escape-luke. Bygg det som et holdbart delsystem med egne jobbposter, vareidentifikatorer, statusmodell, leverandøradaptere, budsjettreservasjon, idempotent inntak og analyser.

  Det viktigste designvalget er regnskap på varenivå. Når hver forespørsel i en batch har en stabil identitet, kan gatewayen avstemme uordnede resultater, bare prøve mislykket arbeid på nytt, kun fakturere fullført leverandørarbeid og vise leietakere hva som skjedde.Det er forskjellen mellom å sende filer til en leverandør og å betjene en pålitelig multi-modell API for asynkrone arbeidsbelastninger.

  Relatert lesing

  • AI-quote, reconcile, reserve, settle, API mønster
  • bruksanalyse på gateway-nivå og token reskontrodesign
  • når ventetid-tolerante arbeidsbelastninger passer til batchbehandling