Alibaba Cloud Model Studio：批量推理

對於無需即時響應的推理情境，批量推理能非同步處理大批量的資料請求，成本僅為即時推理的 50% ，且介面相容 OpenAI，適合執行模型評測、資料標註等批量作業。

工作原理

1. 提交任務：上傳包含多個請求的 JSONL 檔案，建立批量推理任務。
2. 非同步處理：系統在後台隊列中處理任務。可通過控制台或API查詢任務進度和狀態。
3. 下載結果：任務完成後，系統產生結果檔案（記錄成功響應）和錯誤檔案（記錄失敗詳情，如有）。

適用範圍

新加坡

支援的模型：qwen-max、qwen-plus、qwen-flash、qwen-turbo。

華北2（北京）

支援的模型：

• 文本產生模型
  • 千問 Max：qwen3.8-max、qwen3.7-max、qwen3-max、qwen-max、qwen-max-latest
  • 千問 Plus：qwen3.7-plus、qwen3.6-plus、qwen3.5-plus、qwen-plus、qwen-plus-latest
  • 千問 Flash：qwen3.8-flash、qwen3.7-flash、qwen3.6-flash、qwen3.5-flash、qwen-flash
  • 千問 Long：qwen-long-latest
  • QwQ：qwq-plus
  • 第三方模型：deepseek-r1、deepseek-v3.2、deepseek-v3
• 多模態模型
  • 映像與視頻理解：qwen3.8-max、qwen3.8-flash、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen3-vl-plus、qwen3-vl-flash、qwen-vl-max、qwen-vl-max-latest、qwen-vl-plus、qwen-vl-plus-latest
  • 文字提取：qwen-vl-ocr
  • 全模態：qwen3.5-omni-plus

• 文本向量模型：text-embedding-v4

重要

• 在Batch 情境下，qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash和qwen3.5-omni-plus單次請求的上下文 Token 數最大支援 256K，qwen3.5-omni-plus不支援語音輸出。
• 部分模型支援思考模式，開啟後會產生思考tokens導致成本增加。
• qwen3.8、qwen3.7、qwen3.6和qwen3.5 系列模型預設開啟思考模式。建議使用混合思考模型時，顯式設定enable_thinking參數（true開啟/false關閉）。
• 在 JSONL 請求體中，enable_thinking 為 body 的頂層參數，須與 model 同級傳入，不能放在 extra_body 中。

使用批量推理

步驟一：準備輸入檔案

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

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

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

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

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

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

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

• 媒體檔案地址：多模態請求的 body 中通過 image_url、video_url 等欄位引用的媒體檔案，必須使用公網可訪問的 URL。不支援本地檔案路徑（如 file:///home/user/test.mp4）和內網地址；使用此類地址建立的任務雖可提交成功，但不會被處理完成，請先將檔案上傳至公網可訪問的儲存再引用其 URL。

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

欄位	類型	是否必填	說明
custom_id	string	是	請求的唯一識別碼
method	string	是	HTTP 方法，僅支援 POST
url	string	是	請求端點。文本產生與多模態模型填寫 /v1/chat/completions，文本向量模型填寫 /v1/embeddings
body	object	是	請求體，格式與所填 url 對應介面（/v1/chat/completions 或 /v1/embeddings）一致

樣本檔案

可下載樣本檔案test_model.jsonl，內容為：

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

Batch 推理 JSONL 檔案產生工具

Batch 推理需要構造 JSONL 檔案，每行為一個獨立請求。以下 Python 指令碼可直接運行產生符合格式的 JSONL 檔案。

使用方式

1. 將以下代碼儲存為 generate_batch_jsonl.py
2. 修改指令碼中 TASKS 列表的請求內容
3. 運行 python generate_batch_jsonl.py
4. 產生的 batch_input.jsonl 檔案可直接用於 Batch 推理任務

文本產生模型 JSONL 產生指令碼

