Skip to main content

批量推理

阿里雲百煉 CLI 建立、追蹤和下載非同步批量推理任務的命令速查。

bl batch 把 CSV 轉換為 Batch JSONL,建立 Chat 或 Embedding 非同步批量任務,追蹤進度,取消任務,並下載結果與錯誤檔案。非同步檔案批量任務與同步單請求 bl text chat --batch 分開使用。
batch convert 在本機轉換,無需鑑權。建立、查詢、取消和下載任務需要模型 API Key。Batch 的可用範圍和限額取決於模型與服務。
任意命令追加 --help 可查看完整參數說明,例如 bl batch create --help。本文命令明細以 bl 2.8.0 為基準核實。

快速開始

bl batch convert --file input.csv --model qwen-plus --output-file input.jsonl
bl batch create --file input.jsonl
bl batch get --batch-id <batch-id> --follow
bl batch download --batch-id <batch-id> --csv

任務管理

bl batch convert

在本機把 UTF-8 CSV 轉換為 Batch JSONL。無需鑑權。 語法
bl batch convert --file <csv> --model <model> --output-file <jsonl> [flags]
參數類型必填說明
--file <csv>string是帶表頭的 UTF-8 CSV 檔案
--output-file <jsonl>string是本機 JSONL 輸出路徑
--model <model>string是為每筆記錄指定的模型
--id-column <name>string否ID 欄名(預設:custom_id)
--input-column <name>string否輸入欄名(預設:content)
--system <text>string否共用的系統提示詞(僅 Chat)
--body-file <json>string否共用的請求體參數,不包含 model、messages 或 input
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test>string否Batch Endpoint,可從本機 JSONL 推斷
--forceswitch否覆蓋已存在的輸出檔案(按檔案原子替換)
範例:把 CSV 轉換為 Chat JSONL
bl batch convert --file input.csv --model qwen-plus --output-file input.jsonl
範例:把 CSV 轉換為 Embedding JSONL
bl batch convert --file input.csv --model text-embedding-v4 --endpoint /v1/embeddings --output-file vectors.jsonl
  • 僅支援文字與 Embedding 的欄位映射。多模態或多輪輸入請直接撰寫 JSONL。
  • ID 始終按字串處理。用試算表軟體匯入 CSV 時,把 ID 欄設為文字,避免遺失前導零。
  • dry-run 不呼叫業務 API,也不寫入業務檔案。

bl batch create

