Alibaba Cloud Model Studio propose une API Batch File compatible OpenAI permettant d'envoyer des requêtes en masse via des fichiers. Le système traite toutes les requêtes de manière asynchrone et renvoie les résultats une fois toutes les requêtes terminées ou lorsque le délai d'attente maximal est atteint. Les frais représentent seulement 50 % de ceux des appels en temps réel. Cela convient aux scénarios tels que l'analyse de données et l'évaluation de modèles, peu sensibles au temps mais nécessitant un traitement à grande échelle.
Flux de travail
Prérequis
Vous pouvez appeler l'API Batch File via le SDK OpenAI (Python, Node.js) ou l'API HTTP.
- Obtenir une clé API : Obtenir et configurer votre clé API dans des variables d'environnement
- Installer le SDK (facultatif) : Pour appeler l'API avec le SDK, installez le SDK OpenAI
-
Endpoints
- Chine (Pékin) :
https://dashscope.aliyuncs.com/compatible-mode/v1 - Singapour :
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- Chine (Pékin) :
Périmètre
- Singapour
- Chine (Pékin)
-
Modèles de génération de texte
- Qwen Max : qwen3.8-max, qwen-max
- Qwen Plus : qwen3.7-plus, qwen-plus
- Qwen Flash : qwen-flash
-
Modèles multimodaux
- Compréhension d'images et de vidéos : qwen3.8-max, qwen3.7-plus
Prise en main
Avant de traiter des tâches de production, utilisez le modèle de test batch-test-model pour un test de bout en bout. Ce modèle ignore le processus d'inférence et renvoie directement une réponse de succès fixe, qui sert à vérifier que la chaîne d'appels API et le format des données sont corrects.
- Les fichiers de test doivent respecter les exigences relatives au fichier d'entrée, avec une taille de fichier ne dépassant pas 1 Mo et pas plus de 100 lignes.
- Limite de concurrence : jusqu'à 2 tâches simultanées.
- Frais : le modèle de test n'entraîne pas de frais d'inférence de modèle.
Étape 1 : Préparer le fichier d'entrée
Préparez un fichier nommé test_model.jsonl avec le contenu suivant :
Étape 2 : Exécuter le code
Selon le langage de programmation que vous utilisez, sélectionnez l'un des exemples de code suivants, enregistrez-le dans le même répertoire que le fichier d'entrée, puis exécutez-le. Le code couvre le flux de travail complet : téléchargement du fichier, création de la tâche, interrogation de l'état et téléchargement des résultats.
Pour modifier le chemin du fichier ou d'autres paramètres, adaptez le code selon vos besoins.
file-batch-xxx) peut être réutilisé. Si le contenu d'entrée est inchangé, il n'est pas nécessaire de le télécharger à nouveau à chaque fois ; vous pouvez directement créer une tâche avec l'ID existant :client.files.list(purpose="batch").Exemple de code
Exemple de code
Étape 3 : Vérifier le résultat du test
Une fois la tâche terminée avec succès, le fichier de résultats result.jsonl contient la réponse fixe {"content":"This is a test result."} :
Exécuter des tâches formelles
Exigences relatives au fichier d'entrée
- Format : JSONL encodé en UTF-8 (un objet JSON indépendant par ligne)
- Limites de taille : Au plus 50 000 requêtes par fichier, et pas plus de 500 Mo
- Limites par ligne : Chaque objet JSON ne doit pas dépasser 6 Mo et ne doit pas dépasser la longueur de contexte du modèle
- Exigences de cohérence : Toutes les requêtes d'un même fichier doivent utiliser le même modèle et le même mode réflexion (le cas échéant)
- Identifiant unique : Chaque requête doit contenir un champ custom_id unique dans le fichier, utilisé pour faire correspondre les requêtes et les résultats
Les chaînes Base64 des exemples ont été omises ; utilisez le code Python ci-dessous pour générer l'encodage complet.
Transmettre une chaîne encodée en Base64 (exemple avec une image)
Transmettre une chaîne encodée en Base64 (exemple avec une image)
- Convertissez le fichier local en encodage Base64 :
-
Construisez le format Data URL :
data:[MIME_type];base64,{base64_image};MIME_typedoit être remplacé par le type de média réel, en veillant à ce qu'il corresponde à la valeur deMIME Type(par exemple,image/jpeg,image/png) ;base64_imageest la chaîne Base64 générée à l'étape précédente.
Utilisation
- Enregistrez le code suivant sous
generate_batch_jsonl.py - Modifiez le contenu des requêtes de la liste
TASKSdans le script - Exécutez
python generate_batch_jsonl.py - Le fichier
batch_input.jsonlgénéré peut être utilisé directement pour les tâches d'inférence par lots
Script de génération JSONL pour les modèles de génération de texte
Format de requête pour les modèles multimodaux
Pour les modèles multimodaux, le champ content est au format tableau, contenant des objets média et des invites textuelles. Les URL de média de chaque ligne de requête doivent être du même type (image, vidéo ou audio). Remplacez TASKS dans le script ci-dessus par le format suivant :
Format de requête pour les modèles d'embedding de texte
Les modèles d'embedding de texte utilisent l'API /v1/embeddings, et leur format de requête diffère de celui des modèles de génération de texte. Vous pouvez utiliser le script autonome suivant pour le générer :
1. Modifiez le fichier d'entrée
-
Vous pouvez directement modifier le fichier
test_model.jsonlutilisé pour les tests, définir le paramètre model sur le modèle formel cible, et définir le champ URL :Type de modèle
url
Modèles de génération de texte/multimodaux
/v1/chat/completionsModèles d'embedding de texte
/v1/embeddings -
Vous pouvez également utiliser l'« outil de génération JSONL par lots » ci-dessus pour générer un nouveau fichier pour la tâche formelle. L'essentiel est de veiller à ce que les champs
modeleturlsoient corrects.
2. Modifiez le code de prise en main
- Remplacez le chemin du fichier d'entrée par le nom de votre fichier
- Modifiez la valeur du paramètre endpoint pour qu'elle corresponde au champ url du fichier d'entrée
3. Exécutez le code et attendez les résultats
Une fois la tâche terminée, les résultats des requêtes réussies sont enregistrés dans le fichier local result.jsonl. Si une requête échoue, les détails de l'erreur sont enregistrés dans le fichier error.jsonl.
- Résultats réussis (
output_file_id) : chaque ligne correspond à une requête d'origine réussie, contenantcustom_idetresponse.
- Détails des requêtes échouées (
error_file_id) : contiennent les informations des lignes de requête dont le traitement a échoué ainsi que les causes des erreurs. Consultez les codes d'erreur pour le dépannage.
Procédure détaillée
Le flux de travail de l'API Batch se compose de quatre étapes : téléchargement des fichiers, création des tâches, interrogation de l'état des tâches et téléchargement des résultats.
1. Télécharger les fichiers
1. Télécharger les fichiers
file_id.Lors du téléchargement d'un fichier,purposedoit êtrebatch.
file-batch-xxx) peut être réutilisé. Si le contenu d'entrée est inchangé, il n'est pas nécessaire de le télécharger à nouveau à chaque fois ; vous pouvez directement créer une tâche avec l'ID existant :client.files.list(purpose="batch").- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemple de requête
Exemple de réponse
2. Créer une tâche Batch
2. Créer une tâche Batch
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemple de requête
Paramètres d'entrée
Champ | Type | Méthode de transmission des paramètres | Obligatoire | Description |
|---|---|---|---|---|
input_file_id | String | Body | Oui | Spécifie l'ID du fichier utilisé comme fichier d'entrée pour la tâche Batch. Utilisez l'ID de fichier renvoyé par l'interface Préparer et télécharger des fichiers, par exemple |
endpoint | String | Body | Oui | Chemin d'accès, qui doit correspondre au champ URL du fichier d'entrée.
|
completion_window | String | Body | Oui | Délai d'attente, minimum 24h et maximum 336h ; seuls les entiers sont pris en charge. Prend en charge deux unités : « h » et « d », par exemple « 24h » ou « 14d ». |
metadata | Map | Body | Non | Métadonnées d'extension de tâche permettant d'associer des informations supplémentaires sous forme de paires clé-valeur. |
metadata.ds_name | String | Body | Non | Nom de la tâche. Exemple : Limite : jusqu'à 100 caractères. Si ce champ est défini plusieurs fois, la dernière valeur transmise prévaut. |
metadata.ds_description | String | Body | Non | Description de la tâche. Exemple : Limite : jusqu'à 200 caractères. Si ce champ est défini plusieurs fois, la dernière valeur transmise prévaut. |
Exemple de réponse
Paramètres de réponse
Champ | Type | Description |
|---|---|---|
id | String | L'ID de la tâche Batch créée cette fois. |
object | String | Le type d'objet, avec une valeur fixe de |
endpoint | String | Le chemin d'accès. |
errors | Map | Le message d'erreur. |
input_file_id | String | L'ID du fichier. |
completion_window | String | Le délai d'attente. Le délai d'attente minimum est de 24h et le maximum de 336h ; seuls les entiers sont pris en charge. Prend en charge deux unités : « h » et « d », par exemple « 24h » ou « 14d ». |
status | String | L'état de la tâche. Valeurs possibles : validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled. |
output_file_id | String | L'ID du fichier de sortie des requêtes réussies. |
error_file_id | String | L'ID du fichier d'erreur des requêtes échouées. |
created_at | Integer | Horodatage Unix (en secondes) de la création de la tâche. |
in_progress_at | Integer | Horodatage Unix (en secondes) du début d'exécution de la tâche. |
expires_at | Integer | Horodatage Unix (en secondes) de l'expiration prévue de la tâche. |
finalizing_at | Integer | Horodatage Unix (en secondes) du début d'agrégation des résultats de la tâche. |
completed_at | Integer | Horodatage Unix (en secondes) de la fin de la tâche. |
failed_at | Integer | Horodatage Unix (en secondes) de l'échec de la tâche. |
expired_at | Integer | Horodatage Unix (en secondes) de l'expiration de la tâche. |
cancelling_at | Integer | Horodatage Unix (en secondes) du début d'annulation de la tâche. |
cancelled_at | Integer | Horodatage Unix (en secondes) de la fin d'annulation de la tâche. |
request_counts | Map | Statistiques du nombre de requêtes par état. |
metadata | Map | Métadonnées supplémentaires sous forme de paires clé-valeur. |
metadata.ds_name | String | Nom de la tâche. |
metadata.ds_description | String | Description de la tâche. |
3. Interroger et gérer les tâches Batch
3. Interroger et gérer les tâches Batch
Interroger l'état d'une tâche spécifiée
Interroger l'état d'une tâche spécifiée
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemple de requête
Exemple de réponse
Après une requête réussie, les détails de la tâche Batch sont renvoyés. Voici un exemple de réponse pour une tâche à l'état terminé :Champ | Type | Description |
|---|---|---|
id | String | ID de la tâche Batch. |
status | String | État de la tâche. Valeurs possibles :
|
output_file_id | String | L'ID du fichier de résultats de succès, généré une fois la tâche terminée. |
error_file_id | String | L'ID du fichier de résultats d'échec, généré lorsque la tâche est terminée et qu'il y a des requêtes échouées. |
request_counts | Object | L'objet statistique du nombre de requêtes, contenant les champs total, completed et failed. |
Interroger la liste des tâches
Interroger la liste des tâches
batches.list() pour interroger la liste des tâches Batch et récupérer la liste complète des tâches de manière progressive via la pagination.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemple de requête
Paramètres d'entrée
Champ | Type | Méthode de transmission | Obligatoire | Description |
|---|---|---|---|---|
after | String | Query | Non | Le curseur utilisé pour la pagination, dont la valeur est l'ID de la dernière tâche de la page précédente. |
limit | Integer | Query | Non | Le nombre de tâches renvoyées par page, plage [1, 100], 20 par défaut. |
ds_name | String | Query | Non | Correspondance floue par nom de tâche. |
input_file_ids | String | Query | Non | Filtrer par ID de fichier. Plusieurs ID sont séparés par des virgules, jusqu'à 20. |
status | String | Query | Non | Filtrer par état de tâche. Plusieurs états sont séparés par des virgules. |
create_after | String | Query | Non | Filtrer les tâches créées après ce point temporel, au format |
create_before | String | Query | Non | Filtrer les tâches créées avant ce point temporel, au format |
Exemple de réponse
Paramètres de réponse
Champ | Type | Description |
|---|---|---|
object | String | Le type, avec une valeur fixe de list. |
data | Array | L'objet tâche Batch. Voir les paramètres de réponse de la création d'une tâche Batch. |
first_id | String | L'ID de la première tâche Batch de la page actuelle. |
last_id | String | L'ID de la dernière tâche Batch de la page actuelle. |
has_more | Boolean | Indique s'il existe une page suivante. |
Annuler une tâche Batch
Annuler une tâche Batch
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemple de requête
Exemple de réponse
Une fois la tâche annulée avec succès, les détails de la tâche Batch sont renvoyés. Voici un exemple de réponse à l'état cancelling :Après l'annulation de la tâche, l'état passe d'abord àcancelling, en attendant la fin des requêtes en cours ; il finit par passer àcancelled. Les résultats des requêtes terminées restent enregistrés dans le fichier de sortie.
4. Télécharger le fichier de résultats Batch
4. Télécharger le fichier de résultats Batch
file_id commençant par file-batch_output peut être téléchargé.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
content pour récupérer le contenu du fichier de résultats Batch, et la méthode write_to_file pour l'enregistrer localement.Exemple de requête
Exemple de réponse
Exemple de réponse
Résultat de réponse unique :Paramètres de réponse
Champ | Type | Description |
|---|---|---|
id | String | ID de la requête. |
custom_id | String | ID défini par l'utilisateur. |
response | Object | Résultat de la requête. |
status_code | Integer | Code d'état. 200 indique une requête réussie. |
request_id | String | L'ID unique généré par le serveur pour cette requête. |
completion_tokens | Integer | Le nombre de tokens consommés par le contenu de réponse généré par le modèle (completion). |
prompt_tokens | Integer | Le nombre de tokens consommés par le contenu d'entrée ( |
total_tokens | Integer | Le nombre total de tokens consommés par cet appel. |
model | String | Le nom du modèle utilisé par cet appel. |
error | Object | L'objet message d'erreur. Si l'appel API réussit, cette valeur est |
error.code | String | Informations sur la ligne d'erreur et les causes de l'erreur. Consultez les codes d'erreur pour le dépannage. |
error.message | String | Le message d'erreur. |
Fonctionnalités avancées
Configurer les notifications de fin de tâche
L'interrogation (polling) de tâches longues consomme des ressources inutiles. Nous recommandons de configurer des notifications asynchrones afin que le système vous informe proactivement lorsqu'une tâche se termine.
- Callback : Spécifiez une URL accessible publiquement lors de la création d'une tâche
- File de messages EventBridge : Intégration profonde à l'écosystème Alibaba Cloud, sans IP publique requise
Méthode 1 : Callback
Méthode 1 : Callback
metadata lors de la création d'une tâche. Une fois la tâche terminée, le système envoie une requête POST contenant l'état de la tâche à cette URL :- OpenAI Python SDK
- curl(HTTP)
Méthode 2 : File de messages EventBridge
Méthode 2 : File de messages EventBridge
- Source :
acs.dashscope - Type :
dashscope:System:BatchTaskFinish
Mise en production
-
Gestion des fichiers
- Appelez périodiquement l'API de suppression de fichiers OpenAI-File pour supprimer les fichiers inutiles et éviter d'atteindre la limite de stockage de fichiers (10 000 fichiers ou 100 Go)
- Pour les fichiers volumineux, nous recommandons de les stocker dans Alibaba Cloud OSS
-
Surveillance des tâches
- Privilégiez les notifications asynchrones Callback ou EventBridge
- Utilisez un intervalle d'interrogation > 1 minute avec une stratégie de temporisation exponentielle
-
Gestion des erreurs
- Mettez en place un mécanisme complet de gestion des exceptions couvrant les erreurs réseau, les erreurs API, etc.
- Téléchargez et analysez les détails des erreurs dans
error_file_id - Pour les codes d'erreur courants, consultez les codes d'erreur pour les résoudre
-
Optimisation des coûts
- Fusionnez les petites tâches en un seul lot
- Définissez
completion_windowde manière appropriée pour offrir plus de flexibilité de planification
Utilitaires
CSV vers JSONL
CSV vers JSONL
Pour modifier le chemin du fichier ou d'autres paramètres, adaptez le code selon vos besoins.
Résultats JSONL vers CSV
Résultats JSONL vers CSV
result.jsonl en un fichier result.csv facile à analyser dans Excel.Pour modifier le chemin du fichier ou d'autres paramètres, adaptez le code selon vos besoins.
- Utilisez un éditeur de texte (tel que Sublime) pour convertir l'encodage du fichier CSV en GBK, puis ouvrez-le dans Excel.
- Ou créez un nouveau fichier dans Excel et spécifiez le bon format d'encodage (UTF-8) lors de l'importation des données.
Limites de débit de l'API
API | Limite de débit (niveau compte principal) |
|---|---|
Créer une tâche | 1000 fois/minute, jusqu'à 1000 tâches simultanées |
Interroger une tâche | 1000 fois/minute |
Interroger la liste des tâches | 100 fois/minute |
Annuler une tâche | 1000 fois/minute |
Détails de facturation
- Prix unitaire : Pour toutes les requêtes réussies, le prix unitaire des tokens d'entrée et de sortie est de 50 % du prix d'inférence en temps réel du modèle correspondant. Pour plus d'informations, consultez Modèles.
-
Périmètre de facturation :
- Seules les requêtes exécutées avec succès sont facturées.
- Les échecs d'analyse de fichier, les échecs d'exécution de tâche et les requêtes en erreur au niveau ligne n'entraînent aucun frais.
- Pour les tâches annulées, les requêtes terminées avec succès avant l'annulation restent facturées normalement.
- L'inférence par lots est un élément de facturation distinct. Elle prend en charge le plan d'économies universel AI, mais ne prend pas en charge les remises d'achat à l'avance (plan d'économies) ni le quota gratuit pour nouveaux utilisateurs, ni des fonctionnalités telles que le cache de contexte.
- Certains modèles (tels que qwen3.5-plus et qwen3.5-flash) ont le mode réflexion activé par défaut, ce qui génère des tokens de réflexion supplémentaires facturés au prix des tokens de sortie et augmente les coûts. Nous recommandons de définir le paramètre enable_thinking en fonction de la complexité de la tâche pour maîtriser les coûts. Pour plus d'informations, consultez réflexion approfondie.
Codes d'erreur
Si un appel échoue, consultez les codes d'erreur pour le dépannage.
FAQ
- Comment choisir entre Batch Chat et Batch File ? Choisissez Batch File pour traiter un seul fichier volumineux contenant un grand nombre de requêtes et récupérer les résultats de manière asynchrone. Choisissez Batch Chat lorsque vous devez envoyer un grand nombre de requêtes de conversation indépendantes à forte concurrence via des appels API synchrones.
- Comment l'utilisation de Batch File est-elle facturée ? Dois-je l'acheter séparément ? Batch est un mode d'appel utilisant un modèle de paiement à l'usage et facturé en fonction de l'utilisation de tokens des requêtes réussies ; vous n'avez donc pas besoin d'acheter de packages supplémentaires.
- Les fichiers Batch soumis sont-ils exécutés dans l'ordre ? Non. Le système utilise un mécanisme de planification dynamique pour organiser l'exécution des tâches en fonction de la charge des ressources de calcul et ne garantit pas le respect strict de l'ordre de soumission. Lorsque les ressources sont limitées, le démarrage et l'exécution des tâches peuvent être retardés.
- Combien de temps faut-il pour qu'un fichier Batch soumis se termine ? Le temps d'exécution dépend de l'allocation des ressources système et de l'échelle de la tâche. Si une tâche n'est pas terminée dans le completion_window spécifié, son état passe à expired, et les requêtes non traitées ne sont plus exécutées et n'entraînent aucun frais. Recommandations de scénario : Pour les scénarios avec des exigences strictes de rapidité, nous recommandons d'utiliser des appels en temps réel. Pour les scénarios de traitement de données à grande échelle tolérant une certaine latence, nous recommandons d'utiliser des appels Batch.