Travaux par lots unifiés via une passerelle API AI : files d'attente durables, adaptateurs de fournisseur et facturation au niveau du locataire

Le traitement par lots ne doit pas être traité comme une porte secondaire autour de votre passerelle API IA. Si les tâches d'évaluation, d'enrichissement de documents, d'extraction, de balayage de modération ou d'intégration quittent le chemin de requête synchrone, elles nécessitent toujours des contrôles locataires, une attribution des coûts, des tentatives, une auditabilité et des analyses d'utilisation.

Le modèle de mise en œuvre consiste à faire de l'exécution par lots un sous-système de passerelle de premier ordre. La passerelle doit exposer un contrat de travail indépendant du fournisseur tout en s'adaptant en coulisse aux API par lots d'OpenAI, Anthropic, Gemini et des futurs fournisseurs.

Le problème du lecteur : les API par lots ont une intention similaire, un fonctionnement différent

Les charges de travail tolérantes à la latence conviennent naturellement à l'exécution par lots. Le plus difficile n’est pas de décider si un emploi peut attendre. Le plus difficile est d'effectuer le travail par lots de manière cohérente entre les fournisseurs.

Faits vérifiés : L'API Batch d'OpenAI est asynchrone, lit les requêtes à partir d'un fichier téléchargé, écrit les réponses dans un fichier de sortie et utilise actuellement une fenêtre de traitement de 24 heures. OpenAI répertorie les statuts tels que validation, échec, in_progress, finalisation, terminé, expiré, annulation et annulé. L'API Message Batches d'Anthropic traite de nombreuses requêtes de messages de manière asynchrone, gère chaque requête indépendamment, nécessite une interrogation et renvoie les résultats une fois le traitement terminé. Anthropic recommande également des valeurs custom_id significatives car l'ordre des résultats n'est pas garanti. L'API Batch de Gemini expose des méthodes opérationnelles de longue durée, telles que les méthodes de liste, d'annulation, de suppression et de mise à jour, et son opération d'annulation est décrite comme étant un effort optimal.

Ces différences sont importantes une fois que vous ajoutez de réelles exigences commerciales :

• Quel locataire, client, projet ou clé API possède chaque élément ?
• Le budget a-t-il été réservé avant que la tâche ne quitte la passerelle ?
• Quels éléments terminés sont facturables si le lot expire ou est annulé ?
• Comment les échecs partiels sont-ils réessayés sans dupliquer le travail réussi ?
• Combien de temps les fichiers de résultats peuvent-ils être récupérés et que doit stocker la passerelle ?
• Un partenaire peut-il créer un traitement par lots à l'échelle du client sans exposer les informations d'identification du fournisseur en amont ?

La réponse n'est pas de cacher chaque différence entre les fournisseurs. La réponse est de normaliser le contrat d'exploitation tout en préservant les métadonnées natives du fournisseur pour le débogage, la réconciliation et la prise en charge.

API publique recommandée : séparer les tâches par lots des achèvements synchrones

Recommandation : exposer les tâches par lots comme leur propre surface d'API, et non comme un indicateur spécial sur les achèvements de chat. Une requête synchrone et une tâche par lots asynchrone ont des sémantiques différentes en matière de cycle de vie, de facturation, de nouvelle tentative et de récupération des résultats.

Un contrat de passerelle pratique comprend ces opérations :

• create_job : créez une ébauche de tâche appartenant à un client locataire, projet, clé ou partenaire.
• append_items ou upload_manifest : ajoutez des demandes individuelles avec un élément stable. identifiants.
• soumettre : valider, réserver le budget, sélectionner le fournisseur, expédier et verrouiller le manifeste soumis.
• get_status : renvoyer le nombre normalisé de travaux et d'articles.
• list_results : parcourir les résultats, les erreurs et l'utilisation des articles normalisés.
• annuler : demander l'annulation, sans promettre d'immédiat. résiliation.
• export_usage : exportez les enregistrements de coûts au niveau de la tâche et au niveau de l'article pour les systèmes d'analyse ou de facturation.