#!/usr/bin/env python3
"""
Batch 推理 JSONL 檔案產生工具

支援的地區：
  - 華北2（北京）：文本產生、多模態、通用文本向量
  - 新加坡：文本產生（qwen-max、qwen-plus、qwen-turbo）

支援的模型：
  文本產生（華北2）：
    qwen3-max, qwen-max, qwen-max-latest,
    qwen3.5-plus*, qwen3.5-flash*, qwen-flash*,
    qwen-plus*, qwen-plus-latest*, qwen-turbo*, qwen-turbo-latest*,
    qwen-long, qwen-long-latest,
    qwq-plus, qwq-32b-preview, deepseek-r1, deepseek-v3
    (* 表示支援思考模式和非思考模式)
  文本產生（新加坡）：qwen-max, qwen-plus, qwen-turbo
  多模態（華北2）：
    qwen3.5-plus*, qwen3.5-flash*, qwen3-vl-plus*, qwen3-vl-flash*,
    qwen-vl-max, qwen-vl-max-latest, qwen-vl-plus, qwen-vl-plus-latest,
    qwen-vl-ocr, qwen-vl-ocr-latest, qwen-omni-turbo
  文本向量（華北2）：text-embedding-v1/v2/v3/v4

檔案大小限制：單行 ≤6MB，總檔案 ≤500MB，建議 ≤10000 行

使用方式：
  1. 修改下方 TASKS 列表
  2. 運行: python generate_batch_jsonl.py
  3. 輸出: batch_input.jsonl
"""
import json

# ═══════════════════════════════════════════════════════
# 配置區：修改以下內容來產生您需要的 JSONL
# ═══════════════════════════════════════════════════════

MODEL = "qwen-max"          # 選擇模型（參見上方支援列表）
ENABLE_THINKING = False     # 是否開啟思考模式（僅部分模型支援）
THINKING_BUDGET = 50        # 思考 token 預算（思考模式下生效）

# 工作清單：每個 dict 代表一條使用者訊息
TASKS = [
    {"role": "user", "content": "你好！請介紹一下自己。"},
    {"role": "user", "content": "What is 2+2?"},
    {"role": "user", "content": "請用Python寫一個快速排序演算法"},
]

# ═══════════════════════════════════════════════════════
# 以下為產生邏輯，一般無需修改
# ═══════════════════════════════════════════════════════

def build_request(custom_id: str, model: str, messages: list,
                  enable_thinking: bool = False, thinking_budget: int = 50) -> dict:
    """構造單條 Batch 請求"""
    body = {"model": model, "messages": messages}
    if enable_thinking:
        body["enable_thinking"] = True
        body["thinking_budget"] = thinking_budget
        body["stream"] = True  # 思考模式需開啟 stream
    return {
        "custom_id": custom_id,
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": body
    }

def main():
    output_file = "batch_input.jsonl"
    with open(output_file, "w", encoding="utf-8") as f:
        for i, task in enumerate(TASKS, 1):
            messages = [
                {"role": "system", "content": "You are a helpful assistant."},
                task
            ]
            req = build_request(
                custom_id=f"request-{i}",
                model=MODEL,
                messages=messages,
                enable_thinking=ENABLE_THINKING,
                thinking_budget=THINKING_BUDGET
            )
            f.write(json.dumps(req, ensure_ascii=False) + "\n")
    print(f"已產生 {output_file}，共 {len(TASKS)} 條請求")

if __name__ == "__main__":
    main()

多模態模型請求格式

多模態模型的 content 欄位為數組格式，包含媒體對象和文本提問。每行請求中的媒體URL需為同一類型（圖片、視頻或音頻）。將上方指令碼中的 TASKS 替換為以下格式即可：

# 多模態模型配置樣本
MODEL = "qwen-vl-max"       # 多模態模型

# 多模態任務：content 為數組格式
TASKS = [
    {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
        {"type": "text", "text": "這些圖描繪了什麼內容？"}
    ]},
]

# qwen-omni-turbo 音頻/視頻格式：
# {"type": "input_audio", "input_audio": {"data": "https://example.com/audio.wav", "format": "wav"}}
# {"type": "video_url", "video_url": "https://example.com/video.mp4"}

# 注意：
# - qwen3-vl-plus 和 qwen3-vl-flash 不使用 system 角色，thinking_budget 設定為 500
# - 其他多模態模型包含 system 角色，thinking_budget 設定為 50
# - 思考模式需額外設定 ENABLE_THINKING = True

文本向量模型請求格式

文本向量模型使用 /v1/embeddings 介面，請求格式不同於文本產生模型。可使用以下獨立指令碼產生：

#!/usr/bin/env python3
"""文本向量模型 Batch JSONL 產生（使用 /v1/embeddings 介面）"""
import json

MODEL = "text-embedding-v3"  # 可選: v1, v2, v3, v4

TEXTS = [
    "衣服的品質杠杠的，很漂亮，不枉我等了這麼久啊，喜歡，以後還來這裡買。",
    "風急天高猿嘯哀",
    "The quick brown fox jumps over the lazy dog",
]

