Alibaba Cloud Model Studio:バッチ推論

リアルタイムの応答を必要としない推論シナリオ向けに、バッチ推論は大量のデータリクエストを非同期で処理します。コストはリアルタイム推論の 50% です。OpenAI 互換の API は、モデル評価やデータラベリングなどのバッチジョブに最適です。

仕組み

1. タスクの送信：複数のリクエストを含む JSONL ファイルをアップロードして、バッチ推論タスクを作成します。
2. 非同期処理：システムはバックグラウンドのキューでタスクを処理します。コンソールまたは API を使用して、タスクの進捗とステータスを監視できます。
3. 結果のダウンロード：タスクが完了すると、システムは成功した応答の結果ファイルと、失敗の詳細を記録したエラーファイルを生成します。

適用範囲

シンガポール

サポート対象モデル：qwen-max、qwen-plus、qwen-flash、qwen-turbo。

中国 (北京)

サポート対象モデル：

• テキスト生成モデル
  • Qwen-Max：qwen3.8-max、qwen3.7-max、qwen3-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
  • 推奨モデル：qwen-long-latest
  • 推奨モデル：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、qwen3.5-omni-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 のリクエストあたりの最大コンテキストトークンは 256 K です。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 の内部には配置しないでください。

バッチ推論の使用

ステップ 1：入力ファイルの準備

タスクを作成する前に、次の要件を満たす JSONL ファイルを準備します：

• フォーマット：UTF-8 でエンコードされた JSONL (1行に1つの JSON オブジェクト)。

• 規模の制限：ファイルあたり最大 50,000 リクエスト、最大ファイルサイズ 500 MB。

  データセットがこれらの制限を超える場合は、複数のファイルに分割し、別々のタスクとして送信してください。

• 1行あたりの制限：各 JSON オブジェクトは最大 1 MB で、モデルのコンテキストウィンドウを超えてはなりません。

• 一貫性：同じファイル内のすべてのリクエストは、同じモデル を使用する必要があります。

• 一意の識別子：各リクエストには、結果を照合するためにファイル内で一意の custom_id フィールドを含める必要があります。custom_id は最大 256 文字をサポートします。この制限を超えると、タスクの検証は失敗します。より長い識別子を返すには、タスク作成時に metadata パラメーターでカスタムフィールドを使用します。詳細については、「メタデータを使用したカスタム識別子の返却」をご参照ください。

• メディアファイルの URL：マルチモーダルリクエストの 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 リクエストエンドポイントのみがサポートされています。
body	object	はい	リクエストボディは /v1/chat/completions API と同じフォーマットです。

サンプルファイル

サンプルファイル 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 バッチ生成ツール

このツールを使用して、JSONL ファイルを迅速に生成します。

バッチ推論での思考モードの設定

qwen3.7-plus、qwen3.7-max、および qwen3.6、qwen3.5 シリーズなどの一部のモデルでは、思考モードがデフォルトで有効になっており、追加の思考トークンが生成されます。バッチ推論で思考モードを設定するには、各リクエストの body 内で model パラメーターと同じレベルに enable_thinking パラメーターを設定します。オプションの thinking_budget パラメーターを使用して、思考トークンの数の上限を設定できます。

例：思考モードを無効にする

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

例：思考モードを有効にし、思考トークンのバジェットを制限する

{"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":"Please analyze the following question"}]}}

ステップ 2：バッチ推論タスクの作成

1. バッチ ページで、Create Batchをクリックします。

2. 表示されるダイアログボックスで、タスク名 と Task Description を入力し、Maximum Waiting Time (1〜14日) を設定して、JSONL ファイルをアップロードします。

   Download Sample File をクリックしてテンプレートを取得できます。

3. 完了したら、OK をクリックします。

ステップ 3：タスクの監視と管理

• 表示：

  • タスクリストページで、タスクの 進捗 (処理済みリクエスト/合計リクエスト) と 状態 を表示します。
  • タスク名または ID で検索するか、ワークスペースでフィルターをかけて特定のタスクをすばやく見つけます。

• 管理：

  • キャンセル：Actions 列で、実行中のタスクをキャンセルできます。

  • トラブルシューティング：失敗したタスクについては、ステータスにカーソルを合わせるとエラーの概要が表示され、エラーファイルをダウンロードして詳細を確認できます。

    例えば、バッチファイルに異なるモデルが混在している場合、タスクは 失敗 ステータスを表示し、次のようなエラーメッセージが表示されます：The model 'qwen-turbo' for this request does not match the rest of the batch. Each batch must contain requests for a single model.

ステップ 4：結果のダウンロード

タスクが完了したら、View Results をクリックして出力ファイルをダウンロードします：

• 結果ファイル：すべての成功したリクエストとその response 結果を記録します。
• エラーファイル (存在する場合)：すべての失敗したリクエストとその error の詳細を記録します。