Exemple d'objet de tâche public :

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "id_client": "cust_123",
  "endpoint": "chat.completions",
  "model": "analyse-grande",
  "status": "en cours d'exécution",
  "compte": {
    "soumis": 50000,
    "terminé": 31240,
    "échec": 180,
    "expiré": 0
  },
  "coût": {
    "estimé": "184,20",
    "réservé": "205.00",
    "réglé": "117.43",
    "devise": "USD"
  },
  "created_at": "2026-08-19T10:00:00Z",
  "submit_at": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"

L'objet public ne doit pas exposer les ID de fichier du fournisseur, les noms d'opération ou les erreurs brutes en amont par défaut. Ceux-ci appartiennent aux métadonnées destinées à l'opérateur.

Utilisez des enregistrements de tâches durables comme source de vérité

Une couche de lots appartenant à une passerelle a besoin d'un état durable avant que quoi que ce soit ne soit soumis en amont. Ne comptez pas sur les enregistrements de lots du fournisseur comme seul magasin d'état. Les enregistrements du fournisseur sont nécessaires, mais ils ne connaissent pas la hiérarchie de vos locataires, les réservations budgétaires, les alias de modèle interne, les clients partenaires ou les exigences d'analyse.

Modèle de base de données minimum

Un schéma utile comporte trois niveaux :

1. Travail par lots

batch_jobs
- identifiant_travail
-tenant_id
- id_projet
- customer_id nullable- api_key_id
- point final
- modèle_demandé
- fournisseur_résolu
- modèle_provider_résolu
- statut
- item_count
-estimate_input_tokens
-estimate_output_tokens
- montant_réservé
- montant_réglé
- créé_à
- soumis_à
- terminé_à
- expire_at
- date limite de récupération
- Cancellation_requested_at

2. Article du lot

batch_items
- identifiant_travail
- item_id
- identifiant_personnalisé
- clé_idempotence
- request_hash
- statut
- supplier_request_index nullable
- jetons_estimés
- actual_input_tokens nullable
- actual_output_tokens nullable
- montant_réglé nullable
- result_pointer nullable
- error_code nullable
- retry_of_item_id nullable
- créé_à
- réglé_at

3. Métadonnées du fournisseur

batch_provider_metadata
- identifiant_travail
- fournisseur
- provider_batch_id nullable
- input_file_id nullable
- output_file_id nullable
- error_file_id nullable
- operation_name nullable
- point final
- région nullable
-statut_natif
- native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Garder les métadonnées du fournisseur séparées du contrat de travail public permet à la passerelle de faire évoluer les adaptateurs de fournisseur sans interrompre les API destinées aux locataires.

Exiger des identifiants d'élément stables avant l'expédition

Recommandation : générer une passerelle job_id et exiger un custom_id par article ou une clé d'idempotence avant l'expédition. Ne rapprochez jamais les résultats par ordre.

Anthropic avertit explicitement que l'ordre des résultats n'est pas garanti et recommande des valeurs custom_id significatives. Même lorsqu’un fournisseur semble maintenir l’ordre, une passerelle ne devrait pas en dépendre. Les tâches sont fragmentées, réessayées, annulées, partiellement terminées et réingérées. Les hypothèses de commande finissent par échouer.

Un format d'identifiant d'article sécurisé est descriptif mais non sensible :

tenantA.invoice_extraction.2026-08-19.row_000381

Évitez de mettre des e-mails bruts, des noms, des titres de documents ou des secrets clients dans les identifiants. Stockez les données de corrélation sensibles dans votre propre base de données de locataires, et non dans les ID visibles du fournisseur.

Normalisez les statuts sans effacer les détails du fournisseur

