Objedinjeni skupni poslovi putem pristupnika AI API-ja: izdržljivi redovi čekanja, adapteri pružatelja usluga i naplata na razini stanara

Skupnu obradu ne treba tretirati kao sporedna vrata oko vašeg AI API pristupnika. Ako procjene, obogaćivanje dokumenata, izdvajanje, moderiranje ili poslovi ugrađivanja napuste stazu sinkronog zahtjeva, i dalje trebaju kontrole stanara, dodjelu troškova, ponovne pokušaje, reviziju i analitiku upotrebe.

Implementacijski obrazac je napraviti paketno izvršavanje prvoklasnim pristupnim podsustavom. Gateway bi trebao otkriti jedan ugovor o poslu koji je neutralan prema pružatelju dok se iza scene prilagođava OpenAI, Anthropic, Gemini i paketnim API-jima budućih pružatelja usluga.

Problem s čitateljem: skupni API-ji slični su u namjeri, različiti u radu

Radna opterećenja tolerantna na kašnjenje prirodno odgovaraju skupnom izvršavanju. Teži dio nije odlučiti može li posao čekati. Težak dio je dosljedno upravljanje paketnim radom svih pružatelja usluga.

Provjerene činjenice: OpenAI-jev Batch API je asinkroni, čita zahtjeve iz učitane datoteke, piše odgovore u izlaznu datoteku i trenutno koristi 24-satni prozor obrade. OpenAI navodi statuse kao što su provjera, neuspješno, u_tijeku, finaliziranje, dovršeno, isteklo, otkazivanje i otkazano. Anthropicov Message Batches API obrađuje mnoge zahtjeve za poruke asinkrono, obrađuje svaki zahtjev neovisno, zahtijeva anketiranje i vraća rezultate nakon završetka obrade. Anthropic također preporučuje smislene vrijednosti custom_id jer redoslijed rezultata nije zajamčen. Gemini Batch API otkriva dugotrajne metode stila operacija kao što su metode popisa, otkazivanja, brisanja i ažuriranja, a njegova operacija otkazivanja opisana je kao najbolja.

Te su razlike bitne kada dodate stvarne poslovne zahtjeve:

• Koji zakupac, korisnik, projekt ili ključ API-ja posjeduje svaku stavku?
• Je li proračun bio rezerviran prije nego što je posao napustio gateway?
• Koji? dovršene stavke se naplaćuju ako paket istekne ili se poništi?
• Kako se ponovno pokušavaju djelomični neuspjesi bez dupliciranja uspješnog rada?
• Koliko dugo se mogu dohvatiti datoteke s rezultatima i što bi pristupnik trebao pohraniti?
• Može li partner izgraditi skupnu obradu u opsegu korisnika bez izlaganja vjerodajnica uzlaznog pružatelja?

Odgovor nije sakriti svakog pružatelja razlika. Odgovor je normalizirati radni ugovor uz očuvanje izvornih metapodataka dobavljača za otklanjanje pogrešaka, usklađivanje i podršku.

Preporučeni javni API: odvojite skupne poslove od sinkronih dovršetaka

Preporuka: izložite skupne poslove kao vlastitu API površinu, a ne kao posebnu oznaku na dovršecima chata. Sinkroni zahtjev i asinkroni skupni posao imaju različitu semantiku životnog ciklusa, naplate, ponovnog pokušaja i dohvaćanja rezultata.

Praktični pristupni ugovor uključuje ove operacije:

• create_job: kreirajte nacrt posla u vlasništvu zakupca, projekta, ključa ili partnera.
• append_items ili upload_manifest: dodajte pojedinačne zahtjeve sa stabilnim identifikatorima stavki.
• submit: potvrdite, rezervirajte proračun, odaberite davatelja, otpremite i zaključajte poslani manifest.
• get_status: vratite normalizirani broj poslova i stavki.
• list_results: pregledajte normalizirane rezultate stavki, pogreške i korištenje.
• cancel: zatražite otkazivanje, bez obećanja trenutnog raskida.
• export_usage: izvezite zapise o troškovima na razini poslova i stavki za analitiku ili sustave naplate.

Primjer javnog objekta posla:

