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 エンドポイント。ローカル JSONL から推測 |
--force | switch | いいえ | 既存の出力ファイルを置き換える（ファイル単位でアトミック） |
bl batch convert --file input.csv --model qwen-plus --output-file input.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 エンドポイント。ローカル JSONL から推測 |
bl batch create --file input.jsonl --name eval-1 --dry-run
bl batch create --input-file-id file-batch-xxx --endpoint /v1/chat/completions
bl batch create --input-file-id oss:ap-southeast-1:my-bucket/input.jsonl --endpoint /v1/chat/completions --completion-window 7d
{"custom_id":"req-001","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"user","content":"Introduce yourself"}]}}
{"custom_id":"req-001","method":"POST","url":"/v1/embeddings","body":{"model":"text-embedding-v4","input":"Introduce yourself","encoding_format":"float"}}
- ローカル入力の上限：50,000 リクエスト、500 MiB、1 行あたり 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
- 単一の get は、タスクの状態に関係なく、照会に成功すると終了コード 0 で終了します。
--follow では、終了コード 0 は完了（失敗行を含む場合あり）、1 は失敗、期限切れ、またはキャンセル、5 はクライアントタイムアウト、130 は Ctrl-C を意味します。finalizing と cancelling は終了状態ではありません。- 進捗は stderr に、最終結果は stdout に出力されます。
- 再試行されるのは転送エラー、タイムアウト、HTTP 429/5xx のみで、最大 3 回です。
- サーバーの保持期間は限られているため、結果は速やかにダウンロードしてください。
bl batch list
Batch タスクを 1 ページずつ一覧表示します。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 | いいえ | 既存の出力ファイルを置き換える（ファイル単位でアトミック） |
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 を使用します。非同期タスクは作成されません。テキストチャットとオムニを参照してください。 