Les API par lots des fournisseurs exposent différents cycles de vie. La passerelle doit les normaliser dans une petite machine d'état interne que les tableaux de bord, la facturation et l'automatisation peuvent comprendre.

Cycle de vie normalisé recommandé :

• projet : la tâche existe mais est toujours modifiable.
• validation : la validation de la passerelle ou du fournisseur est en cours d'exécution.
• en file d'attente : acceptée mais pas encore traitement.
• en cours d'exécution : le fournisseur traite les éléments.
• finalisation : le fournisseur a terminé le calcul et prépare les artefacts de résultat.
• terminé : tous les éléments acceptés ont atteint le succès du terminal.
• completed_with_errors : certains éléments ont réussi et d'autres ont échoué.
• expiré : la fenêtre du fournisseur s'est terminée avant tout le travail. terminé.
• cancel_requested : le locataire a demandé d'annuler, mais le travail final facturable n'est pas réglé.
• annulé : annulation réglée.
• échec : un échec au niveau de la tâche a empêché une exécution utile.

Ne réduisez pas trop tôt les erreurs du fournisseur natif en étiquettes génériques. Les opérateurs ont toujours besoin d'accéder aux statuts natifs, aux erreurs de validation, au nombre de demandes, aux ID de fichiers et aux noms d'opérations lors du débogage.

Validez par rapport à une matrice de capacités avant la soumission

Recommandation : exécutez une validation préalable avant la réservation du budget et l'envoi du fournisseur. Le mode batch n'est pas seulement un mode synchrone avec un délai. Certains modèles, points de terminaison, fonctionnalités de requête, régions et configurations d'outils peuvent ne pas être pris en charge par l'API batch d'un fournisseur.

Votre matrice de capacités interne doit vérifier :

• Point de terminaison pris en charge : chat, messages, intégrations, modération ou génération.
• Éligibilité du modèle pour le mode batch.
• Taille maximale de la tâche, nombre d'éléments, taille de la demande et taille du fichier téléchargé.
• Le streaming est-il possible ? interdite.
• Utilisation des outils et prise en charge des appels de fonctions.
• Prise en charge des sorties structurées ou des schémas JSON.
• Prise en charge des images, des fichiers audio ou des entrées multimodales.
• Contraintes de région et de résidence.
• Fenêtres de rétention du fournisseur et de récupération des résultats.
• Limites de débit et limites de file d'attente spécifiques aux lots.
• Sémantique d'annulation.

Une bonne réponse de contrôle en amont. is specific:

{
  "error": "batch_capability_not_supported",
  "message": "L'adaptateur par lots du fournisseur sélectionné ne prend pas en charge les réponses en continu. Supprimez stream=true ou choisissez un point de terminaison synchrone.",
  "field": "items[*].request.stream"

C'est plus utile que d'accepter la tâche et de l'échouer après une passe de validation en amont.

Réservez le budget du locataire, puis réglez l'utilisation réelle

L'exécution par lots complique la facturation car la passerelle peut perdre l'accès synchrone à l'utilisation exacte jusqu'à ce que les fichiers de résultats soient disponibles. Le modèle sûr consiste à citer, réserver, soumettre, ingérer, régler et réconcilier.

Faits vérifiés : OpenAI déclare que les prix des API par lots sont proposés à un prix réduit par rapport aux API synchrones, et que les lots expirés ou annulés peuvent toujours renvoyer un travail terminé et facturable. Anthropic note que le traitement par lots à haut débit peut légèrement dépasser une limite de dépenses d'espace de travail, ce qui rend la réservation côté passerelle et le post-règlement importants.

Recommandation : réservez le budget du locataire avant la soumission en utilisant les jetons estimés, les règles de prix du fournisseur sélectionné et une marge de sécurité. Une fois les résultats ingérés, réglez l’utilisation réelle au niveau de l’article. Si l'estimation était trop élevée, libérez la réservation inutilisée. S'il était trop faible, appliquez la politique de dépassement configurée par le locataire.

Événements pratiques du grand livre :

batch.estimated
batch.réservé
lot.soumis
batch.item.règlement
lot.article.remboursé
batch.cancel_requested
lot.expirébatch.reconciled

Le grand livre au niveau des articles est essentiel. Si 45 000 éléments sont terminés et 5 000 expirent, le locataire doit être facturé pour le travail terminé du fournisseur, et non pour le manifeste d'origine sous la forme d'un seul blob indifférencié.

Créez des adaptateurs de fournisseur en tant que traducteurs et non en tant que propriétaires de logique métier.

Chaque adaptateur de fournisseur doit savoir comment transformer la tâche de passerelle au format par lots du fournisseur, le soumettre, interroger ou récupérer l'état, télécharger les résultats et mapper les résultats natifs aux résultats normalisés. enregistrements.

Conserver la stratégie de locataire en dehors de l'adaptateur. L'adaptateur ne doit pas décider si un client dispose d'un budget suffisant, si un client partenaire est suspendu ou si les invites peuvent être stockées. Il s'agit de décisions de passerelle.

Responsabilités de l'adaptateur

• Rendre les manifestes de requête spécifiques au fournisseur.
• Télécharger des fichiers d'entrée ou créer des opérations de fournisseur.
• Stocker les identifiants du fournisseur dans des métadonnées.
• Mapper l'état natif à l'état normalisé.
• Récupérer les artefacts de sortie et d'erreur.
• Analyser les résultats au niveau de l'élément.
• Renvoyer les enregistrements d'utilisation natifs lorsque disponible.
• Surface réessayable par rapport aux erreurs de terminal.

Responsabilités de la passerelle

• Authentifier le locataire et la clé API.
• Appliquer les contrôles de l'équipe, du projet et du client.
• Résoudre les alias de modèle et la politique de routage du fournisseur.
• Valider les capacités par lots.
• Réserver et régler le budget.
• Conserver la tâche et l'élément. état.
• Appliquer la politique de rétention.
• Exposer les analyses et les exportations.

Cette séparation facilite l'ajout d'un nouveau fournisseur sans réécrire la facturation, les analyses ou la gouvernance des locataires.

Ingérer les résultats de manière idempotente

L'ingestion des résultats est l'endroit où de nombreux systèmes par lots dupliquent accidentellement des frais ou perdent une partie du travail. Considérez l’ingestion comme un processus reproductible. Il devrait être prudent de télécharger deux fois le même fichier de sortie, de traiter deux fois la même opération du fournisseur ou de rejouer deux fois le même événement webhook.

Recommandation : utilisez des clés d'idempotence au niveau de l'élément et des contraintes d'unicité du grand livre. Un résultat pour job_id + custom_id devrait être réglé exactement une fois, même si l'ingestion est réessayée.

Un flux d'ingestion robuste :

1. Acquérir un verrou de courte durée pour la tâche ou l'artefact de résultat.
2. Récupérer la sortie du fournisseur et les artefacts d'erreur.
3. Analyser les enregistrements en événements de résultat d'élément normalisés.
4. Faire correspondre chaque enregistrement par custom_id ou par élément de passerelle. ID.
5. Écrivez les métadonnées du résultat et l'utilisation dans une transaction.
6. Créez un événement de règlement du grand livre uniquement s'il n'en existe pas déjà un.
7. Mettez à jour le nombre de tâches à partir des états des articles, et non à partir d'hypothèses.
8. Libérez la réservation budgétaire inutilisée lorsque tous les états des terminaux sont connus.

Si des webhooks sont disponibles, vérifiez les signatures et protégez-vous contre la relecture. Si l'interrogation est requise, utilisez l'interrogation adaptative : interrogez fréquemment à l'approche de la fin prévue, arrêtez-vous pendant les périodes de longue durée et arrêtez-vous après le règlement du terminal.

Réessayez les éléments, pas les tâches entières

Recommandation : réessayez au niveau de l'élément chaque fois que cela est possible. Les nouvelles tentatives de tâches complètes sont simples, mais elles augmentent le risque de travail en double et rendent la facturation plus difficile.

Classez les échecs avant de réessayer :

• Erreurs de validation : généralement terminales jusqu'à ce que la demande soit corrigée.
• Erreurs 5xx du fournisseur : souvent réessayables avec interruption.
• Échecs de quota ou de limite de débit : réessayez uniquement une fois la capacité atteinte. disponibles.
• Blocs de sécurité : ne réessayez pas aveuglément ; route vers la gestion des politiques.
• Éléments expirés : peuvent être réessayés dans une nouvelle tâche si le locataire souhaite toujours que le travail et le budget le permettent.

Une nouvelle tentative doit créer un nouvel élément lié à l'original :

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

Ne soumettez pas à nouveau les éléments terminés simplement parce qu'ils faisaient partie d'un travail qui s'est terminé par completed_with_errors ou expiré.

Décidez quoi stocker : résultats bruts, pointeurs ou hachages

Les systèmes par lots sont des endroits tentants pour accumuler des invites et des sorties. Cela peut être utile pour les exportations et le débogage, mais cela augmente la responsabilité en matière de conservation des données.

Recommandation : rendre la stratégie de stockage configurable par le locataire. Pour les charges de travail sensibles, stockez les métadonnées, les hachages, les utilisations et les pointeurs de résultats plutôt que les invites et les sorties brutes.Pour les charges de travail moins sensibles, le stockage normalisé des résultats peut être acceptable si les fenêtres de conservation, les contrôles d'accès et les workflows de suppression sont clairs.

Suivez au moins :

• Si les entrées brutes ont été stockées.
• Si les sorties brutes ont été stockées.
• Où se trouvent les artefacts de résultat du fournisseur.
• Date limite de récupération du fournisseur.
• Date limite de suppression de la passerelle.
• Hash de demande et réponse d'audit sans exposition de contenu.

Fait vérifié : Les résultats des lots d'états anthropiques sont disponibles pendant 29 jours après la création et isolés dans l'espace de travail. Ce type de fenêtre de récupération spécifique au fournisseur doit être reflété dans les métadonnées de la passerelle et les exportations destinées aux locataires.

Exposer des analyses qui correspondent au fonctionnement des équipes

Les analyses par lots doivent exister au niveau des tâches et des éléments. Un propriétaire de produit souhaite savoir si un enrichissement nocturne est terminé. Un administrateur financier souhaite un coût par locataire, modèle et client. Un ingénieur souhaite savoir quelle classe d'échec réessayer.

Les mesures utiles incluent :

• Nombre d'éléments soumis, terminés, ayant échoué, expirés et annulés.
• Coût estimé par rapport au coût réglé.
• Budget réservé toujours conservé.
• Jetons d'entrée et de sortie par fournisseur et modèle.
• Indicateurs d'accès au cache où les fournisseurs les exposent.
• Nombre de tentatives et réussite des tentatives taux.
• Durée moyenne dans les états de mise en file d'attente, d'exécution et de finalisation.
• Principales erreurs de validation par point de terminaison et modèle.
• Attribution du client partenaire.

Pour les utilisateurs de l'API partenaire, exposez les tâches par lots en tant que ressources à l'échelle du client. Cela permet aux agences et aux constructeurs SaaS de proposer un traitement de l'IA hors ligne tout en conservant les informations d'identification du fournisseur en amont, le rapprochement de la facturation et la gestion des limites de débit au sein de la passerelle.

Compromis à rendre explicites

Abstraction de la passerelle par rapport à la capacité spécifique du fournisseur : un contrat unifié simplifie l'intégration, mais il ne peut pas rendre les fonctionnalités de chaque fournisseur identiques. Gardez les erreurs de capacité explicites.

Réservation budgétaire par rapport à l'exactitude des estimations : la réservation protège les locataires des tâches incontrôlables, mais les estimations peuvent être erronées. Le grand livre doit prendre en charge les ajustements, les remboursements et la gestion des excédents.

Interrogation par rapport aux webhooks : l'interrogation est simple et fiable, mais peut gaspiller des appels d'API et retarder son achèvement. Les webhooks sont plus rapides, mais nécessitent une vérification de signature, une protection contre la relecture et une surveillance.

Stockage des résultats bruts versus minimisation de la rétention : le stockage des résultats normalisés améliore les exportations et les analyses, mais augmente la charge de conformité. Les locataires sensibles peuvent préférer les pointeurs et les hachages.

Des lots volumineux plutôt que des lots fragmentés : des lots volumineux peuvent améliorer l'efficacité du côté du fournisseur, mais des fragments plus petits réduisent le rayon d'explosion et facilitent les nouvelles tentatives.

Liste de contrôle de mise en œuvre

• Créez une surface API de tâche par lots distincte.
• Conservez les enregistrements de tâche et d'élément avant la soumission du fournisseur.
• Exigez les ID de tâche de passerelle et ID personnalisés par article.
• Normalisez les statuts tout en stockant les métadonnées natives du fournisseur.
• Créez une matrice de capacités pour chaque adaptateur de lots de fournisseur.
• Validez les manifestes avant de réserver le budget.
• Réservez le budget du locataire avant l'envoi.
• Réglez l'utilisation réelle au niveau de l'élément après l'ingestion.
• Rendre l'ingestion des résultats idempotente.
• Réessayez les éléments ayant échoué de manière sélective, et non des tâches entières. aveuglément.
• Suivez les délais de récupération des fournisseurs et la politique de rétention de la passerelle.
• Exposez les analyses de tâches et d'articles aux locataires et aux clients partenaires.

Prédictions : vers où se dirige ce modèle

Prédiction : l'exécution par lots deviendra une partie normale de l'infrastructure d'automatisation de l'IA, et pas seulement un mécanisme de remise. À mesure que les équipes effectuent davantage d'évaluations, de tâches de nettoyage des données, d'examens de sécurité et de pipelines d'enrichissement, elles s'attendront à ce que les charges de travail asynchrones aient la même gouvernance que les appels d'API synchrones.

Prédiction : les API par lots des fournisseurs continueront de diverger de manière utile. Certains optimiseront pour les fichiers, d'autres pour les opérations de longue durée et d'autres encore pour les ensembles de données gérés ou les rappels d'événements. Une couche d'adaptateur de passerelle deviendra plus précieuse, et non moins, car le contrat opérationnel au-dessus des adaptateurs peut rester stable.

Conclusion exploitable

Ne placez pas le traitement par lots sur une passerelle API IA en tant que trappe de secours spécifique au fournisseur. Créez-le comme un sous-système durable avec ses propres enregistrements de tâches, identifiants d'éléments, modèle de statut, adaptateurs de fournisseur, réservation budgétaire, ingestion idempotente et analyses.

Le choix de conception le plus important est la comptabilité au niveau des éléments. Une fois que chaque requête d'un lot a une identité stable, la passerelle peut rapprocher les résultats non ordonnés, réessayer uniquement les travaux ayant échoué, facturer uniquement les travaux terminés du fournisseur et montrer aux locataires ce qui s'est passé.C'est la différence entre envoyer des fichiers à un fournisseur et exploiter une API multimodèle fiable pour les charges de travail asynchrones.

Lecture connexe

• citer, réserver, régler et réconcilier le modèle de facturation de l'API AI
• analyse d'utilisation au niveau de la passerelle et conception du grand livre de jetons
• quand les charges de travail tolérantes à la latence s'adaptent au traitement par lots