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.

Uzorak implementacije je da skupno izvršavanje postane prvoklasni pristupni podsustav. Gateway bi trebao izložiti jedan ugovor o poslu koji je neutralan prema pružatelju dok se prilagođava OpenAI, Anthropic, Gemini i budućim paketnim API-jima dobavljača iza scene.

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

Radna opterećenja tolerantna na kašnjenje prirodno odgovaraju skupnom izvršavanju. Teži dio je ne odlučiti može li posao čekati. Težak dio je dosljedan skupni rad kod svih pružatelja usluga.

Provjerene činjenice: OpenAI-ova serija API je asinkrona, č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 validating, failed, in_progress, finalizing, completed, expired, cancelling i cancelled. Anthropic's Message Batchs API asinkrono obrađuje mnoge zahtjeve za poruke, obrađuje svaki zahtjev neovisno, zahtijeva anketiranje i vraća rezultate nakon završetka obrade. Anthropic također preporučuje smislene custom_id vrijednosti jer redoslijed rezultata nije zajamčen. Gemini's Batch API otkriva dugotrajne metode stila operacija kao što su metode popisa, otkazivanja, brisanja i ažuriranja, a njezina operacija otkazivanja opisana je kao najbolja.

Te su razlike bitne kada dodate stvarne poslovne zahtjeve:

• Koji stanar, korisnik, projekt ili API ključ posjeduje svaki stavka?
• Je li proračun bio rezerviran prije nego što je posao napustio gateway?
• Koje dovršene stavke se naplaćuju ako serija istekne ili je otkazana?
• Kako se djelomični neuspjesi ponovno pokušavaju bez dupliciranja uspješnog rada?
• Koliko se dugo mogu dohvaćati datoteke rezultata i što bi trebao pristupnik pohraniti?
• Može li partner izgraditi skupnu obradu u opsegu korisnika bez izlaganja vjerodajnica uzvodnog pružatelja?

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

Preporučeno javno API: odvojite skupne poslove od sinkronih dovršetaka

Preporuka: izložite skupne poslove kao vlastitu API površinu, a ne kao posebnu zastavica na završetku 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 s stabilni identifikatori stavki.
• submit: potvrdite, rezervirajte proračun, odaberite davatelja, pošaljite i zaključajte poslani manifest.
• get_status: vratite normalizirani broj poslova i stavki.
• list_results: pregledajte normalizirane rezultate stavki, pogreške i upotreba.
• cancel: otkazivanje zahtjeva, bez obećanja trenutnog prekida.
• export_usage: izvoz evidencije troškova na razini posla i stavke za analitiku ili sustave naplate.

Primjer objekta javnog posla:

{
  "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"
}

Javni objekt ne bi trebao izlagati ID-ovi datoteka davatelja, nazivi operacija ili neobrađene upstream pogreške prema zadanim postavkama. Oni pripadaju metapodacima okrenutim prema 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, aliase internih modela, klijente partnera ili analitičke zahtjeve.

Minimalni model baze podataka

Korisna shema ima tri razine:

1. Skupni posao

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. Skupna stavka

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. Metapodaci davatelja

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

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

Zahtijevaj stabilne identifikatore stavki prije slanja

Preporuka: generiraj gateway job_id i zahtijevaju po artiklu custom_id ili ključ idempotencije prije slanja. Nikada ne usklađujte rezultate prema redoslijedu.

Anthropic izričito upozorava da redoslijed rezultata nije zajamčen i preporučuje smislene custom_id vrijednosti. Č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 o naručivanju na kraju ne uspiju.

Siguran format identifikatora artikla je deskriptivan, ali nije osjetljiv:

tenantA.invoice_extraction.2026-08-19.row_000381

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

Normalizirajte statuse bez brisanja pojedinosti o pružatelju usluga

Skupni API-ji pružatelja usluga 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:

• draft: posao postoji, ali ga je još uvijek moguće uređivati.
• validating: provjera valjanosti pristupnika ili davatelja je izvodi se.
• queued: prihvaćeno, ali još nije obrađeno.
• running: pružatelj obrađuje stavke.
• finalizing: pružatelj je završio računanje i priprema artefakte rezultata.
• completed: sve prihvaćene stavke stigle su do terminala uspjeh.
• completed_with_errors: neke stavke su uspjele, a neke nisu uspjele.
• expired: prozor pružatelja završio je prije nego što je sav posao dovršen.
• cancel_requested: zakupac je zamoljen da otkaže, ali konačni naplativi posao nije podmiren.
• cancelled: otkazivanje riješeno.
• failed: greška na razini posla spriječila je 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 valjanosti, broju zahtjeva, ID-ovima datoteka i nazivima operacija prilikom otklanjanja pogrešaka.

Provjerite valjanost u odnosu na matricu mogućnosti prije slanja

