全部產品
Search

搜尋本產品

    Alibaba Cloud Model Studio：OpenAI檔案介面相容

    文件中心

    Alibaba Cloud Model Studio：OpenAI檔案介面相容

    更新時間：Nov 15, 2025

    檔案上傳介面用於上傳檔案，以便在Qwen-Long和Qwen-Doc-Turbo模型中進行文檔問答與資料提取，或將其用作批量推理任務的輸入檔案。

    使用方式

    支援通過OpenAI SDK（Python、Java）或HTTP API調用檔案介面，包括上傳、查詢、刪除等操作。

    前提條件

    支援的模型

    檔案ID可用於以下情境：

    • Qwen-Long：通過檔案ID進行長文檔問答

    • Qwen-Doc-Turbo：通過檔案ID進行檔案內資料提取與問答

    • 批量推理：通過檔案ID上傳批量任務輸入檔案

    快速開始

    上傳檔案

    百鍊儲存空間支援的最大檔案數為10000個，總大小不超過100 GB，暫時沒有有效期間限制。

    用於文件剖析

    將purpose指定為file-extract，檔案格式支援文字檔（ TXT、DOCX、PDF、XLSX、EPUB、MOBI、MD、CSV、JSON），圖片檔案（BMP、PNG、JPG/JPEG、GIF和PDF掃描件），單個檔案最大為 150 MB。

    關於通過file_id進行文件剖析，請參考長上下文（Qwen-Long）。

    請求樣本

    import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key="sk-xxx",
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.txt 是一個本地樣本檔案
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())
    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) {
        // 建立用戶端，使用環境變數中的API密鑰
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // 設定檔案路徑,請根據實際需求修改路徑與檔案名稱
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // 建立檔案上傳參數
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("file-extract"))
                .build();

        // 上傳檔案
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}
    # ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === 執行時請刪除該注釋 ===

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

    響應樣本

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

    用於Batch調用

    purpose指定為batch，輸入檔案必須是jsonl檔案且符合輸入檔案，上傳Batch任務的單個檔案最大為500 MB。

    關於Batch調用的更多用法，請參考OpenAI相容-Batch。

    請求樣本

    import os
from pathlib import Path
from openai import OpenAI


client = OpenAI(
    # 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key="sk-xxx",
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl 是一個本地樣本檔案
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())
    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) {
        // 建立用戶端，使用環境變數中的API密鑰
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // 設定檔案路徑,請根據實際需求修改路徑與檔案名稱
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // 建立檔案上傳參數
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("batch"))
                .build();

        // 上傳檔案
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}
    # ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === 執行時請刪除該注釋 ===

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

    響應樣本

    {
    "id": "file-batch-xxx",
    "bytes": 231,
    "created_at": 1729065815,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "status": "processed",
    "status_details": null
}

    查詢檔案資訊

    通過在retrieve或GET方法中指定file_id來查詢檔案資訊。

    OpenAI Python SDK

    請求樣本

    import os
from openai import OpenAI

client = OpenAI(
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：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())

    返回樣本

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

    OpenAI Java SDK

    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) {
        // 建立用戶端，使用環境變數中的API密鑰
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // 建立檔案查詢參數,請根據實際需求替換相應的fileId
        FileRetrieveParams params= FileRetrieveParams.builder()
                .fileId("file-batch-xxx")
                .build();
        //查詢檔案
        FileObject fileObject = client.files().retrieve(params);
        System.out.println(fileObject);
    }
}

    HTTP

    需要配置的endpoint

    新加坡地區：GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
北京地區：GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

    請求樣本

    # ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === 執行時請刪除該注釋 ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
    如果使用華北2（北京）地區的模型，請使用華北2（北京）地區的 API KEY，並將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

    返回樣本

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

    查詢檔案清單

    返回所有檔案的資訊，包括通過上傳檔案介面上傳的檔案以及batch任務的結果檔案。

    說明

    此介面支援更多篩選參數，詳情請參見參數說明。

    OpenAI Python SDK

    請求樣本

    import os
from openai import OpenAI

client = OpenAI(
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
     # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：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())

    返回樣本

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

    OpenAI Java SDK

    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) {
        // 建立用戶端，使用環境變數中的API密鑰
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // 建立檔案清單查詢參數
        FileListParams params = FileListParams.builder()
                .after("file-batch-xxx")
                .limit(20)
                .build();
        //查詢檔案清單
        FileListPage file_stk = client.files().list(params);
        System.out.println(file_stk);
    }
}

    HTTP

    需要配置的endpoint

    新加坡地區：GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files
北京地區：GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

    請求樣本

    # ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === 執行時請刪除該注釋 ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
    如果使用華北2（北京）地區的模型，請使用華北2（北京）地區的 API KEY，並將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files

    返回樣本

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

    刪除檔案

    通過刪除檔案介面刪除指定file_id的檔案。可以通過查詢檔案清單介面查詢檔案資訊。

    OpenAI Python SDK

    請求樣本

    import os
from openai import OpenAI

client = OpenAI(
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：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())

    返回樣本

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

    OpenAI Java SDK

    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 Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：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

    新加坡地區：DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