上傳或引用輸入檔案,建立非同步 Batch 任務。需要 API Key 鑑權。 語法
bl batch create (--file <jsonl> | --input-file-id <source> --endpoint <path>) [flags]
參數類型必填說明
--file <jsonl>string否本機 Batch JSONL,與 --input-file-id 互斥
--input-file-id <source>string否檔案 ID、OSS HTTPS URL 或 oss:region:bucket/path
--completion-window <24h|7d>string否完成視窗,24–336 小時(預設:24h)
--name <text>string否任務名稱,最長 100 個字元
--description <text>string否任務描述,最長 200 個字元
--callback-url <url>string否完成回呼,目前僅中國(北京)地域有說明
--metadata <KEY=VALUE>array否自訂任務中繼資料(可重複)
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test>string否Batch Endpoint,可從本機 JSONL 推斷
範例:預覽建立任務
bl batch create --file input.jsonl --name eval-1 --dry-run
範例:引用檔案 ID 建立任務
bl batch create --input-file-id file-batch-xxx --endpoint /v1/chat/completions
範例:引用 OSS 路徑並設定 7 天完成視窗
bl batch create --input-file-id oss:ap-southeast-1:my-bucket/input.jsonl --endpoint /v1/chat/completions --completion-window 7d
Chat JSONL 範例:
{"custom_id":"req-001","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"user","content":"Introduce yourself"}]}}
Embedding JSONL 範例:
{"custom_id":"req-001","method":"POST","url":"/v1/embeddings","body":{"model":"text-embedding-v4","input":"Introduce yourself","encoding_format":"float"}}
  • 本機輸入上限:50,000 筆請求、500 MiB、單行 6 MiB。單行超過 1 MiB 時給出警告。
  • batch-test-model 限制為 100 筆請求、1 MiB。
  • 遠端引用需要授權且 URL 在有效期內,CLI 不會下載檔案做校驗。
  • 建立成功後傳回任務 ID,不等待任務完成。失敗時不會自動重放 POST,也不會清理已上傳檔案。

bl batch get

查詢 Batch 任務詳情,可追蹤進度。需要 API Key 鑑權。 語法
bl batch get --batch-id <id> [--follow] [--interval <seconds>] [--poll-timeout <seconds>]
參數類型必填說明
--batch-id <id>string是Batch 任務 ID
--followswitch否輪詢直到終態(Ctrl-C 只停止本機輪詢)
--interval <seconds>number否查詢間隔,最小 60 秒(預設:65 秒;僅 --follow)
--poll-timeout <seconds>number否總輪詢時間預算(預設:不限;僅 --follow)
範例:追蹤任務直到結束
bl batch get --batch-id batch_xxx --follow
  • 單次查詢成功後退出碼為 0,與任務狀態無關。
  • --follow 的退出碼:completed 為 0(可能包含失敗列),failed、expired 或 cancelled 為 1,用戶端逾時為 5,Ctrl-C 為 130。
  • finalizing 和 cancelling 都不是終態。
  • 進度寫入 stderr,最終結果寫入 stdout。
  • 只有傳輸錯誤、逾時或 HTTP 429/5xx 會重試,最多 3 次。
  • 伺服器保留結果的時間有限,任務完成後盡快下載。

bl batch list

分頁列出 Batch 任務。需要 API Key 鑑權。 語法
bl batch list [filters] [--after <id>] [--limit <n>]
參數類型必填說明
--limit <n>number否每頁筆數:1–100(預設:20)
--after <id>string否上一頁傳回的 last_id
--name <text>string否按任務名稱篩選
--input-file-id <id>array否按輸入檔案篩選(可重複,最多 20 個)
--status <status>array否按任務狀態篩選(可重複):validating、in_progress、finalizing、completed、failed、expired、cancelling、cancelled
--created-after <yyyyMMddHHmmss>string否建立時間晚於此 API 時間戳
--created-before <yyyyMMddHHmmss>string否建立時間早於此 API 時間戳
範例:查看已完成和失敗的任務
bl batch list --status completed --status failed --limit 20
  • 傳回 data、last_id 和 has_more。下一頁把 last_id 傳給 --after。
  • API 時間戳不做時區轉換。

bl batch cancel

請求取消 Batch 任務。需要 API Key 鑑權。 語法
bl batch cancel --batch-id <id>
參數類型必填說明
--batch-id <id>string是Batch 任務 ID
範例:請求取消任務
bl batch cancel --batch-id batch_xxx
  • 取消請求被接受後可能傳回 cancelling,不代表已經取消。用 batch get --follow 確認。
  • 已執行的請求仍會計費,檔案不會刪除。

bl batch download

下載原始結果或錯誤檔案,可選匯出 CSV。需要 API Key 鑑權。 語法
bl batch download --batch-id <id> [--out-dir <path>] [--csv] [--force]
參數類型必填說明
--batch-id <id>string是Batch 任務 ID
--out-dir <path>string否輸出目錄(預設:./batch-results/<batch-id>/)
--csvswitch否同時產生 result.csv(有損展示投影)
--forceswitch否覆蓋已存在的輸出檔案(按檔案原子替換)
範例:下載結果並匯出 CSV
bl batch download --batch-id batch_xxx --out-dir ./out --csv
  • JSONL 是保真結果。CSV 只讀取 choices[0].message.content、Embedding 資料、response.request_id、status_code、用量及 error.code、error.message。
  • CSV 不包含工具呼叫和額外候選結果,並把類似公式的文字按文字處理。匯入 ID 時選擇文字類型以保留前導零。
  • 不保證保持原始輸入順序。
  • 按檔案原子發布,不按目錄原子發布。CSV 產生失敗時保留已下載的 JSONL;用 --force 重跑恢復。

相關命令

同步單請求使用 bl text chat --batch,不建立非同步任務。見文字對話與全模態。