Preporuka: pokrenite provjeru valjanosti prije provjere proračuna i slanja pružatelja. Skupni način rada nije samo sinkroni način rada s odgodom. Neke modele, krajnje točke, značajke zahtjeva, regije i konfiguracije alata možda ne podržava serija API pružatelja.

Vaša interna matrica mogućnosti treba provjeriti:

• Podržana krajnja točka: chat, poruke, ugradnje, moderiranje ili generiranje.
• Prihvatljivost modela za seriju 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.
• Strukturirani izlaz ili JSON podrška za shemu.
• Slika, audio ili multimodalna podrška za unos.
• Ograničenja regije i prebivališta.
• Prozori zadržavanja pružatelja i dohvaćanja rezultata.
• Ograničenja brzine i čekanja specifična za paket.
• Semantika otkazivanja.

Dobar odgovor prije leta je specifičan:

{
  "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"
}

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

Rezervirajte proračun stanara, 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 obrazac je ponuda, rezervacija, podnošenje, unos, podmirenje i usklađivanje.

Provjerene činjenice: OpenAI navodi da se cijena serije API nudi s popustom u usporedbi sa sinkronim API-jima, a istekle ili otkazane serije još uvijek mogu vraćati dovršeni posao koji se naplaćuje.Anthropic napominje da skupna obrada visoke 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 marginu. 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
batch.reserved
batch.submitted
batch.item.settled
batch.item.refunded
batch.cancel_requested
batch.expired
batch.reconciled

Knjižna knjiga na razini stavke je neophodna. Ako je 45.000 stavki dovršeno, a 5.000 istekne, zakupcu bi se trebao naplatiti dovršeni posao pružatelja usluga, a ne izvorni manifest kao jedna nediferencirana mrlja.

Izradite adaptere pružatelja kao prevoditelje, a ne vlasnike poslovne logike

Svaki adapter pružatelja trebao bi znati kako transformirati posao pristupnika u paketni format pružatelja usluga, poslati ga, anketirajte ili dohvatite status, preuzmite rezultate i preslikajte izvorne ishode natrag u normalizirane zapise.

Zadrž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. To su odluke pristupnika.

Odgovornosti adaptera

• Renderiranje manifesta zahtjeva specifičnih za pružatelja usluga.
• Učitavanje ulaznih datoteka ili stvaranje operacija pružatelja usluga.
• Pohranjivanje identifikatora pružatelja usluga u metapodacima.
• Mapiranje izvornog statusa u normalizirani status.
• Dohvaćanje artefakata izlaza i pogrešaka.
• Raščlanjivanje rezultata na razini stavke.
• Vrati izvorne zapise o korištenju kada su dostupni.
• Površinski pokušaji u odnosu na pogreške terminala.

Gateway odgovornosti

• Provjerite autentičnost zakupca i API ključ.
• Primijenite timske, projektne i korisničke kontrole.
• Razriješite pseudonime modela i pravila usmjeravanja davatelja.
• Provjerite valjanost paketnih mogućnosti.
• Rezervirajte i poravnajte proračun.
• Održavajte posao i stanje stavke.
• Provedite pravila zadržavanja.
• Izložite analitiku i izvoze.

Ovo odvajanje olakšava dodavanje novog pružatelja bez ponovnog pisanja naplate, analitike ili zakupca upravljanje.

Idempotentno ubacivanje rezultata

Ubacivanje rezultata je mjesto gdje mnogi skupni sustavi slučajno dupliciraju naplate ili gube djelomičan rad. Tretirajte gutanje kao proces koji se ponavlja. Trebalo bi biti sigurno dvaput preuzeti istu izlaznu datoteku, dvaput obraditi istu operaciju pružatelja ili dva puta ponovno reproducirati isti webhook događaj.

Preporuka: koristite ključeve idempotencije na razini stavke i ograničenja jedinstvenosti glavne knjige.Rezultat za job_id + custom_id trebao bi se postaviti točno jednom, čak i ako se ponovno pokuša unos.

Robusni tijek unosa:

1. Dobivanje kratkotrajnog zaključavanja za artefakt posla ili rezultata.
2. Dohvaćanje izlaza pružatelja usluga i artefakata pogreške.
3. Raščlanjivanje zapisa u normalizirani rezultat stavke događaji.
4. Uparite svaki zapis prema custom_id ili ID-u stavke pristupnika.
5. Pišite metapodatke rezultata i upotrebu u transakciji.
6. Stvorite događaj poravnanja u glavnoj knjizi samo ako već ne postoji.
7. Ažurirajte brojanje poslova iz stanja stavki, a ne iz pretpostavke.
8. Oslobodi neiskorištenu rezervaciju proračuna kada su sva stanja terminala poznata.

