Treballs per lots unificats mitjançant una passarel·la d'API AI: cues duradores, adaptadors de proveïdors i facturació a nivell de llogater

API pública recomanada: separeu les tasques per lots de les finalitzacions sincròniques

Recomanació: exposa les tasques per lots com la seva pròpia superfície de l'API, no com una marca especial a les finalitzacions del xat. Una sol·licitud síncrona i una tasca per lots asíncrona tenen una semàntica de cicle de vida, facturació, reintent i recuperació de resultats diferents.

Un contracte de passarel·la pràctic inclou aquestes operacions:

• create_job: crea un esborrany de treball propietat d'un inquilí, projecte, clau o client soci.
• >
• >upload_manifest: afegiu sol·licituds individuals amb identificadors d'elements estables.
• enviament: validar, reservar pressupost, seleccionar el proveïdor, enviar i bloquejar el manifest enviat.
• get_status: retornar treballs normalitzats i recomptes d'articles.
• article_results, errors i resultats de la llista de pàgines, errors i resultats de la pàgina. ús.
• cancel·lar: sol·licitar la cancel·lació, sense prometre la terminació immediata.
• export_usage: exportar registres de costos a nivell de treball i a nivell d'article per a sistemes d'anàlisi o facturació.

Exemple d'objecte de feina pública:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "model": "anàlisi-gran",
  "status": "en execució",
  "comptes": {
    "enviat": 50000,
    "completat": 31240,
    "fallit": 180,
    "caducat": 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"
}

L'objecte públic no ha d'exposar els ID de fitxers del proveïdor, els noms d'operacions o els errors en brut de manera predeterminada. Aquestes pertanyen a les metadades orientades a l'operador.

Utilitzeu registres de treball duradors com a font de veritat

Una capa de lots propietat de la passarel·la necessita un estat durador abans que s'enviï res amunt. No confieu en els registres de lots del proveïdor com a únic magatzem estatal. Els registres del proveïdor són necessaris, però no coneixen la vostra jerarquia d'inquilí, les reserves pressupostàries, els àlies de model intern, els clients associats o els requisits d'anàlisi.

Model de base de dades mínim

Un esquema útil té tres nivells:

1. Treball per lots

batch_jobs
- job_id
- identificador_inquilí
- project_id
- customer_id es pot nul·lar- api_key_id
- punt final
- model_sol·licitat
- proveïdor_resolt
- model_proveïdor_resolt
- estat
- nombre_elements
- fitxes_d'entrada_estimada
- fitxes_de_sortida_estimada
- import_reservat
- import_soldat
- creat_a
- enviat_a
- completat_a
- caduca_a les
- termini_de_recuperació
- cancellation_requested_at

2. Element de lot

batch_items
- job_id
- item_id
- id_personalitzat
- clau_idempotència
- request_hash
- estat
- provider_request_index es pot nul·lar
- fitxes_estimades
- actual_input_tokens anul·lables
- actual_output_tokens anul·lables
- import_soldat que es pot nul·lar
- punter_resultat es pot nul·lar
- error_code nul·la
- retry_of_item_id es pot nul·lar
- creat_a
- assentat_a

3. Metadades del proveïdor

batch_provider_metadata
- job_id
- proveïdor
- provider_batch_id nul·lable
- input_file_id nul·lable
- output_file_id nul·lable
- error_file_id nul·lable
- nom_operació es pot nul·lar
- punt final
- regió anul·lable
- estat_natiu
- native_request_counts jsonb
- darrera_enquesta
- raw_error_pointer nullable

Mantenir les metadades del proveïdor separades del contracte de treball públic permet que la passarel·la evolucioni els adaptadors del proveïdor sense trencar les API orientades a l'inquilí.

Requereix identificadors d'elements estables abans de l'enviament

Recomanació: generar una porta d'accés per i requerir una porta d'accés custom_id o clau d'idempotència abans de l'enviament. No concilieu mai els resultats per ordre.

