Skip to main content

Interface de fichier compatible OpenAI

Téléversez des fichiers pour les questions-réponses sur documents et l'extraction de données avec Qwen-Long et Qwen-Doc-Turbo . Cette interface permet également de téléverser des fichiers d'entrée pour les tâches par lot.

Utilisation

Appelez l'interface de fichier via le SDK OpenAI (Python ou Java) ou l'API HTTP. Cette interface prend en charge le téléversement, la requête et la suppression de fichiers.

Prérequis

  • Une clé API Alibaba Cloud Model Studio : Obtenir une clé API et Exporter la clé API en tant que variable d'environnement.
  • Pour utiliser le SDK OpenAI, installez le SDK OpenAI.

Disponibilité des modèles

Vous pouvez utiliser les ID de fichier dans les scénarios suivants :
  • Qwen-Long : Questions-réponses sur des documents longs.
  • Qwen-Doc-Turbo : Extraction de données et questions-réponses sur fichiers.
  • Traitement par lot : Téléversement de fichiers pour traitement par lot.

Prise en main

Téléverser un fichier

Les limites de stockage sont de 10 000 fichiers maximum et 100 Go au total. Les fichiers n'expirent pas.
  • Pour l'analyse de documents
  • Pour le traitement par lot
Définissez purpose sur file-extract. Les formats pris en charge incluent les fichiers texte (TXT, DOCX, PDF, XLSX, EPUB, MOBI, MD, CSV, JSON) et les images (BMP, PNG, JPG/JPEG, GIF, PDF numérisés). La taille maximale du fichier est de 150 Mo.
Pour plus d'informations sur l'analyse de documents à l'aide d'un file_id, consultez contexte long (Qwen-Long) .

Exemples de requête

python
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with api_key="sk-xxx" and use your Model Studio API key.
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.txt is a local sample file.
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

Exemple de réponse

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

Interroger les informations d'un fichier

Spécifiez le file_id dans la méthode retrieve ou GET pour interroger les informations du fichier.
  • SDK OpenAI Python
  • SDK OpenAI Java
  • HTTP

Exemples de requête

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-batch-xxx")

print(file.model_dump_json())

Exemple de réponse

