Uniforme batchtaken via een AI API Gateway: duurzame wachtrijen, provideradapters en facturering op huurderniveau

Batchverwerking mag niet worden behandeld als een zijdeur rondom uw AI API-gateway. Als evaluaties, documentverrijking, extractie, moderatie-opruimingen of insluitingstaken het synchrone aanvraagpad verlaten, hebben ze nog steeds tenantcontroles, kostenattributie, nieuwe pogingen, controleerbaarheid en gebruiksanalyses nodig.

Het implementatiepatroon is om van batchuitvoering een eersteklas gateway-subsysteem te maken. De gateway moet één provider-neutraal taakcontract blootleggen en zich achter de schermen aanpassen aan OpenAI, Anthropic, Gemini en toekomstige batch-API's van de provider.

Het probleem van de lezer: batch-API's hebben dezelfde bedoeling, maar verschillen in werking

Latentietolerante werkbelastingen zijn een natuurlijke oplossing voor batch-uitvoering. Het moeilijkste deel is niet beslissen of een baan kan wachten. Het moeilijkste deel is het consistent uitvoeren van batchwerk voor alle providers.

Geverifieerde feiten: OpenAI's batch API is asynchroon, leest verzoeken uit een geüpload bestand, schrijft antwoorden naar een uitvoerbestand en gebruikt momenteel een verwerkingsperiode van 24 uur. OpenAI geeft statussen weer zoals validating, failed, in_progress, finalizing, completed, expired, cancelling en cancelled. De berichtenbatches van Anthropic API verwerken veel berichtenverzoeken asynchroon, behandelen elk verzoek afzonderlijk, vereisen polling en retourneren resultaten nadat de verwerking is beëindigd. Anthropic raadt ook betekenisvolle custom_id-waarden aan omdat de resultaatvolgorde niet gegarandeerd is. Gemini's Batch API onthult langlopende bewerkingsmethoden zoals lijst-, annulerings-, verwijder- en updatemethoden, en de annuleringsbewerking ervan wordt beschreven als best-effort.

Deze verschillen zijn van belang zodra u echte bedrijfsvereisten toevoegt:

• Welke tenant, klant, project of API sleutel is eigenaar van elk item?
• Was budget gereserveerd voordat de taak de gateway verliet?
• Welke voltooide items zijn factureerbaar als de batch verloopt of wordt geannuleerd?
• Hoe worden gedeeltelijke mislukkingen opnieuw geprobeerd zonder succesvol werk te dupliceren?
• Hoe lang kunnen resultaatbestanden worden opgehaald en wat moet de gateway opslaan?
• Kan een partner klantgerichte batchverwerking bouwen zonder de upstream-provider bloot te leggen inloggegevens?

Het antwoord is niet om elk providerverschil te verbergen. De oplossing is het normaliseren van het exploitatiecontract, terwijl de metagegevens van de provider behouden blijven voor foutopsporing, afstemming en ondersteuning.

Aanbevolen openbaar API: scheid batchtaken van synchrone voltooiingen

Aanbeveling: stel batchtaken bloot als hun eigen API oppervlak, niet als een speciale vlag bij het voltooien van chats.Een synchrone aanvraag en een asynchrone batchtaak hebben verschillende semantieken voor de levenscyclus, facturering, nieuwe poging en het ophalen van resultaten.

Een praktisch gatewaycontract omvat de volgende bewerkingen:

• create_job: maak een concepttaak die eigendom is van een tenant, project, sleutel of partnerklant.
• append_items of upload_manifest: voeg individuele verzoeken toe met een stabiel item identifiers.
• submit: valideren, budget reserveren, provider selecteren, het ingediende manifest verzenden en vergrendelen.
• get_status: genormaliseerde taak- en itemaantallen retourneren.
• list_results: door genormaliseerde itemresultaten, fouten en gebruik bladeren.
• cancel: annulering aanvragen, zonder onmiddellijke belofte beëindiging.
• export_usage: kostenrecords op taak- en artikelniveau exporteren voor analyse- of factureringssystemen.

Voorbeeld van een openbaar taakobject:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "analysis-large",
  "status": "running",
  "counts": {
    "submitted": 50000,
    "completed": 31240,
    "failed": 180,
    "expired": 0
  },
  "cost": {
    "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"
}

Het openbare object mag standaard geen ID's van providerbestanden, bewerkingsnamen of onbewerkte upstream-fouten weergeven. Deze horen thuis in metadata die op de operator gericht is.

Gebruik duurzame taakrecords als de bron van de waarheid

