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 推斷 |
--force | switch | 否 | 覆蓋已存在的輸出檔案(按檔案原子替換) |
範例:把 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 |
--follow | switch | 否 | 輪詢直到終態(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>/) |
--csv | switch | 否 | 同時產生 result.csv(有損展示投影) |
--force | switch | 否 | 覆蓋已存在的輸出檔案(按檔案原子替換) |
範例:下載結果並匯出 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,不建立非同步任務。見文字對話與全模態。