Lavori batch unificati tramite un gateway API AI: code durevoli, adattatori del provider e fatturazione a livello di tenant

L'elaborazione batch non deve essere trattata come una porta secondaria attorno al gateway API AI. Se le valutazioni, l'arricchimento dei documenti, l'estrazione, i controlli di moderazione o i processi di incorporamento lasciano il percorso di richiesta sincrona, hanno comunque bisogno di controlli del tenant, attribuzione dei costi, nuovi tentativi, verificabilità e analisi dell'utilizzo.

Il modello di implementazione è quello di rendere l'esecuzione batch un sottosistema gateway di prima classe. Il gateway dovrebbe esporre un contratto di lavoro indipendente dal fornitore mentre si adatta dietro le quinte a OpenAI, Anthropic, Gemini e alle future API batch dei fornitori.

Il problema del lettore: le API batch sono simili nell'intento, diverse nel funzionamento

I carichi di lavoro con tolleranza alla latenza sono una soluzione naturale per l'esecuzione batch. La parte difficile non è decidere se un lavoro può aspettare. La parte difficile è eseguire il lavoro in batch in modo coerente tra i fornitori.

Fatti verificati: l'API Batch di OpenAI è asincrona, legge le richieste da un file caricato, scrive risposte in un file di output e attualmente utilizza una finestra di elaborazione di 24 ore. OpenAI elenca stati come convalida in corso, failed, in_progress, finalizing, completed, expired, cancelling e cancelled. L'API Message Batches di Anthropic elabora molte richieste di messaggi in modo asincrono, gestisce ciascuna richiesta in modo indipendente, richiede il polling e restituisce i risultati al termine dell'elaborazione. Anthropic consiglia inoltre valori custom_id significativi perché l'ordine dei risultati non è garantito. L'API Batch di Gemini espone metodi di tipo operativo a lunga esecuzione come metodi di elenco, annullamento, eliminazione e aggiornamento e la relativa operazione di annullamento è descritta come il massimo sforzo.

Queste differenze contano una volta aggiunti requisiti aziendali reali:

• Quale tenant, cliente, progetto o chiave API possiede ciascun elemento?
• È stato prenotato il budget prima che il lavoro lasciasse il gateway?
• Quali elementi completati sono fatturabili se il batch scade o è annullato?
• Come vengono ritentati gli errori parziali senza duplicare il lavoro riuscito?
• Per quanto tempo possono essere recuperati i file dei risultati e cosa deve archiviare il gateway?
• Un partner può creare un'elaborazione batch con ambito cliente senza esporre le credenziali del fornitore upstream?

La risposta non è nascondere ogni differenza del fornitore. La risposta è normalizzare il contratto operativo preservando i metadati nativi del provider per il debug, la riconciliazione e il supporto.

API pubblica consigliata: separare i lavori batch dai completamenti sincroni

Raccomandazione: esporre i lavori batch come la propria superficie API, non come un flag speciale sui completamenti della chat. Una richiesta sincrona e un lavoro batch asincrono hanno una diversa semantica di ciclo di vita, fatturazione, tentativi e recupero dei risultati.

Un contratto gateway pratico include queste operazioni:

• create_job: crea un lavoro bozza di proprietà di un tenant, progetto, chiave o cliente partner.
• append_items o upload_manifest: aggiungi richieste individuali con un elemento stabile identificatori.
• invia: convalida, riserva budget, seleziona fornitore, spedizione e blocca il manifest inviato.
• get_status: restituisce il conteggio normalizzato dei lavori e degli articoli.
• list_results: sfoglia i risultati degli articoli normalizzati, gli errori e l'utilizzo.
• cancel: richiede l'annullamento, senza promettere l'immediato terminazione.
• export_usage: esporta record di costi a livello di lavoro e di articolo per sistemi di analisi o fatturazione.

Esempio di oggetto di lavoro pubblico:

{
  "job_id": "lavoro_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "modello": "analisi-grande",
  "stato": "in esecuzione",
  "conta": {
    "inviato": 50000,
    "completato": 31240,
    "fallito": 180,
    "scaduto": 0
  },
  "costo": {
    "stimato": "184.20",
    "riservato": "205,00",
    "risolto": "117.43",
    "valuta": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "subject_at": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"
}

Per impostazione predefinita, l'oggetto pubblico non deve esporre ID di file del provider, nomi di operazioni o errori upstream non elaborati. Questi appartengono ai metadati rivolti all'operatore.

Utilizza record di lavoro durevoli come fonte di verità

Un livello batch di proprietà del gateway necessita di uno stato durevole prima che qualsiasi cosa venga inviata a monte. Non fare affidamento sui record batch del fornitore come unico archivio statale. I record del fornitore sono necessari, ma non conoscono la gerarchia dei tenant, le prenotazioni del budget, gli alias del modello interno, i clienti dei partner o i requisiti di analisi.

Modello di database minimo

Uno schema utile ha tre livelli:

1. Lavoro batch

batch_jobs
- id_lavoro
- id_inquilino
- id_progetto
- customer_id nullable- api_key_id
- punto finale
- modello_richiesto
- risolto_provider
- risolto_provider_model
- stato
- conteggio_articoli
- stima_input_token
- token_output_stimati
- importo_riservato
- importo_stabilito
- creato_il
- presentato_a
- completato_il
- scade_il
- scadenza_recupero
- cancellazione_richiesta_at

2. Articolo batch

batch_items
- id_lavoro
- id_oggetto
- ID_personalizzato
- chiave_idempotenza
- richiesta_hash
- stato
- provider_request_index nullable
- gettoni_stimati
-actual_input_tokens nullable
-actual_output_tokens nullable
- importo_stabilito nullable
- result_pointer nullable
- codice_errore nullable
- retry_of_item_id nullable
- creato_il
- saldato_alle

3. Metadati del fornitore

batch_provider_metadata
- id_lavoro
- fornitore
- provider_batch_id nullable
- input_file_id nullable
- output_file_id nullable
- error_file_id nullable
- nome_operazione nullable
- punto finale
- regione nullable
- stato_nativo
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Mantenere i metadati del provider separati dal contratto di lavoro pubblico consente al gateway di evolvere gli adattatori del provider senza interrompere le API rivolte al tenant.

Richiedi identificatori di elemento stabili prima dell'invio

Raccomandazione: genera un gateway job_id e richiedi prima un custom_id per elemento o una chiave di idempotency spedizione. Non riconciliare mai i risultati in base all'ordine.

Anthropic avverte esplicitamente che l'ordine dei risultati non è garantito e consiglia valori custom_id significativi. Anche quando un fornitore sembra preservare l’ordine, un gateway non dovrebbe dipendere da esso. I lavori vengono suddivisi in blocchi, ritentati, annullati, completati parzialmente e reinseriti. I presupposti per l'ordine alla fine falliscono.

Un formato identificatore di articolo sicuro è descrittivo ma non sensibile:

tenantA.invoice_extraction.2026-08-19.row_000381

Evita di inserire email, nomi, titoli di documenti o segreti del cliente non elaborati negli identificatori. Archivia i dati sensibili di correlazione all'interno del tuo database tenant, non all'interno degli ID visibili del provider.

Normalizza gli stati senza cancellare i dettagli del provider

Le API batch del provider espongono cicli di vita diversi. Il gateway dovrebbe normalizzarli in una piccola macchina a stati interna che dashboard, fatturazione e automazione possono comprendere.

Ciclo di vita normalizzato consigliato:

• bozza: il lavoro esiste ma è ancora modificabile.
• convalida in corso: la convalida del gateway o del provider è in esecuzione.
• in coda: accettato ma non ancora elaborazione.
• in esecuzione: il provider sta elaborando gli elementi.
• finalizzazione: il provider ha terminato il calcolo e sta preparando gli artefatti dei risultati.
• completato: tutti gli elementi accettati hanno raggiunto il terminale con esito positivo.
• completato_con_errori: alcuni elementi sono riusciti e altri non sono riusciti.
• scaduto: la finestra del provider è terminata prima che tutto il lavoro fosse terminato. completato.
• cancel_requested: l'inquilino ha chiesto di annullare, ma il lavoro finale fatturabile non è stato saldato.
• annullato: annullamento risolto.
• fallito: un errore a livello di lavoro ha impedito un'esecuzione utile.

Non comprimere troppo presto gli errori del provider nativo in etichette generiche. Gli operatori devono comunque accedere agli stati nativi, agli errori di convalida, ai conteggi delle richieste, agli ID file e ai nomi delle operazioni durante il debug.

Convalidare rispetto a una matrice di capacità prima dell'invio

Raccomandazione: eseguire la convalida preliminare prima della prenotazione del budget e dell'invio del provider. La modalità batch non è solo la modalità sincrona con un ritardo. Alcuni modelli, endpoint, funzionalità di richiesta, regioni e configurazioni di strumenti potrebbero non essere supportati dall'API batch di un provider.

La matrice delle capacità interne dovrebbe controllare:

• Endpoint supportato: chat, messaggi, incorporamenti, moderazione o generazione.
• Idoneità del modello per la modalità batch.
• Dimensione massima del lavoro, conteggio degli elementi, dimensione della richiesta e dimensione del file caricato.
• Se lo streaming è vietato.
• Supporto per l'utilizzo di strumenti e chiamate di funzioni.
• Supporto per output strutturato o schema JSON.
• Supporto per immagini, audio o input multimodale.
• Vincoli di regione e residenza.
• Finestre di conservazione del provider e di recupero dei risultati.
• Limiti di velocità e limiti di coda specifici del batch.
• Semantica di annullamento.

Una buona risposta preflight è specifico:

{
  "errore": "batch_capability_not_supported",
  "message": "L'adattatore batch del provider selezionato non supporta le risposte in streaming. Rimuovi stream=true o scegli un endpoint sincrono.",
  "field": "items[*].request.stream"}

Questo è più utile che accettare il lavoro e fallirlo dopo un passaggio di convalida upstream.

Riserva il budget del tenant, quindi stabilisci l'utilizzo effettivo

L'esecuzione in batch complica la fatturazione perché il gateway potrebbe perdere l'accesso sincrono all'utilizzo esatto finché non saranno disponibili i file dei risultati. Il modello sicuro è preventivo, prenotazione, invio, acquisizione, liquidazione e riconciliazione.

Fatti verificati: OpenAI afferma che i prezzi delle API batch sono offerti con uno sconto rispetto alle API sincrone e i batch scaduti o annullati potrebbero comunque restituire lavoro completato fatturabile. Anthropic sottolinea che l'elaborazione batch a throughput elevato può superare leggermente un limite di spesa dell'area di lavoro, rendendo importanti la prenotazione lato gateway e la liquidazione successiva.

Raccomandazione: riservare il budget dell'inquilino prima dell'invio utilizzando token stimati, regole sui prezzi del fornitore selezionato e un margine di sicurezza. Dopo aver importato i risultati, stabilisci l'utilizzo effettivo a livello di elemento. Se il preventivo fosse troppo alto, sciogli la prenotazione non utilizzata. Se era troppo basso, applica la politica di eccedenza configurata dal tenant.

Eventi pratici del registro:

batch.estimated
lotto.riservato
batch.inviato
lotto.articolo.saldato
lotto.articolo.rimborsato
batch.cancel_requested
batch.scadutobatch.reconciled

Il registro a livello di articolo è essenziale. Se 45.000 elementi vengono completati e 5.000 scadono, al tenant verrà addebitato il lavoro completato del provider, non il manifest originale come un singolo blob indifferenziato.

Crea adattatori del provider come traduttori, non proprietari della logica aziendale

Ogni adattatore del provider deve sapere come trasformare il lavoro del gateway nel formato batch del provider, inviarlo, eseguire il polling o recuperare lo stato, scaricare i risultati e mappare i risultati nativi su come normalizzati record.

Mantieni la politica del tenant all'esterno dell'adattatore. L'adattatore non deve decidere se un cliente dispone di budget sufficiente, se un cliente partner viene sospeso o se i prompt possono essere archiviati. Queste sono decisioni del gateway.

Responsabilità dell'adattatore

• Renderizzare manifest di richieste specifiche del provider.
• Caricare file di input o creare operazioni del provider.
• Archiviare gli identificatori del provider nei metadati.
• Mappare lo stato nativo sullo stato normalizzato.
• Recuperare output ed artefatti di errore.
• Analizzare i risultati a livello di elemento.
• Restituire i record di utilizzo nativi quando disponibile.
• Riprovabili in superficie rispetto a errori terminali.

Responsabilità del gateway

• Autenticare tenant e chiave API.
• Applicare controlli di team, progetto e cliente.
• Risolvere alias di modello e policy di routing del fornitore.
• Convalidare le funzionalità batch.
• Prenotare e definire il budget.
• Mantenere lavoro e articolo stato.
• Applica criteri di conservazione.
• Esponi analisi ed esportazioni.

Questa separazione semplifica l'aggiunta di un nuovo fornitore senza riscrivere fatturazione, analisi o governance del tenant.

Assimila i risultati in modo idempotente

L'importazione dei risultati è il luogo in cui molti sistemi batch duplicano accidentalmente gli addebiti o perdono il lavoro parziale. Trattare l'ingestione come un processo ripetibile. Dovrebbe essere sicuro scaricare due volte lo stesso file di output, elaborare due volte la stessa operazione del provider o riprodurre due volte lo stesso evento webhook.

Consiglio: utilizzare chiavi di idempotenza a livello di articolo e vincoli di unicità del registro. Un risultato per job_id + custom_id dovrebbe essere risolto esattamente una volta, anche se si tenta nuovamente l'importazione.

Un flusso di acquisizione robusto:

1. acquisizione di un blocco di breve durata per il lavoro o l'artefatto del risultato.
2. Recupera l'output del provider e gli artefatti di errore.
3. Analizza i record in eventi di risultati di elementi normalizzati.
4. Abbina ogni record in base a custom_id o ID elemento gateway.
5. Scrivi i metadati dei risultati e l'utilizzo in una transazione.
6. Crea un evento di liquidazione del registro solo se non ne esiste già uno.
7. Aggiorna i conteggi dei processi dagli stati degli elementi, non dalle ipotesi.
8. Rilascia la prenotazione del budget inutilizzato quando tutti gli stati terminali sono noti.

Se sono disponibili webhook, verifica le firme e proteggi dalla riproduzione. Se è necessario il polling, utilizza il polling adattivo: esegui il polling frequentemente in prossimità del completamento previsto, fai marcia indietro durante i periodi di lunga durata e interrompi dopo la liquidazione terminale.

Riprova elementi, non interi lavori

Raccomandazione: riprova a livello di elemento quando possibile. I tentativi dell'intero processo sono semplici, ma aumentano il rischio di lavoro duplicato e rendono più difficile la fatturazione.

Classificare gli errori prima di riprovare:

• Errori di convalida: solitamente terminali finché la richiesta non viene risolta.
• Errori 5xx del provider: spesso riprovabili con backoff.
• Errori relativi a quota o limite di velocità: riprova solo dopo che la capacità è stata raggiunta. disponibile.
• Blocchi di sicurezza: non riprovare alla cieca; percorso verso la gestione delle policy.
• Elementi scaduti: possono essere ritentati in un nuovo lavoro se l'inquilino desidera ancora il lavoro e il budget lo consente.

Un nuovo tentativo dovrebbe creare un nuovo elemento collegato all'originale:

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

Non inviare nuovamente gli elementi completati solo perché facevano parte di un lavoro terminato come completato_con_errori o scaduto.

Decidi cosa archiviare: risultati grezzi, puntatori o hash

I sistemi batch sono luoghi allettanti in cui accumulare prompt e output. Ciò può essere utile per le esportazioni e il debug, ma aumenta la responsabilità in materia di conservazione dei dati.

Consiglio: rendere la policy di archiviazione configurabile dal tenant. Per i carichi di lavoro sensibili, archivia metadati, hash, utilizzo e puntatori ai risultati anziché prompt e output non elaborati.Per carichi di lavoro meno sensibili, l'archiviazione normalizzata dei risultati può essere accettabile se le finestre di conservazione, i controlli di accesso e i flussi di lavoro di eliminazione sono chiari.

Traccia almeno:

• Se è stato archiviato l'input non elaborato.
• Se è stato archiviato l'output non elaborato.
• Dove si trovano gli artefatti dei risultati del provider.
• Scadenza per il recupero del provider.
• Scadenza per l'eliminazione del gateway.
• Hash di richiesta e risposta per l'audit senza esposizione del contenuto.

Fatto verificato: i risultati batch degli stati antropici sono disponibili per 29 giorni dopo la creazione e isolati all'interno dell'area di lavoro. Questo tipo di finestra di recupero specifica del provider dovrebbe riflettersi nei metadati del gateway e nelle esportazioni rivolte ai tenant.

Esporre analisi che corrispondono al modo in cui operano i team

Le analisi batch dovrebbero esistere sia a livello di lavoro che di articolo. Il proprietario di un prodotto desidera sapere se un arricchimento notturno è stato completato. Un amministratore finanziario desidera che i costi vengano suddivisi in base al tenant, al modello e al cliente. Un tecnico vuole sapere quale classe di errore riprovare.

I parametri utili includono:

• Conteggio degli articoli inviati, completati, non riusciti, scaduti e annullati.
• Costo stimato rispetto a quello stabilito.
• Budget riservato ancora trattenuto.
• Token di input e output per fornitore e modello.
• Indicatori di cache-hit in cui i provider li espongono.
• Riprova il conteggio e riprova con successo. tasso.
• Tempo medio negli stati in coda, in esecuzione e in fase di finalizzazione.
• Principali errori di convalida per endpoint e modello.
• Attribuzione cliente partner.

Per gli utenti API Partner, esporre i processi batch come risorse con ambito cliente. Ciò consente alle agenzie e ai costruttori SaaS di offrire l'elaborazione AI offline mantenendo le credenziali del fornitore a monte, la riconciliazione della fatturazione e la gestione dei limiti di tariffa all'interno del gateway.

Compromessi per rendere esplicito

Astrazione del gateway rispetto a funzionalità specifiche del fornitore: un contratto unificato semplifica l'integrazione, ma non può rendere identiche tutte le funzionalità del fornitore. Mantieni espliciti gli errori di capacità.

Prenotazione del budget rispetto all'accuratezza della stima: la prenotazione protegge gli inquilini da posti di lavoro in fuga, ma le stime possono essere errate. Il registro deve supportare aggiustamenti, rimborsi e gestione delle eccedenze.

Polling rispetto ai webhook: il polling è semplice e affidabile, ma può sprecare chiamate API e ritardare il completamento. I webhook sono più veloci, ma richiedono la verifica della firma, la protezione dalla riproduzione e il monitoraggio.

Archiviazione dei risultati grezzi rispetto alla minimizzazione della conservazione: l'archiviazione dei risultati normalizzati migliora le esportazioni e l'analisi, ma aumenta il carico di conformità. I tenant più sensibili potrebbero preferire puntatori e hash.

Lot di grandi dimensioni rispetto a batch suddivisi in blocchi: batch di grandi dimensioni possono migliorare l'efficienza lato provider, ma blocchi più piccoli riducono il raggio di esplosione e semplificano i tentativi.

Elenco di controllo per l'implementazione

• Crea una superficie API separata per i processi batch.
• Rendi persistenti i record di processi e articoli prima dell'invio al provider.
• Richiedi ID processo gateway e ID personalizzati per elemento.
• Normalizza gli stati durante l'archiviazione dei metadati nativi del provider.
• Crea una matrice di funzionalità per ciascun adattatore batch del provider.
• Convalida i manifest prima di riservare il budget.
• Prenota il budget del tenant prima dell'invio.
• Determina l'utilizzo effettivo a livello di elemento dopo l'acquisizione.
• Rendi idempotente l'acquisizione dei risultati.
• Riprova selettivamente gli elementi non riusciti, non interi processi ciecamente.
• Tracciare le scadenze di recupero del fornitore e la politica di conservazione del gateway.
• Esporre l'analisi di lavori e articoli a tenant e clienti partner.

Previsioni: dove sta andando questo modello

Previsione: l'esecuzione batch diventerà una parte normale dell'infrastruttura di automazione dell'intelligenza artificiale, non solo un meccanismo di sconto. Man mano che i team eseguono più valutazioni, attività di pulizia dei dati, revisioni della sicurezza e pipeline di arricchimento, si aspetteranno che i carichi di lavoro asincroni abbiano la stessa governance delle chiamate API sincrone.

Previsione: le API batch dei provider continueranno a divergere in modi utili. Alcuni ottimizzeranno per i file, altri per operazioni di lunga durata e altri per set di dati gestiti o callback di eventi. Un livello di adattatore gateway diventerà più prezioso, non meno, perché il contratto operativo sopra gli adattatori può rimanere stabile.

Conclusione attuabile

Non fissare l'elaborazione batch su un gateway API AI come una via di fuga specifica del provider. Costruiscilo come un sottosistema durevole con record di lavoro, identificatori di articolo, modello di stato, adattatori del fornitore, prenotazione del budget, acquisizione idempotente e analisi.

La scelta progettuale più importante è la contabilità a livello di articolo. Una volta che ogni richiesta all'interno di un batch ha un'identità stabile, il gateway può riconciliare i risultati non ordinati, riprovare solo il lavoro non riuscito, fatturare solo il lavoro completato dal fornitore e mostrare ai tenant cosa è successo.Questa è la differenza tra l'invio di file a un provider e il funzionamento di un'API multimodello affidabile per carichi di lavoro asincroni.

Leggi correlati

• preventivo, prenotazione, liquidazione e riconciliazione del modello di fatturazione dell'API AI
• analisi dell'utilizzo a livello di gateway e progettazione del registro dei token
• quando i carichi di lavoro con tolleranza alla latenza si adattano all'elaborazione batch