Le traitement par lots est une approche puissante pour gérer efficacement de grands volumes de requêtes. Au lieu de traiter les requêtes une par une avec des réponses immédiates, le traitement par lots vous permet de soumettre plusieurs requêtes ensemble pour un traitement asynchrone. Ce modèle est particulièrement utile lorsque :

• Vous devez traiter de grands volumes de données
• Les réponses immédiates ne sont pas nécessaires
• Vous souhaitez optimiser l’efficacité des coûts
• Vous effectuez des évaluations ou des analyses à grande échelle

L’API Message Batches est notre première implémentation de ce modèle.

​

API Message Batches

L’API Message Batches est une façon puissante et rentable de traiter de manière asynchrone de grands volumes de requêtes Messages. Cette approche est bien adaptée aux tâches qui ne nécessitent pas de réponses immédiates, la plupart des lots se terminant en moins d’une heure tout en réduisant les coûts de 50 % et en augmentant le débit.

Vous pouvez explorer directement la référence de l’API, en plus de ce guide.

​

Comment fonctionne l’API Message Batches

Lorsque vous envoyez une requête à l’API Message Batches :

1. Le système crée un nouveau lot de messages avec les requêtes Messages fournies.
2. Le lot est ensuite traité de manière asynchrone, chaque requête étant traitée indépendamment.
3. Vous pouvez interroger l’état du lot et récupérer les résultats une fois le traitement terminé pour toutes les requêtes.

Ceci est particulièrement utile pour les opérations en masse qui ne nécessitent pas de résultats immédiats, comme :

• Évaluations à grande échelle : Traiter efficacement des milliers de cas de test.
• Modération de contenu : Analyser de grands volumes de contenu généré par les utilisateurs de manière asynchrone.
• Analyse de données : Générer des insights ou des résumés pour de grands ensembles de données.
• Génération de contenu en masse : Créer de grandes quantités de texte pour diverses fins (par exemple, descriptions de produits, résumés d’articles).

​

Limitations des lots

• Un lot de messages est limité soit à 100 000 requêtes de messages, soit à 256 Mo, selon la première limite atteinte.
• Nous traitons chaque lot aussi rapidement que possible, la plupart des lots se terminant en moins d’une heure. Vous pourrez accéder aux résultats du lot lorsque tous les messages seront terminés ou après 24 heures, selon la première éventualité. Les lots expireront si le traitement n’est pas terminé dans les 24 heures.
• Les résultats des lots sont disponibles pendant 29 jours après leur création. Après cela, vous pourrez toujours voir le lot, mais ses résultats ne seront plus disponibles au téléchargement.
• Les lots sont limités à un Workspace. Vous pouvez voir tous les lots - et leurs résultats - qui ont été créés dans le Workspace auquel appartient votre clé API.
• Les limites de taux s’appliquent à la fois aux requêtes HTTP de l’API Batches et au nombre de requêtes dans un lot en attente de traitement. Voir Limites de taux de l’API Message Batches. De plus, nous pouvons ralentir le traitement en fonction de la demande actuelle et de votre volume de requêtes. Dans ce cas, vous pourriez voir plus de requêtes expirer après 24 heures.
• En raison du débit élevé et du traitement concurrent, les lots peuvent légèrement dépasser la limite de dépenses configurée pour votre Workspace.

​

Modèles pris en charge

L’API Message Batches prend actuellement en charge :

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 et claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

Ce qui peut être traité par lots

Toute requête que vous pouvez faire à l’API Messages peut être incluse dans un lot. Cela comprend :

• Vision
• Utilisation d’outils
• Messages système
• Conversations à plusieurs tours
• Toutes les fonctionnalités bêta

Puisque chaque requête dans le lot est traitée indépendamment, vous pouvez mélanger différents types de requêtes au sein d’un même lot.

​

Tarification

L’API Batches offre des économies significatives. Toute utilisation est facturée à 50 % des prix standard de l’API.

​

Comment utiliser l’API Message Batches

​

Préparer et créer votre lot

Un lot de messages est composé d’une liste de requêtes pour créer un message. La forme d’une requête individuelle comprend :

• Un custom_id unique pour identifier la requête Messages
• Un objet params avec les paramètres standard de l’API Messages

Vous pouvez créer un lot en passant cette liste dans le paramètre requests :

Dans cet exemple, deux requêtes distinctes sont regroupées pour un traitement asynchrone. Chaque requête a un custom_id unique et contient les paramètres standard que vous utiliseriez pour un appel à l’API Messages.

Lorsqu’un lot est créé pour la première fois, la réponse aura un statut de traitement in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

​

