批量推理

步驟一：準備輸入檔案

建立任務前，準備一個符合以下規範的 JSONL 檔案：

• 格式：UTF-8 編碼的 JSONL（每行一個獨立JSON對象）。

• 規模限制：單檔案 ≤ 50,000 個請求，且 ≤ 500 MB。

  資料量超出此限制時，拆分為多個任務分別提交。

• 單行限制：每個JSON對象 ≤ 6 MB，且不超過模型上下文長度。

• 一致性要求：同一檔案內所有請求須使用相同模型。

• 唯一標識：每個請求必須包含檔案內唯一的 custom_id 欄位，用於結果匹配。custom_id 最大支援 256 個字元，超過此限制將導致任務校正失敗。如需回傳更長的標識資訊，可在建立任務時通過 metadata 的自訂欄位實現，詳見使用 metadata 回傳自訂標識。

每個JSON對象須遵循以下欄位規範：

{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-max","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-max","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}

{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":false,"messages":[{"role":"user","content":"你好"}]}}

{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":true,"thinking_budget":50,"messages":[{"role":"user","content":"請分析以下問題"}]}}

步驟二：建立批量推理任務

1. 在**批量推理**頁面，單擊创建批量推理任务。

2. 在彈出的對話方塊中：填寫任务名称和描述，設定最长等待时间（1–14 天），上傳 JSONL 檔案。

   可單擊 下载示例文件 擷取模板。

   

3. 填寫完成後，單擊确认。

步驟三：監控和管理工作

• 查看：

  • 在工作清單頁，查看任務的進度（已處理請求數/總請求數）和状态。

  • 按任務名稱或ID搜尋，或按業務空間篩選，快速定位目標任務。

• 管理：

  • 取消："執行中"的任務可在操作列取消。

  • 排錯："失敗"的任務可懸停狀態查看錯誤概要，下載錯誤檔案查看詳情。

步驟四：下載結果

任務完成後，單擊查看结果，下載產出檔案：

• 結果檔案：記錄所有成功請求及其 response 結果。

• 錯誤檔案（如有）：記錄所有失敗請求及其 error 詳情。

兩個檔案均包含 custom_id 欄位，用於與原始輸入資料匹配，關連接果或定位錯誤。

步驟五：查看用量統計（可選）

在模型監控頁面，篩選並查看批量推理的用量統計。

metadata 欄位說明

metadata 是建立 Batch 任務時的選擇性參數，支援以下欄位：

• ds_name：任務名稱，設定後將顯示在控制台的任务名称列。

• ds_description：任務描述，設定後將顯示在控制台的任务描述列。

• 自訂欄位：除上述官方欄位外，metadata 還支援任意自訂欄位，且自訂欄位的值不受 256 個字元的限制。查詢任務詳情時，所有自訂欄位會完整回傳。

程式碼範例

以下樣本展示如何通過 metadata 的自訂欄位回傳超過 256 個字元的標識資訊：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxxxxxxxxxxxxxxxxxxx",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "ds_name": "my_batch_task",
        "ds_description": "批量推理任務描述",
        "my_custom_field": "此欄位的值可以超過256個字元，用於回傳更長的標識資訊..."
    }
)
print(batch)

任務建立成功後，通過查詢任務詳情介面（GET /v1/batches/{batch_id}）可擷取完整的 metadata 資訊，包括所有自訂欄位及其完整內容。

在生產環境中，使用相容 OpenAI 的API自動化建立和管理 Batch 任務。核心流程如下：

1. 上傳檔案

   調用 POST /v1/files 上傳檔案，記錄返回的檔案 ID。

2. 建立任務傳入檔案ID ，調用 POST /v1/batches 建立任務，記錄返回的 batch_id。

3. 輪詢狀態使用 batch_id 輪詢 GET /v1/batches/{batch_id}。當 status 變為 completed 時，記錄 output_file_id 並停止輪詢。

4. 下載結果使用 output_file_id 調用 GET /v1/files/{output_file_id}/content，下載結果檔案。

• 計費單價： 所有成功請求的輸入和輸出 Token，單價均為對應模型即時推理價格的 50%，具體請參見模型列表。

• 計費範圍：

  • 僅對任務中成功執行的請求計費。

  • 檔案解析失敗、任務執行失敗、或行級錯誤請求均不產生費用。

  • 對於被取消的任務，在取消前已成功完成的請求仍正常計費。