阿里雲百鍊提供與 OpenAI 相容的 Batch File API,支援通過檔案批量提交請求。系統非同步處理所有請求,在全部完成或達到最長等待時間後返回結果,費用僅為即時調用的 50% 。適用於資料分析、模型評測等時效性要求不高但需大批量處理的情境。
工作流程
前提條件
支援通過 OpenAI SDK(Python、Node.js)或HTTP API調用 Batch File 介面。
- 擷取API Key:擷取並配置API Key 到環境變數
- 安裝 SDK(可選):如需使用SDK調用,請安裝 OpenAI SDK
-
服務端點
- 華北2(北京):
https://dashscope.aliyuncs.com/compatible-mode/v1 - 新加坡:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- 華北2(北京):
適用範圍
- 新加坡
- 華北2(北京)
快速開始
在處理正式任務前,使用測試模型batch-test-model進行全鏈路閉環測試。該模型跳過推理過程,直接返回固定的成功響應,用於驗證API調用鏈路和資料格式是否正確。
- 測試檔案需滿足輸入檔案要求,且檔案大小不超過 1 MB,行數不超過100行。
- 並發限制:最大並行任務數 2 個。
- 費用:測試模型不產生模型推理費用。
第 1 步:準備輸入檔案
準備一個名為test_model.jsonl的檔案,內容如下:
第 2 步:運行代碼
根據使用的程式設計語言,選擇以下範例程式碼並儲存到輸入檔案的同一目錄下,然後運行。代碼將完成檔案上傳、建立任務、輪詢狀態和下載結果的完整流程。
如需調整檔案路徑或其他參數,請根據實際情況修改代碼。
file-batch-xxx)可重複使用。如果輸入內容不變,無需每次重新上傳,直接用已有 ID 建立任務即可:client.files.list(purpose="batch") 介面查詢已上傳的 Batch 檔案 ID。範例程式碼
範例程式碼
第 3 步: 驗證測試結果
任務成功完成後,結果檔案result.jsonl包含固定響應{"content":"This is a test result."}:
執行正式任務
輸入檔案要求
- 格式:UTF-8 編碼的 JSONL(每行一個獨立JSON對象)
- 規模限制:單檔案最多 50,000 個請求,且不超過 500 MB
- 單行限制:每個JSON對象不超過 6 MB,且不超過模型上下文長度
- 一致性要求:同一檔案內所有請求須使用相同的模型及思考模式(如適用)
- 唯一標識:每個請求必須包含檔案內唯一的 custom_id 欄位,用於匹配請求與結果
樣本中的 Base64 字串已省略,使用下方 Python 代碼產生完整編碼即可。
傳入 Base 64 編碼字串(以映像為例)
傳入 Base 64 編碼字串(以映像為例)
- 將本地檔案轉換為 Base 64 編碼:
-
構建Data URL格式:
data:[MIME_type];base64,{base64_image};MIME_type需替換為實際的媒體類型,確保與MIME Type的值匹配(如image/jpeg、image/png);base64_image為上一步產生的 Base64 字串。
使用方式
- 將以下代碼儲存為
generate_batch_jsonl.py - 修改指令碼中
TASKS列表的請求內容 - 運行
python generate_batch_jsonl.py - 產生的
batch_input.jsonl檔案可直接用於 Batch 推理任務
文本產生模型 JSONL 產生指令碼
多模態模型請求格式
多模態模型的 content 欄位為數組格式,包含媒體對象和文本提問。每行請求中的媒體URL需為同一類型(圖片、視頻或音頻)。將上方指令碼中的 TASKS 替換為以下格式即可:
文本向量模型請求格式
文本向量模型使用 /v1/embeddings 介面,請求格式不同於文本產生模型。可使用以下獨立指令碼產生:
1. 修改輸入檔案
-
可直接修改用於測試的
test_model.jsonl檔案,將 model 參數設定為目標正式模型,並設定URL欄位:模型類型
url
文本產生/多模態模型
/v1/chat/completions文本向量模型
/v1/embeddings -
或使用上方的“JSONL 批量產生工具”為正式任務產生一個新的檔案。關鍵是確保
model和url欄位正確。
2. 修改快速開始的代碼
- 輸入檔案路徑更改為您的檔案名稱
- 將 endpoint 參數值修改為與輸入檔案中URL欄位一致的值
3. 運行代碼並等待結果
任務完成後,成功請求的結果儲存在本地 result.jsonl 檔案中。如有請求失敗,錯誤詳情儲存在 error.jsonl 檔案中。
- 成功結果(
output_file_id):每一行對應一個成功的原始請求,包含custom_id和response。
- 失敗請求詳情(
error_file_id):包含處理失敗的請求行資訊和錯誤原因,可參考錯誤碼進行排查。
具體流程
Batch API使用流程分為四步:上傳檔案、建立任務、查詢任務狀態、下載結果。
1. 上傳檔案
1. 上傳檔案
file_id。上傳檔案,purpose必須是batch。
file-batch-xxx)可重複使用。如果輸入內容不變,無需每次重新上傳,直接用已有 ID 建立任務即可:client.files.list(purpose="batch") 介面查詢已上傳的 Batch 檔案 ID。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
請求樣本
返回樣本
2. 建立 Batch 任務
2. 建立 Batch 任務
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
請求樣本
輸入參數
欄位 | 類型 | 傳參 方式 | 必選 | 描述 |
|---|---|---|---|---|
input_file_id | String | Body | 是 | 用於指定檔案ID,作為Batch任務的輸入檔案。 使用準備與上傳檔案介面返回的檔案ID,如 |
endpoint | String | Body | 是 | 訪問路徑,須與輸入檔案中的URL欄位一致。
|
completion_window | String | Body | 是 | 等待時間,最短 24h,最長 336h,僅支援整數。 支援"h"和"d"兩個單位,如"24h"或"14d"。 |
metadata | Map | Body | 否 | 任務擴充中繼資料,以索引值對形式附加額外資訊。 |
metadata.ds_name | String | Body | 否 | 任務名稱。 樣本: 限制:長度不超過100個字元。 若重複定義該欄位,以最後一次傳入的值為準。 |
metadata.ds_description | String | Body | 否 | 任務描述。 樣本: 限制:長度不超過200個字元。 若重複定義該欄位,以最後一次傳入的值為準。 |
返回樣本
返回參數
欄位 | 類型 | 描述 |
|---|---|---|
id | String | 本次建立的 Batch 任務 ID。 |
object | String | 物件類型,固定值 |
endpoint | String | 訪問路徑。 |
errors | Map | 錯誤資訊。 |
input_file_id | String | 檔案ID 。 |
completion_window | String | 等待時間,支援最短等待時間24h,最長等待時間336h,僅支援整數。 支援"h"和"d"兩個單位,如"24h"或"14d"。 |
status | String | 任務狀態,可選值:validating、failed、in_progress、finalizing、completed、expired、cancelling、cancelled。 |
output_file_id | String | 成功請求的輸出檔案 ID。 |
error_file_id | String | 失敗請求的錯誤檔案 ID。 |
created_at | Integer | 任務建立的 Unix 時間戳記(秒)。 |
in_progress_at | Integer | 任務開始啟動並執行 Unix 時間戳記(秒)。 |
expires_at | Integer | 任務預計到期的 Unix 時間戳記(秒)。 |
finalizing_at | Integer | 任務開始匯總結果的 Unix 時間戳記(秒)。 |
completed_at | Integer | 任務完成的 Unix 時間戳記(秒)。 |
failed_at | Integer | 任務失敗的 Unix 時間戳記(秒)。 |
expired_at | Integer | 任務到期的 Unix 時間戳記(秒)。 |
cancelling_at | Integer | 任務開始取消的 Unix 時間戳記(秒)。 |
cancelled_at | Integer | 任務取消完成的 Unix 時間戳記(秒)。 |
request_counts | Map | 各狀態的請求數量統計。 |
metadata | Map | 附加中繼資料,索引值對形式。 |
metadata.ds_name | String | 任務名稱。 |
metadata.ds_description | String | 任務描述。 |
3. 查詢 與管理 Batch 任務
3. 查詢 與管理 Batch 任務
查詢指定任務狀態
查詢指定任務狀態
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
請求樣本
返回樣本
查詢成功後返回 Batch 任務的詳細資料。以下為 completed 狀態的返回樣本:欄位 | 類型 | 描述 |
|---|---|---|
id | String | Batch 任務 ID。 |
status | String | 任務狀態,可能的值包括:
|
output_file_id | String | 成功結果檔案的 ID,任務完成後產生。 |
error_file_id | String | 失敗結果檔案的 ID,任務完成且有失敗請求時產生。 |
request_counts | Object | 請求數量統計對象,包含 total、completed、failed 欄位。 |
查詢工作清單
查詢工作清單
batches.list() 方法查詢 Batch 工作清單,通過分頁機制逐步擷取完整的工作清單。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
請求樣本
輸入參數
欄位 | 類型 | 傳參方式 | 必選 | 描述 |
|---|---|---|---|---|
after | String | Query | 否 | 用於分頁的遊標,值為上一頁最後一個任務的ID。 |
limit | Integer | Query | 否 | 每頁返回的任務數量,範圍[1, 100],預設20。 |
ds_name | String | Query | 否 | 按任務名稱進行模糊比對。 |
input_file_ids | String | Query | 否 | 按檔案ID篩選,多個ID用逗號分隔,最多20個。 |
status | String | Query | 否 | 按任務狀態篩選,多個狀態用逗號分隔。 |
create_after | String | Query | 否 | 篩選在此時間點之後建立的任務,格式: |
create_before | String | Query | 否 | 篩選在此時間點之前建立的任務,格式: |
返回樣本
返回參數
欄位 | 類型 | 描述 |
|---|---|---|
object | String | 類型,固定值list。 |
data | Array | Batch任務對象,參見建立Batch任務的返回參數。 |
first_id | String | 當前頁第一個 Batch任務 ID。 |
last_id | String | 當前頁最後一個Batch任務 ID。 |
has_more | Boolean | 是否有下一頁。 |
取消Batch任務
取消Batch任務
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
請求樣本
返回樣本
取消任務成功後返回 Batch 任務的詳細資料。以下是一個 cancelling 狀態的返回樣本:取消任務後,狀態會先變為cancelling,等待正在執行的請求完成;最終會變為cancelled。已完成的請求結果仍會儲存在輸出檔案中。
4. 下載Batch結果檔案
4. 下載Batch結果檔案
file-batch_output開頭的file_id對應的檔案。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
content方法擷取Batch任務結果檔案內容,並通過write_to_file方法將其儲存至本地。請求樣本
返回樣本
返回樣本
單條響應結果:返回參數
欄位 | 類型 | 描述 |
|---|---|---|
id | String | 請求 ID。 |
custom_id | String | 使用者自訂的 ID。 |
response | Object | 請求結果。 |
status_code | Integer | 狀態代碼。200表示請求成功。 |
request_id | String | 服務端為這次請求產生的唯一ID。 |
completion_tokens | Integer | 模型產生的回複內容(completion)所消耗的Token數量。 |
prompt_tokens | Integer | 發送給模型的輸入內容( |
total_tokens | Integer | 本次調用總共消耗的Token數量。 |
model | String | 本次調用所使用的模型名稱。 |
error | Object | 錯誤資訊對象。如果API調用成功,該值為 |
error.code | String | 錯誤行資訊和錯誤原因,可參考錯誤碼進行排查。 |
error.message | String | 錯誤資訊。 |
進階功能
配置任務完成通知
長時間啟動並執行任務使用輪詢會消耗不必要的資源。建議配置非同步通知,系統在任務完成後主動通知。
- Callback 回調:在建立任務時指定一個公網可訪問的 URL
- EventBridge 訊息佇列:與阿里雲生態深度整合,無需公網 IP
方式一:Callback 回調
方式一:Callback 回調
metadata 指定一個公網可訪問的 URL。任務完成後,系統向該URL發送包含任務狀態的 POST 請求:- OpenAI Python SDK
- curl(HTTP)
方式二:EventBridge 訊息佇列
方式二:EventBridge 訊息佇列
- 事件來源 (Source):
acs.dashscope - 事件類型 (Type):
dashscope:System:BatchTaskFinish
應用於生產環境
-
檔案管理
- 定期調用 OpenAI-File刪除檔案介面刪除不需要的檔案,避免達到檔案儲存體上限(10000個檔案或100GB)
- 對於大型檔案,推薦將其儲存在阿里雲OSS中
-
任務監控
- 優先使用 Callback 或 EventBridge 非同步通知
- 輪詢間隔 > 1分鐘,使用指數退避策略
-
錯誤處理
- 實現完整的異常處理機制,涵蓋網路錯誤、API 錯誤等
- 下載並分析
error_file_id的錯誤詳情 - 對於常見錯誤碼,參考錯誤碼進行解決
-
成本最佳化
- 合并小任務到一個批次
- 合理設定
completion_window提供更多調度靈活性
工具 + 生產力
CSV 轉 JSONL
CSV 轉 JSONL
如需調整檔案路徑或其他參數,請根據實際情況修改代碼。
JSONL 結果轉 CSV
JSONL 結果轉 CSV
result.jsonl 檔案解析為易於在Excel中分析的 result.csv 檔案。如需調整檔案路徑或其他參數,請根據實際情況修改代碼。
- 可使用文字編輯器(如Sublime)將 CSV 檔案的編碼轉換為GBK,然後再用Excel開啟。
- 或在Excel中建立一個Excel檔案,並在匯入資料時指定正確的編碼格式 UTF-8。
介面限流
介面 | 限流(主帳號層級) |
|---|---|
建立任務 | 1000 次/分鐘,最大並行 1000 個 |
查詢任務 | 1000 次/分鐘 |
查詢工作清單 | 100 次/分鐘 |
取消任務 | 1000 次/分鐘 |
計費說明
- 計費單價: 所有成功請求的輸入和輸出Token,單價均為對應模型即時推理價格的50% ,具體請參見模型列表。
-
計費範圍:
- 僅對成功執行的請求計費。
- 檔案解析失敗、任務執行失敗或行級錯誤請求均不產生費用 。
- 已取消的任務中,取消前已成功完成的請求仍正常計費。
- 批量推理為獨立計費項目,支援AI 通用型節省計劃,但不支援預付費(節省計劃)、新人免費額度等優惠,以及上下文緩衝等功能。
- 部分模型(如 qwen3.5-plus、qwen3.5-flash)預設開啟思考模式,會產生額外的思考tokens,並按輸出token價格計費,導致成本增加。建議根據任務複雜度設定enable_thinking參數以控製成本,具體請參考深度思考。
錯誤碼
調用失敗時,請參見錯誤碼進行解決。
常見問題
- 如何選擇使用 Batch Chat 還是Batch File? 處理包含大量請求的單個大檔案且可非同步擷取結果時,選擇 Batch File。需要以API同步調用方式高並發提交大量獨立對話請求時,選擇 Batch Chat。
- Batch File調用如何計費?需要單獨購買嗎? 答:Batch 是一種調用方式,採用後付費模式,按成功請求的 Token 用量計費,無需額外購買套餐。
- 提交的Batch File是按順序執行的嗎? 答:不是。系統採用動態調度機制,根據計算資源負載安排任務執行,不保證嚴格遵循提交順序。資源緊張時,任務啟動和執行可能延遲。
- 提交的Batch File需要多長時間完成? 答:執行時間取決於系統資源分派和任務規模。若任務在設定的 completion_window 內未完成,狀態變為 expired,未處理的請求不再執行,也不產生費用。 情境建議:對時效性有嚴格要求的情境,建議使用即時調用;對時效性有一定容忍度的大規模資料處理情境,推薦使用 Batch 調用。