北京地區：https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

    請求樣本

    # ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === 執行時請刪除該注釋 ===
curl -X  DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
    如果使用華北2（北京）地區的模型，請使用華北2（北京）地區的 API KEY，並將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

    返回樣本

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

    計費說明

    檔案上傳、儲存和查詢操作不產生費用。僅在調用模型API時，根據實際使用的輸入Token和輸出Token進行計費。

    限流

    上傳檔案介面的QPS（每秒請求數）限制為3。查詢檔案資訊、查詢檔案清單、刪除檔案介面的QPS總和限制為10。

    應用於生產環境

    • 定期清理：定期刪除不再使用的檔案，避免達到10000個檔案上限。

    • 狀態檢查：上傳後檢查檔案狀態，確保status為processed後再使用。

    • 限流檢查：上傳檔案介面的QPS（每秒請求數）限制為3。查詢檔案資訊、查詢檔案清單、刪除檔案介面的QPS總和限制為10。

    • 錯誤處理：實現完整的異常處理機制，包括網路錯誤、API錯誤等。

    常見問題

    1. 檔案上傳後狀態一直是"processing"怎麼辦？

    檔案處理需要一定時間，通常幾秒內完成。如果長時間處於"processing"狀態：

    • 檢查檔案格式是否支援

    • 檢查檔案大小是否超過限制

    • 使用retrieve介面定期查詢狀態

    2. 檔案ID可以跨帳號使用嗎？

    不可以。檔案ID僅在產生它的阿里雲主帳號內有效，不支援跨帳號共用。

    3. 上傳的檔案會被永久儲存嗎？

    是的，上傳的檔案會被永久儲存在您的阿里雲帳號下，除非主動刪除。建議定期清理不需要的檔案。

    4. 檔案上傳失敗，可能的原因有哪些？

    • API Key無效或未配置

    • 檔案格式不支援

    • 檔案大小超過限制（file-extract: 150MB，batch: 500MB）

    • 已達到檔案數量上限（10000個）或總大小上限（100GB）

    • 上傳檔案介面的QPS（每秒請求數）限制為3。

    5. purpose參數應該選擇file-extract還是batch？

    • file-extract：用於文件剖析情境，配合Qwen-Long或Qwen-Doc-Turbo使用

    • batch：用於批量推理任務，檔案必須是符合格式要求的JSONL檔案

    參數說明

    介面類別

    參數名

    類型

    必選

    說明

    樣本值

    文檔上傳

    file

    File

    是

    用於指定待上傳的檔案。

    Path("test.txt")

    purpose

    String

    是

    用於指定上傳檔案的用途，當前可選值如下：

    file-extract: 用於qwen-long模型的文檔理解；

    batch: 用於OpenAI相容-Batch任務，file格式必須滿足輸入檔案

    "file-extract"

    檔案查詢

    file_id

    String

    是

    待查詢的檔案id。

    "file-fe-xxx"

    after

    String

    否

    查詢檔案清單任務中用於分頁的遊標。

    參數after的取值為當前分頁的最後一個file_id，表示查詢該ID之後下一頁的資料。

    例如，若本次查詢返回了20條資料，且最後一個file_id是file-batch-xxx，則後續查詢時可以設定after="file-batch-xxx"，以擷取列表的下一頁。

    "file-fe-xxx"

    create_before

    String

    否

    查詢檔案清單任務中，一個字串格式的時間戳記。用於篩選並返回建立時間早於該指定時間點的file_id。

    "20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"

    create_after

    String

    否

    查詢檔案清單任務中，一個字串格式的時間戳記。用於篩選並返回建立時間晚於該指定時間點的file_id。

    "20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"

    purpose

    String

    否

    查詢檔案清單任務中根據檔案的用途進行篩選，僅返回與指定 purpose（file-extract或batch）相匹配的file_id。

    "batch"

    limit

    Integer

    否

    查詢檔案清單任務中每次查詢返回的檔案數量，取值範圍[1,2000]，預設2000。

    2000

    檔案刪除

    file_id

    String

    是

    待刪除檔案id。

    "file-fe-xxx"

    響應參數

    通用響應參數

    id

    String

    \

    檔案的標識符

    刪除檔案任務中表示成功刪除的檔案的id。

    "file-fe-xxx"

    bytes

    Integer

    檔案大小，單位為位元組。

    81067

    created_at

    Integer

    檔案建立時的 Unix 時間戳記（秒）。

    1617981067

    filename

    String

    上傳的檔案名稱。

    "text.txt"

    object

    String

    物件類型

    查詢檔案清單任務中始終為"list"。

    其餘類型任務中始終為"file"。

    "file"

    purpose

    String

    檔案的用途，取值有batch、file-extract、batch_output。

    "file-extract"

    status

    String

    檔案的目前狀態。

    "processed"

    查詢檔案清單

    has_more

    Boolean

    是否還有下一頁資料。

    false

    data

    Array

    返回的檔案清單，列表中每個元素格式與通用相應參數一致。

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

    刪除檔案

    deleted

    Boolean

    是否刪除成功，true表示刪除成功。

    true

    錯誤碼

    如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。