Lots de Messages
L’API de Lots de Messages est une méthode puissante et rentable pour traiter de manière asynchrone de grands volumes de requêtes de Messages. Cette approche est bien adaptée aux tâches qui ne nécessitent pas de réponses immédiates, réduisant les coûts de 50% tout 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 de Lots de Messages
Lorsque vous envoyez une requête à l’API de Lots de Messages :
- Le système crée un nouveau Lot de Messages avec les requêtes de Messages fournies.
- Le lot est ensuite traité de manière asynchrone, chaque requête étant traitée indépendamment.
- Vous pouvez interroger l’état du lot et récupérer les résultats une fois le traitement terminé pour toutes les requêtes.
Cela 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é à 100 000 requêtes de Messages ou 256 Mo en taille, selon la première limite atteinte.
- Le lot prend jusqu’à 24 heures pour générer des réponses, bien que le traitement puisse se terminer plus tôt. Les résultats de votre lot ne seront pas disponibles tant que le traitement du lot entier n’est pas terminé. Les lots expireront si le traitement ne se termine pas 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 Espace de travail. Vous pouvez voir tous les lots — et leurs résultats — qui ont été créés dans l’Espace de travail auquel appartient votre clé API.
- Les limites de taux s’appliquent à la fois aux requêtes HTTP de l’API de Lots et au nombre de requêtes dans un lot en attente de traitement. Voir Limites de taux de l’API de Lots de Messages. 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 Espace de travail.
Modèles pris en charge
L’API de Lots de Messages prend actuellement en charge :
- Claude 3.5 Sonnet (
claude-3-5-sonnet-20240620
etclaude-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 de Lots offre des économies significatives. Toute utilisation est facturée à 50% des prix standard de l’API.
Modèle | Entrée par lot | Sortie par lot |
---|---|---|
Claude 3.5 Sonnet | 1,50 $ / MTok | 7,50 $ / MTok |
Claude 3 Opus | 7,50 $ / MTok | 37,50 $ / MTok |
Claude 3 Haiku | 0,125 $ / MTok | 0,625 $ / MTok |
Comment utiliser l’API de Lots de Messages
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.
Testez vos requêtes par lots avec l’API Messages
La validation de l’objet params
pour chaque requête de message est effectuée de manière asynchrone, et les erreurs de validation sont renvoyées lorsque le traitement du lot entier est terminé. Vous pouvez vous assurer que vous construisez correctement votre entrée en vérifiant d’abord la forme de votre requête avec l’API Messages.
Lorsqu’un lot est créé pour la première fois, la réponse aura un statut de traitement in_progress
.
Suivre votre lot
Le champ processing_status
du Lot de Messages indique l’étape de traitement du 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érer les 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 :
Type de résultat | Description |
---|---|
succeeded | La requête a réussi. Inclut le résultat du message. |
errored | La requête a rencontré une erreur et aucun message n’a été créé. Les erreurs possibles incluent les requêtes invalides et les erreurs internes du serveur. Ces requêtes ne vous seront pas facturées. |
canceled | L’utilisateur a annulé le lot avant que cette requête ne puisse être envoyée au modèle. Ces requêtes ne vous seront pas facturées. |
expired | Le lot a atteint son expiration de 24 heures avant que cette requête ne puisse être envoyée au modèle. Ces requêtes ne vous seront pas facturées. |
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 selon son custom_id
et son type de résultat. Voici un exemple d’ensemble de résultats :
Si votre résultat comporte une erreur, son result.error
sera défini selon notre forme d’erreur standard.
Les résultats des lots peuvent ne pas correspondre à l’ordre d’entrée
Les résultats des lots peuvent être renvoyés dans n’importe quel ordre et peuvent ne pas correspondre à l’ordre des requêtes lors de la création du lot. Dans l’exemple ci-dessus, le résultat de la deuxième requête du lot est renvoyé avant la première. Pour faire correspondre correctement les résultats avec leurs requêtes correspondantes, utilisez toujours le champ custom_id
.
Meilleures pratiques pour un traitement par lots efficace
Pour tirer le meilleur parti de l’API de Lots :
- Surveillez régulièrement l’état de traitement des lots et mettez en œuvre 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, car l’ordre n’est pas garanti. - Envisagez de diviser les très grands ensembles de données en plusieurs lots pour une meilleure gestion.
- Faites un essai à sec d’une seule forme de requête avec l’API Messages pour éviter les erreurs de validation.
Résolution des problèmes courants
En cas de comportement inattendu :
- Vérifiez que la taille totale de la requête du 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 traitementended_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 espaces de travail : Les lots sont isolés dans l’Espace de travail où ils sont créés. Ils ne peuvent être accessibles que par les clés API associées à cet Espace de travail, ou par les utilisateurs autorisés à voir les lots de l’Espace de travail 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
Was this page helpful?
L’API de Lots de Messages offre une réduction de 50% sur toute utilisation par rapport aux prix standard de l’API. Cela s’applique aux jetons d’entrée, aux jetons de sortie et à tous les jetons spéciaux. Pour plus d’informations sur la tarification, visitez notre page de tarification.