Anthropic adverteix explícitament que l'ordre dels resultats no està garantit i recomana valors significatius de custom_id. Fins i tot quan un proveïdor sembla preservar l'ordre, una passarel·la no hauria de dependre d'ella. Les feines es redueixen, es tornen a intentar, es cancel·len, es completen parcialment i es tornen a ingerir. Les hipòtesis de la comanda acaben fallant.

Un format d'identificador d'article segur és descriptiu però no sensible:

tenantA.invoice_extraction.2026-08-19.row_000381

Eviteu posar correus electrònics, noms, títols de documents o secrets de clients en brut als identificadors. Emmagatzemeu dades de correlació sensibles a la vostra pròpia base de dades d'inquilí, no dins d'identificadors visibles pel proveïdor.

Normalitzeu els estats sense esborrar els detalls del proveïdor

Les API de lots del proveïdor exposen cicles de vida diferents. La passarel·la hauria de normalitzar-los en una petita màquina d'estat intern que els quadres de comandament, la facturació i l'automatització puguin entendre.

Cicle de vida normalitzat recomanat:

• esborrany: la feina existeix però encara es pot editar.
• validació: la validació de la passarel·la o del proveïdor encara no s'està executant. processant.
• executant: el proveïdor està processant elements.
• finalitzant: el proveïdor ha acabat el càlcul i està preparant els artefactes de resultats.
• completat: tots els elements acceptats han arribat a un èxit del terminal.
• completed_with_errors: alguns elements reeixits. ha fallat.
• caducat: la finestra del proveïdor s'ha acabat abans que s'hagi completat tot el treball.
• cancel_requested: l'arrendatari va demanar la cancel·lació, però el treball facturable final no s'ha liquidat.
• cancel·lat: la cancel·lació s'ha resolt.
• cancel_requested: error d'execució.
• no s'ha resolt. errors del proveïdor natiu en etiquetes genèriques massa aviat. Els operadors encara necessiten accés a estats natius, errors de validació, recomptes de sol·licituds, identificadors de fitxers i noms d'operacions quan es depuren.

  Validació amb una matriu de capacitats abans de l'enviament

  Recomanació: executeu la validació prèvia al control abans de la reserva del pressupost i l'enviament del proveïdor. El mode per lots no és només un mode síncron amb un retard. És possible que alguns models, punts finals, característiques de sol·licitud, regions i configuracions d'eines no siguin compatibles amb l'API de lots d'un proveïdor.

  La vostra matriu de capacitat interna hauria de comprovar:

  • Punt final admès: xat, missatges, incrustacions, moderació o generació.
  • Elegibilitat del model per al mode de lots, mida de fitxer de càrrega i mida d'elements per lots, recompte de sol·licitud de treball i mida de Maxi
  • . mida.
  • Si la transmissió està prohibida.
  • Compatibilitat amb l'ús d'eines i les trucades de funcions.
  • Suport estructurat de sortida o esquema JSON.
  • Suport d'imatge, àudio o entrada multimodal.
  • Restriccions de regió i residència.
  • Finestres de retenció i recuperació de resultats. límits.
  • Semàntica de cancel·lació.

  Una bona resposta de verificació prèvia és específica:

  {
    "error": "batch_capability_not_supported",
    "message": "L'adaptador per lots del proveïdor seleccionat no admet respostes en temps real. Elimineu stream=true o trieu un punt final síncron.",
    "field": "elements[*].request.stream"}

  Això és més útil que acceptar la feina i fallar-la després d'una passada de validació amunt.

  Reserveu el pressupost de l'arrendatari i, a continuació, liquideu l'ús real

  L'execució per lots complica la facturació perquè la passarel·la pot perdre l'accés sincrònic a l'ús exacte fins que els fitxers de resultats estiguin disponibles. El patró segur és cotitzar, reservar, enviar, ingerir, liquidar i conciliar.

  Fets verificats: OpenAI afirma que el preu de l'API per lots s'ofereix amb un descompte en comparació amb les API síncrones i que els lots vençuts o cancel·lats encara poden retornar treballs acabats que siguin facturables. Anthropic assenyala que el processament per lots d'alt rendiment pot superar lleugerament el límit de despesa de l'espai de treball, cosa que fa que la reserva i la liquidació posterior a la passarel·la siguin importants.

  Recomanació: reserveu el pressupost de l'arrendatari abans de l'enviament mitjançant fitxes estimades, regles de preus de proveïdor seleccionades i un marge de seguretat. Després d'ingerir els resultats, establiu l'ús real a nivell d'element. Si l'estimació era massa alta, allibereu la reserva no utilitzada. Si era massa baix, apliqueu la política d'excés configurada per l'arrendatari.

  Esdeveniments pràctics del llibre major:

  batch.estimated
  lot.reservat
  lot.enviat
  lot.element.soldat
  lot.element.reemborsat
  batch.cancel_requested
  lot.caducatbatch.reconciled

  El llibre major a nivell d'article és essencial. Si s'han completat 45.000 elements i 5.000 caduquen, s'ha de facturar a l'arrendatari el treball completat del proveïdor, no el manifest original com un únic blob indiferenciat.

  Crea adaptadors de proveïdors com a traductors, no propietaris de la lògica empresarial

  Cada adaptador de proveïdors ha de saber com transformar el treball de passarel·la, enviar-lo en el format de descàrrega o tornar a enquestar l'estat. resultats i mapegeu els resultats natius als registres normalitzats.

  Mantingueu la política d'inquilí fora de l'adaptador. L'adaptador no ha de decidir si un client té prou pressupost, si un client soci està suspès o si es poden emmagatzemar les sol·licituds. Aquestes són decisions de passarel·la.

  Responsabilitats de l'adaptador

  • Representar manifests de sol·licitud específics del proveïdor.
  • Penjar fitxers d'entrada o crear operacions del proveïdor.
  • Emgatzemar els identificadors del proveïdor a les metadades.
  • Mapejar l'estat natiu a l'estat normalitzat.
  • Recuperar els elements de sortida i errors. resultats.
  • Torna els registres d'ús natius quan estiguin disponibles.
  • Reintent a la superfície versus errors de terminal.

  Responsabilitats de passarel·la

  • Autenticar l'arrendatari i la clau de l'API.
  • Aplicar controls d'equip, de projectes i de clients.
  • Resolver polítiques d'àlies de model.
  • Validació d'àlies de model.
  • Valida. capacitats.
  • Reservar i liquidar el pressupost.
  • Mantenir l'estat de la feina i de l'article.
  • Aplicar la política de retenció.
  • Exposar les anàlisis i les exportacions.

  Aquesta separació facilita afegir un proveïdor nou sense haver de reescriure la facturació, les anàlisis o la governança dels inquilins.

  2>Ingest resultats. és on molts sistemes per lots dupliquen els càrrecs accidentalment o perden treball parcial. Tracta la ingestió com un procés repetible. Hauria de ser segur baixar el mateix fitxer de sortida dues vegades, processar la mateixa operació del proveïdor dues vegades o reproduir el mateix esdeveniment webhook dues vegades.

  Recomanació: utilitzeu claus d'idempotència a nivell d'element i restriccions d'unicitat del llibre major. Un resultat per a job_id + custom_id s'hauria de resoldre exactament una vegada, fins i tot si es torna a intentar la ingestió.

  Un flux d'ingestió sòlid:

  1. Adquirir un bloqueig de curta durada per al treball o l'artefacte del resultat.
  2. Obtenir la sortida del proveïdor i els artefactes d'error.
  3. Analitzar els registres de resultats de cada element per normalitzar-los. custom_id o identificador d'element de passarel·la.
  4. Escriu metadades i ús del resultat en una transacció.
  5. Creeu un esdeveniment de liquidació del llibre major només si encara no n'hi ha cap.
  6. Actualitzeu el recompte de treballs a partir dels estats de l'element, no a partir de supòsits.
  7. Alliberar la reserva de pressupost no utilitzada quan es coneguin totes les reserves de pressupost de l'estat del terminal no utilitzades.
  verificar les signatures i protegir contra la reproducció. Si cal l'enquesta, utilitzeu l'enquesta adaptativa: enquesta freqüentment a prop de la finalització prevista, retrocedeix durant períodes de llarga durada i atureu-vos després de la liquidació del terminal.

  Torna a provar elements, no treballs sencers

  Recomanació: torna-ho a provar a nivell d'element sempre que sigui possible. Els reintents de tot el treball són senzills, però augmenten el risc de duplicar el treball i dificulten la facturació.

  Classifica els errors abans de tornar-ho a provar:

  • Errors de validació: normalment es terminal fins que la sol·licitud s'arregla.
  • Errors del proveïdor 5xx: sovint es poden tornar a provar amb una taxa de retard. només quan hi hagi capacitat disponible.
  • Blocs de seguretat: no ho torneu a intentar cegament; ruta cap a la gestió de la política.
  • Elements caducats: es pot tornar a provar en una feina nova si l'arrendatari encara vol que la feina i el pressupost ho permetin.

  Un nou intent hauria de crear un element nou enllaçat a l'original:

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

  No torneu a enviar els elements completats només perquè formaven part d'un treball que va acabar com a completed_with_errors o caducat.

  Decideu què voleu emmagatzemar: resultats en brut, punters o hash

  Els sistemes per lots són llocs temptadors per acumular sol·licituds i sortides. Això pot ser útil per a les exportacions i la depuració, però augmenta la responsabilitat de la retenció de dades.

  Recomanació: feu que la política d'emmagatzematge sigui configurable per l'inquilí. Per a càrregues de treball sensibles, emmagatzemeu metadades, hash, ús i punters de resultats en lloc de sol·licituds i sortides en brut.Per a càrregues de treball menys sensibles, l'emmagatzematge de resultats normalitzat pot ser acceptable si les finestres de retenció, els controls d'accés i els fluxos de treball d'eliminació estan clars.

  Fes un seguiment com a mínim de:

  • Si s'ha emmagatzemat l'entrada en brut.
  • Si s'ha emmagatzemat la sortida en brut.
  • On els artefactes de resultats del proveïdor estan vius.
  >
  • Recuperació de dades. data límit d'eliminació.
  • Hash de sol·licitud i resposta per a l'auditoria sense exposició de contingut.

  Fet verificat: Anthropic afirma que els resultats del lot estan disponibles durant 29 dies després de la creació i aïllats dins de l'espai de treball. Aquest tipus de finestra de recuperació específica del proveïdor s'hauria de reflectir a les metadades de la passarel·la i a les exportacions orientades als inquilins.

  Exposa les analítiques que coincideixen amb el funcionament dels equips

  Les analítiques per lots haurien d'existir tant a nivell de treball com d'element. El propietari del producte vol saber si s'ha completat un enriquiment nocturn. Un administrador financer vol un cost per inquilí, model i client. Un enginyer vol saber quina classe d'errors ha de tornar a provar.

  Les mètriques útils inclouen:

  • Recomptes d'articles enviats, completats, fallits, caducats i cancel·lats.
  • Cost estimat en comparació amb el cost liquidat.
  • Pressupost reservat encara disponible.
  • Fitxa d'entrada i sortida.
  • Fitxas d'entrada i sortida. exposar-los.
  • Recompte de reintents i percentatge d'èxit de reintents.
  • Temps mitjà en estats en cua, execució i finalització.
  • Errors de validació principals per punt final i model.
  • Atribució del client del partner.

  Per als usuaris de l'API del partner, exposa les feines per lots com a recursos de l'àmbit del client. Això permet que les agències i els creadors de SaaS ofereixin processament d'IA fora de línia mentre mantenen les credencials del proveïdor, la conciliació de la facturació i el maneig del límit de tarifes dins de la passarel·la.

  Compartiments per fer explícits

  L'abstracció de la passarel·la versus la capacitat específica del proveïdor: un contracte unificat no pot simplificar totes les funcions d'integració idèntiques. Manteniu explícits els errors de capacitat.

  Reserva del pressupost versus precisió de l'estimació: la reserva protegeix els llogaters de les feines que no es troben, però les estimacions poden ser incorrectes. El llibre major ha d'admetre ajustos, reembossaments i gestió d'excés.

  Enquestes versus webhooks: l'enquesta és senzilla i fiable, però pot malgastar les trucades de l'API i retardar la finalització. Els webhooks són més ràpids, però requereixen verificació de signatura, protecció de reproducció i supervisió.

  Emmagatzematge de resultats en brut versus minimització de retenció: emmagatzemar resultats normalitzats millora les exportacions i les anàlisis, però augmenta la càrrega de compliment. Els inquilins sensibles poden preferir punters i hashes.

  Lots grans en comparació amb lots fragmentats: lots enormes poden millorar l'eficiència del proveïdor, però els trossos més petits redueixen el radi d'explosió i faciliten els reintents.

  Llista de comprovació d'implementació

  • Creeu un treball per lots separat i una superfície de registre d'API per lots
  • . enviament.
  • Requereix identificadors de treball de passarel·la i identificadors personalitzats per element.
  • Normalitzeu els estats mentre emmagatzemeu metadades del proveïdor nadiu.
  • Construïu una matriu de capacitats per a cada adaptador per lots de proveïdors.
  • Valideu els manifestos abans de reservar pressupost.
  • Reserveu el pressupost real de l'inquilí abans de l'enviament de l'article. ingestió.
  • Fes que la ingestió de resultats sigui idempotent.
  • Torna a provar els elements que han fallat de manera selectiva, no les feines senceres a cegues.
  • Fes un seguiment dels terminis de recuperació del proveïdor i de la política de retenció de passarel·les.
  • Exposa l'anàlisi de feines i articles als inquilins i als clients associats.

  Prediccions:

  Encapçalament:

