Locuri de muncă unificate printr-un gateway AI API: cozi durabile, adaptoare pentru furnizori și facturare la nivel de chiriaș

Procesarea în loturi nu trebuie tratată ca o ușă laterală în jurul porții AI API. Dacă evaluările, îmbogățirea documentelor, extragerea, controlul de moderare sau încorporarea joburilor părăsesc calea cererii sincrone, acestea au nevoie în continuare de controale pentru locatari, atribuirea costurilor, reîncercări, auditabilitate și analize de utilizare.

Modelul de implementare este de a face din execuția lotului un subsistem gateway de primă clasă. Gateway-ul ar trebui să expună un contract de muncă neutru pentru furnizor, în timp ce se adaptează la API-urile de lot OpenAI, Anthropic, Gemini și viitorul furnizor în culise.

Problema cititorului: API-urile batch sunt similare ca intenție, diferă în funcționare

Scărcăturile de lucru tolerante la latență sunt o potrivire naturală pentru execuția în lot. Partea grea este să nu decizi dacă un loc de muncă poate aștepta. Partea grea este să opereze în mod consecvent lucrul în loturi între furnizori.

Fate verificate: API-ul OpenAI Batch este asincron, citește solicitările dintr-un fișier încărcat, scrie răspunsuri într-un fișier de ieșire și în prezent utilizează o fereastră de procesare de 24 de ore. OpenAI listează stări precum validare, eșuat, în curs, finalizare, finalizat, expirat, anulare și anulat. API-ul Message Batches de la Anthropic procesează multe solicitări Messages în mod asincron, gestionează fiecare cerere în mod independent, necesită interogare și returnează rezultate după încheierea procesării. Anthropic recomandă, de asemenea, valori semnificative custom_id, deoarece ordinea rezultatelor nu este garantată. API-ul Batch de la Gemini expune metode de operare de lungă durată, cum ar fi metode de listare, anulare, ștergere și actualizare, iar operațiunea de anulare a acesteia este descrisă ca fiind cea mai bună efort.

Aceste diferențe contează odată ce adăugați cerințe reale de afaceri:

• Ce chiriaș, client, proiect sau cheie API deține fiecare articol?
• Care a lăsat bugetul înainte? articolele finalizate sunt facturabile dacă lotul expiră sau este anulat?
• Cum sunt reîncercate eșecurile parțiale fără a duplica munca de succes?
• Cât timp pot fi recuperate fișierele rezultate și ce ar trebui să stocheze gateway-ul?
• Poate un partener să construiască procesarea loturilor la nivelul clientului fără a expune acreditările furnizorului din amonte? Răspunsul este de a normaliza contractul de operare, păstrând în același timp metadatele native ale furnizorului pentru depanare, reconciliere și asistență.

  API publică recomandată: sarcinile lot separate de completările sincrone

  Recomandare: expune lucrările lot ca propria suprafață API, nu ca un semnal special pentru finalizarea prin chat. O solicitare sincronă și o sarcină lot asincronă au o semantică diferită de ciclu de viață, facturare, reîncercare și extragere a rezultatelor.

  Un contract gateway practic include aceste operațiuni:

  • create_job: creați o schiță de job deținută de un chiriaș, proiect, cheie sau client partener.
  • >
  • > upload_manifest: adăugați solicitări individuale cu identificatori stabili de articol.
  • trimite: validați, rezervați buget, selectați furnizorul, expediați și blocați manifestul trimis.
  • get_status: returnați numărul normalizat de locuri de muncă și de articole.
  • code>list_results, rezultate normalizate
  • element_results; utilizare.
  • anulați: solicitați anularea, fără a promite rezilierea imediată.
  • export_usage: exportați înregistrări de cost la nivel de job și la nivel de articol pentru sisteme de analiză sau de facturare.

  Exemplu de obiect de job public:

  {
    "job_id": "job_01j7...",
    "tenant_id": "tenant_acme",
    "customer_id": "customer_123",
    "endpoint": "chat.completions",
    "model": "analiza-mare",
    "status": "în rulare",
    „contează”: {
      „trimis”: 50000,
      „finalizat”: 31240,
      „eșuat”: 180,
      „expirat”: 0
    },
    „cost”: {
      "estimat": "184,20",
      "rezervat": "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”
  }

  Obiectul public nu ar trebui să expună ID-urile fișierelor furnizorului, numele operațiunilor sau erorile brute din amonte în mod implicit. Acestea aparțin metadatelor orientate către operator.

  Utilizați înregistrările durabile ale jobului ca sursă de adevăr

  Un strat de lot deținut de gateway are nevoie de o stare durabilă înainte de a fi trimis ceva în amonte. Nu vă bazați pe înregistrările loturilor furnizorului ca singurul magazin de stat. Înregistrările furnizorului sunt necesare, dar aceștia nu vă cunosc ierarhia chiriașilor, rezervările bugetare, aliasurile modelului intern, clienții parteneri sau cerințele de analiză.

  Model minim de bază de date

  O schemă utilă are trei niveluri:

  1. Locuri de muncă

  batch_jobs
  - job_id
  - tenant_id
  - project_id
  - customer_id nullabil- api_key_id
  - punctul final
  - modelul_ solicitat
  - provider_rezolvat
  - model_furnizor_rezolvat
  - starea
  - item_count
  - jetoane_de_intrare_estimate
  - jetoane_de_ieșire_estimate
  - suma_rezervată
  - sumă_decontată
  - creat_la
  - trimis_la
  - finalizat_la
  - expiră_la
  - termenul_preluare
  - anulation_requested_at

  2. Loturi de articole

  batch_items
  - job_id
  - item_id
  - custom_id
  - cheie_idempotenta
  - request_hash
  - starea
  - provider_request_index nullabil
  - jetoane_estimate
  - actual_input_tokens nullabil
  - actual_output_tokens nullabil
  - suma_decontată nulă
  - rezultat_pointer nulabil
  - error_code nullabil
  - retry_of_item_id nulăbil
  - creat_la
  - settled_at

  3. Metadatele furnizorului

  batch_provider_metadata
  - job_id
  - furnizor
  - provider_batch_id nullabil
  - input_file_id nullabil
  - output_file_id nullabil
  - error_file_id nullabil
  - operațiune nulă
  - punctul final
  - regiune nulă
  - stare_nativă
  - native_request_counts jsonb
  - ultimul_solicitat
  - raw_error_pointer nullable

  Păstrarea metadatelor furnizorului separat de contractul public de muncă permite gateway-ului să evolueze adaptoarele furnizorului fără a întrerupe API-urile care se confruntă cu chiriașii.

  Solicită identificatori stabili de articol înainte de expediere

  Recomandare: generați o poartă de acces. custom_id sau cheia idempotence înainte de expediere. Nu reconciliați niciodată rezultatele după ordine.

  Anthropic avertizează în mod explicit că ordinea rezultatelor nu este garantată și recomandă valori semnificative custom_id. Chiar și atunci când un furnizor pare să păstreze ordinea, un gateway nu ar trebui să depindă de aceasta. Lucrările sunt fragmentate, reîncercate, anulate, finalizate parțial și reingerate. În cele din urmă, ipotezele de comandă eșuează.

  Un format sigur de identificare a articolului este descriptiv, dar nu sensibil:

  tenantA.invoice_extraction.2026-08-19.row_000381

  Evitați să introduceți e-mailuri brute, nume, titluri de documente sau secrete ale clienților în identificatori. Stocați date sensibile de corelare în propria bază de date a chiriașilor, nu în ID-urile vizibile de furnizor.

  Normalizați stările fără a șterge detaliile furnizorului

  API-urile loturilor furnizorului expun cicluri de viață diferite. Gateway-ul ar trebui să le normalizeze într-o mică mașină de stare internă pe care tablourile de bord, facturarea și automatizarea o pot înțelege.

  Ciclul de viață normalizat recomandat:

  • schiță: job-ul există, dar este încă editabil.
  • validare: validarea gateway-ului sau a furnizorului nu rulează încă.>>
  • . procesare.
  • rularea: furnizorul procesează articole.
  • finalizing: furnizorul a terminat calculul și pregătește artefacte de rezultat.
  • finalizat: toate elementele acceptate au ajuns cu succes la terminal.
  • compleed_with_errors: unele elemente reușite. a eșuat.
  • expirat: fereastra furnizorului s-a încheiat înainte de finalizarea tuturor lucrărilor.
  • cancel_requested: chiriașul a cerut să anuleze, dar lucrarea finală facturabilă nu este decontată.
  • anulată: anularea a fost soluționată.
  • eșecul eșuat:
  p. erorile furnizorului nativ în etichetele generice prea devreme. Operatorii au în continuare nevoie de acces la stările native, erorile de validare, numărul de solicitări, ID-urile fișierelor și numele operațiunilor atunci când depanează.

  Validați cu o matrice de capabilități înainte de trimitere

  Recomandare: executați validarea preflight înainte de rezervarea bugetului și expedierea furnizorului. Modul lot nu este doar un mod sincron cu întârziere. Este posibil ca unele modele, puncte finale, caracteristici de solicitare, regiuni și configurații de instrumente să nu fie acceptate de API-ul batch al unui furnizor.

  Matricea dvs. internă de capabilități ar trebui să verifice:

  • Punctul final acceptat: chat, mesaje, încorporare, moderare sau generare.
  • Eligibilitatea modelului pentru modul lot, dimensiunea fișierului de încărcare și numărul de solicitare de lot, dimensiunea de încărcare a sarcinii, numărul de articole Maxi
  • . dimensiune.
  • Dacă este interzisă transmiterea în flux.
  • Suport de utilizare a instrumentelor și de apelare a funcției.
  • Suport structurat de ieșire sau de schemă JSON.
  • Suport de imagine, audio sau intrare multimodală.
  • Constrângeri de regiune și rezidență.
  • Reținerea furnizorului și ferestrele specifice de recuperare a rezultatelor. Limitează ferestrele și rata de căutare a rezultatelor. limite.
  • Semantica anulării.

  Un răspuns bun preflight este specific:

  {
    "eroare": "batch_capability_not_supported",
    "message": "Adaptorul lot al furnizorului selectat nu acceptă răspunsuri în flux. Eliminați stream=true sau alegeți un punct final sincron.",
    „câmp”: „articole[*].request.stream”}

  Acest lucru este mai util decât acceptarea sarcinii și eșuarea acesteia după o trecere de validare în amonte.

  Rezervați bugetul locatarului, apoi stabiliți utilizarea efectivă

  Execuția în lot complică facturarea, deoarece gateway-ul poate pierde accesul sincron la utilizarea exactă până când fișierele cu rezultate sunt disponibile. Modelul sigur este citarea, rezervarea, trimiterea, asimilarea, soluționarea și reconcilierea.

  Fapte verificate: OpenAI afirmă că prețul API-ului pentru lot este oferit la o reducere în comparație cu API-urile sincrone, iar loturile expirate sau anulate pot returna în continuare lucrări finalizate care sunt facturabile. Anthropic observă că procesarea în loturi cu debit mare poate depăși ușor limita de cheltuieli pentru spațiul de lucru, ceea ce face ca rezervarea și post-decontarea la gateway să fie importante.

  Recomandare: rezervați bugetul locatarului înainte de trimitere folosind indicative estimate, regulile de preț ale furnizorului selectat și o marjă de siguranță. După ce rezultatele sunt ingerate, stabiliți utilizarea efectivă la nivel de articol. Dacă estimarea a fost prea mare, eliberați rezervarea neutilizată. Dacă a fost prea scăzut, aplicați politica de depășire configurată a chiriașului.

  Evenimente practice în registru:

  batch.estimated
  lot.rezervat
  lot.depus
  lot.articol.decontat
  lot.articol.rambursat
  batch.cancel_requested
  lot.expiratbatch.reconciled

  Registrul la nivel de articol este esențial. Dacă 45.000 de articole sunt finalizate și 5.000 expiră, chiriașul ar trebui să fie facturat pentru munca finalizată a furnizorului, nu pentru manifestul original ca un singur blob nediferențiat.

  Construiți adaptoare de furnizor ca traducători, nu proprietari de logica de afaceri

  Fiecare adaptor de furnizor ar trebui să știe cum să transforme job-ul de gateway, să furnizeze lotul de gateway, să furnizeze starea de descărcare, să reia formatul de descărcare sau să-l sondajeze. rezultate și mapați rezultatele native înapoi la înregistrările normalizate.

  Păstrați politica locatarilor în afara adaptorului. Adaptorul nu ar trebui să decidă dacă un client are suficient buget, dacă un client partener este suspendat sau dacă solicitările pot fi stocate. Acestea sunt decizii de gateway.

  Responsabilitățile adaptorului

  • Afișează manifeste de solicitare specifice furnizorului.
  • Încărcați fișiere de intrare sau creați operațiuni ale furnizorului.
  • Stochează identificatorii furnizorului în metadate.
  • Mapați starea nativă la starea normalizată.
  • Preluați elementele de ieșire și de eroare.
  • Recuperați elementele de ieșire. rezultate.
  • Returnați înregistrările de utilizare native atunci când sunt disponibile.
  • Erori care pot fi reîncercate de suprafață versus erori ale terminalului.

  Responsabilități ale gateway-ului

  • Autentificați chiriașul și cheia API.
  • Aplicați controalele pentru echipă, proiect și clienți.
  • Rezolvați politicile de modelare a modelului.
  • Rezolvați aliasurile de model. capabilități.
  • Rezervați și stabiliți bugetul.
  • Persistați starea postului și a articolului.
  • Implementați politica de păstrare.
  • Expunerea analizelor și exporturilor.

  Această separare face mai ușoară adăugarea unui nou furnizor fără a rescrie facturarea, analiza sau guvernanța chiriașilor.

  2>Întregest rezultat
  2>impregnare. este locul în care multe sisteme batch duplică accidental taxele sau pierd parțial lucru. Tratați ingestia ca pe un proces repetabil. Ar trebui să fie sigur să descărcați de două ori același fișier de ieșire, să procesați aceeași operațiune de furnizor de două ori sau să redați același eveniment webhook de două ori.

  Recomandare: utilizați chei de idempotitate la nivel de articol și constrângeri de unicitate a registrului. Un rezultat pentru job_id + custom_id ar trebui să se stabilească exact o dată, chiar dacă asimilarea este reîncercată.

  Un flux de asimilare robust:

  1. Achiziționați o blocare de scurtă durată pentru lucrare sau artefact rezultat.
  2. Preluați ieșirea furnizorului și artefactele de eroare.
  3. Partează înregistrările rezultate din fiecare articol în funcție de eveniment.
  5. . custom_id sau ID-ul articolului gateway.
  6. Scrieți metadatele rezultatelor și utilizarea într-o tranzacție.
  7. Creați un eveniment de decontare registru numai dacă nu există deja unul.
  8. Actualizați numărul de locuri de muncă din stările articolului, nu din ipoteze.
  9. Eliberați rezervarea bugetului neutilizat atunci când sunt cunoscute toate rezervările bugetare neutilizate.

  10. sunt cunoscute. verificați semnăturile și protejați împotriva reluării. Dacă este necesară interogarea, utilizați sondajul adaptiv: interogați frecvent aproape de finalizarea așteptată, retrageți în perioadele de lungă durată și opriți-vă după soluționarea terminalului.

      Reîncercați articole, nu lucrări întregi

      Recomandare: reîncercați la nivel de articol ori de câte ori este posibil. Reîncercările întregii lucrări sunt simple, dar cresc riscul de duplicare a lucrărilor și fac facturarea mai dificilă.

      Clasificați eșecurile înainte de a reîncerca:

      • Erori de validare:, de obicei, până când solicitarea este remediată.
      • Erorile furnizorului 5xx: adesea reîncercate cu rata de eșec sau backoff. numai după ce capacitatea este disponibilă.
      • Blocuri de siguranță: nu reîncercați orbește; ruta către gestionarea politicii.
      • Elemente expirate: pot fi reîncercate într-o nouă lucrare dacă locatarul dorește în continuare munca și bugetul permite.

      O reîncercare ar trebui să creeze un nou articol legat de originalul:

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

      Nu retrimiteți articolele finalizate doar pentru că făceau parte dintr-o lucrare care s-a încheiat ca completed_with_errors sau expirat.

      Decideți ce să stocați: rezultate brute, indicatori sau hashe-uri

      Sistemele de loturi sunt locuri tentante pentru acumularea de solicitări și rezultate. Acest lucru poate fi util pentru exporturi și depanare, dar crește responsabilitatea de păstrare a datelor.

      Recomandare: faceți politica de stocare configurabilă de către chiriaș. Pentru sarcinile de lucru sensibile, stocați metadate, hashuri, utilizare și indicatori de rezultat, mai degrabă decât solicitări și rezultate brute.Pentru încărcături de lucru mai puțin sensibile, stocarea normală a rezultatelor poate fi acceptabilă dacă ferestrele de reținere, controalele de acces și fluxurile de lucru de ștergere sunt clare.

      Urmăriți cel puțin:

      • Dacă a fost stocată intrarea brută.
      • Dacă a fost stocată ieșirea brută.
      • Unde există artefacte rezultate ale furnizorului.
      >
      • Recuperare. termenul limită de ștergere.
      • Hash de solicitare și răspuns pentru audit fără expunere a conținutului.

      Fapt verificat: rezultatele antropice sunt disponibile timp de 29 de zile de la creare și izolate în spațiul de lucru. Acest tip de fereastră de preluare specifică furnizorului ar trebui să se reflecte în metadatele gateway-ului și în exporturile orientate către chiriași.

      Expunerea analizelor care se potrivesc cu modul în care funcționează echipele

      Analitica loturilor ar trebui să existe atât la nivel de job, cât și la nivel de articol. Un proprietar de produs dorește să știe dacă o îmbogățire nocturnă a fost finalizată. Un administrator financiar dorește costuri în funcție de chiriaș, model și client. Un inginer dorește să știe ce clasă de eșec să reîncerce.

      Măricile utile includ:

      • Numărul de articole trimise, finalizate, eșuate, expirate și anulate.
      • Cost estimat versus costul decontat.
      • Buget rezervat încă păstrat.
      • Jetonele de intrare și de ieșire. expuneți-le.
      • Numărul de reîncercări și rata de succes a reîncercărilor.
      • Timp mediu în stările de așteptare, de rulare și de finalizare.
      • Erorile de validare cele mai importante în funcție de punct final și model.
      • Atribuirea clienților partenerului.

      Pentru utilizatorii API-ului partener, expuneți joburile în lot ca resurse aferente clientului. Acest lucru permite agențiilor și constructorilor SaaS să ofere procesare AI offline, păstrând în același timp acreditările furnizorului în amonte, reconcilierea facturării și gestionarea limitelor de tarife în interiorul gateway-ului.

      Compartimentele pentru a face explicit

      Abstracția gateway-ului versus capacitatea specifică furnizorului: un contract unificat nu poate simplifica fiecare integrare, dar nu poate simplifica fiecare integrare. Păstrați erorile de capacitate explicite.

      Rezervarea bugetului versus acuratețea estimărilor: rezervarea îi protejează pe chiriași de locurile de muncă eșuate, dar estimările pot fi greșite. Registrul trebuie să accepte ajustări, rambursări și gestionarea depășirilor.

      Sondarea versus webhooks: sondarea este simplă și de încredere, dar poate irosi apelurile API și poate întârzia finalizarea. Webhook-urile sunt mai rapide, dar necesită verificarea semnăturii, protecție la redare și monitorizare.

      Stocare rezultate brute versus minimizarea reținerii: stocarea rezultatelor normalizate îmbunătățește exporturile și analizele, dar crește sarcina conformității. Chiriașii sensibili pot prefera indicatorii și codurile hash.

      Loturi mari față de loturi în bucăți: loturile uriașe pot îmbunătăți eficiența furnizorului, dar bucățile mai mici reduc raza de explozie și fac reîncercările mai ușoare.

      Lista de verificare a implementării

      • Creați o suprafață separată pentru lot.
      • Înainte de sarcina de înregistrare API. trimitere.
      • Solicită ID-uri de job gateway și ID-uri personalizate per articol.
      • Normalizează stările în timp ce stochează metadatele furnizorului nativ.
      • Construiți o matrice de capabilități pentru fiecare adaptor de lot de furnizor.
      • Validați manifestele înainte de rezervarea bugetului.
      • Rezervați bugetul chiriașului înainte de expediere.
      • Rezervați bugetul real înainte de livrare.
      • asimilarea rezultatelor.
      • Faceți asimilarea rezultatului idempotentă.
      • Reîncercați elementele eșuate în mod selectiv, nu lucrări întregi în mod orbește.
      • Urmăriți termenele limită de recuperare ale furnizorilor și politica de păstrare a gateway-ului.
      • Expuneți analiza jobului și a articolelor chiriașilor și clienților parteneri.

      Predicții:>>

      Predicții:>> 2. execuția loturilor va deveni o parte normală a infrastructurii de automatizare AI, nu doar un mecanism de reducere. Pe măsură ce echipele execută mai multe evaluări, sarcini de curățare a datelor, analize de siguranță și conducte de îmbogățire, se vor aștepta ca sarcinile de lucru asincrone să aibă aceeași guvernanță ca și apelurile API sincrone.

      Predicție: API-urile batch ale furnizorilor vor continua să difere în moduri utile. Unele se vor optimiza pentru fișiere, altele pentru operațiuni de lungă durată, iar altele pentru seturi de date gestionate sau apeluri inverse de evenimente. Un strat de adaptor de gateway va deveni mai valoros, nu mai puțin, deoarece contractul operațional de deasupra adaptoarelor poate rămâne stabil.

      Concluzie acționabilă

      Nu fixați procesarea loturilor pe un gateway AI API ca trapă de evacuare specifică furnizorului. Construiți-l ca un subsistem durabil cu propriile înregistrări de locuri de muncă, identificatori de articole, model de stare, adaptoare de furnizor, rezervare bugetară, asimilare idempotent și analize.

      Cea mai importantă alegere de proiectare este contabilitatea la nivel de articol. Odată ce fiecare solicitare dintr-un lot are o identitate stabilă, gateway-ul poate reconcilia rezultatele neordonate, reîncerca doar lucrările eșuate, facturează doar munca finalizată a furnizorului și poate arăta chiriașilor ce s-a întâmplat.Aceasta este diferența dintre trimiterea de fișiere către un furnizor și operarea unui API multi-model de încredere pentru sarcini de lucru asincrone.

      Lectură similară

      • API billing, reserve, settle model
      • analitice de utilizare la nivel de gateway și design token ledger
      • când sarcinile de lucru tolerante la latență se potrivesc procesării în lot