Alibaba Cloud Model Studio は、OpenAI 互換のバッチファイル API を提供します。ファイルを通じてリクエストを一括で送信すると、システムが非同期で処理し、すべてのリクエストが完了するか、最大待機時間に達した時点で結果を返します。コストはリアルタイム呼び出しのわずか 50% です。データ分析、モデル評価など、レイテンシーが重要でない大規模ワークロードに最適です。
コンソールを使用するには、「コンソールガイド」をご参照ください。
ワークフロー
前提条件
バッチファイル API は、OpenAI SDK (Python、Node.js) または HTTP API を介して呼び出すことができます。
-
API キーの取得:Model Studio の API キーを取得し、環境変数として設定します
-
SDK のインストール (任意):使用する場合は、OpenAI SDK をインストールします。
-
サービスエンドポイント
-
中国 (北京):
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 -
シンガポール:
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
-
Model Studio は、中国 (北京) およびシンガポールリージョン向けにワークスペース固有のドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します:
-
中国 (北京):
https://dashscope.aliyuncs.comからhttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ -
シンガポール:
https://dashscope-intl.aliyuncs.comからhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ
{WorkspaceId} は、Model Studio コンソールの [ワークスペース詳細] ページで確認できるワークスペース ID です。既存のドメインも引き続き完全に機能します。
範囲
シンガポール
サポート対象モデル:qwen-max、qwen-plus、qwen-flash、qwen-turbo。
中国 (北京)
サポート対象モデル:
-
テキスト生成モデル:Qwen-Max、Plus、Flash、Long の安定版および一部の
latestバージョン。QwQ シリーズ (qwq-plus) および一部のサードパーティモデル (deepseek-r1、deepseek-v3.2、deepseek-v3) もサポートされています。 -
マルチモーダルモデル:Qwen-VL-Max、Plus、Flash の安定版および一部の
latestバージョン。Qwen-OCR モデルもサポートされています。 -
テキスト埋め込みモデル:text-embedding-v4 モデル。
-
バッチ処理シナリオでは、
qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.5-plus、qwen3.5-flashのリクエストあたりの最大コンテキストトークンは 256 K です。 -
一部のモデルは思考モードをサポートしています。このモードを有効にすると、思考
トークンが生成され、コストが増加します。 -
qwen3.7、qwen3.6、qwen3.5シリーズのモデルでは、思考モードがデフォルトで有効になっています。ハイブリッド思考モデルを使用する場合は、enable_thinkingパラメーターを明示的に設定する必要があります。このパラメーターをtrueに設定するとモードが有効になり、falseに設定すると無効になります。 -
JSONL リクエストボディでは、
enable_thinkingはbodyのトップレベルパラメーターであり、modelと同じレベルに配置する必要があります。extra_bodyの内側には配置しないでください。
クイックスタート
正式なタスクを処理する前に、batch-test-model でテストしてください。このテストモデルは推論をスキップし、固定の成功レスポンスを返すため、API 呼び出しチェーンとデータ形式を検証できます。
batch-test-model の制限事項:
-
テストファイルは入力ファイルの要件を満たす必要があります。最大サイズ:1 MB。最大行数:100。
-
同時実行数制限:最大 2 つの並列タスク。
-
コスト:テストモデルではモデル推論料金は発生しません。
ステップ 1: 入力ファイルの準備
test_model.jsonl という名前のファイルに以下の内容を準備します:
{"custom_id":"1","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello! How can I help you?"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
マルチモーダルモデル (例:qwen-vl-plus) は、ファイル URL と Base64 エンコードされた入力をサポートします:
{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}
ステップ 2: コードの実行
プログラミング言語に応じたコードスニペットを選択します。入力ファイルと同じディレクトリに保存して実行します。このコードは、アップロード、タスク作成、ステータスのポーリング、結果のダウンロードという一連のワークフローを処理します。
ファイルパスやその他のパラメーターをカスタマイズするには、必要に応じてコードを修正してください。
既存のファイル ID の再利用:ファイルをアップロードした後に返される ID (例:file-batch-xxx) は再利用できます。入力内容が同じであれば、再アップロードをスキップし、既存の ID で直接タスクを作成できます:
batch = client.batches.create(
input_file_id="file-batch-xxx", # 既存のファイル ID を再利用し、再アップロードは不要
endpoint="/v1/chat/completions",
completion_window="24h"
)
client.files.list(purpose="batch") API を使用して、アップロード済みのバッチファイル ID を照会し、過去のファイル ID を取得できます。
ステップ 3: テスト結果の確認
タスクが成功すると、結果ファイル result.jsonl には固定レスポンス {"content":"This is a test result."} が含まれます:
{"id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","custom_id":"1","response":{"status_code":200,"request_id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-bca7295b-67c3-4b1f-8239-d78323bb669f","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
{"id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","custom_id":"2","response":{"status_code":200,"request_id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-1e32a8ba-2b69-4dc4-be42-e2897eac9e84","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
正式なタスクの実行
入力ファイルの要件
-
フォーマット:UTF-8 エンコードの JSONL (1行に1つの独立した JSON オブジェクト)。
-
サイズ制限:ファイルあたり最大 50,000 リクエスト、最大 500 MB。
-
行制限:各 JSON オブジェクトは 6 MB を超えず、モデルのコンテキストウィンドウ内に収まる必要があります。
-
一貫性:同じファイル内のすべてのリクエストは、同じモデルと同じ思考モード (該当する場合) を使用する必要があります。
-
一意の識別子:各リクエストには、ファイル内で一意の custom_id フィールドを含める必要があります。このフィールドは、リクエストと結果を照合するために使用されます。
シナリオ 1: テキストチャット
ファイル内容の例:
{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","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-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
シナリオ 2: 画像・動画理解
マルチモーダルモデル (例:qwen-vl-plus) は、ファイル URL と Base64 エンコードされた入力をサポートします。
{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"video-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":"https://example.com/video.mp4"},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"video-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":["data:image/jpeg;base64,{frame1}","data:image/jpeg;base64,{frame2}","data:image/jpeg;base64,{frame3}"]},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"multi-image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"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":"Compare these two images."}]}]}}
{"custom_id":"multi-image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image1_base64}"}},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image2_base64}"}},{"type":"text","text":"Compare these two images."}]}]}}
上記の例の Base64 文字列は切り捨てられています。以下の Python コードを使用して完全なエンコーディングを生成してください。
詳細 (ファイル制限、MIME タイプ、エンコーディング方式など) については、「ローカルファイルの渡し方 (Base64 エンコーディングまたはファイルパス)」をご参照ください。
1. 入力ファイルの修正
-
test_model.jsonlファイルで、modelパラメーターをターゲットモデルに設定し、urlフィールドを設定します:モデルタイプ
url
テキスト生成/マルチモーダルモデル
/v1/chat/completionsテキスト埋め込みモデル
/v1/embeddings -
または、上記の「JSONL バッチ生成ツール」を使用して、正式なタスク用の新しいファイルを生成します。
modelとurlフィールドが正しいことを確認してください。
2. クイックスタートのコードの修正
-
入力ファイルパスを実際のファイル名に変更します。
-
endpoint パラメーターを入力ファイルの url フィールドと一致するように設定します。
3. コードを実行し、結果を待つ
タスクが完了すると、成功したリクエストの結果はローカルの result.jsonl ファイルに保存されます。リクエストが失敗した場合は、エラーの詳細が error.jsonl ファイルに保存されます。
-
成功した結果 (
output_file_id):各行は成功した1つのリクエストに対応し、custom_idとresponseが含まれます。{"id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","custom_id":"req-001","response":{"status_code":200,"request_id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","body":{"created":1768306034,"usage":{"completion_tokens":654,"prompt_tokens":14,"total_tokens":668},"model":"qwen-plus","id":"chatcmpl-3a5c39d5-3981-4e4c-97f2-e0e821893f03","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"こんにちは!杭州西湖は中国の有名な景勝地で、浙江省杭州市の西部に位置していることから「西湖」と名付けられました。中国の十大景勝地の一つであり、世界文化遺産(2011年にユネスコに登録)でもあります。その美しい自然景観と奥深い文化的遺産で世界的に有名です。\n\n### I. 自然景観\n西湖は三方を山に囲まれ、一方は市街地に接しており、面積は約6.39平方キロメートルで、さざ波が立つ如意の形をしています。湖は孤山、白堤、蘇堤、楊公堤によって自然または人工的に複数の水域に分けられ、「一山、二塔、三島、三堤」という配置を形成しています。\n\n主な見どころは以下の通りです:\n- **蘇堤春暁**:北宋時代、偉大な文人である蘇東坡が杭州の知事を務めていた際、西湖の浚渫を指揮し、掘り出された土砂で堤を築きました。後に「蘇堤」と名付けられました。春には桃の花と柳が絵のような風景を作り出します。\n- **断橋残雪**:白堤の東端に位置し、『白蛇伝』の再会の場面の舞台となった場所です。冬に雪が降った後、その銀白色の姿で特に有名です。\n- **雷峰夕照**:雷峰塔は夕日に照らされて金色に輝き、かつて「西湖十景」の一つでした。\n- **三潭印月**:湖中の小瀛洲島には三つの石塔があります。中秋節の夜には、塔の中に灯籠を灯すことができ、月光、灯火、湖の反射が調和した美しい光景が生まれます。\n- **平湖秋月**:白堤の西端に位置し、湖上の月を眺める絶好のスポットです。\n- **花港観魚**:花と魚を観賞することで知られ、庭園では牡丹と鯉が美しく引き立て合っています。\n\n### II. 文化歴史\n西湖は美しい景色だけでなく、豊かな歴史的・文化的意義も持っています:\n- 唐・宋時代以降、白居易、蘇東坡、林逋、楊万里など数多くの文人がここに詩を残しました。\n- 白居易は「白堤」の建設を監督し、西湖を浚渫して地元の人々に恩恵をもたらしました。\n- 西湖周辺には、岳王廟(国民的英雄・岳飛を記念)、霊隠寺(千年の歴史を持つ仏教寺院)、六和塔、龍井村(中国十大銘茶の一つである龍井茶の発祥地)など、多くの史跡があります。\n\n### III. 文化的象徴\n西湖は「地上の楽園」の代表と見なされ、中国の伝統的な風景美学のモデルです。自然の美しさと文化的な深みを統合することで、「天人合一」という哲学的概念を体現しています。多くの詩、絵画、オペラが西湖を題材としており、中国文化の重要な象徴となっています。\n\n### IV. 旅行の推奨\n- 最適な訪問時期:春(3月~5月)は桃の花と柳、秋(9月~11月)は晴天で涼しい気候です。\n- 推奨される方法:散策、サイクリング(湖畔の緑道沿い)、または湖上でのボート遊び。\n- 地元料理:西湖酢魚、龍井蝦仁、東坡肉、片儿川麺。\n\n要約すると、杭州西湖は単なる自然の驚異ではなく、詳細に探求する価値のある生きた文化博物館でもあります。もし杭州を訪れる機会があれば、「薄化粧でも濃い化粧でも等しく魅力的」なこの地上の楽園をお見逃しなく。"}}],"object":"chat.completion"}},"error":null} {"id":"628312ba-172c-457d-ba7f-3e5462cc6899","custom_id":"req-002","response":{"status_code":200,"request_id":"628312ba-172c-457d-ba7f-3e5462cc6899","body":{"created":1768306035,"usage":{"completion_tokens":25,"prompt_tokens":18,"total_tokens":43},"model":"qwen-plus","id":"chatcmpl-628312ba-172c-457d-ba7f-3e5462cc6899","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"春風は緑の柳を撫で、\n夜雨は赤い花を潤す。\n鳥のさえずりが森に満ち、\n山と川は同じ美しさを分かち合う。"}}],"object":"chat.completion"}},"error":null} -
失敗の詳細 (
error_file_id):失敗したリクエストに関する情報を行番号とエラー理由とともに含みます。トラブルシューティングについては、「エラーコード」をご参照ください。
詳細な手順
バッチ API のワークフローは、ファイルのアップロード、タスクの作成、タスクステータスの照会、結果のダウンロードの4つのステップで構成されます。
1. ファイルのアップロード
2. バッチタスクの作成
3. バッチタスクのクエリと管理
4. バッチ結果ファイルのダウンロード
高度な機能
完了通知の設定
長時間実行されるタスクの場合、ポーリングの代わりに非同期通知メッセージを使用してリソース消費を削減します。
完了通知は北京リージョンでのみサポートされています。
-
コールバック:タスク作成時に、公開アクセス可能な URL を指定します。
-
EventBridge メッセージキュー:Alibaba Cloud エコシステムと深く統合されています。パブリック IP は不要です。
方法 1: コールバック
方法 2: EventBridge メッセージキュー
本番運用
-
ファイル管理
-
OpenAI ファイル削除 API を使用して不要なファイルを定期的に削除し、ストレージ制限 (10,000 ファイルまたは 100 GB) に達しないようにします。
-
大きなファイルは直接アップロードするのではなく、OSS に保存します。
-
-
タスクモニタリング
-
コールバックまたは EventBridge の非同期通知メッセージを使用します。
-
ポーリングが必要な場合は、間隔を 1 分以上に設定し、指数バックオフ戦略を使用します。
-
-
エラー処理
-
ネットワークエラー、API エラー、その他の例外に対する処理を実装します。
-
error_file_idからエラーの詳細をダウンロードして分析します。 -
一般的なエラーコードについては、「エラーコード」をご参照ください。
-
-
コスト最適化
-
小さなタスクを単一のバッチに統合します。
-
completion_windowを適切に設定して、スケジューリングの柔軟性を高めます。
-
ユーティリティツール
CSV から JSONL へ
JSONL 結果を CSV へ
レート制限
|
API |
レート制限 (Alibaba Cloud アカウントごと) |
|
タスクの作成 |
1,000 回/分;最大 1,000 の同時タスク |
|
タスクの照会 |
1,000 回/分 |
|
タスクリストの照会 |
100 回/分 |
|
タスクのキャンセル |
1,000 回/分 |
課金
-
単価:すべての成功したリクエストの入力および出力トークンは、対応するモデルのリアルタイム推論価格の 50% で課金されます。詳細については、「モデルリスト」をご参照ください。
-
課金範囲:
-
タスク内で正常に実行されたリクエストのみが課金されます。
-
ファイル解析エラー、タスク実行の失敗、または行レベルのエラーによる失敗したリクエストは課金されません。
-
キャンセルされたタスクの場合、キャンセル前に正常に完了したリクエストは通常通り課金されます。
-
-
バッチ推論は別の課金項目です。AI 汎用節約プランをサポートしますが、サブスクリプション (その他の節約プラン) や新規ユーザー向けの無料クォータなどの割引はサポートしません。コンテキストキャッシュなどの機能もサポートしません。
-
qwen3.5-plus や qwen3.5-flash などの一部のモデルでは、思考モードがデフォルトで有効になっています。このモードは追加の思考トークンを生成し、出力トークン価格で課金されるため、コストが増加します。コストを管理するには、タスクの複雑さに応じて `enable_thinking` パラメーターを設定してください。詳細については、「ディープシンキング」をご参照ください。
エラーコード
リクエストが失敗し、エラーメッセージが返された場合は、「エラーコード」で解決策をご参照ください。
よくある質問
-
バッチチャットとバッチファイルのどちらを選ぶべきですか?
多くのリクエストを含む大きなファイルを非同期で処理する必要がある場合は、バッチファイルを使用します。ビジネスロジックが、高い同時実行性で多くの独立した会話リクエストを同期的に送信する必要がある場合は、バッチチャットを使用します。
-
バッチファイル API はどのように課金されますか?別途パッケージを購入する必要がありますか?
バッチは、成功したリクエストによって消費されたトークンに基づいて従量課金されます。別途リソースパッケージを購入する必要はありません。
-
送信されたバッチファイルは順番に実行されますか?
いいえ。システムは計算負荷に基づいて動的スケジューリングを使用するため、実行順序は保証されません。リソースが制約されている場合、タスクが遅延することがあります。
-
送信されたバッチファイルが完了するまでどのくらいかかりますか?
実行時間は、システムリソースとタスクの規模によって異なります。タスクが completion_window 内に完了しない場合、期限切れになります。期限切れのタスク内の未処理のリクエストは実行されず、課金もされません。
シナリオの推奨事項:厳密なリアルタイムのモデル推論が必要なシナリオではリアルタイム呼び出しを使用します。遅延を許容できる大規模なデータ処理シナリオではバッチ呼び出しを使用します。