Skip to main content
工具包/架構

OpenAI檔案介面相容

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

使用方式

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

前提條件

支援的模型

檔案ID可用於以下情境：
  • Qwen-Long：通過檔案ID進行長文檔問答
  • Qwen-Doc-Turbo：通過檔案ID進行檔案內資料提取與問答
  • 批量推理：通過檔案ID上傳批量任務輸入檔案

快速開始

上傳檔案

百鍊儲存空間支援的最大檔案數為10000個，總大小不超過100 GB，暫時沒有有效期間限制。
  • 用於文件剖析
  • 用於Batch調用
將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())

響應樣本 

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

查詢檔案資訊

通過在retrieve或GET方法中指定file_id來查詢檔案資訊。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

請求樣本 

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
}

查詢檔案清單

返回所有檔案的資訊，包括通過上傳檔案介面上傳的檔案以及batch任務的結果檔案。
此介面支援更多篩選參數，詳情請參見參數說明。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

請求樣本 

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
}

刪除檔案

通過刪除檔案介面刪除指定file_id的檔案。可以通過查詢檔案清單介面查詢檔案資訊。
  • OpenAI Python SDK
  • OpenAI Java SDK
  • HTTP

請求樣本 

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

計費說明

檔案上傳、儲存和查詢操作不產生費用。僅在調用模型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檔案

參數說明

介面類別參數名類型必選說明樣本值
文檔上傳fileFile是用於指定待上傳的檔案。Path("test.txt")
purposeString是用於指定上傳檔案的用途，當前可選值如下：file-extract: 用於qwen-long模型的文檔理解；batch: 用於OpenAI相容-Batch任務，file格式必須滿足輸入檔案"file-extract"
檔案查詢file_idString是待查詢的檔案id。"file-fe-xxx"
afterString否查詢檔案清單任務中用於分頁的遊標。參數after的取值為當前分頁的最後一個file_id，表示查詢該ID之後下一頁的資料。例如，若本次查詢返回了20條資料，且最後一個file_id是file-batch-xxx，則後續查詢時可以設定after="file-batch-xxx"，以擷取列表的下一頁。"file-fe-xxx"
create_beforeString否查詢檔案清單任務中，一個字串格式的時間戳記。用於篩選並返回建立時間早於該指定時間點的file_id。"20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
create_afterString否查詢檔案清單任務中，一個字串格式的時間戳記。用於篩選並返回建立時間晚於該指定時間點的file_id。"20250306123000", "2025-11-12 10:10:10", "2025-11-12", "20251112"
purposeString否查詢檔案清單任務中根據檔案的用途進行篩選，僅返回與指定 purpose（file-extract或batch）相匹配的file_id。"batch"
limitInteger否查詢檔案清單任務中每次查詢返回的檔案數量，取值範圍[1,2000]，預設2000。2000
檔案刪除file_idString是待刪除檔案id。"file-fe-xxx"
響應參數
通用響應參數idString\檔案的標識符刪除檔案任務中表示成功刪除的檔案的id。"file-fe-xxx"
bytesInteger檔案大小，單位為位元組。81067
created_atInteger檔案建立時的 Unix 時間戳記（秒）。1617981067
filenameString上傳的檔案名稱。"text.txt"
objectString物件類型查詢檔案清單任務中始終為"list"。其餘類型任務中始終為"file"。"file"
purposeString檔案的用途，取值有batch、file-extract、batch_output。"file-extract"
statusString檔案的目前狀態。"processed"
查詢檔案清單has_moreBoolean是否還有下一頁資料。false
dataArray返回的檔案清單，列表中每個元素格式與通用相應參數一致。
[{
 "id": "xxx",
 "bytes": 27,
 "created_at": 1722480543,
 "filename": "test.txt",
 "object": "file",
 "purpose": "batch",
 "status": "processed",
 "status_details": null
 }]
刪除檔案deletedBoolean是否刪除成功，true表示刪除成功。true

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多