両方のファイルには custom_id フィールドが含まれており、元の入力データとの照合、結果の関連付け、またはエラーの特定に使用されます。

ステップ 5：使用状況の統計表示 (任意)

モデルモニタリング ページで、バッチ推論の使用状況の統計をフィルターして表示できます。

• データ概要の表示：選択時間 (最大 30 日) し、推論タイプ を Batches に設定すると、以下を表示できます：

  • モニタリングデータ：選択した期間における全モデルの概要統計 (総呼び出し回数や失敗回数など)。
  • モデルリスト：各モデルの詳細データ (総呼び出し回数、失敗率、平均呼び出し時間など)。

  30 日以上前の推論データを表示するには、 [請求書] ページに移動します。

• モデル詳細の表示：Models で、対象モデルの Actions 列にある 監視 をクリックして、Call Statistics (呼び出し回数や呼び出し量など) を表示します。

メタデータを使用したカスタム識別子の返却

custom_id は最大 256 文字をサポートします。結果ファイルでより長い識別子を返す必要がある場合は、metadata のカスタムフィールドを使用できます。

メタデータフィールド

metadata は、バッチタスクを作成するためのオプションのパラメーターです。次のフィールドをサポートしています：

• ds_name：タスクの名前。この名前は、コンソールの タスク名 列に表示されます。
• ds_description：タスクの説明。この説明は、コンソールの Task 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": "A description for my batch inference task",
        "my_custom_field": "The value of this field can exceed 256 characters and is used to pass back longer identifier information..."
    }
)
print(batch)

タスクが正常に作成された後、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 などのメソッドを介してバッチ推論タスクを送信することはできません。

例：

from openai import OpenAI

client = OpenAI(
    api_key="your-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 を呼び出します。

完全なバッチ API の定義とコード例については、「OpenAI 互換 - バッチ (ファイル入力)」をご参照ください。

タスクのライフサイクル

ステータス	説明
validating	システムがファイル形式 (JSONL 仕様) と各リクエストの API 形式を検証しています。
in_progress	システムがファイルの検証を終え、推論リクエストの処理を開始しました。
finalizing	すべてのリクエストが処理され、システムが出力ファイルに結果を書き込んでいます。コンソールでは、この段階は in_progress と同じ Executing ステータスラベルで表示されます。
completed	結果ファイルとエラーファイルが生成され、ダウンロード可能です。
failed	タスクは validating 段階で失敗しました。通常、JSONL 形式の誤りやファイルサイズ超過などのファイルレベルのエラーが原因です。この状態では、推論リクエストは実行されず、結果ファイルも生成されません。
expired	タスクのランタイムが作成時に設定された最大待機時間を超えたため、システムによって終了されました。新しいタスクを作成する際は、より長い待機時間を設定することを検討してください。
cancelled	タスクはユーザーによってキャンセルされました。未処理のリクエストはすべて終了します。コンソールでは、このステータスは Stopped と表示されます。

課金

• 料金：すべての成功したリクエストに対して、入力トークンと出力トークンの両方が、対応するモデルのリアルタイム推論価格の 50% で課金されます。詳細については、「モデルと料金」をご参照ください。

• 課金範囲：
  • タスク内で正常に実行されたリクエストに対してのみ課金されます。
  • ファイルの解析失敗、タスク実行の失敗、または行レベルのリクエストエラーでは課金されません。
  • キャンセルされたタスクの場合、キャンセル前に正常に完了したリクエストは通常どおり課金されます。

よくある質問

1. バッチ推論を使用するために、追加で何かを購入したり有効にしたりする必要はありますか？

   いいえ。この機能は Model Studio を有効化すると利用可能になります。料金は従量課金制で発生し、アカウントの残高から差し引かれます。

2. タスクが送信直後に失敗したのはなぜですか (ステータスがfailedに変わった)？

   これは通常、ファイルレベルのエラーを示しており、推論リクエストは実行されていません。次の順序で確認してください：

   • ファイル形式：ファイルが厳密な JSONL 形式を使用しており、1行に1つの完全な JSON オブジェクトが含まれていることを確認します。
   • ファイル規模：ファイルサイズと行数が制限を超えていないことを確認します。詳細については、「ステップ 1：入力ファイルの準備」をご参照ください。
   • モデルの一貫性：ファイル内のすべてのリクエストで body.model フィールドが同一であること、および使用されているモデルが現在のリージョンでサポートされていることを確認します。
3. タスクの処理にはどのくらい時間がかかりますか？

   処理時間は、タスクが送信されたときのシステム負荷によって異なります。繁忙期にはタスクがキューに入れられることがあります。ただし、指定された最大待機時間内に必ず結果 (成功または失敗) が返されます。

エラーコード

呼び出しが失敗し、エラーメッセージが返された場合は、「エラーコード」をご参照ください。