リアルタイムの応答を必要としない推論シナリオでは、バッチ推論を使用すると、大量のデータリクエストをリアルタイム推論の 50% のコストで非同期に処理できます。OpenAI 互換 API を提供しており、モデル評価やデータアノテーションなどのバッチジョブに最適です。
仕組み
- タスクの送信:複数のリクエストを含む JSONL ファイルをアップロードして、バッチ推論タスクを作成します。
- 非同期処理:システムはバックグラウンドキューでタスクを処理します。コンソールまたは API からタスクの進捗とステータスを照会できます。
- 結果のダウンロード:タスクが完了すると、システムは結果ファイル(成功した応答を記録)とエラーファイル(失敗の詳細があれば記録)を生成します。
適用範囲
シンガポール
サポート対象モデル:
-
テキスト生成モデル
- Qwen Max: qwen3.8-max, qwen-max
- Qwen Plus: qwen3.7-plus, qwen-plus
- Qwen Flash: qwen-flash
-
マルチモーダルモデル
- 画像・動画理解: qwen3.8-max, qwen3.7-plus
中国 (北京)
サポート対象モデル:
-
テキスト生成モデル
- Qwen Max: qwen4-max, qwen3.8-max, qwen3.7-max, qwen-max, qwen-max-latest
- Qwen Plus: qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen-plus, qwen-plus-latest
- Qwen Flash: qwen3.8-flash, qwen3.7-flash, qwen3.6-flash, qwen3.5-flash, qwen-flash
- マルチモーダルモデル
-
テキスト埋め込みモデル: text-embedding-v4
重要
- バッチシナリオでは、
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-flash、およびqwen3.5-omni-plusは、リクエストあたり最大 256K のコンテキストトークンをサポートします。qwen3.5-omni-plusとqwen3.5-omni-flashは音声出力をサポートしていません。 - 一部のモデルは思考モードをサポートしています。有効にすると思考
tokensが生成され、コストが増加します。 qwen3.8、qwen3.7、qwen3.6、およびqwen3.5シリーズのモデルは、デフォルトで思考モードが有効になっています。ハイブリッド思考モデルを使用する場合は、enable_thinkingパラメーターを明示的に設定することをお勧めします(trueで有効 /falseで無効)。- JSONL リクエストボディでは、
enable_thinkingはbodyのトップレベルパラメーターであり、modelと同じレベルで渡す必要があります。extra_bodyの内部に配置することはできません。 - バッチ推論の結果ファイルには
reasoning_contentフィールドは含まれません。enable_thinking=trueを設定しても、結果ファイルのchoices[0].messageにはcontentとroleフィールドのみが含まれます。思考プロセスの内容を取得するには、リアルタイム API 呼び出しを使用してください(ストリーミング・非ストリーミングどちらでも対応しており、enable_thinking=trueを設定するだけです)。詳細については、ディープシンキングをご参照ください。
バッチ推論の使用
ステップ 1:入力ファイルの準備
タスクを作成する前に、以下の仕様に準拠した JSONL ファイルを準備してください:
-
形式:UTF-8 でエンコードされた JSONL(1 行に 1 つの独立した JSON オブジェクト)。
-
サイズ制限:ファイルあたり最大 50,000 リクエスト、最大 500 MB。
データ量がこれらの制限を超える場合は、複数のタスクに分割して個別に送信してください。
-
1 行あたりの制限:各 JSON オブジェクトは 1 MB 以下で、モデルのコンテキスト長を超えてはなりません。
-
一貫性要件:同じファイル内のすべてのリクエストは、同じモデルを使用する必要があります。
-
一意の識別子:各リクエストには、結果の照合に使用する、ファイル内で一意の custom_id フィールドを含める必要があります。
custom_idは最大 256 文字をサポートします。この制限を超えると、タスクの検証に失敗します。より長い識別子情報を渡すには、タスク作成時にmetadataのカスタムフィールドを使用してください。詳細については、メタデータを使用したカスタム識別子の返却をご参照ください。 -
メディアファイルのアドレス:マルチモーダルリクエストの
body内のimage_urlやvideo_urlなどのフィールドで参照されるメディアファイルは、パブリックにアクセス可能な URL を使用する必要があります。ローカルファイルパス(file:///home/user/test.mp4など)やイントラネットアドレスはサポートされていません。このようなアドレスで作成されたタスクは送信には成功しますが、完了まで処理されることはありません。先にファイルをパブリックにアクセス可能なストレージにアップロードし、その URL を参照してください。
各 JSON オブジェクトは、以下のフィールド仕様に従う必要があります:
フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
| string | はい | リクエストの一意の識別子 |
| string | はい | HTTP メソッド。 |
| string | はい | リクエストのエンドポイント。テキスト生成モデルとマルチモーダルモデルの場合は |
| object | はい | リクエストボディ。形式は指定した |
サンプルファイル
サンプルファイル 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?"}]}}
バッチ推論 JSONL ファイル生成ツール
バッチ推論では、1 行が 1 つの独立したリクエストである JSONL ファイルを構築する必要があります。以下の Python スクリプトは、そのまま実行して形式に準拠した JSONL ファイルを生成できます。
使用方法
- 以下のコードを
generate_batch_jsonl.pyとして保存します - スクリプト内の
TASKSリストのリクエスト内容を変更します python generate_batch_jsonl.pyを実行します- 生成された
batch_input.jsonlファイルは、そのままバッチ推論タスクに使用できます
テキスト生成モデル用 JSONL 生成スクリプト
#!/usr/bin/env python3
"""
Batch 推理 JSONL 文件生成工具
支持的地域与模型请参见上方“适用范围”。
文件大小限制:单行 ≤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 を以下の形式に置き換えてください:
# 多模态模型配置示例
# 多模态任务: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": "这些图描绘了什么内容?"}
]},
]
# {"type": "input_audio", "input_audio": {"data": "https://example.com/audio.wav", "format": "wav"}}
# {"type": "video_url", "video_url": "https://example.com/video.mp4"}
# 注意:
# - 其他多模态模型包含 system 角色,thinking_budget 设置为 50
# - 思考模式需额外设置 ENABLE_THINKING = True
テキスト埋め込みモデルのリクエスト形式
テキスト埋め込みモデルは /v1/embeddings API を使用し、リクエスト形式はテキスト生成モデルとは異なります。以下のスタンドアロンスクリプトで生成できます:
#!/usr/bin/env python3
"""文本向量模型 Batch JSONL 生成(使用 /v1/embeddings 接口)"""
import json
MODEL = "text-embedding-v3" # 向量模型,可选型号参见上方“适用范围”
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 シリーズなど)はデフォルトで思考モードが有効になっており、追加の思考トークンが生成されます。バッチ推論で思考モードを設定するには、JSONL ファイル内の各リクエスト行の body に enable_thinking パラメーターを設定し、model と同じレベルに配置します。オプションの thinking_budget パラメーターは、思考トークンの最大数を制限するために使用します。
重要enable_thinking と thinking_budget は、body のトップレベル(model と同じレベル)に直接配置する必要があります。extra_body には入れないでください。extra_body は OpenAI Python SDK が非標準パラメーターを渡すためのメカニズムであり、リアルタイム推論の SDK 呼び出しでのみ機能し、バッチ推論の JSONL ファイルには適用されません。
例:思考モードを無効にする
{"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":"请分析以下问题"}]}}
ステップ 2:バッチ推論タスクの作成
-
**バッチ推論** ページで、バッチの作成 をクリックします。
-
表示されたダイアログボックスで:タスク名 と タスク説明 を入力し、最大待機時間(1〜14 日)を設定して、JSONL ファイルをアップロードします。
サンプルファイルのダウンロード をクリックするとテンプレートを取得できます。
-
フォームへの入力が完了したら、確認 をクリックします。
ステップ 3:タスクの監視と管理
-
表示:
- タスクページで、タスクの 進捗(処理済みリクエスト数/総リクエスト数)と ステータス を表示できます。
- タスク名または ID で検索するか、ワークスペースでフィルタリングして、対象のタスクをすばやく見つけられます。
-
管理:
- キャンセル:「実行中」状態のタスクは、操作 列からキャンセルできます。
ステップ 4:結果のダウンロード
重要タスクは完了後 30 日で自動的に削除されます。結果は速やかにダウンロードしてください。
タスクが完了したら、結果の表示 をクリックして出力ファイルをダウンロードします:
- 結果ファイル:成功したすべてのリクエストとその
response結果を記録します。 - エラーファイル (存在する場合):失敗したすべてのリクエストとその
errorの詳細を記録します。
両方のファイルには custom_id フィールドが含まれており、元の入力データとの照合、結果の関連付け、またはエラーの特定に使用されます。
ステップ 5:使用統計の表示 (任意)
モニタリング ページで、バッチ推論の使用統計をフィルターして表示できます。
-
データ概要の表示:時間を選択(最大 30 日)し、推論タイプ を バッチ推論 に設定すると、以下を表示できます:
- モニタリングデータ:期間内の全モデルのサマリー統計(総呼び出し回数や総失敗数など)。
- モデル:各モデルの詳細データ(総呼び出し回数、失敗率、平均呼び出し時間など)。
30 日以上前の推論データを表示するには、請求 ページに移動してください。
-
モデル詳細の表示:モデル リストで、対象モデルの 操作 列にある モニタリング をクリックすると、呼び出し統計 の詳細(呼び出し回数や呼び出し量など)を表示できます。

重要
- バッチ推論の呼び出しデータは、タスク終了時刻に基づいてカウントされます。実行中のタスクについては、タスクが完了するまで呼び出し情報を照会できません。
- モニタリングデータには 1〜2 時間の遅延があります。
メタデータを使用したカスタム識別子の返却
custom_id は最大 256 文字をサポートします。結果ファイルでより長い識別子情報を返すには、metadata のカスタムフィールドを使用できます。
metadata フィールド
metadata はバッチタスク作成時のオプションパラメーターで、以下のフィールドをサポートします:
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)
タスクの作成後、タスク詳細照会 API(GET /v1/batches/{batch_id})を呼び出すと、すべてのカスタムフィールドとその完全な内容を含む完全な metadata 情報を取得できます。
API リファレンス
本番環境では、OpenAI 互換 API を使用してバッチタスクの作成と管理を自動化します。コアワークフローは次のとおりです:
重要バッチ推論は OpenAI 互換形式の API 呼び出しのみをサポートします。OpenAI Python SDK を使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に設定してください。DashScope Python SDK(dashscope パッケージ)はバッチ推論インターフェイスを提供しないため、dashscope.BatchInference、dashscope.Batches などのメソッドでバッチ推論タスクを送信することはできません。
例:
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",
)
-
POST /v1/filesを呼び出してファイルをアップロードし、返されたファイル ID を記録します。 -
タスクの作成 ファイル ID を渡して
POST /v1/batchesを呼び出してタスクを作成し、返されたbatch_idを記録します。 -
ステータスのポーリング
batch_idを使用してGET /v1/batches/{batch_id}をポーリングします。statusがcompletedに変わったら、output_file_idを記録してポーリングを停止します。 -
結果のダウンロード
output_file_idを使用してGET /v1/files/{output_file_id}/contentを呼び出し、結果ファイルをダウンロードします。
完全なバッチ API の定義とコード例については、OpenAI 互換バッチ (ファイル入力) をご参照ください。
タスクのライフサイクル
ステータス | 説明 |
|---|---|
validating (検証中) | システムがファイル形式(JSONL 仕様)と各リクエスト行の API 形式の有効性を検証しています。 |
in_progress (実行中) | ファイルは検証を通過し、システムが推論リクエストの処理を 1 行ずつ開始しました。 |
finalizing (実行中) | すべてのリクエストが処理され、結果が結果ファイルとエラーファイルにそれぞれ書き込まれています。コンソールのタスクリストでは、この段階は in_progress と同じ 実行中 ステータスラベルで表示され、個別の表示テキストはありません。 |
completed (完了) | 結果ファイルとエラーファイルが書き込まれ、ダウンロードできる状態です。 |
failed | タスクは validating 段階で失敗しました。通常、ファイルレベルのエラー(JSONL 形式の無効やファイルサイズ超過など)が原因です。この状態では、推論リクエストは実行されず、結果ファイルも生成されません。 |
expired | タスクの実行時間が作成時に設定された最大待機時間を超えたため、システムによって終了されました。新しいタスクを作成する際は、より長い待機時間を設定することをお勧めします。 |
cancelled | ユーザーがタスクをキャンセルすると、処理が開始されていないリクエストは終了されます。 |
課金詳細
-
課金単価:成功したすべてのリクエストについて、入力トークンと出力トークンの単価は、対応するモデルのリアルタイム推論価格の 50% です。詳細については、モデルをご参照ください。
-
課金範囲:
- タスク内で正常に実行されたリクエストのみが課金対象です。
- ファイルの解析失敗、タスク実行の失敗、行レベルの誤ったリクエストは課金されません。
- キャンセルされたタスクの場合、キャンセル前に正常に完了したリクエストは通常どおり課金されます。
注記
- バッチ推論は独立した課金項目です。AI ユニバーサル削減プランをサポートしますが、前払い (削減プラン) や 新規ユーザー無料クォータ などの割引、および コンテキストキャッシュ などの機能はサポートしません。
- 一部のモデル(qwen3.7-plus、qwen3.7-max、および qwen3.6 と qwen3.5 シリーズなど)はデフォルトで思考モードが有効になっており、追加の思考トークンが出力トークンの価格で課金されるため、コストが増加します。タスクの複雑さに応じて enable_thinking パラメーターを設定し、コストを管理することをお勧めします。詳細については、ディープシンキングをご参照ください。
よくある質問
-
バッチ推論を使用するために、追加の購入や有効化は必要ですか?
いいえ。Alibaba Cloud Model Studio を有効化すれば利用でき、料金は従量課金でアカウント残高から差し引かれます。
-
タスクが送信直後に失敗するのはなぜですか(ステータスが failed に変わる)?
これは通常、ファイルレベルのエラーが原因であり、タスクは推論リクエストを 1 つも実行していません。以下の順序でトラブルシューティングしてください:
- ファイル形式:厳密な JSONL 形式で、1 行に 1 つの完全な JSON オブジェクトが含まれていますか?
- ファイルサイズ:ファイルサイズや行数などが制限を超えていませんか?詳細については、入力ファイルの準備をご参照ください。
- モデルの一貫性:ファイル内のすべてのリクエストの
body.modelフィールドが完全に同一であること、および使用しているモデルが現在のリージョンでサポートされていることを確認してください。
-
タスクの処理にはどのくらい時間がかかりますか?
処理時間は、主に送信時のシステム負荷によって異なります。システムが混雑しているときはタスクがキューで待機する場合がありますが、成功か失敗かに関わらず、設定された最大待機時間内に結果が返されます。
エラーコード
呼び出しが失敗してエラーメッセージが返された場合は、エラーコードをご参照ください。