Alibaba Cloud Model Studio は、OpenAI 互換のバッチファイル API を提供します。ファイルを通じてリクエストを一括で送信すると、システムが非同期で処理し、すべてのリクエストが完了するか、最大待機時間に達した時点で結果を返します。コストはリアルタイム呼び出しのわずか 50% です。データ分析、モデル評価など、レイテンシーが重要でない大規模ワークロードに最適です。
ワークフロー
前提条件
バッチファイル API は、OpenAI SDK (Python、Node.js) または HTTP API を通じて呼び出すことができます。
- API キーの取得:Model Studio の API キーを取得し、環境変数として設定します
- SDK のインストール (任意):使用する場合は、OpenAI SDK をインストールします。
-
サービスエンドポイント
- 華北 2 (北京):
https://dashscope.aliyuncs.com/compatible-mode/v1 - シンガポール:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- 華北 2 (北京):
サポート範囲
- シンガポール
- 中国 (北京)
はじめに
正式なタスクを処理する前に、batch-test-model でテストしてください。このテストモデルは推論をスキップし、固定の成功応答を返すため、API 呼び出しチェーンとデータ形式を検証できます。
- テストファイルは入力ファイルの要件を満たす必要があります。最大サイズ:1 MB。最大行数:100。
- 同時実行数制限:最大 2 つの並列タスク。
- コスト:テストモデルではモデル推論料金は発生しません。
ステップ 1:入力ファイルの準備
test_model.jsonl という名前のファイルに、以下の内容を準備します。
ステップ 2:コードの実行
ご使用のプログラミング言語のコードスニペットを選択します。入力ファイルと同じディレクトリに保存して実行してください。このコードは、アップロード、タスク作成、ステータスのポーリング、結果のダウンロードという完全なワークフローを処理します。
ファイルパスやその他のパラメーターをカスタマイズするには、必要に応じてコードを修正してください。
file-batch-xxx) は再利用できます。入力内容が同じ場合は、再アップロードをスキップし、既存の ID で直接タスクを作成します。client.files.list(purpose="batch") API を通じて過去のファイル ID を取得し、アップロード済みのバッチファイル ID をクエリできます。サンプルコード
サンプルコード
ステップ 3:テスト結果の検証
タスクが成功すると、結果ファイル result.jsonl には固定の応答 {"content":"This is a test result."} が含まれます。
正式なタスクの実行
入力ファイルの要件
- フォーマット:UTF-8 エンコードの JSONL (1行に1つの独立した JSON オブジェクト)。
- サイズ制限:ファイルあたり最大 50,000 リクエスト、最大 500 MB。
- 行制限:各 JSON オブジェクトは 6 MB を超えず、モデルのコンテキストウィンドウ内に収まる必要があります。
- 一貫性:同じファイル内のすべてのリクエストは、同じモデルと同じ思考モード (該当する場合) を使用する必要があります。
- 一意の識別子:各リクエストには、ファイル内で一意の custom_id フィールドを含める必要があります。このフィールドは、リクエストと結果を照合するために使用されます。
上記の例の Base64 文字列は省略されています。完全なエンコーディングを生成するには、以下の Python コードを使用してください。
Base64 エンコードされた文字列を渡す (画像を例として)
Base64 エンコードされた文字列を渡す (画像を例として)
- ローカルファイルを Base64 エンコーディングに変換します。
-
Data URL フォーマットを構築します:
data:[MIME_type];base64,{base64_image}MIME_typeを実際のメディアタイプに置き換えます。これはMIME Typeの値 (例:image/jpeg、image/png) と一致する必要があります。base64_imageは、前のステップで生成された 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が含まれます。
- 失敗した詳細 (
error_file_id):失敗したリクエストに関する情報 (行番号とエラー理由を含む) が含まれます。トラブルシューティングについては、「エラーコード」をご参照ください。
詳細な手順
バッチ API のワークフローは、ファイルのアップロード、タスクの作成、タスクステータスのクエリ、結果のダウンロードの 4 つのステップで構成されます。
1. ファイルのアップロード
1. ファイルのアップロード
file_id を取得します。ファイルをアップロードする際、purposeパラメーターはbatchである必要があります。
file-batch-xxx) は再利用できます。入力コンテンツが同じままであれば、再アップロードをスキップし、既存の ID を使用して直接タスクを作成します:client.files.list(purpose="batch") API を通じて過去のファイル ID を取得し、アップロード済みのバッチファイル ID をクエリできます。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
リクエスト例
レスポンス例
2. バッチタスクの作成
2. バッチタスクの作成
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
リクエスト例
入力パラメーター
フィールド | タイプ | メソッド | 必須 | 説明 |
|---|---|---|---|---|
input_file_id | String | Body | はい | 入力ファイルの ID。 ファイルの準備とアップロード API によって返されるファイル ID (例: |
endpoint | String | Body | はい | API アクセスパス。入力ファイル内の url フィールドと一致する必要があります。
|
completion_window | String | Body | はい | 最大待機時間。範囲:24h~336h、整数のみ。 単位:「h」または「d」(例:「24h」または「14d」)。 |
metadata | Map | Body | いいえ | タスクの拡張メタデータ。キーと値のペアとして指定します。 |
metadata.ds_name | String | Body | いいえ | タスク名。 例: 最大長:100 文字。 複数回指定された場合、最後の値が有効になります。 |
metadata.ds_description | String | Body | いいえ | タスクの説明。 例: 最大長:200 文字。 複数回指定された場合、最後の値が有効になります。 |
レスポンス例
レスポンスパラメーター
フィールド | タイプ | 説明 |
|---|---|---|
id | String | バッチタスク ID。 |
object | String | 固定値: |
endpoint | String | API アクセスパス。 |
errors | Map | エラー情報。 |
input_file_id | String | 入力ファイル ID 。 |
completion_window | String | 最大待機時間。範囲:24h~336h、整数のみ。 単位:「h」または「d」(例:「24h」または「14d」)。 |
status | String | タスクステータス:validating、failed、in_progress、finalizing、completed、expired、cancelling、cancelled。 |
output_file_id | String | 成功したリクエストの結果のファイル ID。 |
error_file_id | String | 失敗したリクエストの結果のファイル ID。 |
created_at | Integer | タスクが作成されたときの UNIX タイムスタンプ (秒)。 |
in_progress_at | Integer | タスクが処理を開始したときの UNIX タイムスタンプ (秒)。 |
expires_at | Integer | タスクがタイムアウトを開始するときの UNIX タイムスタンプ (秒)。 |
finalizing_at | Integer | タスクが最後に開始されたときの UNIX タイムスタンプ (秒)。 |
completed_at | Integer | タスクが完了したときの UNIX タイムスタンプ (秒)。 |
failed_at | Integer | タスクが失敗したときの UNIX タイムスタンプ (秒)。 |
expired_at | Integer | タスクが期限切れになったときの UNIX タイムスタンプ (秒)。 |
cancelling_at | Integer | タスクがキャンセル中状態になったときの UNIX タイムスタンプ (秒)。 |
cancelled_at | Integer | タスクがキャンセルされたときの UNIX タイムスタンプ (秒)。 |
request_counts | Map | 状態別のリクエスト数。 |
metadata | Map | キーと値のペアとしての追加メタデータ。 |
metadata.ds_name | String | タスク名。 |
metadata.ds_description | String | タスクの説明。 |
3. バッチタスクのクエリと管理
3. バッチタスクのクエリと管理
特定のタスクステータスのクエリ
特定のタスクステータスのクエリ
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
リクエスト例
レスポンス例
クエリが成功すると、詳細なバッチタスク情報が返されます。以下は、ステータスが completed のタスクのレスポンス例です:フィールド | タイプ | 説明 |
|---|---|---|
id | String | バッチタスク ID。 |
status | String | タスクステータス。指定できる値:
|
output_file_id | String | 成功した結果を含む出力ファイルの ID。タスク完了後に生成されます。 |
error_file_id | String | 失敗したリクエストの詳細を含むエラーファイルの ID。リクエストが失敗した場合にタスク完了後に生成されます。 |
request_counts | Object | 合計、完了、失敗のカウントを含むリクエスト数の統計。 |
タスクリストのクエリ
タスクリストのクエリ
batches.list() メソッドを使用して、バッチタスクのリストを取得します。ページネーションを使用して、完全なタスクリストを取得します。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
リクエスト例
入力パラメーター
フィールド | タイプ | メソッド | 必須 | 説明 |
|---|---|---|---|---|
after | String | Query | いいえ | ページネーション用のカーソル。 前のページの最後のタスク ID を設定します。 |
limit | Integer | Query | いいえ | 1 ページあたりのタスク数。範囲:[1, 100]。デフォルト:20。 |
ds_name | String | Query | いいえ | タスク名によるあいまい一致。 |
input_file_ids | String | Query | いいえ | カンマで区切った複数のファイル ID (最大 20 個) でフィルタリングします。 |
status | String | Query | いいえ | タスクステータスでフィルターします。複数のステータスはカンマで区切って指定します。 |
create_after | String | Query | いいえ | この時間以降に作成されたタスクをフィルターします。形式: |
create_before | String | Query | いいえ | 指定した時間より前に作成されたタスクをフィルターします。 形式: |
レスポンス例
レスポンスパラメーター
フィールド | タイプ | 説明 |
|---|---|---|
object | String | オブジェクトタイプ。固定値:list。 |
data | Array | バッチタスクオブジェクトの配列。バッチタスク作成のレスポンスパラメーターをご参照ください。 |
first_id | String | 現在のページの最初のバッチタスクの ID。 |
last_id | String | 現在のページの最後のバッチタスクの ID。 |
has_more | Boolean | 追加のページがあるかどうか。 |
バッチタスクのキャンセル
バッチタスクのキャンセル
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
リクエスト例
レスポンス例
タスクを正常にキャンセルすると、API は詳細なバッチタスク情報を返します。以下は、ステータスが cancelling のタスクのレスポンス例です:タスクをキャンセルすると、ステータスはまずcancellingに変わり、システムが現在実行中のリクエストの完了を待ちます。ステータスは最終的にcancelledに変わります。完了したリクエストの結果は、引き続き出力ファイルに保存されます。
4. バッチ結果ファイルのダウンロード
4. バッチ結果ファイルのダウンロード
file_id が file-batch_output で始まるファイルのみダウンロードできます。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
content メソッドを使用してバッチタスクの結果ファイルの内容を取得し、write_to_file メソッドを使用してローカルに保存します。リクエスト例
レスポンス例
レスポンス例
単一のレスポンス例:レスポンスパラメーター
フィールド | タイプ | 説明 |
|---|---|---|
id | String | リクエスト ID。 |
custom_id | String | ユーザー定義のリクエスト識別子。 |
response | Object | リクエストの結果。 |
status_code | Integer | HTTP ステータスコード。200 は成功を示します。 |
request_id | String | このリクエストに対してサーバーが生成した一意の ID。 |
completion_tokens | Integer | モデルが生成したレスポンスのトークン数。 |
prompt_tokens | Integer | モデルに送信された入力コンテンツ ( |
total_tokens | Integer | このリクエストで使用された合計トークン数。 |
model | String | このリクエストで使用されたモデルの名前。 |
error | Object | エラーオブジェクト。成功時は |
error.code | String | エラー行と理由の情報。トラブルシューティングについては、エラーコードをご参照ください。 |
error.message | String | エラーメッセージ。 |
高度な機能
完了通知の設定
長時間実行タスクの場合、ポーリングの代わりに非同期通知を使用することで、リソース消費を削減できます。
- コールバック:タスク作成時に、パブリックにアクセス可能な URL を指定します。
- EventBridge メッセージキュー:Alibaba Cloud エコシステムと緊密に統合されています。パブリック IP は不要です。
方式 1:コールバック
方式 1:コールバック
metadata を介してパブリックにアクセス可能な URL を指定します。タスクが完了すると、システムはタスクステータスを含む POST リクエストを指定された URL に送信します。- OpenAI Python SDK
- curl (HTTP)
方式 2:EventBridge メッセージキュー
方式 2:EventBridge メッセージキュー
- イベントソース (Source):
acs.dashscope - イベントタイプ (Type):
dashscope:System:BatchTaskFinish
本番環境への適用
-
ファイル管理
- ストレージ制限 (10,000 ファイルまたは 100 GB) に達しないように、OpenAI File delete API を使用して不要なファイルを定期的に削除してください。
- サイズの大きいファイルは直接アップロードするのではなく、OSS に保存してください。
-
タスクのモニタリング
- Callback または EventBridge の非同期通知を使用してください。
- ポーリングが必要な場合は、間隔を 1 分以上に設定し、指数バックオフ戦略を使用してください。
-
エラー処理
- ネットワークエラー、API エラー、およびその他の例外に対する処理を実装してください。
error_file_idからエラーの詳細をダウンロードして分析してください。- 一般的なエラーコードについては、「エラーコード」をご参照ください。
-
コストの最適化
- 小規模なタスクは 1 つのバッチにまとめてください。
- スケジューリングの柔軟性を高めるために、
completion_windowを適切に設定してください。
ユーティリティツール
CSV から JSONL へ
CSV から JSONL へ
ファイルパスやその他のパラメーターをカスタマイズするには、必要に応じてコードを修正してください。
JSONL の結果を CSV へ
JSONL の結果を CSV へ
result.jsonl を result.csv に変換し、Excel で分析します。ファイルパスやその他のパラメーターをカスタマイズするには、必要に応じてコードを修正してください。
- テキストエディター (Sublime Text など) を使用して CSV ファイルのエンコーディングを GBK に変換してから、Excel で開きます。
- または、新しい Excel ファイルを作成し、データをインポートする際に UTF-8 エンコーディングを指定します。
レート制限
API | レート制限 (Alibaba Cloud アカウントあたり) |
|---|---|
タスクの作成 | 1,000 呼び出し/分、最大 1,000 同時タスク |
タスクの照会 | 1,000 呼び出し/分 |
タスクリストの照会 | 100 呼び出し/分 |
タスクのキャンセル | 1,000 呼び出し/分 |
課金
- 単価:すべての成功したリクエストの入力トークンと出力トークンは、対応するモデルのリアルタイム推論価格の 50% で課金されます。詳細については、「モデルリスト」をご参照ください。
-
課金範囲:
- タスク内で正常に実行されたリクエストのみが課金対象となります。
- ファイル解析エラー、タスク実行の失敗、または行レベルのエラーによって失敗したリクエストには、料金は発生しません。
- キャンセルされたタスクの場合、キャンセル前に正常に完了したリクエストは通常どおり課金されます。
- バッチ推論は独立した課金項目です。これは AI 汎用節約プラン をサポートしますが、サブスクリプション (その他の節約プラン) や 新規ユーザー向けの無料クォータ などの割引は対象外です。また、コンテキストキャッシュ などの機能もサポートしていません。
- qwen3.5-plus や qwen3.5-flash などの一部のモデルでは、思考モードがデフォルトで有効になっています。このモードでは追加の思考トークンが生成され、出力トークン価格で課金されるため、コストが増加します。コストをコントロールするには、タスクの複雑さに応じて enable_thinking パラメーターを設定してください。詳細については、「ディープシンキング」をご参照ください。
エラーコード
リクエストが失敗し、エラーメッセージが返された場合のソリューションは、エラーコードをご参照ください。
よくある質問
- Batch Chat と Batch File はどのように使い分ければよいですか? 多数のリクエストを含む大規模なファイルを非同期で処理する必要がある場合は、Batch File を使用します。ビジネスロジック上、多数の独立した会話リクエストを高い同時実行性で同期的に送信する必要がある場合は、Batch Chat を使用します。
- Batch File API の課金方法について教えてください。別途パッケージの購入は必要ですか? Batch は、成功したリクエストによって消費されたトークン数に基づく従量課金制です。別途リソースパッケージを購入する必要はありません。
- 送信されたバッチファイルは順番に実行されますか? いいえ。システムはコンピューティング負荷に基づいて動的スケジューリングを使用するため、実行順序は保証されません。リソースが制限されている場合、タスクが遅延することがあります。
- 送信されたバッチファイルの完了まで、どのくらいの時間がかかりますか? 実行時間は、システムリソースとタスクの規模によって異なります。タスクが completion_window 内に完了しない場合、そのタスクは期限切れになります。期限切れになったタスク内の未処理のリクエストは実行されず、料金も発生しません。 シナリオの推奨事項: 厳密なリアルタイムのモデル推論が必要なシナリオでは、リアルタイム呼び出しを使用してください。遅延を許容できる大規模データ処理のシナリオでは、バッチ呼び出しを使用してください。