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

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

Het implementatiepatroon is om van batchuitvoering een eersteklas gateway-subsysteem te maken. De gateway moet één provider-neutraal arbeidscontract 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

Latentie-tolerante workloads 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 tussen 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 verwerkingsvenster van 24 uur. OpenAI geeft statussen weer zoals valideren, mislukt, in_progress, finaliseren, voltooid, verlopen, annuleren en geannuleerd. De Message Batches API van Anthropic verwerkt veel berichtenverzoeken asynchroon, handelt elk verzoek afzonderlijk af, vereist polling en retourneert resultaten nadat de verwerking is beëindigd. Anthropic raadt ook betekenisvolle custom_id-waarden aan, omdat de resultaatvolgorde niet gegarandeerd is. De Batch API van Gemini maakt gebruik van 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 huurder, klant, project of API-sleutel is eigenaar van elk item?
• Is er budget gereserveerd voordat de taak de gateway verliet?
• Welke voltooide items zijn factureerbaar als de batch verloopt of is verlopen? 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 inloggegevens van de upstream-provider vrij te geven?

Het antwoord is niet om elk providerverschil te verbergen. Het antwoord is om het operationele contract te normaliseren en tegelijkertijd de metagegevens van de provider te behouden voor foutopsporing, afstemming en ondersteuning.

Aanbevolen openbare 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 ID's.
• verzenden: valideer, reserveer budget, selecteer provider, verzend en vergrendel het ingediende manifest.
• get_status: retourneer genormaliseerde taak- en itemaantallen.
• list_results: blader door genormaliseerde itemresultaten, fouten en gebruik.
• annuleren: verzoek tot annulering, zonder onmiddellijke belofte beëindiging.
• export_usage: exporteer kostenrecords op taak- en artikelniveau voor analyse- of factureringssystemen.