Prediccions: 2. l'execució per lots es convertirà en una part normal de la infraestructura d'automatització d'IA, no només un mecanisme de descompte. A mesura que els equips realitzin més avaluacions, tasques de neteja de dades, revisions de seguretat i canalitzacions d'enriquiment, esperaran que les càrregues de treball asíncrones tinguin la mateixa governança que les trucades d'API síncrones.

Predicció: les API de lots del proveïdor continuaran divergent de maneres útils. Alguns s'optimitzaran per a fitxers, d'altres per a operacions de llarga durada i d'altres per a conjunts de dades gestionats o devolució d'esdeveniments. Una capa d'adaptador de passarel·la serà més valuosa, no menys, perquè el contracte operatiu que hi ha a sobre dels adaptadors pot romandre estable.

Conclusió accionable

No connecteu el processament per lots a una passarel·la d'API d'IA com a escotilla d'escapament específica del proveïdor. Creeu-lo com un subsistema durador amb els seus propis registres de treball, identificadors d'elements, model d'estat, adaptadors de proveïdors, reserva de pressupost, ingesta d'idempotents i analítiques.

L'opció de disseny més important és la comptabilitat a nivell d'article. Una vegada que cada sol·licitud d'un lot té una identitat estable, la passarel·la pot conciliar els resultats no ordenats, tornar a provar només el treball fallit, facturar només el treball del proveïdor completat i mostrar als inquilins què ha passat.Aquesta és la diferència entre enviar fitxers a un proveïdor i operar una API multimodel fiable per a càrregues de treball asíncrones.

Lectura relacionada

• API billing, reserve, AI patró
• analítica d'ús a nivell de passarel·la i disseny de registre de testimonis
• quan les càrregues de treball tolerants a la latència s'adapten al processament per lots