Een batchlaag die eigendom is van de gateway heeft een duurzame status nodig voordat er iets upstream wordt ingediend. Vertrouw niet op batchrecords van de provider als uw enige staatsopslag. Providerrecords zijn nodig, maar ze kennen uw tenanthiërarchie, budgetreserveringen, interne modelaliassen, partnerklanten of analysevereisten niet.

Minimaal databasemodel

Een nuttig schema heeft drie niveaus:

1. Batchtaak

batch_jobs
- job_id
- tenant_id
- project_id
- customer_id nullable
- api_key_id
- endpoint
- requested_model
- resolved_provider
- resolved_provider_model
- status
- item_count
- estimated_input_tokens
- estimated_output_tokens
- reserved_amount
- settled_amount
- created_at
- submitted_at
- completed_at
- expires_at
- retrieval_deadline
- cancellation_requested_at

2. Batchartikel

batch_items
- job_id
- item_id
- custom_id
- idempotency_key
- request_hash
- status
- provider_request_index nullable
- estimated_tokens
- actual_input_tokens nullable
- actual_output_tokens nullable
- settled_amount nullable
- result_pointer nullable
- error_code nullable
- retry_of_item_id nullable
- created_at
- settled_at

3. Metagegevens van de provider

batch_provider_metadata
- job_id
- provider
- provider_batch_id nullable
- input_file_id nullable
- output_file_id nullable
- error_file_id nullable
- operation_name nullable
- endpoint
- region nullable
- native_status
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Door de metagegevens van de provider gescheiden te houden van het openbare arbeidscontract, kan de gateway provideradapters ontwikkelen zonder de tenant-gerichte API's te verbreken.

Stable item-ID's vereisen vóór verzending

Aanbeveling: genereer een gateway job_id en vereis een per-item custom_id of idempotentiesleutel vóór verzending. Stem resultaten nooit op volgorde af.

Anthropic waarschuwt expliciet dat de resultaatvolgorde niet gegarandeerd is en beveelt zinvolle custom_id waarden aan. Zelfs als een aanbieder de orde lijkt te bewaren, mag een gateway er niet afhankelijk van zijn. Taken worden opgedeeld, opnieuw geprobeerd, geannuleerd, gedeeltelijk voltooid en opnieuw opgenomen. Aannames over de volgorde mislukken uiteindelijk.

Een veilig item-ID-formaat is beschrijvend maar niet gevoelig:

tenantA.invoice_extraction.2026-08-19.row_000381

Vermijd het plaatsen van onbewerkte e-mails, namen, documenttitels of klantgeheimen in ID's. Sla gevoelige correlatiegegevens op in uw eigen tenantdatabase, niet in voor de provider zichtbare ID's.

Normaliseer statussen zonder providerdetails te wissen

Batch-API's van providers geven verschillende levenscycli weer.De gateway moet ze normaliseren tot een kleine interne statusmachine die dashboards, facturering en automatisering kunnen begrijpen.

Aanbevolen genormaliseerde levenscyclus:

• draft: taak bestaat maar kan nog steeds worden bewerkt.
• validating: gateway- of providervalidatie wordt uitgevoerd.
• queued: geaccepteerd maar nog niet processing.
• running: provider verwerkt items.
• finalizing: provider is klaar met berekenen en bereidt resultaatartefacten voor.
• completed: alle geaccepteerde items zijn voltooid.
• completed_with_errors: sommige items zijn geslaagd en sommige zijn mislukt.
• expired: providervenster is beëindigd voordat al het werk is voltooid.
• cancel_requested: huurder gevraagd om te annuleren, maar het definitieve factureerbare werk is nog niet verrekend.
• cancelled: annulering afgehandeld.
• failed: fout op taakniveau verhindert nuttige uitvoering.

Verzamel fouten van de native provider niet te vroeg in algemene labels. Operators hebben nog steeds toegang nodig tot systeemeigen statussen, validatiefouten, aantal verzoeken, bestands-ID's en namen van bewerkingen tijdens het debuggen.

Valideren op basis van een mogelijkhedenmatrix vóór indiening

Aanbeveling: voer preflight-validatie uit vóór budgetreservering en verzending door provider. Batchmodus is niet alleen synchrone modus met vertraging. Sommige modellen, eindpunten, verzoekfuncties, regio's en toolconfiguraties worden mogelijk niet ondersteund door de batch van een provider API.

Uw interne mogelijkhedenmatrix moet het volgende controleren:

• Ondersteund eindpunt: chat, berichten, insluitingen, moderatie of generatie.
• Modelgeschiktheid voor batch mode.
• Maximale taakgrootte, aantal items, verzoekgrootte en geüploade bestandsgrootte.
• Of streaming verboden is.
• Ondersteuning voor het gebruik van tools en het aanroepen van functies.
• Gestructureerde uitvoer of JSON schema-ondersteuning.
• Afbeelding, audio of multimodale invoer support.
• Regio- en verblijfsbeperkingen.
• Bewaarvensters voor providers en ophalen van resultaten.
• Batchspecifieke snelheidslimieten en wachtrijlimieten.
• Annuleringssemantiek.

Een goed preflight-antwoord is specific:

{
  "error": "batch_capability_not_supported",
  "message": "The selected provider batch adapter does not support streaming responses. Remove stream=true or choose a synchronous endpoint.",
  "field": "items[*].request.stream"
}

Dit is nuttiger dan de taak accepteren en mislukken nadat deze upstream is gevalideerd.

Reserveer het tenantbudget en reken vervolgens het werkelijke gebruik af

Batchuitvoering bemoeilijkt de facturering omdat de gateway mogelijk de synchrone toegang tot het exacte gebruik verliest totdat resultaatbestanden beschikbaar zijn. Het veilige patroon is citeren, reserveren, indienen, opnemen, verrekenen en afstemmen.

Geverifieerde feiten: OpenAI stelt dat batch API-prijzen met korting worden aangeboden in vergelijking met synchrone API's, en verlopen of geannuleerde batches kunnen nog steeds voltooid werk opleveren dat factureerbaar is.Anthropic merkt op dat batchverwerking met hoge doorvoer de bestedingslimiet voor de werkruimte enigszins kan overschrijden, waardoor reservering aan de gatewayzijde en post-afrekening belangrijk zijn.

Aanbeveling: reserveer het huurdersbudget voordat u het indient, met behulp van geschatte tokens, geselecteerde prijsregels van de provider en een veiligheidsmarge. Nadat de resultaten zijn verwerkt, verrekent u het werkelijke gebruik op artikelniveau. Als de schatting te hoog was, geeft u de ongebruikte reservering vrij. Als deze te laag was, past u het geconfigureerde overschrijdingsbeleid van de tenant toe.

Praktische grootboekgebeurtenissen:

batch.estimated
batch.reserved
batch.submitted
batch.item.settled
batch.item.refunded
batch.cancel_requested
batch.expired
batch.reconciled

Het grootboek op itemniveau is essentieel. Als 45.000 items zijn voltooid en 5.000 verlopen, moet de tenant worden gefactureerd voor het voltooide werk van de provider, en niet voor het oorspronkelijke manifest als een enkele ongedifferentieerde blob.

Bouw provideradapters als vertalers, niet als eigenaren van bedrijfslogica

Elke provideradapter moet weten hoe hij de gatewaytaak moet omzetten in de batchindeling van de provider, deze moet indienen, de status kan opvragen of ophalen, resultaten kan downloaden en de oorspronkelijke resultaten weer in kaart kan brengen genormaliseerde records.

Houd het tenantbeleid buiten de adapter. De adapter mag niet beslissen of een klant voldoende budget heeft, of een partnerklant is opgeschort of dat prompts kunnen worden opgeslagen. Dit zijn gateway-beslissingen.

Adapterverantwoordelijkheden

• Genereer providerspecifieke verzoekmanifesten.
• Upload invoerbestanden of maak providerbewerkingen.
• Sla provider-ID's op in metadata.
• Wijs de oorspronkelijke status toe aan de genormaliseerde status.
• Uitvoer en fouten ophalen artefacten.
• Resultaten op itemniveau parseren.
• Retourneer systeemeigen gebruiksrecords indien beschikbaar.
• Oppervlak opnieuw te proberen versus terminalfouten.

Gatewayverantwoordelijkheden

• Tenant verifiëren en API key.
• Pas team-, project- en klantcontroles toe.
• Los modelaliassen en providerroutingbeleid op.
• Batchmogelijkheden valideren.
• Reserveren en budget afrekenen.
• Taak- en itemstatus behouden.
• Retentie afdwingen policy.
• Blootstelling van analyses en exporten.

Deze scheiding maakt het gemakkelijker om een nieuwe provider toe te voegen zonder de facturering, analyses of tenantbeheer te herschrijven.

Resultaten op idempotente wijze verwerken

Bij de opname van resultaten kunnen veel batchsystemen per ongeluk kosten dupliceren of gedeeltelijk werk verliezen. Behandel inname als een herhaalbaar proces. Het zou veilig moeten zijn om hetzelfde uitvoerbestand twee keer te downloaden, dezelfde providerbewerking twee keer te verwerken of dezelfde webhook-gebeurtenis twee keer af te spelen.

