Interface de fichier OpenAI - Alibaba Cloud Model Studio - Centre de documentation Alibaba Cloud

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

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())

java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 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
                .apiKey(System.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
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Set the file path. Modify the path and filename as needed.
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // Create file upload parameters.
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("file-extract"))
                .build();

        // Upload the file.
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}

bash

# ======= Important =======
# 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
# 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/files
# === Delete this comment before running ===

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.txt"' \
--form 'purpose="file-extract"'

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
}

Pour le traitement par lot

Définissez purpose sur batch. Le fichier d'entrée doit être au format JSONL et conforme aux Exigences relatives aux fichiers par lot. La taille maximale du fichier est de 500 Mo.

Pour plus d'informations sur les appels par lot, consultez Compatible OpenAI - Lot (entrée de fichier) .

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.jsonl is a local sample file.
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())

java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 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
                .apiKey(System.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
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Set the file path. Modify the path and filename as needed.
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // Create file upload parameters.
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("batch"))
                .build();

        // Upload the file.
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}

bash

# ======= Important =======
# 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
# 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/files
# === Delete this comment before running ===

curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="batch"'

Exemple de réponse

{
    "id": "file-batch-xxx",
    "bytes": 231,
    "created_at": 1729065815,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "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

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
}

SDK OpenAI Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileObject;
import com.openai.models.FileRetrieveParams;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 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
                .apiKey(System.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
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Create file query parameters. Replace the fileId as needed.
        FileRetrieveParams params= FileRetrieveParams.builder()
                .fileId("file-batch-xxx")
                .build();
        //Query the file.
        FileObject fileObject = client.files().retrieve(params);
        System.out.println(fileObject);
    }
}

HTTP

Endpoint

Singapore region: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
China (Beijing) region: GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Exemples de requête

# ======= Important =======
# 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
# 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/files/file-batch-xxx
# === Delete this comment before running ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Si vous utilisez un modèle dans la région Chine (Pékin), vous devez utiliser une CLÉ API de la région Chine (Pékin) et remplacer l'URL par : https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

Exemple de réponse

{
    "id": "file-batch-xxx",
    "object": "file",
    "bytes": 499719,
    "created_at": 1715935833,
    "filename": "test.txt",
    "purpose": "batch",
    "status": "processed"
}

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.

RemarqueCette opération prend en charge des paramètres de filtrage supplémentaires. Pour plus d'informations, consultez Description des paramètres.

SDK OpenAI Python

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
}

SDK OpenAI Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        // Create a client and use the API key from the environment variable.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 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
                .apiKey(System.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
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Create file list query parameters.
        FileListParams params = FileListParams.builder()
                .after("file-batch-xxx")
                .limit(20)
                .build();
        //Query the file list.
        FileListPage file_stk = client.files().list(params);
        System.out.println(file_stk);
    }
}

HTTP

Endpoint

Singapore region: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files
China (Beijing) region: GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

Exemples de requête

# ======= Important =======
# 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
# 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/files
# === Delete this comment before running ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Si vous utilisez un modèle dans la région Chine (Pékin), vous devez utiliser une CLÉ API de la région Chine (Pékin) et remplacer l'URL par : https://dashscope.aliyuncs.com/compatible-mode/v1/files

Exemple de réponse

{
    "object": "list",
    "has_more": true,
    "data": [
        {
            "id": "file-batch-xxx",
            "object": "file",
            "bytes": 84889,
            "created_at": 1715569225,
            "filename": "example.txt",
            "purpose": "batch",
            "status": "processed"
        },
        {
            "id": "file-batch-yyy",
            "object": "file",
            "bytes": 722355,
            "created_at": 1715413868,
            "filename": "Agent_survey.pdf",
            "purpose": "batch",
            "status": "processed"
        }
    ]
}

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

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"
}

SDK OpenAI Java

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileDeleteParams;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 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
                .apiKey(System.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
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        FileDeleteParams params = FileDeleteParams.builder()
                .fileId("file-batch-xxx")
                .build();

        System.out.println(client.files().delete(params));
    }
}

HTTP

Endpoint

Singapore region: DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
China (Beijing) region: https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Exemples de requête

# ======= Important =======
# 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
# 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/files/file-batch-xxx
# === Delete this comment before running ===
curl -X  DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Si vous utilisez un modèle de la région Chine (Pékin), vous devez utiliser une CLÉ API de la région Chine (Pékin) et remplacer l'URL par : https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

Exemple de réponse

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

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 que le status est processed avant d'utiliser les fichiers téléversés.
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.

Description des paramètres

Catégorie	Paramètre	Type	Obligatoire	Description	Exemple
Téléversement de fichier	file	File	Oui	Fichier à téléverser.	Path("test.txt")
Téléversement de fichier	purpose	String	Oui	Spé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 fichier	file_id	String	Oui	ID du fichier à interroger.	"file-fe-xxx"
	after	String	Non	Curseur 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_before	String	Non	Horodatage (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_after	String	Non	Horodatage (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"`
	purpose	String	Non	Pour Interroger une liste de fichiers : filtre par objectif (`file-extract` ou `batch`).	"batch"
	limit	Integer	Non	Nombre de fichiers par requête dans Interroger une liste de fichiers. Plage : 1-2 000. Par défaut : 2 000.	2000
Suppression de fichier	file_id	String	Oui	ID du fichier à supprimer.	"file-fe-xxx"
Paramètres de réponse
Paramètres de réponse communs	id	String	\	ID du fichier. Pour Supprimer un fichier : ID du fichier supprimé.	"file-fe-xxx"
	bytes	Integer		Taille du fichier en octets.	81067
	created_at	Integer		Horodatage UNIX en secondes de la création du fichier.	1617981067
	filename	String		Nom du fichier téléversé.	"text.txt"
	object	String		Type d'objet. Toujours « list » pour Interroger une liste de fichiers, « file » pour les autres opérations.	"file"
	purpose	String		Objectif du fichier. Les valeurs valides sont `batch`, `file-extract` et `batch_output`.	"file-extract"
	status	String		Statut actuel du fichier.	"processed"
Requête de liste de fichiers	has_more	Boolean		Indique s'il existe une page de données suivante.	false
Requête de liste de fichiers	data	Array		Liste 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 fichier	deleted	Boolean		Indique 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.