Voorbeeld van een openbaar taakobject:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "klant_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "analyse-groot",
  "status": "actief",
  "telt": {
    "ingediend": 50000,
    "voltooid": 31240,
    "mislukt": 180,
    "verlopen": 0
  },
  "kosten": {
    "geschat": "184,20",
    "gereserveerd": "205,00",
    "afgewikkeld": "117.43",
    "valuta": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "subised_at": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"

Het publieke object mag standaard geen bestands-ID's van de provider, namen van bewerkingen of onbewerkte upstream-fouten openbaar maken. Deze horen thuis in de met de operator gerichte metadata.

Gebruik duurzame taakrecords als de bron van de waarheid

Een batchlaag die eigendom is van een gateway heeft een duurzame status nodig voordat er upstream iets kan worden 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
- huurder_id
- project_id
- klant_id nulleerbaar- api_key_id
- eindpunt
- aangevraagd_model
- opgeloste_provider
- opgelost_provider_model
- status
- item_count
- geschatte_invoer_tokens
- geschatte_output_tokens
- gereserveerd_bedrag
- vereffend_bedrag
- aangemaakt_at
- ingediend_at
- voltooid_at
- verloopt_at
- ophaaltermijn
- annulering_aangevraagd_at

2. Batchartikel

batch_items
- job_id
- item_id
- aangepaste_id
- idempotentie_sleutel
- verzoek_hash
- status
- provider_request_index nulbaar
- geschatte_tokens
- actual_input_tokens nulbaar
- actual_output_tokens nullable
- afgewikkeld_bedrag nulbaar
- resultaat_pointer nulbaar
- foutcode nulbaar
- retry_of_item_id nullable
- aangemaakt_at
- afgewikkeld_at

3. Metagegevens van de provider

batch_provider_metadata
- job_id
- aanbieder
- provider_batch_id nulleerbaar
- input_file_id nulleerbaar
- output_file_id nulbaar
- error_file_id nulbaar
- bewerkingsnaam nulbaar
- eindpunt
- regio nulleerbaar
- inheemse_status
- native_request_counts jsonb
- laatst_opgevraagd_at
- raw_error_pointer nullable

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

Vraag stabiele item-ID's vóór verzending

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

Anthropic waarschuwt expliciet dat de volgorde van de resultaten niet gegarandeerd is en beveelt betekenisvolle 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. Bewaar gevoelige correlatiegegevens in uw eigen tenantdatabase, niet in voor de provider zichtbare ID's.

Normaliseer statussen zonder de details van de provider te wissen

Batch-API's van de provider leggen verschillende levenscycli bloot. De gateway zou ze moeten 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.
• in wachtrij geplaatst: geaccepteerd maar nog niet processing.
• running: provider is items aan het verwerken.
• finalizing: provider is klaar met berekenen en bereidt resultaatartefacten voor.
• completed: alle geaccepteerde items hebben een eindsucces bereikt.
• completed_with_errors: sommige items zijn geslaagd en sommige zijn mislukt.
• expired: providervenster is beëindigd voordat al het werk is uitgevoerd. voltooid.
• cancel_requested: huurder gevraagd om te annuleren, maar het definitieve factureerbare werk is nog niet verrekend.
• cancelled: annulering afgehandeld.
• mislukt: een fout op taakniveau verhindert een nuttige uitvoering.

Verpak native providerfouten niet te vroeg in generieke labels. Operators hebben nog steeds toegang nodig tot systeemeigen statussen, validatiefouten, aantal aanvragen, bestands-ID's en namen van bewerkingen tijdens het debuggen.

Valideren op basis van een mogelijkhedenmatrix voordat ze worden ingediend

Aanbeveling: voer preflight-validatie uit voordat het budget wordt gereserveerd en de provider wordt verzonden. Batchmodus is niet alleen synchrone modus met vertraging. Sommige modellen, eindpunten, verzoekfuncties, regio's en toolconfiguraties worden mogelijk niet ondersteund door de batch-API van een provider.

Uw interne mogelijkhedenmatrix moet het volgende controleren:

• Ondersteund eindpunt: chat, berichten, insluitingen, moderatie of generatie.
• Model geschikt voor batchmodus.
• Maximale taakgrootte, aantal items, verzoekgrootte en geüploade bestandsgrootte.
• Of streaming nu plaatsvindt verboden.
• Ondersteuning voor het gebruik van tools en het aanroepen van functies.
• Gestructureerde uitvoer of ondersteuning voor JSON-schema's.
• Ondersteuning voor afbeeldingen, audio of multimodale invoer.
• Regio- en verblijfsbeperkingen.
• Bewaarvensters voor providers en ophalen van resultaten.
• Batchspecifieke snelheidslimieten en wachtrijlimieten.
• Semantiek van annulering.

Een goede preflight-antwoord is specifiek:

{
  "error": "batch_capability_not_supported",
  "message": "De geselecteerde batchadapter van de provider ondersteunt geen streamingreacties. Verwijder stream=true of kies een synchroon eindpunt.",
  "field": "items[*].request.stream"}

Dit is nuttiger dan het accepteren van de taak en het mislukken ervan na een stroomopwaartse validatie.

Reserveer het tenantbudget en verreken vervolgens het daadwerkelijke gebruik

Batchuitvoering bemoeilijkt de facturering omdat de gateway mogelijk de synchrone toegang tot het exacte gebruik verliest totdat de resultaatbestanden beschikbaar zijn. Het veilige patroon is citeren, reserveren, indienen, opnemen, afrekenen 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 retourneren dat factureerbaar is. Anthropic merkt op dat batchverwerking met hoge doorvoer de bestedingslimiet voor een 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 providerprijsregels 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, pas dan het geconfigureerde overschrijdingsbeleid van de tenant toe.

Praktische grootboekgebeurtenissen:

batch. estimate
batch.gereserveerd
batch.verzonden
batch.item.afgewikkeld
batch.item.terugbetaald
batch.cancel_requested
batch.verlopenbatch.reconciled

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

Bouw provideradapters als vertalers, niet als eigenaars van bedrijfslogica

Elke provideradapter moet weten hoe hij de gatewaytaak moet omzetten in de batchindeling van de provider, hoe hij deze moet indienen, de status kan opvragen of ophalen, resultaten kan downloaden en de oorspronkelijke uitkomsten weer kan normaliseren 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.

Verantwoordelijkheden van de adapter

• Geef providerspecifieke verzoekmanifesten weer.
• Upload invoerbestanden of maak providerbewerkingen.
• Sla provider-ID's op in metadata.
• Wijs native status toe aan genormaliseerde status.
• Haal uitvoer- en foutartefacten op.
• Resultaten op itemniveau parseren.
• Retourneer native gebruiksrecords wanneer beschikbaar.
• Herhaalbare versus terminalfouten.

Gatewayverantwoordelijkheden

• Authenticeer tenant en API-sleutel.
• Pas team-, project- en klantcontroles toe.
• Los modelaliassen en providerroutingbeleid op.
• Valideer batchmogelijkheden.
• Reserveer en verreken budget.
• Ga door met taak en item state.
• Retentiebeleid afdwingen.
• Analytics en exporten blootleggen.

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

Idempotent resultaten opnemen

Bij veel batchsystemen worden de kosten per ongeluk gedupliceerd of gaat gedeeltelijk werk verloren bij de opname van resultaten. 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 opnieuw 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. Parseer records in genormaliseerde itemresultaatgebeurtenissen.
4. Maak elke record op elkaar afgestemd door custom_id of gateway-item-ID.
5. Schrijf resultaatmetagegevens en gebruik in een transactie.
6. Maak alleen een grootboekafrekeningsgebeurtenis als deze nog niet bestaat.
7. Update de taakaantallen op basis van itemstatussen, niet op basis van aannames.
8. Laat ongebruikte budgetreservering vrij wanneer alle terminalstatussen bekend zijn.

Als webhooks beschikbaar zijn, verifieer dan de handtekeningen en bescherm ze tegen herhaling. Als polling vereist is, maak dan gebruik van adaptieve polling: poll regelmatig in de buurt van de verwachte voltooiing, stop tijdens langdurige perioden en stop na de definitieve afwikkeling.

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 de facturering moeilijker.

Classificeer fouten voordat u het opnieuw probeert:

• Validatiefouten: duren meestal totdat het verzoek is opgelost.
• Provider 5xx-fouten: vaak opnieuw te proberen met uitstel.
• Mislukken van quota of tarieflimieten: probeer het alleen opnieuw nadat de capaciteit is bereikt. beschikbaar.
• Veiligheidsblokkeringen: probeer het niet blindelings opnieuw; route naar beleidsafhandeling.
• 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 expirors.

Beslis wat u wilt opslaan: onbewerkte resultaten, pointers of hashes

Batchsystemen zijn verleidelijke plekken om prompts en outputs te verzamelen. Dat kan handig zijn voor export 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 de retentieperiodes, toegangscontroles en verwijderingsworkflows duidelijk zijn.

Houd op zijn minst bij:

• Of onbewerkte invoer is opgeslagen.
• Of onbewerkte uitvoer is opgeslagen.
• Waar artefacten van de resultaten van de provider leven.
• Deadline voor het ophalen van de provider.
• Deadline voor verwijdering van de gateway.
• Hash van verzoek en antwoord voor audit zonder blootstelling aan inhoud.

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

Blootstelling van analyses die overeenkomen met de manier waarop teams werken

Batchanalyses moeten bestaan ​​op zowel functie- 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 ingenieur wil weten welke foutklasse hij opnieuw moet proberen.

Nuttige statistieken zijn onder meer:

• Aantallen verzonden, voltooide, mislukte, verlopen en geannuleerde items.
• Geschatte versus verrekende kosten.
• Gereserveerd budget nog steeds vastgehouden.
• Invoer- en uitvoertokens per provider en model.
• Cache-hit-indicatoren waar providers deze weergeven.
• Aantal nieuwe pogingen en succes opnieuw proberen. snelheid.
• Gemiddelde tijd in de status van wachtrij, uitvoering en voltooiing.
• Topvalidatiefouten per eindpunt en model.
• Attributie van partnerklant.

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

Afwegingen om expliciet te maken

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

Budgetreservering versus nauwkeurigheid van schattingen: reservering beschermt huurders tegen weggelopen 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-aanroepen 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 verhoogt de nalevingslast. Gevoelige tenants geven misschien de voorkeur aan pointers en hashes.

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

Implementatiechecklist

• Maak een apart API-oppervlak voor batchtaken.
• Bewaar taak- en itemrecords voordat de provider indient.
• Vereist gateway-taak-ID's en per item aangepaste ID's.
• Normaliseer statussen terwijl native metadata van de provider wordt opgeslagen.
• Bouw een mogelijkhedenmatrix voor elke batchadapter van de provider.
• Valideer manifesten voordat u budget reserveert.
• Reserveer tenantbudget vóór verzending.
• Regel feitelijk gebruik op itemniveau na opname.
• Maak resultaatopname idempotent.
• Probeer mislukte items selectief opnieuw, niet hele taken. blindelings.
• Volg de deadlines voor het ophalen van providers en het retentiebeleid van de gateway.
• Maak taak- en itemanalyses openbaar aan huurders en partnerklanten.

Voorspellingen: waar dit patroon naartoe gaat

Voorspelling: batchuitvoering zal een normaal onderdeel worden van de AI-automatiseringsinfrastructuur, en niet alleen maar een kortingsmechanisme. Naarmate teams meer evaluaties, taken voor het opschonen van gegevens, veiligheidsbeoordelingen en verrijkingspijplijnen uitvoeren, zullen ze verwachten dat asynchrone werklasten 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

Vergrendel batchverwerking niet op 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 werk van de provider factureren 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 betrouwbare multi-model API voor asynchrone workloads.

Gerelateerd lezen

• AI API-factureringspatroon citeren, reserveren, verrekenen en afstemmen
• gebruiksanalyses op gateway-niveau en token ledger-ontwerp
• wanneer latentietolerante productietaken passen bij batchverwerking