{
  "job_id": "job_01j7...",
  "tenant_id": "stanar_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "analiza-velika",
  "status": "u tijeku",
  "broji": {
    "podneseno": 50000,
    "dovršeno": 31240,
    "nije uspjelo": 180,
    "isteklo": 0
  },
  "cijena": {
    "procijenjeno": "184,20",
    "rezervirano": "205,00",
    "podmireno": "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"
}

Javni objekt prema zadanim postavkama ne bi trebao otkrivati ID-ove datoteka pružatelja usluga, nazive operacija ili neobrađene uzvodne pogreške. Oni pripadaju metapodacima okrenutim operateru.

Koristite trajne zapise o poslovima kao izvor istine

Sloj serije u vlasništvu pristupnika treba trajno stanje prije nego što se bilo što pošalje uzvodno. Nemojte se oslanjati na serijske zapise pružatelja usluga kao svoju jedinu državnu pohranu. Evidencija pružatelja usluga je neophodna, ali oni ne znaju vašu hijerarhiju stanara, proračunske rezervacije, pseudonime internih modela, klijente partnera ili analitičke zahtjeve.

Minimalni model baze podataka

Korisna shema ima tri razine:

1. Skupni posao

batch_jobs
- ID_posla
- tenant_id
- ID_projekta
- customer_id null- api_key_id
- krajnja točka
- traženi_model
- riješen_provider
- model_razriješenog_provajdera
- status
- broj_stvari
- procijenjeni_ulazni_tokeni
- procijenjeni_izlazni_tokeni
- rezervirani_iznos
- podmireni_iznos
- stvoreno_na
- podnesen_at
- dovršeno_at
- istječe_u
- rok_preuzimanja
- cancellation_requested_at

2. Skupna stavka

batch_items
- ID_posla
- item_id
- prilagođeni_id
- idempotencija_ključ
- zahtjev_hash
- status
- provider_request_index nullable
- procijenjeni_tokeni
- stvarni_ulazni_tokeni nullable
- stvarni_izlazni_tokeni nullable
- podmireni_iznos nullable
- rezultat_pokazivač nullable
- error_code nullable
- retry_of_item_id nullable
- stvoreno_na
- naseljeno_u

3. Metapodaci pružatelja usluga

batch_provider_metadata
- ID_posla
- pružatelj usluga
- provider_batch_id nullable
- input_file_id null
- output_file_id nullable
- error_file_id nullable
- naziv_operacije nullable
- krajnja točka
- regija nullable
- izvorni_status
- native_request_counts jsonb
- zadnji_anket_at
- raw_error_pointer nullable

Održavanje metapodataka pružatelja odvojenih od ugovora o javnom poslu omogućuje pristupniku da razvije adaptere pružatelja usluga bez kvara API-ja okrenutih stanarima.

Zahtijevaj stabilne identifikatore stavki prije slanja

Preporuka: generiraj pristupnik job_id i zahtijevaj po artiklu custom_id ili ključ idempotencije prije otpreme. Nikada ne usklađujte rezultate prema redoslijedu.

Anthropic izričito upozorava da redoslijed rezultata nije zajamčen i preporučuje smislene vrijednosti custom_id. Čak i kada se čini da pružatelj održava red, pristupnik ne bi trebao ovisiti o njemu. Poslovi se dijele, ponovno pokušavaju, otkazuju, djelomično dovršavaju i ponovno unose. Pretpostavke naručivanja na kraju ne uspiju.

Siguran format identifikatora artikla je opisni, ali nije osjetljiv:

tenantA.invoice_extraction.2026-08-19.row_000381

Izbjegavajte stavljanje neobrađenih e-poruka, imena, naslova dokumenata ili tajni korisnika u identifikatore. Pohranite osjetljive podatke o korelaciji unutar vlastite baze podataka stanara, a ne unutar ID-ova vidljivih pružatelju.

Normalizirajte statuse bez brisanja detalja pružatelja

Skupni API-ji pružatelja otkrivaju različite životne cikluse. Pristupnik bi ih trebao normalizirati u mali interni stroj stanja koji nadzorne ploče, naplata i automatizacija mogu razumjeti.

Preporučeni normalizirani životni ciklus:

• skica: posao postoji, ali se još uvijek može uređivati.
• provjera valjanosti: provjera valjanosti pristupnika ili davatelja je u tijeku.
• na čekanju: prihvaćeno, ali još nije obrada.
• running: pružatelj obrađuje stavke.
• finalizing: pružatelj je završio izračunavanje i priprema artefakte rezultata.
• completed: sve prihvaćene stavke dosegnule su terminalni uspjeh.
• completed_with_errors: neke su stavke uspjele, a neke nije uspio.
• istekao: prozor pružatelja završio je prije nego što je sav posao dovršen.
• cancel_requested: stanar je zamoljen da otkaže, ali konačni naplativi posao nije podmiren.
• cancelled: otkazivanje riješeno.
• failed: kvar na razini posla spriječen korisno korisno izvršenje.

Ne sažimajte izvorne pogreške pružatelja u generičke oznake prerano. Operatori i dalje trebaju pristup izvornim statusima, pogreškama provjere, broju zahtjeva, ID-ovima datoteka i nazivima operacija prilikom otklanjanja pogrešaka.

Provjerite valjanost u odnosu na matricu mogućnosti prije podnošenja

Preporuka: pokrenite provjeru prije leta prije rezervacije proračuna i slanja pružatelja usluga. Skupni način rada nije samo sinkroni način rada s odgodom. Neki modeli, krajnje točke, značajke zahtjeva, regije i konfiguracije alata možda nisu podržani od strane paketnog API-ja pružatelja usluga.

Vaša interna matrica mogućnosti trebala bi provjeriti:

• Podržana krajnja točka: chat, poruke, ugradnje, moderiranje ili generiranje.
• Podobnost modela za skupni način rada.
• Maksimalna veličina posla, broj stavki, veličina zahtjeva, i veličina učitane datoteke.
• Je li strujanje zabranjeno.
• Upotreba alata i podrška za pozivanje funkcija.
• Podrška za strukturirani izlaz ili JSON shemu.
• Podrška za slikovni, audio ili multimodalni unos.
• Ograničenja regije i prebivališta.
• Zadržavanje pružatelja i dohvaćanje rezultata prozora.
• Ograničenja brzine i čekanja specifična za paket.
• Semantika otkazivanja.

Dobar odgovor prije provjere je specifičan:

{
  "greška": "batch_capability_not_supported",
  "message": "Odabrani paketni adapter pružatelja usluga ne podržava strujanje odgovora. Uklonite stream=true ili odaberite sinkronu krajnju točku.",
  "polje": "stavke[*].request.stream"}

Ovo je korisnije od prihvaćanja posla i neuspjeha nakon prolaska uzvodne provjere.

Rezervirajte proračun zakupca, a zatim podmirite stvarnu upotrebu

Skupno izvršenje komplicira naplatu jer pristupnik može izgubiti sinkroni pristup točnoj upotrebi dok datoteke rezultata ne budu dostupne. Siguran uzorak je ponuda, rezervacija, podnošenje, unos, podmirenje i usklađivanje.

Provjerene činjenice: OpenAI navodi da se cijena Batch API-ja nudi s popustom u usporedbi sa sinkronim API-jima, a istekle ili otkazane serije još uvijek mogu vraćati dovršen posao koji se naplaćuje. Anthropic napominje da skupna obrada velike propusnosti može neznatno premašiti ograničenje potrošnje radnog prostora, zbog čega su rezervacija na strani pristupnika i naknadna nagodba važni.

Preporuka: rezervirajte proračun zakupca prije podnošenja koristeći procijenjene tokene, pravila cijena odabranih pružatelja usluga i sigurnosnu maržu. Nakon unosa rezultata, poravnajte stvarnu upotrebu na razini stavke. Ako je procjena bila previsoka, otpustite neiskorištenu rezervaciju. Ako je bio prenizak, primijenite konfiguriranu politiku prekoračenja stanara.

Praktični događaji u glavnoj knjizi:

batch.estimated
serija.rezervirano
serija.podneseno
serija.predmet.staložen
batch.item.refunded
batch.cancel_requested
serija.istekaobatch.reconciled

Glavna knjiga na razini stavke je neophodna. If 45,000 items complete and 5,000 expire, the tenant should be billed for completed provider work, not for the original manifest as a single undifferentiated blob.

Build provider adapters as translators, not business logic owners

Each provider adapter should know how to transform the gateway job into the provider’s batch format, submit it, poll or retrieve status, preuzmite rezultate i preslikajte izvorne ishode natrag u normalizirane zapise.

Držite politiku stanara izvan adaptera. Adapter ne bi trebao odlučiti ima li kupac dovoljan proračun, je li partnerski korisnik suspendiran ili mogu li se pohraniti upute. Those are gateway decisions.

Adapter responsibilities

• Render provider-specific request manifests.
• Upload input files or create provider operations.
• Store provider identifiers in metadata.
• Map native status to normalized status.
• Retrieve output and error artifacts.
• Parse item-level results.
• Return native usage records when available.
• Surface retryable versus terminal errors.

Gateway responsibilities

• Authenticate tenant and API key.
• Apply team, project, and customer controls.
• Resolve model aliases and provider routing policy.
• Validate batch capabilities.
• Reserve and settle budget.
• Persist job and item state.
• Enforce retention policy.
• Expose analytics and exports.

This separation makes it easier to add a new provider without rewriting billing, analytics, or tenant governance.

Ingest results idempotently

Result ingestion is where many batch systems accidentally duplicate charges or lose partial work. Tretirajte gutanje kao proces koji se ponavlja. It should be safe to download the same output file twice, process the same provider operation twice, or replay the same webhook event twice.

Recommendation: use item-level idempotency keys and ledger uniqueness constraints. A result for job_id + custom_id should settle exactly once, even if ingestion is retried.

A robust ingestion flow:

1. Acquire a short-lived lock for the job or result artifact.
2. Fetch provider output and error artifacts.
3. Parse records into normalized item result events.
4. Match each record by custom_id or gateway item ID.
5. Write result metadata and usage in a transaction.
6. Create ledger settlement event only if one does not already exist.
7. Update job counts from item states, not from assumptions.
8. Release unused budget reservation when all terminal states are known.

If webhookovi su dostupni, provjeravaju potpise i štite od ponavljanja. If polling is required, use adaptive polling: poll frequently near expected completion, back off during long-running periods, and stop after terminal settlement.

Retry items, not whole jobs

Recommendation: retry at item level whenever possible. Whole-job retries are simple, but they increase duplicate-work risk and make billing harder.

Classify failures before retrying:

• Validation errors: usually terminal until the request is fixed.
• Provider 5xx errors: often retryable with backoff.
• Quota or rate-limit neuspjesi: pokušajte ponovo tek nakon što je kapacitet dostupan.
• Sigurnosni blokovi: ne pokušavajte ponovo naslijepo; route to policy handling.
• Expired items: may be retried in a new job if the tenant still wants the work and budget allows.

A retry should create a new item linked to the original:

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

Do not resubmit completed items just because they were part of a job that ended as completed_with_errors or expired.

Decide what to store: raw results, pointers, or hashes

Batch systems are tempting places to accumulate prompts and outputs. That may be useful for exports and debugging, but it increases data-retention responsibility.

Recommendation: make storage policy tenant-configurable. Za osjetljiva radna opterećenja pohranite metapodatke, hashove, upotrebu i pokazivače rezultata umjesto sirovih upita i izlaza.Za manje osjetljiva radna opterećenja, normalizirano pohranjivanje rezultata može biti prihvatljivo ako su prozori zadržavanja, kontrole pristupa i tijekovi rada brisanja jasni.

Pratite barem:

• je li neobrađeni unos pohranjen.
• Je li neobrađeni izlaz pohranjen.
• Gdje su aktivni artefakti rezultata pružatelja.
• Dohvaćanje pružatelja rok.
• Rok za brisanje pristupnika.
• Hash zahtjeva i odgovora za reviziju bez izlaganja sadržaja.

Provjerena činjenica: Skupni rezultati antropskih stanja dostupni su 29 dana nakon stvaranja i izolirani unutar radnog prostora. Ova vrsta prozora za dohvaćanje specifičnog za pružatelja usluga trebala bi se odraziti na metapodatke pristupnika i izvoze okrenute stanarima.

Izložite analitiku koja odgovara načinu rada timova

Skupna analitika trebala bi postojati i na razini posla i na razini stavke. Vlasnik proizvoda želi znati je li završeno noćno obogaćivanje. Financijski administrator želi trošak prema najmoprimcu, modelu i kupcu. Inženjer želi znati koju klasu neuspjeha treba pokušati ponovno.

Korisni podaci uključuju:

• Broje se predane, dovršene, neuspjele, istekle i otkazane stavke.
• Procijenjeni u odnosu na podmireni trošak.
• Rezervirani proračun još uvijek postoji.
• Ulazni i izlazni tokeni po pružatelju i modelu.
• Pogodak predmemorije indikatori gdje ih pružatelji izlažu.
• Broj ponovnih pokušaja i stopa uspješnosti ponovnih pokušaja.
• Prosječno vrijeme u stanjima čekanja, izvođenja i finaliziranja.
• Najčešće pogreške provjere valjanosti po krajnjoj točki i modelu.
• Pripisivanje partnera partneru.

Za korisnike API-ja partnera, izložite skupne poslove kao resurse s opsegom korisnika. To omogućuje agencijama i sastavljačima SaaS-a da ponude izvanmrežnu AI obradu uz zadržavanje vjerodajnica davatelja usluga uzvodno, usklađivanje naplate i rukovanje ograničenjem stope unutar pristupnika.

Kompromisi za eksplicitnost

Apstrakcija pristupnika u odnosu na mogućnosti specifične za davatelja: objedinjeni ugovor pojednostavljuje integraciju, ali ne može svaku značajku davatelja učiniti identičnom. Pogreške u mogućnostima neka budu eksplicitne.

Rezervacija proračuna u odnosu na točnost procjene: rezervacija štiti stanare od nestalih poslova, ali procjene mogu biti pogrešne. Glavna knjiga mora podržavati prilagodbe, povrate i rukovanje viškom.

Prozivanje u odnosu na webdojavnike: prozivanje je jednostavno i pouzdano, ali može uzalud potrošiti API pozive i odgoditi završetak. Web-dojavnici su brži, ali zahtijevaju provjeru potpisa, zaštitu od ponavljanja i nadzor.

Pohranjivanje neobrađenih rezultata u odnosu na minimiziranje zadržavanja: pohranjivanje normaliziranih rezultata poboljšava izvoz i analitiku, ali povećava teret usklađenosti. Osjetljivi zakupci možda će više voljeti pokazivače i hashove.

Velike serije u odnosu na podijeljene serije: ogromne serije mogu poboljšati učinkovitost na strani pružatelja usluga, ali manji dijelovi smanjuju radijus eksplozije i olakšavaju ponovne pokušaje.

Kontrolni popis za implementaciju

• Stvorite zasebnu API površinu za skupne poslove.
• Trajni poslovi i zapisi stavki prije podnošenja dobavljača.
• Zahtijevaj ID-ove poslova pristupnika i prilagođene ID-ove po stavkama.
• Normaliziraj statuse dok pohranjuje izvorne metapodatke pružatelja.
• Izradi matricu mogućnosti za svaki serijski adapter pružatelja.
• Potvrdi manifeste prije rezerviranja proračuna.
• Rezerviraj proračun zakupca prije slanja.
• Podmiri stvarnu upotrebu na stavci razina nakon unosa.
• Učinite unos rezultata idempotentnim.
• Ponovo pokušajte neuspješne stavke selektivno, a ne cijele poslove naslijepo.
• Pratite rokove preuzimanja pružatelja usluga i politiku zadržavanja pristupnika.
• Izložite analitiku poslova i stavki zakupcima i partnerskim kupcima.

Predviđanja: gdje je ovaj uzorak heading

Predviđanje: serijsko će izvršenje postati normalan dio infrastrukture automatizacije umjetne inteligencije, a ne samo mehanizam popusta. Kako timovi pokreću više procjena, zadataka čišćenja podataka, sigurnosnih pregleda i cjevovoda za obogaćivanje, očekivat će da će asinkrona radna opterećenja imati isto upravljanje kao sinkroni API pozivi.

Predviđanje: paketni API-ji pružatelja nastavit će se razlikovati na korisne načine. Neki će optimizirati za datoteke, drugi za dugotrajne operacije, a treći za upravljane skupove podataka ili povratne pozive događaja. Sloj adaptera pristupnika postat će vrijedniji, a ne manje, jer operativni ugovor iznad adaptera može ostati stabilan.

Zaključak koji se može poduzeti

Nemojte pričvrstiti skupnu obradu na pristupnik AI API-ja kao otvor za spašavanje specifičan za pružatelja usluga. Izgradite ga kao izdržljiv podsustav s vlastitim zapisima o poslovima, identifikatorima stavki, modelom statusa, adapterima pružatelja usluga, rezervacijom proračuna, idempotentnim unosom i analitikom.

Najvažniji izbor dizajna je računovodstvo na razini stavke. Jednom kada svaki zahtjev unutar paketa ima stabilan identitet, pristupnik može uskladiti neuređene rezultate, ponovno pokušati samo neuspjeli rad, naplatiti samo dovršeni posao pružatelja i pokazati stanarima što se dogodilo.To je razlika između slanja datoteka pružatelju i rada pouzdanog višemodelnog API-ja za asinkrona radna opterećenja.

Povezano čitanje

• citirajte, rezervirajte, poravnajte i uskladite AI API obrazac naplate
• analiza korištenja na razini pristupnika i dizajn knjige tokena
• kada radna opterećenja tolerantna na kašnjenje odgovaraju skupnoj obradi