Aanbeveling: gebruik idempotentiesleutels op itemniveau en beperkingen voor de uniciteit van het grootboek.Een resultaat voor job_id + custom_id moet precies één keer worden afgehandeld, zelfs als de opname opnieuw wordt geprobeerd.

Een robuuste opnamestroom:

1. Verkrijg een kortstondige vergrendeling voor de taak of het resultaatartefact.
2. Haal uitvoer- en foutartefacten van de provider op.
3. Parse records in genormaliseerde itemresultaatgebeurtenissen.
4. Overeenkomen met elk record op custom_id of gateway-item-ID.
5. Schrijf resultaatmetagegevens en gebruik in een transactie.
6. Maak alleen een grootboekvereffeningsgebeurtenis als er nog geen bestaat.
7. Werk het aantal taken bij op basis van itemstatussen, niet op basis van aannames.
8. Laat ongebruikte budgetreservering vrij wanneer alle eindstatussen zijn bekend.

Als webhooks beschikbaar zijn, verifieer dan de handtekeningen en bescherm ze tegen herhaling. Als polling vereist is, gebruik dan adaptieve polling: poll regelmatig rond de verwachte voltooiing, ga terug tijdens lange perioden en stop na de eindafrekening.

Probeer items opnieuw, niet hele taken

Aanbeveling: probeer het indien mogelijk opnieuw op itemniveau. Het opnieuw proberen van een hele taak is eenvoudig, maar verhoogt het risico op dubbel werk en maakt facturering moeilijker.

Classificeer fouten voordat u opnieuw probeert:

• Validatiefouten: eindigen meestal totdat het verzoek is opgelost.
• Provider 5xx-fouten: vaak opnieuw te proberen met backoff.
• Fouten in quota of snelheidslimieten: probeer het alleen opnieuw nadat er capaciteit beschikbaar is.
• Veiligheidsblokkeringen: probeer het niet blindelings opnieuw; route to policy handling.
• Verlopen items: kunnen opnieuw worden geprobeerd in een nieuwe taak als de huurder nog steeds het werk wil en het budget dit toelaat.

Een nieuwe poging zou een nieuw item moeten creëren dat is gekoppeld aan het origineel:

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

Dien voltooide items niet opnieuw in alleen maar omdat ze deel uitmaakten van een taak die eindigde als completed_with_errors of expired.

Bepaal wat u wilt opslaan: onbewerkte resultaten, verwijzingen of hashes

Batchsystemen zijn verleidelijke plaatsen om aanwijzingen en uitvoer te verzamelen. Dat kan handig zijn voor exports en foutopsporing, maar het vergroot de verantwoordelijkheid voor het bewaren van gegevens.

Aanbeveling: maak het opslagbeleid tenant-configureerbaar. Voor gevoelige werkbelastingen kunt u metagegevens, hashes, gebruiks- en resultaataanwijzers opslaan in plaats van onbewerkte aanwijzingen en uitvoer.Voor minder gevoelige werkbelastingen kan genormaliseerde opslag van resultaten acceptabel zijn als bewaarperioden, toegangscontroles en verwijderingsworkflows duidelijk zijn.

Volg ten minste het volgende:

• Of onbewerkte invoer is opgeslagen.
• Of onbewerkte uitvoer is opgeslagen.
• Waar artefacten van de providerresultaten voorkomen.
• Ophalen van de provider deadline.
• Deadline voor verwijdering van de gateway.
• Hash van verzoek en antwoord voor audit zonder blootstelling van de inhoud.

Geverifieerd feit: Anthropic stelt dat batchresultaten 29 dagen na creatie beschikbaar zijn en worden geïsoleerd binnen de werkruimte. Dit soort providerspecifieke ophaalperiode moet worden weerspiegeld in de metagegevens van de gateway en de tenantgerichte exports.

Blootstelling van analyses die overeenkomen met de manier waarop teams werken

Batchanalyses moeten bestaan ​​op zowel taak- als itemniveau. Een producteigenaar wil weten of een nachtelijke verrijking is voltooid. Een financiële beheerder wil de kosten per tenant, model en klant. Een technicus wil weten welke foutklasse hij opnieuw moet proberen.

Handige statistieken zijn onder meer:

• Aantallen verzonden, voltooide, mislukte, verlopen en geannuleerde artikelen.
• Geschatte versus verrekende kosten.
• Gereserveerd budget nog steeds vastgehouden.
• Invoer- en uitvoertokens per provider en model.
• Indicatoren voor cachehits waar providers deze weergeven.
• Aantal nieuwe pogingen en slagingspercentage van nieuwe pogingen.
• Gemiddelde tijd in wachtrij, actieve status en voltooiingsstatus.
• Meest voorkomende validatiefouten per eindpunt en model.
• Partnerklant attribution.