Ako su dostupni webdojavnici, provjeri potpise i zaštiti od ponovne reprodukcije. Ako je anketiranje potrebno, upotrijebite prilagodljivo anketiranje: anketirajte često blizu očekivanog završetka, povucite se tijekom dugotrajnih razdoblja i zaustavite se nakon poravnanja terminala.

Pokušajte ponovo stavke, ne cijele poslove

Preporuka: pokušajte ponovo na razini stavke kad god je to moguće. Ponovni pokušaji cijelog posla su jednostavni, ali povećavaju rizik dupliciranja posla i otežavaju naplatu.

Klasificirajte neuspjehe prije ponovnog pokušaja:

• Pogreške valjanosti: obično terminal dok se zahtjev ne popravi.
• Dobavljač 5xx pogreške: često se može ponovno pokušati s odmakom.
• Neuspjesi ograničenja kvote ili stope: pokušajte ponovo samo nakon što je kapacitet dostupan.
• Sigurnosni blokovi: ne pokušavajte ponovo naslijepo; ruta do obrade pravila.
• Istekle stavke: mogu se ponovno isprobati u novom poslu ako zakupac i dalje želi posao i proračun to dopušta.

Ponovni pokušaj trebao bi stvoriti novu stavku povezanu s izvornikom:

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

Nemojte ponovno slati dovršene stavke samo zato što su bile dio posla koji završava kao completed_with_errors ili expired.

Odlučite što pohraniti: neobrađene rezultate, pokazivače ili hashove

Skupni sustavi su primamljiva mjesta za akumuliranje upita i izlaza. To može biti korisno za izvoze i otklanjanje pogrešaka, ali povećava odgovornost za zadržavanje podataka.

Preporuka: neka politika pohrane bude konfigurabilna zakupcu. Za osjetljiva radna opterećenja pohranite metapodatke, hashove, upotrebu i pokazivače rezultata umjesto sirovih upita i izlaza.Za manje osjetljiva radna opterećenja, normalizirana pohrana rezultata može biti prihvatljiva 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 artefakti rezultata pružatelja uživo.
• Rok za pronalaženje pružatelja usluga.
• Rok za brisanje pristupnika.
• Hash zahtjeva i odgovora za reviziju bez izlaganja sadržaja.

Provjerena činjenica: Anthropic navodi da su skupni rezultati dostupni 29 dana nakon stvaranja i izolirani unutar radni prostor. 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 dovrš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.

Korisne metrike uključuju:

• Broje se predane, dovršene, neuspjele, istekle i otkazane stavke.
• Procijenjeni u odnosu na podmireni trošak.
• Rezervirani proračun i dalje zadržano.
• Ulazni i izlazni tokeni po pružatelju i modelu.
• Indikatori pogodaka predmemorije 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 po krajnjoj točki i model.
• Pripisivanje partnera partneru.

Za korisnike partnera API, 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 uzlaznog davatelja, usklađivanja naplate i rukovanja ograničenjem stope unutar pristupnika.

Kompromisi koji treba učiniti eksplicitnim

Apstrakcija pristupnika u odnosu na mogućnost specifične za davatelja: objedinjeni ugovor pojednostavljuje integraciju, ali ne može svaku značajku pružatelja 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 odbjeglih 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 API prouzročiti 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 izvoze i analitiku, ali povećava teret usklađenosti.Osjetljivi zakupci možda preferiraju pokazivače i hashove.

Velike serije u odnosu na skupine u komadima: 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 zaseban skupni posao API površina.
• Održavajte zapise o poslovima i stavkama prije podnošenja pružatelja.
• Zahtijevaj ID-ove poslova pristupnika i prilagođene ID-ove po stavkama.
• Normaliziraj statuse uz pohranu izvornih metapodataka pružatelja.
• Izradi matricu mogućnosti za svaku seriju pružatelja adapter.
• Potvrdite manifeste prije rezerviranja proračuna.
• Rezervirajte proračun zakupca prije slanja.
• Odredite stvarnu upotrebu na razini stavke nakon unosa.
• Učinite unos rezultata idempotentnim.
• Ponovo pokušajte selektivno neuspješne stavke, a ne cijele poslove naslijepo.
• Pratite rokove za dohvaćanje pružatelja usluga i politiku zadržavanja pristupnika.
• Izložite analitiku poslova i stavki stanarima i partnerskim klijentima.

Predviđanja: kamo ide ovaj obrazac

Predviđanje: skupno ć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 i sinkroni API pozivi.

Predviđanje: batch 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 spajati serijsku obradu na AI API pristupnik kao izlazni otvor 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 davatelju usluga i rada pouzdanog multi-modela API za asinkrona radna opterećenja.

Povezano čitanje

• ponudite, rezervirajte, podmirite i uskladite AI API naplatu uzorak
• analitika korištenja na razini pristupnika i dizajn knjige tokena
• kada radna opterećenja tolerantna na kašnjenje odgovaraju skupnoj obradi