Egységes kötegelt munkák AI API-átjárón keresztül: tartós sorok, szolgáltatói adapterek és bérlői szintű számlázás

Javasolt nyilvános API: különítse el a kötegelt feladatokat a szinkron befejezésektől

Javaslat: a kötegelt feladatokat saját API-felületként tegye közzé, ne pedig speciális jelzőként. A szinkron kérés és az aszinkron kötegelt feladat eltérő életciklusú, számlázási, újrapróbálkozási és eredménylekérési szemantikával rendelkezik.

A gyakorlati átjárószerződés a következő műveleteket tartalmazza:

• create_job: egy bérlő, projekt, kulcs vagy partnerügyfél tulajdonában lévő feladat-vázlat létrehozása.upload_manifest: egyedi kérések hozzáadása stabil cikkazonosítókkal.
• submit: érvényesítés, költségkeret lefoglalása, szolgáltató kiválasztása, feladás és zárolás a beküldött jegyzékben.
• get_status: normalizált feladat- és cikkszámok visszaadása.
• eredmények
, normalized, item_re: pages_ andre: használat.
• mégse: kérjen törlést azonnali lemondás ígérete nélkül.
• export_usage: feladat- és cikkszintű költségrekordok exportálása analitikai vagy számlázási rendszerek számára.

Példa nyilvános feladatobjektum:

{
  "job_id": "job_01j7...",
  "tenant_id": "bérlő_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "modell": "analízis-nagy",
  "status": "fut",
  "számít": {
    "benyújtva": 50000,
    "befejezett": 31240,
    "sikertelen": 180,
    "lejárt": 0
  },
  "költség": {
    "becsült": "184,20",
    "fenntartva": "205.00",
    "kiegyenlített": "117.43",
    "valuta": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "submitted_at": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"
}

A nyilvános objektum alapértelmezés szerint nem fedheti fel a szolgáltatói fájlazonosítókat, műveletneveket vagy nyers upstream hibákat. Ezek az operátorra néző metaadatok közé tartoznak.

Használjon tartós feladatrekordokat az igazság forrásaként

Az átjáró tulajdonában lévő kötegelt rétegnek tartós állapotra van szüksége, mielőtt bármit is elküldene az áramlás felé. Ne hagyatkozzon a szolgáltató kötegelt rekordjaira, mint az egyetlen állami áruházra. A szolgáltatói rekordok szükségesek, de nem ismerik a bérlői hierarchiát, a költségvetés-foglalásokat, a belső modellálneveket, a partnerügyfeleket vagy az elemzési követelményeket.

Minimális adatbázismodell

A hasznos sémának három szintje van:

1. Batch job

batch_jobs
- job_id
- bérlő_azonosítója
- project_id
- a customer_id nullable- api_key_id
- végpont
- kért_modell
- megoldott_szolgáltató
- megoldott_szolgáltató_modell
- állapot
- item_count
- becsült_bemeneti_tokenek
- becsült_kimeneti_tokenek
- lefoglalt_összeg
- elszámolt_összeg
- Created_at
- benyújtott_kukac
- kész_at
- lejár_kor
- visszakeresési_határidő
- cancellation_requested_at

2. Batch item

batch_items
- job_id
- item_id
- custom_id
- idempotency_key
- request_hash
- állapot
- a szolgáltató_kérés_index nulla
- becsült_tokenek
- Az aktuális_bemeneti_tokenek nullázhatók
- A tényleges_kimeneti_tokenek nullázhatók
- elszámolt_összeg nullálható
- eredménymutató nullázható
- error_code nullable
- újrapróbálkozási_elem_azonosító nulla
- Created_at
- letelepedett_at

3. Szolgáltatói metaadatok

batch_provider_metadata
- job_id
- szolgáltató
- a szolgáltatói_kötegelt_azonosító nullálható
- input_file_id nullable
- output_file_id nullable
- error_file_id nullable
- a művelet_neve nullázható
- végpont
- a régió nullázható
- natív_állapot
- native_request_counts jsonb
- utolsó_lekérdezett_at
- raw_error_pointer nullable

A szolgáltatói metaadatok elkülönítése a nyilvános munkaszerződéstől lehetővé teszi az átjáró számára a szolgáltatói adapterek fejlesztését anélkül, hogy megszakítaná a bérlői API-kat.

Stabil elemazonosítók megkövetelése a feladás előtt

Ajánlás: code_idgeneration:custom_id vagy idempotenciakulcs a feladás előtt. Soha ne egyeztetje össze az eredményeket sorrend szerint.

Az Anthropic kifejezetten figyelmeztet arra, hogy az eredmények sorrendje nem garantált, és értelmes custom_id értékeket ajánl. Még ha úgy tűnik is, hogy egy szolgáltató megőrzi a rendet, egy átjáró nem függhet tőle. A munkákat darabokra osztják, újrapróbálják, lemondják, részben befejezik, és újra bedolgozzák. A rendelési feltételezések végül meghiúsulnak.

A biztonságos tételazonosító formátum leíró jellegű, de nem érzékeny:

tenantA.invoice_extraction.2026-08-19.row_000381

Kerülje el a nyers e-mailek, nevek, ügyfél-azonosítók vagy .tifiers titkos dokumentumok címeinek megadását. Az érzékeny korrelációs adatokat saját bérlői adatbázisában tárolja, ne a szolgáltató által látható azonosítókban.

Normalizálja az állapotokat a szolgáltató adatainak törlése nélkül.

A szolgáltatói kötegelt API-k különböző életciklusokat tesznek elérhetővé. Az átjárónak egy kis belső állapotú géppé kell normalizálnia őket, amelyet az irányítópultok, a számlázás és az automatizálás is megértenek.

Javasolt normalizált életciklus:

• piszkozat: a feladat létezik, de még szerkeszthető.
• ellenőrzés: < kód érvényesítése::
még feldolgozás alatt áll.
• fut: a szolgáltató elemeket dolgoz fel.
• finalizing: a szolgáltató befejezte a számítást, és előkészíti az eredménytermékeket.
• befejezve: az összes elfogadott elem elérte a terminál sikerét.
• completed_with_errors: néhány sikertelen ablak szolgáltató. néhány sikertelen elem az összes munka befejezése előtt véget ért.
• cancel_requested: a bérlő lemondást kért, de a végső számlázható munka nincs kiegyenlítve.
• cancelled: a lemondás rendezve.
• sikertelen: feladatszintű hiba akadályozta meg a hasznos végrehajtást.

D generic labels túl korai collapse. Az üzemeltetőknek továbbra is hozzá kell férniük a natív állapotokhoz, az érvényesítési hibákhoz, a kérések számához, a fájlazonosítókhoz és a műveletnevekhez a hibakeresés során.

Elküldés előtt végezze el az érvényesítést egy képességmátrixszal.

Javaslat: futtassa le az előzetes ellenőrzést a költségvetés lefoglalása és a szolgáltató feladása előtt. A kötegelt mód nem csak késleltetett szinkron mód. Előfordulhat, hogy egyes modelleket, végpontokat, kérésfunkciókat, régiókat és eszközkonfigurációkat a szolgáltató kötegelt API-ja nem támogat.

A belső képességmátrixnak ellenőriznie kell a következőket:

• Támogatott végpont: csevegés, üzenetek, beágyazások, moderálás vagy generálás.
• Modell jogosultság kötegelt módra.
• A kérés maximális mérete és feltöltési mérete.
, max itemimumcounted. méret.
• Tiltott-e az adatfolyam.
• Eszközhasználat és funkcióhívás támogatása.
• Strukturált kimenet vagy JSON-séma támogatása.
• Kép-, hang- vagy multimodális bemenet támogatása.
• Régió- és lakóhely-megszorítások.
• Szolgáltatói adatmegőrzési és -retenciális ablakok
• korlátok.
• A törlés szemantikája.

A jó repülés előtti válasz specifikus:

{
  "error": "batch_capability_not_supported",
  "message": "A kiválasztott szolgáltató kötegelt adaptere nem támogatja a streaming válaszokat. Távolítsa el a stream=true-t, vagy válasszon szinkron végpontot.",
  "field": "elemek[*].request.stream"}

Ez hasznosabb, mint a feladat elfogadása és sikertelensége egy upstream érvényesítés után.

A bérlői költségkeret lefoglalása, majd a tényleges használat rendezése

A kötegelt végrehajtás bonyolítja a számlázást, mert az átjáró elveszítheti a szinkron hozzáférést a pontos használathoz, amíg az eredményfájlok nem állnak rendelkezésre. A biztonságos minta az ajánlattétel, a tartalékolás, a benyújtás, a feldolgozás, a kiegyenlítés és az egyeztetés.

Ellenőrzött tények: Az OpenAI szerint a kötegelt API-árakat a szinkron API-khoz képest kedvezményesen kínálják, és a lejárt vagy lemondott kötegek továbbra is visszaküldhetik a számlázandó befejezett munkát. Az Anthropic megjegyzi, hogy a nagy áteresztőképességű kötegelt feldolgozás kismértékben meghaladhatja a munkaterület költési korlátját, ami fontossá teszi az átjáróoldali foglalást és az utólagos elszámolást.

Javaslat: foglaljon le bérlői költségkeretet a benyújtás előtt becsült tokenekkel, kiválasztott szolgáltatói árszabályokkal és biztonsági tartalékkal. Az eredmények feldolgozása után a tényleges felhasználást tételszinten rendezze. Ha a becslés túl magas volt, engedje fel a fel nem használt foglalást. Ha túl alacsony volt, alkalmazza a bérlő konfigurált túllépési szabályzatát.

Gyakorlati főkönyvi események:

batch.estimated
tétel.fenntartva
köteg.benyújtva
tétel.tétel.elszámolva
batch.item.refunded
batch.cancel_requested
köteg.lejártbatch.reconciled

A tételszintű főkönyv elengedhetetlen. Ha 45 000 elem kész, és 5000 lejár, a bérlőnek az elvégzett szolgáltatói munkáért kell számláznia, nem pedig az eredeti jegyzékért, mint egyetlen differenciálatlan blobért.

Szolgáltatói adaptereket készítsen fordítóként, ne pedig üzleti logika tulajdonosaként

Minden szolgáltatói adapternek tudnia kell, hogyan alakítsa át a szolgáltatói átjáró, a retrie itve batch-letöltési vagy a szolgáltatói kötegletöltési formátumba. eredményeket, és leképezi a natív eredményeket a normalizált rekordokra.

Tartsa az adapteren kívül a bérlői szabályzatot. Az illesztőnek nem szabad eldöntenie, hogy az ügyfélnek elegendő költségvetése van-e, hogy egy partnerügyfelet felfüggesztettek-e, vagy tárolhatók-e az értesítések. Ezek az átjárók döntései.

Adapter felelőssége

• Szolgáltató-specifikus kérésjegyzékek megjelenítése.
• Töltsön fel bemeneti fájlokat vagy hozzon létre szolgáltatói műveleteket.
• A szolgáltatói azonosítók tárolása a metaadatokban.
• Natív állapot és a kimeneti állapot hozzárendelése normalizált hibaállapothoz.
műtermékek.
• Elemszintű eredmények elemzése.
• Natív használati rekordok visszaküldése, ha rendelkezésre állnak.
• Felszíni újrapróbálhatóság a terminálhibákkal szemben.

Az átjáró felelősségei

• A bérlő és az ügyfélmodell hitelesítése, az ügyfélmodell és az API-kulcs.
• RealveApply> álnevek és szolgáltatói útválasztási szabályzat.
• A kötegelt képességek ellenőrzése.
• Foglalja le és rendezze a költségkeretet.
• A feladat és a tétel állapotának megőrzése.
• A megőrzési politika érvényesítése.
• Nyomja meg az elemzéseket és az exportálást.

Ez a szétválasztás megkönnyíti a szolgáltatók újraírását, új számlák kiírását. irányítás.

Eredmények azonnali feldolgozása

Az eredmények feldolgozásakor sok kötegelt rendszer véletlenül megkettőzi a terheléseket, vagy elveszíti részleges munkáját. A lenyelést megismételhető folyamatként kezelje. Biztonságosnak kell lennie, ha kétszer letölti ugyanazt a kimeneti fájlt, kétszer dolgozza fel ugyanazt a szolgáltatói műveletet, vagy kétszer játssza le ugyanazt a webhook-eseményt.

Javaslat: használjon elemszintű idempotenciakulcsokat és főkönyvi egyediségi megszorításokat. A job_id + custom_id eredményének pontosan egyszer kell rendeződnie, még akkor is, ha újra megpróbálja a feldolgozást.

Rendkívüli feldolgozási folyamat:

1. Rövid ideig tartó zárolást szerezhet a feladathoz vagy az eredmény melléktermékéhez.
2. A szolgáltató kimenetének és a hibatermékek lekérése a normalizált item rekordokba.
eseményeket.
3. Egyezze meg az egyes rekordokat a custom_id vagy az átjáróelem azonosítójával.
4. Írja meg az eredmények metaadatait és a felhasználást egy tranzakcióban.
5. Csak akkor hozzon létre főkönyvi kiegyenlítési eseményt, ha még nem létezik.
6. Frissítse a munkaszámlálásokat a tételállapotokból, ne pedig a nem használt költségvetésből, ha a nem használt költségkeret feltételezésekből áll. ismert.

Ha rendelkezésre állnak webhoook, ellenőrizze az aláírásokat, és védje meg az újrajátszást. Ha lekérdezésre van szükség, használjon adaptív lekérdezést: gyakran végezzen lekérdezést a várható befejezés közelében, húzza le a hosszú futási időszakokat, és hagyja abba a terminál elszámolását követően.

Tételekkel próbálkozzon újra, ne a teljes munkákkal.

Javaslat: lehetőség szerint próbálja újra elemszinten. A teljes munka újrapróbálkozása egyszerű, de növeli az ismétlődő munka kockázatát, és megnehezíti a számlázást.

Osztályozza a hibákat az újrapróbálkozás előtt:

• Érvényesítési hibák: általában terminál, amíg a kérést kijavítják.
• Szolgáltatói 5xx hibák: gyakran újrapróbálhatóhiba vagy backoff-limittel. próbálja újra csak a kapacitás rendelkezésre állása után.
• Biztonsági blokkok: ne próbálja vakon újra; útvonal a szabályzat kezeléséhez.
• Lejárt tételek: újrapróbálkozhat egy új munkával, ha a bérlő továbbra is azt akarja, hogy a munka és a költségvetés megengedje.

Az újrapróbálkozás során létre kell hozni egy új elemet, amely az eredetihez kapcsolódik:

{
  "item_id": "item_retry_002",
  "retry_of_item_id": "item_001",
  "custom_id": "bérlőA.eval.row_901.retry_1"
}

Ne küldje be újra a befejezett tételeket csak azért, mert egy olyan feladat részét képezték, amely completed_with_errors vagy expiredként végződött.

Döntse el, mit tároljon: nyers eredmények, mutatók vagy hash

A kötegelt rendszerek csábító helyek a felszólítások és kimenetek felhalmozására. Ez hasznos lehet az exportáláshoz és a hibakereséshez, de növeli az adatmegőrzési felelősséget.

Javaslat: tegye konfigurálhatóvá a tárolási házirendet a bérlő számára. Érzékeny munkaterhelések esetén a nyers promptok és kimenetek helyett metaadatokat, kivonatokat, használati és eredménymutatókat tároljon.Kevésbé érzékeny munkaterhelések esetén a normalizált eredménytárolás elfogadható lehet, ha a megőrzési ablakok, a hozzáférés-vezérlés és a törlési munkafolyamatok egyértelműek.

Kövesse legalább a következőket:

• tárolták-e a nyers bemenetet.
• A nyers kimenetet tárolták-e.
• Ahol a szolgáltatói eredmények melléktermékei élnek.Provi.
• A kérés és a válasz kivonatolása a tartalom közzététele nélkül.

Ellenőrzött tény: Az antropikus állapotok kötegeredményei a létrehozás után 29 napig elérhetők, és a munkaterületen belül elkülönítve állnak rendelkezésre. Ennek a szolgáltató-specifikus visszakeresési ablaknak tükröződnie kell az átjáró metaadataiban és a bérlő felé irányuló exportálásban.

A csapatok működésének megfelelő elemzések megjelenítése

A kötegelt elemzésnek mind a feladat, mind a tétel szintjén léteznie kell. Egy terméktulajdonos tudni szeretné, hogy az éjszakai dúsítás befejeződött-e. A pénzügyi adminisztrátor a költségeket bérlő, modell és ügyfél szerint kéri. Egy mérnök tudni szeretné, melyik hibaosztályt kell újrapróbálnia.

A hasznos mutatók a következők:

• A beküldött, befejezett, sikertelen, lejárt és törölt tételek száma.
• Becsült versus kiegyenlített költség.
• A fenntartott költségkeret továbbra is érvényben van.
• Bemeneti és kimeneti mutatók a szolgáltatótól
• Ckentsli> a szolgáltatók teszik közzé őket.
• Újrapróbálkozások számlálása és sikerességi arány.
• Átlagos idő várakozási, futási és véglegesítési állapotban.
• Legnagyobb ellenőrzési hibák végpont és modell szerint.
• Partner-ügyfél-hozzárendelés.

A Partner API-felhasználók számára a kötegelt ügyfél-feladatokat tegye közzé. Ez lehetővé teszi az ügynökségek és a SaaS-készítők számára, hogy offline mesterséges intelligencia feldolgozást kínáljanak, miközben a szolgáltatói hitelesítési adatokat, a számlázási egyeztetést és a díjkorlátok kezelését az átjárón belül tartják.

Az explicitté tett kompromisszumok

Az átjáró absztrakciója a szolgáltató-specifikus képességekkel szemben: nem tehet minden szolgáltatót egységes integrációvá. Tartsa tisztán a képességhibákat.

A költségkeret foglalása a becslés pontosságával szemben: a foglalás megvédi a bérlőket az elszabadult munkáktól, de a becslések tévesek lehetnek. A főkönyvnek támogatnia kell a korrekciókat, a visszatérítéseket és a túllépések kezelését.

Lekérdezés a webhookkal szemben: a lekérdezés egyszerű és megbízható, de elpazarolhatja az API-hívásokat, és késleltetheti a befejezést. A webhookok gyorsabbak, de aláírás-ellenőrzést, visszajátszásvédelmet és figyelést igényelnek.

A nyers eredmények tárolása a megőrzés minimalizálásával szemben: a normalizált eredmények tárolása javítja az exportálást és az elemzést, de növeli a megfelelési terhet. Az érzékeny bérlők előnyben részesíthetik a mutatókat és a hash-eket.

A nagy kötegek a darabolt kötegekkel szemben: A hatalmas kötegek javíthatják a szolgáltató oldali hatékonyságát, de a kisebb darabok csökkentik a robbanási sugarat és könnyebbé teszik az újrapróbálkozásokat.

Megvalósítási ellenőrzőlista