Suivi de votre lot

Le champ processing_status du lot de messages indique l’étape de traitement dans laquelle se trouve le lot. Il commence par in_progress, puis passe à ended une fois que toutes les requêtes du lot ont terminé leur traitement et que les résultats sont prêts. Vous pouvez surveiller l’état de votre lot en visitant la Console, ou en utilisant le point de terminaison de récupération :

Vous pouvez interroger ce point de terminaison pour savoir quand le traitement est terminé.

​

Récupération des résultats du lot

Une fois le traitement du lot terminé, chaque requête Messages dans le lot aura un résultat. Il existe 4 types de résultats :

Vous verrez un aperçu de vos résultats avec les request_counts du lot, qui montre combien de requêtes ont atteint chacun de ces quatre états.

Les résultats du lot sont disponibles au téléchargement à la fois dans la Console et à l’URL results_url sur le lot de messages. En raison de la taille potentiellement importante des résultats, il est recommandé de diffuser les résultats plutôt que de les télécharger tous en une fois.

Les résultats seront au format .jsonl, où chaque ligne est un objet JSON valide représentant le résultat d’une seule requête dans le lot de messages. Pour chaque résultat diffusé, vous pouvez faire quelque chose de différent en fonction de son custom_id et de son type de résultat. Voici un exemple d’ensemble de résultats :

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Si votre résultat a une erreur, son result.error sera défini selon notre forme d’erreur standard.

​

Utilisation de la mise en cache des prompts avec les lots de messages

L’API Message Batches prend en charge la mise en cache des prompts, ce qui vous permet de potentiellement réduire les coûts et le temps de traitement pour les requêtes par lots. Les réductions de prix de la mise en cache des prompts et des lots de messages peuvent s’additionner, offrant des économies de coûts encore plus importantes lorsque les deux fonctionnalités sont utilisées ensemble. Cependant, comme les requêtes par lots sont traitées de manière asynchrone et concurrente, les succès de cache sont fournis sur une base de meilleur effort. Les utilisateurs connaissent généralement des taux de succès de cache allant de 30 % à 98 %, selon leurs modèles de trafic.

Pour maximiser la probabilité de succès de cache dans vos requêtes par lots :

1. Incluez des blocs cache_control identiques dans chaque requête Message de votre lot
2. Maintenez un flux constant de requêtes pour empêcher l’expiration des entrées de cache après leur durée de vie de 5 minutes
3. Structurez vos requêtes pour partager autant de contenu mis en cache que possible

Exemple d’implémentation de la mise en cache des prompts dans un lot :

Dans cet exemple, les deux requêtes du lot incluent des messages système identiques et le texte complet d’Orgueil et Préjugés marqué avec cache_control pour augmenter la probabilité de succès de cache.

​

Meilleures pratiques pour un traitement par lots efficace

Pour tirer le meilleur parti de l’API Batches :

• Surveillez régulièrement l’état de traitement du lot et implémentez une logique de nouvelle tentative appropriée pour les requêtes échouées.
• Utilisez des valeurs custom_id significatives pour faire facilement correspondre les résultats avec les requêtes, puisque l’ordre n’est pas garanti.
• Envisagez de diviser les très grands ensembles de données en plusieurs lots pour une meilleure gérabilité.
• Testez une seule forme de requête avec l’API Messages pour éviter les erreurs de validation.

​

Résolution des problèmes courants

Si vous rencontrez un comportement inattendu :

• Vérifiez que la taille totale de la requête par lot ne dépasse pas 256 Mo. Si la taille de la requête est trop grande, vous pourriez obtenir une erreur 413 request_too_large.
• Vérifiez que vous utilisez des modèles pris en charge pour toutes les requêtes du lot.
• Assurez-vous que chaque requête dans le lot a un custom_id unique.
• Assurez-vous qu’il s’est écoulé moins de 29 jours depuis l’heure de created_at du lot (pas l’heure de fin de traitement ended_at). Si plus de 29 jours se sont écoulés, les résultats ne seront plus visibles.
• Confirmez que le lot n’a pas été annulé.

Notez que l’échec d’une requête dans un lot n’affecte pas le traitement des autres requêtes.

​

Stockage et confidentialité des lots

• Isolation des Workspaces : Les lots sont isolés dans le Workspace où ils sont créés. Ils ne peuvent être accessibles que par les clés API associées à ce Workspace, ou par les utilisateurs ayant la permission de voir les lots du Workspace dans la Console.

• Disponibilité des résultats : Les résultats des lots sont disponibles pendant 29 jours après la création du lot, laissant amplement le temps pour la récupération et le traitement.

​

FAQ

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)