output_file = "batch_embedding.jsonl"
with open(output_file, "w", encoding="utf-8") as f:
    for i, text in enumerate(TEXTS, 1):
        req = {
            "custom_id": f"emb-{i}",
            "method": "POST",
            "url": "/v1/embeddings",
            "body": {"model": MODEL, "input": text, "encoding_format": "float"}
        }
        f.write(json.dumps(req, ensure_ascii=False) + "\n")
print(f"已產生 {output_file}，共 {len(TEXTS)} 條請求")

在批量推理中配置思考模式

部分模型（如 qwen3.7-plus、qwen3.7-max 及 qwen3.6、qwen3.5 系列）預設開啟思考模式，會產生額外的思考 Token。如需在批量推理中配置思考模式，請在 JSONL 檔案每行請求的 body 中設定 enable_thinking 參數，與 model 同級放置。選擇性參數 thinking_budget 用於限制思考 Token 數量上限。

樣本：關閉思考模式

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

樣本：開啟思考模式並限制思考 Token 預算

{"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搜尋，或按業務空間篩選，快速定位目標任務。

• 管理：

  • 取消："執行中"的任務可在操作列取消。
  • 排錯："失敗"的任務可懸停狀態查看錯誤概要，下載錯誤檔案查看詳情。例如，若批次檔案中混用了不同模型，任務將顯示失敗狀態，錯誤資訊樣本：The model 'qwen-turbo' for this request does not match the rest of the batch. Each batch must contain requests for a single model.

步驟四：下載結果

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

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

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

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

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

• 查看資料概覽：选择时间（最長 30 天），將推理类型選為批量推理，可查看：

  • 監控資料：該時間段內所有模型的匯總統計，如總調用次數、總失敗次數等。
  • 模型列表：每個模型的詳細資料，如調用總量、失敗率、平均調用時間長度等。

  如需查看 30 天前的推理資料，前往 賬單 頁面查詢。

• 查看模型詳情：在模型列表中，單擊目標模型操作列的监控，查看调用统计（如調用次數、調用量等）詳情。

使用 metadata 回傳自訂標識

custom_id 最大支援 256 個字元。如需在結果檔案中回傳更長的標識資訊，可使用 metadata 的自訂欄位實現。

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 資訊，包括所有自訂欄位及其完整內容。

API 參考

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

樣本：

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_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)

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，下載結果檔案。

完整的 Batch API介面定義和程式碼範例，請參見OpenAI相容-Batch（檔案輸入）。

任務生命週期

狀態	說明
validating（驗證中）	系統正在校正檔案格式（JSONL 規範）及每行請求的API格式合法性。
in_progress（執行中）	檔案驗證通過，系統已開始逐行處理推理請求。
finalizing（执行中）	所有請求均已處理完畢，結果正在分別寫入結果檔案和錯誤檔案。在控制台工作清單中，此階段與 in_progress 共用执行中狀態標籤，無獨立展示文案。
completed（已完成）	結果檔案和錯誤檔案已寫入完成，可下載。
failed（失敗）	任務在 validating 階段失敗，通常由檔案級錯誤（如 JSONL 格式錯誤、檔案過大）導致。此狀態下不會執行任何推理請求，也不會產生結果檔案。
expired（已終止）	任務已耗用時間超過建立時設定的最長等待時間，被系統終止。建立新任務時，建議設定更長的等待時間。
cancelled（已終止）	使用者取消任務，未開始處理的請求將被終止。

計費說明

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

• 計費範圍：
  • 僅對任務中成功執行的請求計費。
  • 檔案解析失敗、任務執行失敗、或行級錯誤請求均不產生費用。
  • 對於被取消的任務，在取消前已成功完成的請求仍正常計費。

常見問題

1. 使用批量推理需要額外購買或開通嗎？

   不需要。開通阿里雲百鍊服務後即可使用，費用按後付費模式從賬戶餘額中扣除。

2. 任務提交後為什麼立即失敗（狀態變為 failed）？

   這通常是檔案級錯誤導致的，任務並未執行任何推理請求。按以下順序排查：

   • 檔案格式：是否為嚴格的 JSONL 格式，每行一個完整的JSON對象。
   • 檔案規模：檔案大小、行數等是否超出限制。詳情請參見準備輸入檔案。
   • 模型一致性：檢查檔案中所有請求的 body.model 欄位是否完全一致，且使用的是當前地區支援的模型。
3. 任務處理需要多長時間？

   處理時間長度主要取決於系統當時的負載。系統繁忙時任務可能需要排隊，成功或失敗都會在設定的最長等待時間內返回結果。

錯誤碼

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