Voor Partner API-gebruikers: stel batchtaken beschikbaar als klantgerichte bronnen. Hierdoor kunnen bureaus en SaaS-bouwers offline AI-verwerking aanbieden terwijl de inloggegevens van de upstream-provider, afstemming van facturering en afhandeling van tarieflimieten binnen de gateway behouden blijven.

Afwegingen om expliciet

Gateway-abstractie versus provider-specifieke mogelijkheden te maken: een uniform contract vereenvoudigt de integratie, maar kan niet elke providerfunctie identiek maken. Houd capaciteitsfouten expliciet.

Budgetreservering versus nauwkeurigheid van schatting: Reservering beschermt huurders tegen op hol geslagen banen, maar schattingen kunnen verkeerd zijn. Het grootboek moet aanpassingen, terugbetalingen en afhandeling van overschrijdingen ondersteunen.

Polling versus webhooks: polling is eenvoudig en betrouwbaar, maar kan API oproepen verspillen en de voltooiing vertragen. Webhooks zijn sneller, maar vereisen handtekeningverificatie, bescherming tegen opnieuw afspelen en monitoring.

Opslag van onbewerkte resultaten versus minimalisering van retentie: het opslaan van genormaliseerde resultaten verbetert de export en analyse, maar vergroot de nalevingslast.Gevoelige tenants geven misschien de voorkeur aan pointers en hashes.

Grote batches versus opgedeelde batches: grote batches kunnen de efficiëntie aan de providerzijde verbeteren, maar kleinere chunks verkleinen de ontploffingsradius en maken nieuwe pogingen gemakkelijker.

Implementatiechecklist

• Maak een aparte batchtaak API oppervlak.
• Persist taak en item records voordat de provider deze indient.
• Vereist gateway-taak-ID's en aangepaste ID's per item.
• Normaliseer de status terwijl de native metagegevens van de provider worden opgeslagen.
• Stel een mogelijkhedenmatrix op voor elke batchadapter van de provider.
• Valideer manifesten voordat u budget reserveert.
• Reserveer huurdersbudget voordat dispatch.
• Regel het werkelijke gebruik op itemniveau na opname.
• Maak de opname van resultaten idempotent.
• Probeer mislukte items selectief opnieuw, niet blindelings hele taken.
• Houd de ophaaldeadlines van de provider en het bewaarbeleid van de gateway bij.
• Bloot taak- en itemanalyses aan huurders en partners klanten.

Voorspellingen: waar dit patroon naartoe gaat

Voorspelling: batchuitvoering wordt een normaal onderdeel van de AI-automatiseringsinfrastructuur, en niet slechts een kortingsmechanisme. Naarmate teams meer evaluaties, taken voor het opschonen van gegevens, veiligheidsbeoordelingen en verrijkingspijplijnen uitvoeren, verwachten ze dat asynchrone productietaken hetzelfde beheer zullen hebben als synchrone API aanroepen.

Voorspelling: batch-API's van providers zullen op nuttige manieren blijven uiteenlopen. Sommige optimaliseren voor bestanden, andere voor langlopende bewerkingen en weer andere voor beheerde datasets of callbacks van gebeurtenissen. Een gateway-adapterlaag zal waardevoller worden, niet minder, omdat het operationele contract boven de adapters stabiel kan blijven.

Bruikbare conclusie

Breng batchverwerking niet vast aan een AI API-gateway als een providerspecifiek ontsnappingsluik. Bouw het als een duurzaam subsysteem met eigen taakrecords, item-ID's, statusmodel, provideradapters, budgetreservering, idempotente opname en analyses.

De belangrijkste ontwerpkeuze is boekhouding op itemniveau. Zodra elk verzoek binnen een batch een stabiele identiteit heeft, kan de gateway ongeordende resultaten afstemmen, alleen mislukt werk opnieuw proberen, alleen voltooid providerwerk in rekening brengen en huurders laten zien wat er is gebeurd. Dat is het verschil tussen het verzenden van bestanden naar een provider en het gebruiken van een betrouwbaar multi-model API voor asynchrone productietaken.

Gerelateerd lezen

• AI gebruiken, reserveren, afrekenen en afstemmen. API Factureringspatroon
• Gebruiksanalyse op gatewayniveau en tokengrootboek ontwerp
• wanneer latentietolerante productietaken geschikt zijn voor batchverwerking