{
  "id": "file-batch-xxx",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

Interroger une liste de fichiers

Cette opération retourne toutes les informations sur les fichiers, y compris les fichiers téléversés et les fichiers de résultats par lot.
Cette opération prend en charge des paramètres de filtrage supplémentaires. Pour plus d'informations, consultez Description des paramètres.
  • SDK OpenAI Python
  • SDK OpenAI Java
  • HTTP

Exemples de requête

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
     # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list(after="file-batch-xxx",limit=20)
print(file_stk.model_dump_json())

Exemple de réponse

{
  "data": [
    {
      "id": "file-batch-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-batch-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

Supprimer un fichier

Supprimez un fichier par son file_id. Utilisez l'API Interroger une liste de fichiers pour trouver les ID de fichier.
  • SDK OpenAI Python
  • SDK OpenAI Java
  • HTTP

Exemples de requête

import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-batch-xxx")
print(file_object.model_dump_json())

Exemple de réponse

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-xxx"
}

Facturation

Le téléversement, le stockage et la requête de fichiers sont gratuits. Des frais s'appliquent uniquement aux tokens d'entrée et de sortie lors de l'appel des modèles.

Limitation de débit

La limite QPS pour le téléversement de fichiers est de 3. La limite QPS totale pour les opérations de requête, de liste et de suppression est de 10.

Mise en production

  • Nettoyage périodique : Supprimez régulièrement les fichiers inutilisés pour rester dans la limite de 10 000 fichiers.
  • Vérification du statut : Vérifiez le statut du fichier après le téléversement. Un status à processed indique que le téléversement est terminé et que le fichier peut être référencé, mais pas que l'analyse est terminée. Avant la fin de l'analyse, les appels peuvent renvoyer File parsing in progress ; réessayez plus tard.
  • Contrôle des limites de débit : Assurez-vous de respecter les limites QPS (téléversement : 3 QPS, requête/liste/suppression : 10 QPS au total).
  • Gestion des erreurs : Mettez en œuvre une gestion des exceptions pour les erreurs réseau, les erreurs d'API et autres défaillances.

FAQ

1. Que faire si le statut du fichier reste « processing » après le téléversement ?

Le traitement des fichiers se termine généralement en quelques secondes. Si le statut reste « processing » pendant une période prolongée :
  • Vérifiez si le format du fichier est pris en charge.
  • Vérifiez si la taille du fichier dépasse la limite.
  • Utilisez l'API retrieve pour interroger périodiquement le statut.

2. Les ID de fichier peuvent-ils être utilisés sur différents comptes ?

Non. Les ID de fichier ne sont valides que dans le compte Alibaba Cloud qui les a créés et ne peuvent pas être partagés entre comptes.

3. Les fichiers téléversés sont-ils stockés définitivement ?

Oui. Les fichiers sont stockés de manière permanente dans votre compte sauf s'ils sont supprimés. Nettoyez périodiquement les fichiers inutiles.

4. Quelles sont les causes possibles d'échec de téléversement d'un fichier ?

  • La clé API est invalide ou n'a pas été exportée.
  • Le format du fichier n'est pas pris en charge.
  • La taille du fichier dépasse la limite (file-extract : 150 Mo, batch : 500 Mo).
  • Le nombre maximal de fichiers (10 000) ou la limite de taille totale (100 Go) a été atteint.
  • La limite QPS de l'interface de téléversement de fichiers a été dépassée. La limite est de 3 QPS.

5. Dois-je choisir file-extract ou batch pour le paramètre purpose ?

  • file-extract : À utiliser pour les scénarios d'analyse de documents avec Qwen-Long ou Qwen-Doc-Turbo.
  • batch : À utiliser pour les tâches par lot. Le fichier doit être un fichier JSONL conforme aux exigences de format.

6. Pourquoi Qwen-Long indique-t-il encore que le fichier est en cours d'analyse alors que le statut est « processed » ?

Un status à processed indique uniquement que le téléversement du fichier est terminé et que le fichier peut être référencé ; cela ne signifie pas que l'analyse est terminée. Si Qwen-Long renvoie File parsing in progress, please try again later., réessayez plus tard, une fois l'analyse du fichier terminée.

Description des paramètres

CatégorieParamètreTypeObligatoireDescriptionExemple
Téléversement de fichierfileFileOuiFichier à téléverser.Path("test.txt")
purposeStringOuiSpécifie l'objectif du fichier téléversé. Valeurs valides :file-extract : Pour la compréhension de documents avec le modèle qwen-long.batch : Pour les tâches Compatible OpenAI - Lot (entrée de fichier). Le fichier doit respecter le format spécifié dans Compatible OpenAI - Lot (entrée de fichier)."file-extract"
Requête de fichierfile_idStringOuiID du fichier à interroger."file-fe-xxx"
afterStringNonCurseur utilisé pour la pagination dans la tâche Interroger une liste de fichiers.Définissez after sur le dernier file_id de la page actuelle pour récupérer la page suivante. Exemple : si le dernier file_id est file-batch-xxx, définissez after="file-batch-xxx" dans la requête suivante."file-fe-xxx"
create_beforeStringNonHorodatage (format chaîne) pour Interroger une liste de fichiers. Retourne les ID de fichiers créés avant l'heure spécifiée."20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
create_afterStringNonHorodatage (format chaîne) pour Interroger une liste de fichiers. Retourne les ID de fichiers créés après l'heure spécifiée."20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
purposeStringNonPour Interroger une liste de fichiers : filtre par objectif (file-extract ou batch)."batch"
limitIntegerNonNombre de fichiers par requête dans Interroger une liste de fichiers. Plage : 1-2 000. Par défaut : 2 000.2000
Suppression de fichierfile_idStringOuiID du fichier à supprimer."file-fe-xxx"
Paramètres de réponse
Paramètres de réponse communsidString\ID du fichier.Pour Supprimer un fichier : ID du fichier supprimé."file-fe-xxx"
bytesIntegerTaille du fichier en octets.81067
created_atIntegerHorodatage UNIX en secondes de la création du fichier.1617981067
filenameStringNom du fichier téléversé."text.txt"
objectStringType d'objet. Toujours « list » pour Interroger une liste de fichiers, « file » pour les autres opérations."file"
purposeStringObjectif du fichier. Les valeurs valides sont batch, file-extract et batch_output."file-extract"
statusStringStatut actuel du fichier. processed indique que le téléversement est terminé et que le fichier peut être référencé ; cela ne signifie pas que l'analyse est terminée."processed"
Requête de liste de fichiershas_moreBooleanIndique s'il existe une page de données suivante.false
dataArrayListe des fichiers. Chaque élément suit le format des paramètres de réponse communs.
[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }]
Suppression de fichierdeletedBooleanIndique le succès de la suppression. Retourne true en cas de succès.true

Codes d'erreur

Si l'appel du modèle échoue et retourne un message d'erreur, consultez Codes d'erreur pour la résolution.