Alibaba Cloud Model Studio は、OpenAI 互換のバッチファイル API を提供します。この API を使用すると、ファイルを使ってバッチタスクを送信できます。システムはこれらのタスクを非同期で処理し、タスクが完了するか最大待機時間に達した後に結果を返します。料金はリアルタイム呼び出しの 50% です。これは、大規模な処理が必要でありながら、時間に制約されないデータ分析やモデル評価などのサービスに最適です。
コンソールでこの操作を実行する方法については、「バッチ推論」をご参照ください。
ワークフロー
前提条件
バッチファイル API は、OpenAI SDK for Python または Node.js、あるいは HTTP API 呼び出しを使用して呼び出すことができます。
-
API キーの取得:API キーを取得し、環境変数として設定します
-
SDK のインストール (任意):SDK を使用して呼び出しを行う場合は、OpenAI SDK をインストールする必要があります。
-
サーバーエンドポイント
-
中国本土:
https://dashscope.aliyuncs.com/compatible-mode/v1 -
国際:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
-
可用性
国際
国際デプロイメントモードでは、エンドポイントとデータストレージの両方がシンガポールリージョンにあります。モデル推論の計算リソースは、中国本土を除くグローバルリージョンで動的にスケジューリングされます。
サポート対象モデル:qwen-max、qwen-plus、qwen-flash、qwen-turbo。
中国本土
中国本土デプロイメントモードでは、エンドポイントとデータストレージの両方が北京リージョンにあります。モデル推論の計算リソースは中国本土でのみ利用可能です。
サポート対象モデル:
テキスト生成モデル: Qwen-Max、Plus、Flash、Long の安定版および一部の
latest版。QwQ シリーズ(qwq-plus)および一部のサードパーティ製モデル(deepseek-r1、deepseek-v3)もサポートされています。マルチモーダルモデル: Qwen-VL-Max、Plus、Flash の安定版に加え、一部の
latestバージョンもサポートされています。また、Qwen-OCR モデルもサポートされています。テキスト埋め込みモデル:text-embedding-v4。
サポート対象モデル名
テキスト生成
Qwen-Max:qwen3-max、qwen-max、qwen-max-latest
Qwen-Plus:qwen3.5-plus、qwen-plus、qwen-plus-latest
Qwen-Flash:qwen3.5-flash、qwen-flash
Qwen-Long:qwen-long-latest
QwQ:qwq-plus
サードパーティモデル:deepseek-r1、deepseek-v3
マルチモーダル
テキスト埋め込みモデル: text-embedding-v4
一部のモデルは思考モードをサポートしています。有効にすると、このモードは思考
トークンを生成し、コストが増加します。qwen3.5シリーズ (qwen3.5-plusやqwen3.5-flashなど) は、デフォルトで思考モードが有効になっています。ハイブリッド思考モデルを使用する場合は、enable_thinkingパラメーター (trueまたはfalse) を明示的に設定してください。
クイックスタート
正式なタスクを処理する前に、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?"}]}}
ステップ 2:コードの実行
ご使用のプログラミング言語のサンプルコードを選択し、入力ファイルと同じディレクトリに保存してから実行します。このコードは、ファイルのアップロード、タスクの作成、ステータスのポーリング、結果のダウンロードという全プロセスを完了します。
ファイルパスやその他のパラメーターを調整するには、必要に応じてコードを修正してください。
サンプルコード
OpenAI Python SDK
import os
from pathlib import Path
from openai import OpenAI
import time
# クライアントを初期化します。
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Model Studio API キーに置き換えることができます:api_key="sk-xxx"。
# セキュリティのため、本番コードに API キーをハードコーディングしないでください。
# シンガポールリージョンと北京リージョンの API キーは異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンのベース URL です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1" # Alibaba Cloud Model Studio サービスのベース URL
)
def upload_file(file_path):
print(f"リクエスト情報を含む JSONL ファイルをアップロードしています...")
file_object = client.files.create(file=Path(file_path), purpose="batch")
print(f"ファイルがアップロードされました。ファイル ID:{file_object.id}\n")
return file_object.id
def create_batch_job(input_file_id):
print(f"ファイル ID からバッチタスクを作成しています...")
# 注意:endpoint パラメーターの値は、入力ファイルの url フィールドの値と同じでなければなりません。テストモデル (batch-test-model) の場合は、endpoint を /v1/chat/ds-test に設定します。テキスト埋め込みモデルの場合は /v1/embeddings に設定します。その他のモデルの場合は /v1/chat/completions に設定します。
batch = client.batches.create(input_file_id=input_file_id, endpoint="/v1/chat/ds-test", completion_window="24h")
print(f"バッチタスクが作成されました。バッチタスク ID:{batch.id}\n")
return batch.id
def check_job_status(batch_id):
print(f"バッチタスクのステータスを確認しています...")
batch = client.batches.retrieve(batch_id=batch_id)
print(f"バッチタスクのステータス:{batch.status}\n")
return batch.status
def get_output_id(batch_id):
print(f"バッチタスク内の成功したリクエストの出力ファイル ID を取得しています...")
batch = client.batches.retrieve(batch_id=batch_id)
print(f"出力ファイル ID:{batch.output_file_id}\n")
return batch.output_file_id
def get_error_id(batch_id):
print(f"バッチタスク内の失敗したリクエストの出力ファイル ID を取得しています...")
batch = client.batches.retrieve(batch_id=batch_id)
print(f"エラーファイル ID:{batch.error_file_id}\n")
return batch.error_file_id
def download_results(output_file_id, output_file_path):
print(f"バッチタスクの成功結果を印刷およびダウンロードしています...")
content = client.files.content(output_file_id)
# テスト用に一部のコンテンツを印刷します。
print(f"成功結果の最初の 1000 文字を印刷します:{content.text[:1000]}...\n")
# 結果ファイルをローカルに保存します。
content.write_to_file(output_file_path)
print(f"完全な出力はローカルの出力ファイル result.jsonl に保存されました\n")
def download_errors(error_file_id, error_file_path):
print(f"バッチタスクの失敗情報を印刷およびダウンロードしています...")
content = client.files.content(error_file_id)
# テスト用に一部のコンテンツを印刷します。
print(f"失敗情報の最初の 1000 文字を印刷します:{content.text[:1000]}...\n")
# エラー情報ファイルをローカルに保存します。
content.write_to_file(error_file_path)
print(f"完全な失敗情報はローカルのエラーファイル error.jsonl に保存されました\n")
def main():
# ファイルパス
input_file_path = "test_model.jsonl" # ご利用の入力ファイルパスに置き換えてください。
output_file_path = "result.jsonl" # ご利用の出力ファイルパスに置き換えてください。
error_file_path = "error.jsonl" # ご利用のエラーファイルパスに置き換えてください。
try:
# ステップ 1:リクエスト情報を含む JSONL ファイルをアップロードして、入力ファイル ID を取得します。
input_file_id = upload_file(input_file_path)
# ステップ 2:入力ファイル ID に基づいてバッチタスクを作成します。
batch_id = create_batch_job(input_file_id)
# ステップ 3:バッチタスクが完了するまでステータスを確認します。
status = ""
while status not in ["completed", "failed", "expired", "cancelled"]:
status = check_job_status(batch_id)
print(f"タスクの完了を待っています...")
time.sleep(10) # 10 秒待ってから再度ステータスを確認します。
# タスクが失敗した場合は、エラーメッセージを印刷して終了します。
if status == "failed":
batch = client.batches.retrieve(batch_id)
print(f"バッチタスクが失敗しました。エラー:{batch.errors}\n")
print(f"詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください")
return
# ステップ 4:結果をダウンロードします。出力ファイル ID が空でない場合は、成功結果の最初の 1000 文字を印刷し、完全な結果をローカルの出力ファイルにダウンロードします。
# エラーファイル ID が空でない場合は、失敗情報の最初の 1000 文字を印刷し、完全な情報をローカルのエラーファイルにダウンロードします。
output_file_id = get_output_id(batch_id)
if output_file_id:
download_results(output_file_id, output_file_path)
error_file_id = get_error_id(batch_id)
if error_file_id:
download_errors(error_file_id, error_file_path)
print(f"詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください")
except Exception as e:
print(f"エラーが発生しました:{e}")
print(f"詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください")
if __name__ == "__main__":
main()
OpenAI Node.js SDK
/**
* Alibaba Cloud Model Studio バッチ API テスト - OpenAI Node.js SDK を使用
*
* 依存関係のインストール:npm install openai
* 実行:node test-nodejs.js
*/
const OpenAI = require('openai');
const fs = require('fs');
// シンガポールリージョンのベース URL
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、次の URL を使用してください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
process.exit(1);
}
// クライアントを初期化します。
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
async function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
async function main() {
try {
console.log('=== バッチ API テストを開始します ===\n');
// ステップ 1:ファイルをアップロード
console.log('ステップ 1:リクエスト情報を含む JSONL ファイルをアップロードしています...');
const fileStream = fs.createReadStream('test_model.jsonl');
const fileObject = await client.files.create({
file: fileStream,
purpose: 'batch'
});
const fileId = fileObject.id;
console.log(`✓ ファイルがアップロードされました。ファイル ID:${fileId}\n`);
// ステップ 2:バッチタスクを作成
console.log('ステップ 2:バッチタスクを作成しています...');
const batch = await client.batches.create({
input_file_id: fileId,
endpoint: '/v1/chat/ds-test', // テストモデルには /v1/chat/ds-test を使用
completion_window: '24h'
});
const batchId = batch.id;
console.log(`✓ バッチタスクが作成されました。タスク ID:${batchId}\n`);
// ステップ 3:タスクステータスをポーリング
console.log('ステップ 3:タスクの完了を待っています...');
let status = batch.status;
let pollCount = 0;
let latestBatch = batch;
while (!['completed', 'failed', 'expired', 'cancelled'].includes(status)) {
await sleep(10000); // 10 秒待機
latestBatch = await client.batches.retrieve(batchId);
status = latestBatch.status;
pollCount++;
console.log(` [${pollCount}] タスクステータス:${status}`);
}
console.log(`\n✓ タスクが終了しました。最終ステータス:${status}\n`);
// ステップ 4:結果を処理
if (status === 'completed') {
console.log('ステップ 4:結果ファイルをダウンロードしています...');
// 成功した結果をダウンロード
const outputFileId = latestBatch.output_file_id;
if (outputFileId) {
console.log(` 出力ファイル ID:${outputFileId}`);
const content = await client.files.content(outputFileId);
const text = await content.text();
console.log('\n--- 成功した結果 (最初の 500 文字) ---');
console.log(text.substring(0, Math.min(500, text.length)));
console.log('...\n');
}
// エラーファイルをダウンロード (もしあれば)
const errorFileId = latestBatch.error_file_id;
if (errorFileId) {
console.log(` エラーファイル ID:${errorFileId}`);
const errorContent = await client.files.content(errorFileId);
const errorText = await errorContent.text();
console.log('\n--- エラー情報 ---');
console.log(errorText);
}
console.log('\n=== テストは正常に完了しました ===');
} else if (status === 'failed') {
console.error('\n✗ バッチタスクが失敗しました');
if (latestBatch.errors) {
console.error('エラー情報:', latestBatch.errors);
}
console.error('\n詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください');
} else {
console.log(`\nタスクステータス:${status}`);
}
} catch (error) {
console.error('エラーが発生しました:', error.message);
console.error(error);
}
}
main();
Java (HTTP)
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;
/**
* Alibaba Cloud Model Studio バッチ API テスト - HTTP API 呼び出しを使用
*
* 前提条件:
* 1. DASHSCOPE_API_KEY 環境変数が設定されていることを確認してください。
* 2. プロジェクトのルートディレクトリにテストファイル test_model.jsonl を準備してください。
*
* リージョン設定に関する注意:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
*/
public class BatchAPITest {
// シンガポールリージョンのベース URL
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
private static String API_KEY;
public static void main(String[] args) throws Exception {
// 環境変数から API キーを取得します。
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.exit(1);
}
System.out.println("=== バッチ API テストを開始します ===\n");
try {
// ステップ 1:ファイルをアップロード
System.out.println("ステップ 1:リクエスト情報を含む JSONL ファイルをアップロードしています...");
String fileId = uploadFile("test_model.jsonl");
System.out.println("✓ ファイルがアップロードされました。ファイル ID:" + fileId + "\n");
// ステップ 2:バッチタスクを作成
System.out.println("ステップ 2:バッチタスクを作成しています...");
String batchId = createBatch(fileId);
System.out.println("✓ バッチタスクが作成されました。タスク ID:" + batchId + "\n");
// ステップ 3:タスクステータスをポーリング
System.out.println("ステップ 3:タスクの完了を待っています...");
String status = "";
int pollCount = 0;
while (!isTerminalStatus(status)) {
Thread.sleep(10000); // 10 秒待機
String batchInfo = getBatch(batchId);
status = parseStatus(batchInfo);
pollCount++;
System.out.println(" [" + pollCount + "] タスクステータス:" + status);
// ステップ 4:完了した場合、結果をダウンロード
if ("completed".equals(status)) {
System.out.println("\n✓ タスクが完了しました!\n");
System.out.println("ステップ 4:結果ファイルをダウンロードしています...");
String outputFileId = parseOutputFileId(batchInfo);
if (outputFileId != null && !outputFileId.isEmpty()) {
System.out.println(" 出力ファイル ID:" + outputFileId);
String content = getFileContent(outputFileId);
System.out.println("\n--- 成功した結果 (最初の 500 文字) ---");
System.out.println(content.substring(0, Math.min(500, content.length())));
System.out.println("...\n");
}
String errorFileId = parseErrorFileId(batchInfo);
if (errorFileId != null && !errorFileId.isEmpty() && !"null".equals(errorFileId)) {
System.out.println(" エラーファイル ID:" + errorFileId);
String errorContent = getFileContent(errorFileId);
System.out.println("\n--- エラー情報 ---");
System.out.println(errorContent);
}
System.out.println("\n=== テストは正常に完了しました ===");
break;
} else if ("failed".equals(status)) {
System.err.println("\n✗ バッチタスクが失敗しました");
System.err.println("タスク情報:" + batchInfo);
System.err.println("\n詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください");
break;
} else if ("expired".equals(status) || "cancelled".equals(status)) {
System.out.println("\nタスクステータス:" + status);
break;
}
}
} catch (Exception e) {
System.err.println("エラーが発生しました:" + e.getMessage());
e.printStackTrace();
}
}
/**
* ファイルをアップロード
*/
private static String uploadFile(String filePath) throws Exception {
String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
URL url = new URL(BASE_URL + "/files");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
try (DataOutputStream out = new DataOutputStream(conn.getOutputStream())) {
// purpose フィールドを追加
out.writeBytes("--" + boundary + "\r\n");
out.writeBytes("Content-Disposition: form-data; name=\"purpose\"\r\n\r\n");
out.writeBytes("batch\r\n");
// ファイルを追加
out.writeBytes("--" + boundary + "\r\n");
out.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + filePath + "\"\r\n");
out.writeBytes("Content-Type: application/octet-stream\r\n\r\n");
byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
out.write(fileBytes);
out.writeBytes("\r\n");
out.writeBytes("--" + boundary + "--\r\n");
}
String response = readResponse(conn);
return parseField(response, "\"id\":\s*\"([^\"]+)\"");
}
/**
* バッチタスクを作成
*/
private static String createBatch(String fileId) throws Exception {
String jsonBody = String.format(
"{\"input_file_id\":\"%s\",\"endpoint\":\"/v1/chat/ds-test\",\"completion_window\":\"24h\"}",
fileId
);
String response = sendRequest("POST", "/batches", jsonBody);
return parseField(response, "\"id\":\s*\"([^\"]+)\"");
}
/**
* バッチタスク情報を取得
*/
private static String getBatch(String batchId) throws Exception {
return sendRequest("GET", "/batches/" + batchId, null);
}
/**
* ファイルコンテンツを取得
*/
private static String getFileContent(String fileId) throws Exception {
return sendRequest("GET", "/files/" + fileId + "/content", null);
}
/**
* HTTP リクエストを送信
*/
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
/**
* レスポンスを読み取り
*/
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
/**
* JSON フィールドを解析 (簡易実装)
*/
private static String parseField(String json, String regex) {
java.util.regex.Pattern pattern = java.util.regex.Pattern.compile(regex);
java.util.regex.Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
private static String parseStatus(String json) {
return parseField(json, "\"status\":\s*\"([^\"]+)\"");
}
private static String parseOutputFileId(String json) {
return parseField(json, "\"output_file_id\":\s*\"([^\"]+)\"");
}
private static String parseErrorFileId(String json) {
return parseField(json, "\"error_file_id\":\s*\"([^\"]+)\"");
}
/**
* 終了ステータスかどうかを確認
*/
private static boolean isTerminalStatus(String status) {
return "completed".equals(status)
|| "failed".equals(status)
|| "expired".equals(status)
|| "cancelled".equals(status);
}
}
curl (HTTP)
#!/bin/bash
# Alibaba Cloud Model Studio バッチ API テスト - curl を使用
#
# 前提条件:
# 1. DASHSCOPE_API_KEY 環境変数が設定されていることを確認してください。
# 2. 現在のディレクトリにテストファイル test_model.jsonl を準備してください。
#
# リージョン設定に関する注意:
# - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
# - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
API_KEY="${DASHSCOPE_API_KEY}"
BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
# 北京リージョンを使用する場合は、BASE_URL を置き換えてください:
# BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
# API キーの確認
if [ -z "$API_KEY" ]; then
echo "エラー:DASHSCOPE_API_KEY 環境変数を設定してください。"
exit 1
fi
echo "=== バッチ API テストを開始します ==="
echo ""
# ステップ 1:ファイルをアップロード
echo "ステップ 1:リクエスト情報を含む JSONL ファイルをアップロードしています..."
UPLOAD_RESPONSE=$(curl -s -X POST "${BASE_URL}/files" \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@test_model.jsonl' \
-F 'purpose=batch')
FILE_ID=$(echo $UPLOAD_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "✓ ファイルがアップロードされました。ファイル ID:${FILE_ID}"
echo ""
# ステップ 2:バッチタスクを作成
echo "ステップ 2:バッチタスクを作成しています..."
BATCH_RESPONSE=$(curl -s -X POST "${BASE_URL}/batches" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\":\"${FILE_ID}\",\"endpoint\":\"/v1/chat/ds-test\",\"completion_window\":\"24h\"}")
BATCH_ID=$(echo $BATCH_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "✓ バッチタスクが作成されました。タスク ID:${BATCH_ID}"
echo ""
# ステップ 3:タスクステータスをポーリング
echo "ステップ 3:タスクの完了を待っています..."
STATUS=""
POLL_COUNT=0
while [[ "$STATUS" != "completed" && "$STATUS" != "failed" && "$STATUS" != "expired" && "$STATUS" != "cancelled" ]]; do
sleep 10
BATCH_INFO=$(curl -s -X GET "${BASE_URL}/batches/${BATCH_ID}" \
-H "Authorization: Bearer ${API_KEY}")
STATUS=$(echo $BATCH_INFO | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
POLL_COUNT=$((POLL_COUNT + 1))
echo " [${POLL_COUNT}] タスクステータス:${STATUS}"
done
echo ""
echo "✓ タスクが終了しました。最終ステータス:${STATUS}"
echo ""
# ステップ 4:結果をダウンロード
if [[ "$STATUS" == "completed" ]]; then
echo "ステップ 4:結果ファイルをダウンロードしています..."
OUTPUT_FILE_ID=$(echo $BATCH_INFO | grep -o '"output_file_id":"[^"]*"' | cut -d'"' -f4)
if [[ -n "$OUTPUT_FILE_ID" && "$OUTPUT_FILE_ID" != "null" ]]; then
echo " 出力ファイル ID:${OUTPUT_FILE_ID}"
RESULT_CONTENT=$(curl -s -X GET "${BASE_URL}/files/${OUTPUT_FILE_ID}/content" \
-H "Authorization: Bearer ${API_KEY}")
echo ""
echo "--- 成功した結果 (最初の 500 文字) ---"
echo "${RESULT_CONTENT:0:500}"
echo "..."
echo ""
fi
ERROR_FILE_ID=$(echo $BATCH_INFO | grep -o '"error_file_id":"[^"]*"' | cut -d'"' -f4)
if [[ -n "$ERROR_FILE_ID" && "$ERROR_FILE_ID" != "null" ]]; then
echo " エラーファイル ID:${ERROR_FILE_ID}"
ERROR_CONTENT=$(curl -s -X GET "${BASE_URL}/files/${ERROR_FILE_ID}/content" \
-H "Authorization: Bearer ${API_KEY}")
echo ""
echo "--- エラー情報 ---"
echo "${ERROR_CONTENT}"
fi
echo ""
echo "=== テストは正常に完了しました ==="
elif [[ "$STATUS" == "failed" ]]; then
echo ""
echo "✗ バッチタスクが失敗しました"
echo "タスク情報:${BATCH_INFO}"
echo ""
echo "詳細については、https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code をご参照ください"
else
echo ""
echo "タスクステータス:${STATUS}"
fi
ステップ 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}
本番タスクの実行
入力ファイルの要件
-
フォーマット:JSONL (UTF-8 エンコーディング、1行に1つの独立した JSON オブジェクト)
-
サイズ制限:1つのファイルには最大 50,000 リクエストを含めることができ、サイズは 500 MB を超えることはできません。
-
行制限:各 JSON オブジェクトは 6 MB を超えることはできず、モデルのコンテキスト長を超えてはなりません。
-
一貫性の要件:同じファイル内のすべてのリクエストは、同じモデルと同じ思考モード (該当する場合) を使用する必要があります。
-
一意の識別子:各リクエストには、ファイル内で一意の `custom_id` フィールドを含める必要があります。これは結果を照合するために使用されます。
ファイル内容の例:
{"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?"}]}}JSONL バッチ生成ツール
このツールを使用して、JSONL ファイルを迅速に生成します。
1. 入力ファイルの修正
-
テストに使用される
test_model.jsonlファイルを直接変更できます。使用する本番用モデルに model パラメーターを設定し、url フィールドを設定します。モデルタイプ
URL
テキスト生成/マルチモーダルモデル
/v1/chat/completionsテキスト埋め込みモデル
/v1/embeddings -
または、JSONL Batch Generation Tool を使用してプロダクションタスク用の新しいファイルを生成することもできます。
modelフィールドとurlフィールドが正しいことを確認してください。
2. クイックスタートコードの修正
-
入力ファイルパスをご利用のファイル名に変更します。
-
`endpoint` パラメーターの値を、入力ファイルの `url` フィールドと一致するように修正します。
3. コードの実行と結果の待機
タスクが成功すると、成功したリクエストの結果はローカルの result.jsonl ファイルに保存されます。一部のリクエストが失敗した場合、エラー詳細は error.jsonl ファイルに保存されます。
-
成功した結果 (
output_file_id):各行は成功したリクエストを表し、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. ファイルのアップロード
Batch タスクを作成する前に、入力ファイル形式の要件を満たす JSONL ファイルをファイルアップロードインターフェイスを使用してアップロードし、file_id を取得します。
ファイルをアップロードする際は、purposeパラメーターをbatchに設定します。
OpenAI Python SDK
リクエスト例
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
# test.jsonl はローカルのサンプルファイルです。purpose は batch である必要があります。
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")
print(file_object.model_dump_json())
OpenAI Node.js SDK
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - ファイルのアップロード
*
* 環境変数が設定されていない場合は、コード内で API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
const fs = require('fs');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
const fileStream = fs.createReadStream('test.jsonl');
const fileObject = await client.files.create({
file: fileStream,
purpose: 'batch'
});
console.log(fileObject.id);
Java (HTTP)
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - ファイルのアップロード
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPIUploadFile {
// シンガポールリージョンの設定
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
String fileId = uploadFile("test.jsonl");
System.out.println("ファイル ID: " + fileId);
}
// === ユーティリティメソッド ===
private static String uploadFile(String filePath) throws Exception {
String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
URL url = new URL(BASE_URL + "/files");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
conn.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
try (DataOutputStream out = new DataOutputStream(conn.getOutputStream())) {
// purpose フィールドを追加
out.writeBytes("--" + boundary + "\r\n");
out.writeBytes("Content-Disposition: form-data; name=\"purpose\"\r\n\r\n");
out.writeBytes("batch\r\n");
// ファイルを追加
out.writeBytes("--" + boundary + "\r\n");
out.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + filePath + "\"\r\n");
out.writeBytes("Content-Type: application/octet-stream\r\n\r\n");
byte[] fileBytes = Files.readAllBytes(Paths.get(filePath));
out.write(fileBytes);
out.writeBytes("\r\n");
out.writeBytes("--" + boundary + "--\r\n");
}
String response = readResponse(conn);
return parseField(response, "\"id\":\\s*\"([^\"]+)\"");
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1/files に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="batch"'
レスポンス例
{
"id": "file-batch-xxx",
"bytes": 437,
"created_at": 1742304153,
"filename": "test.jsonl",
"object": "file",
"purpose": "batch",
"status": "processed",
"status_details": null
}
2. バッチタスクの作成
ファイルアップロードインターフェイスから返された `file_id` を使用して、バッチジョブを作成します。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.create(
input_file_id="file-batch-xxx", # ファイルアップロードから返された ID。
endpoint="/v1/chat/completions", # batch-test-model の場合は /v1/chat/ds-test を使用します。テキスト埋め込みモデルの場合は /v1/embeddings を使用します。テキスト生成/マルチモーダルモデルの場合は /v1/chat/completions を使用します。
completion_window="24h",
metadata={'ds_name':"タスク名",'ds_description':'タスクの説明'} # メタデータ、オプションのフィールドで、タスク名と説明を作成するために使用されます。
)
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - バッチタスクの作成
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
const batch = await client.batches.create({
input_file_id: 'file-batch-xxx',
endpoint: '/v1/chat/completions',
completion_window: '24h',
metadata: {'ds_name': 'タスク名', 'ds_description': 'タスクの説明'}
});
console.log(batch.id);
Java (HTTP)
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - バッチタスクの作成
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPICreateBatch {
// シンガポールリージョンの設定 (デフォルト)
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
String jsonBody = "{\"input_file_id\":\"file-batch-xxx\",\"endpoint\":\"/v1/chat/completions\",\"completion_window\":\"24h\",\"metadata\":{\"ds_name\":\"タスク名\",\"ds_description\":\"タスクの説明\"}}";
String response = sendRequest("POST", "/batches", jsonBody);
String batchId = parseField(response, "\"id\":\\s*\"([^\"]+)\"");
System.out.println("バッチタスク ID: " + batchId);
}
// === ユーティリティメソッド ===
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1/batches に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl -X POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/batches \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-batch-xxx",
"endpoint": "/v1/chat/completions",
"completion_window": "24h",
"metadata":{"ds_name":"タスク名","ds_description":"タスクの説明"}
}'
入力パラメーター
|
フィールド |
タイプ |
パラメーター渡し メソッド |
必須 |
説明 |
|
input_file_id |
String |
Body |
はい |
バッチタスクの入力ファイルとしてファイル ID を指定します。 「ファイルの準備とアップロード」操作によって返されるファイル ID(例: |
|
endpoint |
String |
Body |
はい |
アクセスパス。入力ファイルの `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": "batch_xxx",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-xxx",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"created_at": 1742367779,
"in_progress_at": null,
"expires_at": null,
"finalizing_at": null,
"completed_at": null,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"metadata": {
"ds_name": "タスク名",
"ds_description": "タスクの説明"
}
}
レスポンスパラメーター
|
フィールド |
タイプ |
説明 |
|
id |
String |
作成されたバッチタスクの ID。 |
|
object |
String |
オブジェクト型、静的フィールド |
|
endpoint |
String |
アクセスパス。 |
|
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 |
タスクがタイムアウトを開始したときのタイムスタンプ (秒)。 |
|
finalizing_at |
Integer |
タスクが最後に開始されたときのタイムスタンプ (秒)。 |
|
completed_at |
Integer |
タスクが完了したときのタイムスタンプ (秒)。 |
|
failed_at |
Integer |
タスクが失敗したときのタイムスタンプ (秒)。 |
|
expired_at |
Integer |
タスクが期限切れになったときのタイムスタンプ (秒)。 |
|
cancelling_at |
Integer |
タスクがキャンセル中に設定されたときのタイムスタンプ (秒)。 |
|
cancelled_at |
Integer |
タスクがキャンセルされたときのタイムスタンプ (秒)。 |
|
request_counts |
Map |
異なるステータスのリクエスト数。 |
|
metadata |
Map |
追加情報、キーと値のペア。 |
|
metadata.ds_name |
String |
現在のタスクの名前。 |
|
metadata.ds_description |
String |
現在のタスクの説明。 |
3. バッチタスクのクエリと管理
タスクを作成した後、以下のインターフェイスを使用して、そのステータスのクエリ、履歴タスクのリスト表示、または進行中のタスクのキャンセルができます。
特定のタスクステータスのクエリ
バッチタスク ID を提供することで、特定のバッチタスクの情報をクエリします。過去 30 日以内に作成されたバッチタスクのみクエリできます。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.retrieve("batch_id") # batch_id をバッチタスク ID に置き換えてください。
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - 単一タスクのクエリ
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
const batch = await client.batches.retrieve('batch_id');
console.log(batch.status);
Java (HTTP)
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - 単一タスクのクエリ
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPIRetrieveBatch {
// シンガポールリージョンの設定
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
String batchInfo = sendRequest("GET", "/batches/batch_id", null);
String status = parseField(batchInfo, "\"status\":\\s*\"([^\"]+)\"");
System.out.println("タスクステータス: " + status);
}
// === ユーティリティメソッド ===
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_id に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl --request GET 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/batches/batch_id' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
レスポンス例
クエリが成功すると、詳細なバッチタスク情報が返されます。以下は、完了したタスクのレスポンス例です:
{
"id": "batch_abc123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-abc123",
"completion_window": "24h",
"status": "completed",
"output_file_id": "file-batch_output-xyz789",
"error_file_id": "file-batch_error-xyz789",
"created_at": 1711402400,
"in_progress_at": 1711402450,
"expires_at": 1711488800,
"finalizing_at": 1711405000,
"completed_at": 1711406000,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 100,
"completed": 95,
"failed": 5
},
"metadata": {
"customer_id": "user_123456789",
"batch_description": "夜間評価ジョブ"
}
}
返された JSON オブジェクトには、タスクステータス、結果ファイル ID、リクエスト統計など、完全なバッチタスク情報が含まれています。詳細なフィールドの説明については、以下の表をご参照ください。
|
フィールド |
タイプ |
説明 |
|
id |
String |
バッチタスク ID。 |
|
status |
String |
タスクステータス。可能な値は以下の通りです:
|
|
output_file_id |
String |
タスク完了後に生成される、成功した結果ファイルの ID。 |
|
error_file_id |
String |
失敗したリクエストがある場合にタスク完了後に生成される、失敗した結果ファイルの ID。 |
|
request_counts |
Object |
合計、完了、失敗のカウントを含む統計オブジェクト。 |
タスクリストのクエリ
batches.list() メソッドを使用して、Batch ジョブのリストを取得できます。完全なリストを増分で取得するには、ページング機構を使用します。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batches = client.batches.list(after="batch_xxx", limit=2,extra_query={'ds_name':'タスク名','input_file_ids':'file-batch-xxx,file-batch-xxx','status':'completed,expired','create_after':'20250304000000','create_before':'20250306123000'})
print(batches)
OpenAI Node.js SDK
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - タスクリストのクエリ
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
const batches = await client.batches.list({
after: 'batch_xxx',
limit: 2,
extra_query: {
'ds_name': 'タスク名',
'input_file_ids': 'file-batch-xxx,file-batch-xxx',
'status': 'completed,expired',
'create_after': '20250304000000',
'create_before': '20250306123000'
}
});
for (const batch of batches.data) {
console.log(batch.id, batch.status);
}
Java (HTTP)
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - タスクリストのクエリ
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPIListBatches {
// シンガポールリージョンの設定
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
String response = sendRequest("GET", "/batches?after=batch_xxx&limit=2&ds_name=Batch&input_file_ids=file-batch-xxx,file-batch-xxx&status=completed,failed&create_after=20250303000000&create_before=20250320000000", null);
// JSON を解析してタスクリストを取得
System.out.println(response);
}
// === ユーティリティメソッド ===
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンのベース URL です。北京リージョンのモデルを使用する場合は、ベース URL を https://dashscope.aliyuncs.com/compatible-mode/v1/batches?xxx同下方内容xxx に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl --request GET 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/batches?after=batch_xxx&limit=2&ds_name=Batch&input_file_ids=file-batch-xxx,file-batch-xxx&status=completed,failed&create_after=20250303000000&create_before=20250320000000' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
batch_idをafter=batch_id内で実際の値に置き換え、limitパラメーターを返されるタスク数に設定し、ds_nameをタスク名のフラグメントとして指定します。input_file_ids の値には複数のファイル ID を指定できます。statusをバッチタスクの複数のステータスとして指定し、create_afterとcreate_beforeの値を時点として指定します。
入力パラメーター
|
フィールド |
タイプ |
パラメーター渡し方法 |
必須 |
説明 |
|
after |
String |
Query |
いいえ |
前のページの最後のジョブの ID を値とするページネーションカーソル。 |
|
limit |
Integer |
Query |
いいえ |
ページごとに返されるタスクの数。範囲は 1 から 100 です。デフォルトは 20 です。 |
|
ds_name |
String |
Query |
いいえ |
タスク名によるあいまい一致。 |
|
input_file_ids |
String |
Query |
いいえ |
ファイル ID でフィルターします。複数の ID はコンマで区切り、最大 20 個まで指定できます。 |
|
status |
String |
Query |
いいえ |
タスクステータスでフィルタリングします。複数のステータスはカンマで区切ります。 |
|
create_after |
String |
Query |
いいえ |
この時刻以降に作成されたタスクをフィルターします。形式: |
|
create_before |
String |
Query |
いいえ |
指定した時間より前に作成されたタスクをフィルターします。 形式: |
レスポンス例
{
"object": "list",
"data": [
{
"id": "batch_xxx",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-xxx",
"completion_window": "24h",
"status": "completed",
"output_file_id": "file-batch_output-xxx",
"error_file_id": null,
"created_at": 1722234109,
"in_progress_at": 1722234109,
"expires_at": null,
"finalizing_at": 1722234165,
"completed_at": 1722234165,
"failed_at": null,
"expired_at": null,
"cancelling_at": null,
"cancelled_at": null,
"request_counts": {
"total": 100,
"completed": 95,
"failed": 5
},
"metadata": {}
},
{ ... }
],
"first_id": "batch_xxx",
"last_id": "batch_xxx",
"has_more": true
}
レスポンスパラメーター
|
フィールド |
タイプ |
説明 |
|
object |
String |
タイプ、静的フィールドリスト。 |
|
data |
Array |
バッチタスクオブジェクト。バッチタスク作成のレスポンスパラメーターをご参照ください。 |
|
first_id |
String |
現在のページの最初のバッチタスクの ID。 |
|
last_id |
String |
現在のページの最後のバッチタスクの ID。 |
|
has_more |
Boolean |
さらにページがあるかどうかを示します。 |
バッチタスクのキャンセル
進行中またはキュー内のタスクをキャンセルできます。呼び出しが成功すると、タスクのステータスは `cancelling` に変わり、最終的に `cancelled` になります。タスクが完全にキャンセルされるまで完了した部分については、引き続き課金されます。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.cancel("batch_id") # batch_id をバッチタスク ID に置き換えてください。
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - タスクのキャンセル
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
const batch = await client.batches.cancel('batch_id');
console.log(batch.status); // cancelled
Java (HTTP)
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - タスクのキャンセル
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPICancelBatch {
// シンガポールリージョンの設定
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
String response = sendRequest("POST", "/batches/batch_id/cancel", null);
System.out.println(response);
}
// === ユーティリティメソッド ===
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_id/cancel に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl --request POST 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/batches/batch_id/cancel' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
batch_id を実際の値に置き換えます。
レスポンス例
タスクのキャンセルが成功すると、詳細なバッチタスク情報が返されます。以下は、キャンセル中のタスクのレスポンス例です:
{
"id": "batch_abc123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-abc123",
"completion_window": "24h",
"status": "cancelling",
"output_file_id": null,
"error_file_id": null,
"created_at": 1711402400,
"in_progress_at": 1711402450,
"expires_at": 1711488800,
"finalizing_at": null,
"completed_at": null,
"failed_at": null,
"expired_at": null,
"cancelling_at": 1711403000,
"cancelled_at": null,
"request_counts": {
"total": 100,
"completed": 23,
"failed": 1
},
"metadata": null
}
タスクをキャンセルすると、ステータスはまずcancellingに変更され、進行中のリクエストが完了するのを待ちます。最終的にcancelledになります。完了したリクエストの結果は、引き続き出力ファイルに保存されます。
4. バッチ結果ファイルのダウンロード
タスクが終了すると、結果ファイル (`output_file_id`) と、潜在的なエラーファイル (`error_file_id`) が生成されます。両方のファイルは、同じファイルダウンロードインターフェイスを使用して取得されます。
file_id が file-batch_output で始まるファイルのみダウンロードできます。
OpenAI Python SDK
content メソッドを使用して、Batch タスクの結果ファイルの内容を取得します。write_to_file メソッドを使用して、ローカルに保存します。
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を Alibaba Cloud Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1 に置き換えてください。
# 注意:リージョンを切り替える際は、API キーも適宜更新してください。
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
content = client.files.content(file_id="file-batch_output-xxx")
# 結果ファイルの内容を印刷
print(content.text)
# 結果ファイルをローカルに保存
content.write_to_file("result.jsonl")
レスポンス例
{"id":"c308ef7f-xxx","custom_id":"1","response":{"status_code":200,"request_id":"c308ef7f-0824-9c46-96eb-73566f062426","body":{"created":1742303743,"usage":{"completion_tokens":35,"prompt_tokens":26,"total_tokens":61},"model":"qwen-plus","id":"chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426","choices":[{"finish_reason":"stop","index":0,"message":{"content":"こんにちは!もちろん。情報の照会、学習資料、問題解決の方法、またはその他のサポートが必要な場合でも、私はあなたを支援するためにここにいます。どのようなお手伝いが必要ですか?"}}],"object":"chat.completion"}},"error":null}
{"id":"73291560-xxx","custom_id":"2","response":{"status_code":200,"request_id":"73291560-7616-97bf-87f2-7d747bbe84fd","body":{"created":1742303743,"usage":{"completion_tokens":7,"prompt_tokens":26,"total_tokens":33},"model":"qwen-plus","id":"chatcmpl-73291560-7616-97bf-87f2-7d747bbe84fd","choices":[{"finish_reason":"stop","index":0,"message":{"content":"2+2 は 4 です。"}}],"object":"chat.completion"}},"error":null}
OpenAI Node.js SDK
content メソッドを使用して、バッチタスクの結果ファイルの内容を取得します。
リクエスト例
/**
* Alibaba Cloud Model Studio バッチ API - 結果ファイルのダウンロード
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:apiKey: 'sk-xxx'
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* 依存関係のインストール:npm install openai
*/
const OpenAI = require('openai');
const fs = require('fs');
// シンガポールリージョンの設定 (デフォルト)
const BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// const BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
const apiKey = process.env.DASHSCOPE_API_KEY;
if (!apiKey) {
console.error('エラー:DASHSCOPE_API_KEY 環境変数を設定してください。');
console.error('またはコード内で設定してください:const apiKey = "sk-xxx";');
process.exit(1);
}
const client = new OpenAI({
apiKey: apiKey,
baseURL: BASE_URL
});
// 結果ファイルをダウンロード
const content = await client.files.content('file-batch_output-xxx');
const text = await content.text();
console.log(text);
// ローカルファイルに保存
fs.writeFileSync('result.jsonl', text);
console.log('結果が result.jsonl に保存されました');
Java (HTTP)
/files/{file_id}/content エンドポイントに GET リクエストを送信して、ファイルの内容を取得します。
リクエスト例
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Scanner;
import java.util.regex.Pattern;
import java.util.regex.Matcher;
/**
* Alibaba Cloud Model Studio バッチ API - 結果ファイルのダウンロード
*
* 環境変数が設定されていない場合は、API キーをハードコーディングできます:API_KEY = "sk-xxx"
* ただし、API キーの漏洩リスクを減らすため、本番環境では API キーを直接ハードコーディングしないでください。
* API キーはシンガポールリージョンと北京リージョンで異なります。
*
* リージョン設定:
* - 北京リージョン:https://dashscope.aliyuncs.com/compatible-mode/v1
* - シンガポールリージョン:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:リージョンを切り替える際は、API キーも適宜更新してください。
*/
public class BatchAPIDownloadFile {
// シンガポールリージョンの設定
private static final String BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
// 北京リージョンを使用する場合は、上記の BASE_URL を次のように置き換えてください:
// private static final String BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
// 注意:リージョンを切り替える際は、API キーも適宜更新してください。
private static String API_KEY;
public static void main(String[] args) throws Exception {
API_KEY = System.getenv("DASHSCOPE_API_KEY");
if (API_KEY == null || API_KEY.isEmpty()) {
System.err.println("エラー:DASHSCOPE_API_KEY 環境変数を設定してください。");
System.err.println("またはコード内で設定してください:API_KEY = \"sk-xxx\";");
System.exit(1);
}
// 結果ファイルをダウンロード
String content = sendRequest("GET", "/files/file-batch_output-xxx/content", null);
System.out.println(content);
// ローカルファイルに保存
Files.write(Paths.get("result.jsonl"), content.getBytes());
System.out.println("結果が result.jsonl に保存されました");
}
// === ユーティリティメソッド ===
private static String sendRequest(String method, String path, String jsonBody) throws Exception {
URL url = new URL(BASE_URL + path);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
if (jsonBody != null) {
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json");
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes("UTF-8"));
}
}
return readResponse(conn);
}
private static String readResponse(HttpURLConnection conn) throws Exception {
int responseCode = conn.getResponseCode();
InputStream is = (responseCode < 400) ? conn.getInputStream() : conn.getErrorStream();
try (Scanner scanner = new Scanner(is, "UTF-8").useDelimiter("\\A")) {
return scanner.hasNext() ? scanner.next() : "";
}
}
private static String parseField(String json, String regex) {
Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(json);
return matcher.find() ? matcher.group(1) : null;
}
}
curl (HTTP)
GET リクエストを使用して、URL で file_id を指定してバッチタスク結果ファイルをダウンロードします。
リクエスト例
# ======= 重要事項 =======
# API キーはシンガポールリージョンと北京リージョンで異なります。
# 以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch_output-xxx/content に置き換えてください。
# === 実行前にこのコメントを削除してください ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch_output-xxx/content \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" > result.jsonl
レスポンス例
単一のレスポンス結果:
{
"id": "c308ef7f-xxx",
"custom_id": "1",
"response": {
"status_code": 200,
"request_id": "c308ef7f-0824-9c46-96eb-73566f062426",
"body": {
"created": 1742303743,
"usage": {
"completion_tokens": 35,
"prompt_tokens": 26,
"total_tokens": 61
},
"model": "qwen-plus",
"id": "chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"content": "こんにちは!もちろん。情報の照会、学習資料、問題解決の方法、またはその他のサポートが必要な場合でも、私はあなたを支援するためにここにいます。どのようなお手伝いが必要ですか?"
}
}
],
"object": "chat.completion"
}
},
"error": null
}
レスポンスパラメーター
|
フィールド |
タイプ |
説明 |
|
id |
String |
リクエスト ID。 |
|
custom_id |
String |
ユーザー定義 ID。 |
|
response |
Object |
リクエスト結果。 |
|
status_code |
Integer |
ステータスコード。200 は成功したリクエストを示します。 |
|
request_id |
String |
このリクエストに対してサーバーが生成した一意の ID。 |
|
completion_tokens |
Integer |
モデルが生成した応答 (completion) で消費されたトークン数。 |
|
prompt_tokens |
Integer |
モデルに送信された入力コンテンツ ( |
|
total_tokens |
Integer |
この呼び出しで消費されたトークンの総数。 |
|
model |
String |
この呼び出しで使用されたモデルの名前。 |
|
error |
Object |
エラーメッセージオブジェクト。API 呼び出しが成功した場合、この値は |
|
error.code |
String |
エラー行情報およびエラー原因。トラブルシューティングについては、「エラーコード」をご参照ください。 |
|
error.message |
String |
エラーメッセージ。 |
高度な機能
タスク完了通知の構成
長時間実行されるジョブの場合、ポーリングはリソースを大量に消費します。非同期通知を使用することを推奨します。非同期通知では、ジョブが完了するとシステムが自動的に通知します。
-
コールバック:ジョブを作成する際に、パブリックにアクセス可能な URL を指定します。
-
EventBridge メッセージキュー:この方法は Alibaba Cloud エコシステムと統合されており、パブリック IP アドレスを必要としません。
方法 1:コールバック
ジョブを作成する際は、metadata パラメーターに公開可能な URL を設定します。ジョブが完了すると、システムはその URL に POST リクエストを送信します。このリクエストにはジョブのステータスが含まれます:
OpenAI Python SDK
import os
from openai import OpenAI
client = OpenAI(
# 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えてください。ただし、本番コードに API キーをハードコーディングすると、漏洩リスクが高まります。
# API キーはシンガポールリージョンと北京リージョンで異なります。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 北京リージョンのベース URL。シンガポールリージョンのモデルを使用する場合は、https://dashscope-intl.aliyuncs.com/compatible-mode/v1 を使用します。
# 注意:リージョンを切り替える際は、API キーも変更してください。
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.create(
input_file_id="file-batch-xxx", # ファイルアップロード後に返された ID
endpoint="/v1/chat/completions", # テキスト埋め込みモデルの場合は "/v1/embeddings" を使用します。テストモデル (batch-test-model) の場合は "/v1/chat/ds-test" を使用します。その他のモデルの場合は "/v1/chat/completions" を使用します。
completion_window="24h",
metadata={
"ds_batch_finish_callback": "https://xxx/xxx"
}
)
print(batch)
curl (HTTP)
リクエスト例
curl -X POST --location "https://dashscope.aliyuncs.com/compatible-mode/v1/batches" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-batch-xxxxx",
"endpoint": "/v1/chat/completions",
"completion_window": "24h",
"metadata": {
"ds_batch_finish_callback": "https://xxx/xxx"
}
}'
方法 2:EventBridge メッセージキュー
この方法では、パブリック IP アドレスは不要です。Function Compute や RocketMQ など、他の Alibaba Cloud サービスとの統合が必要な複雑なシナリオに最適です。
バッチジョブが完了すると、システムが Alibaba Cloud EventBridge にイベントを送信します。EventBridge ルールを構成して、このイベントをリッスンし、ターゲットにルーティングできます。
-
イベントソース (Source):
acs.dashscope -
イベントタイプ (Type):
dashscope:System:BatchTaskFinish
詳細については、「Apache RocketMQ 用メッセージキューへのイベントのルーティング」をご参照ください。
本番稼働
-
ファイル管理
-
OpenAI ファイル削除 API を定期的に呼び出して、不要なファイルを削除し、ファイルストレージ制限 (10,000 ファイルまたは 100 GB) に達しないようにしてください。
-
大規模なファイルの場合は、Alibaba Cloud OSS に格納してください。
-
-
タスク監視
-
ポーリングよりも、コールバックまたは EventBridge 非同期通知メッセージを優先してください。
-
ポーリング間隔を 1 分以上に設定し、指数バックオフポリシーを適用してください。
-
-
エラー処理
-
ネットワークエラー、API エラー、その他の例外をカバーする包括的な例外処理メカニズムを実装してください。
-
error_file_idに関連付けられているエラー詳細をダウンロードし、分析してください。 -
一般的なエラーコードの解決策については、「エラーメッセージ」をご参照ください。
-
-
コスト最適化
-
小規模なタスクを 1 つのバッチに結合してください。
-
completion_windowパラメーターを設定して、スケジューリングの柔軟性を高めます。
-
ユーティリティ
CSV から JSONL への変換
元のデータが CSV ファイルに格納されている場合(1 列目に ID、2 列目にコンテンツが含まれる)は、以下のスクリプトを使用して、バッチタスクに必要な JSONL ファイルを生成できます。
ファイルパスやその他のパラメーターを調整するには、コードを必要に応じて修正してください。
import csv
import json
def messages_builder_example(content):
messages = [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": content}]
return messages
with open("input_demo.csv", "r") as fin:
with open("input_demo.jsonl", 'w', encoding='utf-8') as fout:
csvreader = csv.reader(fin)
for row in csvreader:
body = {"model": "qwen-turbo", "messages": messages_builder_example(row[1])}
# テキスト埋め込みモデルを呼び出す場合、URL の値は "/v1/embeddings" である必要があります。その他のモデルの場合は /v1/chat/completions を使用します。
request = {"custom_id": row[0], "method": "POST", "url": "/v1/chat/completions", "body": body}
fout.write(json.dumps(request, separators=(',', ':'), ensure_ascii=False) + "\n")
JSONL 結果から CSV への変換
以下のスクリプトを使用して、result.jsonl ファイルを Excel で扱いやすい result.csv ファイルに解析します。
ファイルパスやその他のパラメーターを調整するには、コードを必要に応じて修正してください。
import json
import csv
columns = ["custom_id",
"model",
"request_id",
"status_code",
"error_code",
"error_message",
"created",
"content",
"usage"]
def dict_get_string(dict_obj, path):
obj = dict_obj
try:
for element in path:
obj = obj[element]
return obj
except:
return None
with open("result.jsonl", "r") as fin:
with open("result.csv", 'w', encoding='utf-8') as fout:
rows = [columns]
for line in fin:
request_result = json.loads(line)
row = [dict_get_string(request_result, ["custom_id"]),
dict_get_string(request_result, ["response", "body", "model"]),
dict_get_string(request_result, ["response", "request_id"]),
dict_get_string(request_result, ["response", "status_code"]),
dict_get_string(request_result, ["error", "error_code"]),
dict_get_string(request_result, ["error", "error_message"]),
dict_get_string(request_result, ["response", "body", "created"]),
dict_get_string(request_result, ["response", "body", "choices", 0, "message", "content"]),
dict_get_string(request_result, ["response", "body", "usage"])]
rows.append(row)
writer = csv.writer(fout)
writer.writerows(rows)
Excel の文字化け対策
-
Sublime Text などのテキストエディターを使用して、CSV ファイルのエンコーディングを GBK に変換し、その後 Excel で開きます。
-
または、新しい Excel ファイルを作成し、データをインポートする際に UTF-8 エンコーディングを指定します。
インターフェイスのレート制限
|
インターフェイス |
レート制限 (Alibaba Cloud アカウントレベル) |
|
タスクの作成 |
1000 リクエスト/分、最大同時タスク数 1000 |
|
タスクのクエリ |
1000 リクエスト/分 |
|
タスクリストのクエリ |
100 リクエスト/分 |
|
タスクのキャンセル |
1000 リクエスト/分 |
請求情報
単価:すべての成功したリクエストの入力および出力トークンは、対応するモデルのリアルタイム推論価格の 50% で課金されます。詳細については、「モデル一覧」をご参照ください。
課金範囲:
ジョブ内で正常に実行されたリクエストのみが課金対象となります。
ファイル解析エラー、ジョブ実行失敗、または行レベルのエラーによって失敗したリクエストは課金されません。
キャンセルされたジョブについては、キャンセル前に正常に完了したリクエストは通常通り課金されます。
バッチ推論は、独立した課金項目です。割引対象外であり、以下のような割引は適用されません:サブスクリプション(セービングズプラン)または、新規ユーザー向けの無料クォータ。また、以下のような機能もサポートしていません:コンテキストキャッシュ。
一部のモデル (例:qwen3.5-plus、qwen3.5-flash) では、思考モードがデフォルトで有効になっています。このモードでは追加の思考トークンが生成され、出力トークン価格で課金され、コストが増加します。コストを制御するには、タスクの複雑さに応じて `enable_thinking` パラメーターを設定してください。詳細については、「深層思考」をご参照ください。
エラーコード
呼び出しが失敗してエラーメッセージが返された場合、問題を解決するには「エラーメッセージ」をご参照ください。
よくある質問
-
バッチチャットとバッチファイルのどちらを使用すべきですか?
多数のリクエストを含む単一の大きなファイルを非同期で結果ファイルを取得できる場合に、バッチファイルを使用します。アプリケーションのロジックで多数の個別の会話リクエストを同時に同期 API 呼び出しで送信する必要がある場合に、バッチチャットを使用します。
-
バッチファイル呼び出しの課金方法は?別途プランを購入する必要がありますか?
バッチは従量課金方式の呼び出し方法です。ジョブ内の成功したリクエストのトークン使用量に基づいて課金されます。別途プランの購入は不要です。
-
提出されたバッチファイルジョブは、提出順に実行されますか?
いいえ。バックエンドでは動的スケジューリングメカニズムが使用されています。システムは現在の計算リソースの全体負荷に基づいてジョブの実行をスケジューリングするため、実行順序は保証されません。リソースが不足している場合、ジョブの開始および実行が遅延することがあります。
-
提出されたバッチファイルジョブの完了までにどのくらい時間がかかりますか?
実行時間は、システムのリソース割り当てとジョブのサイズによって異なります。ジョブが設定した `completion_window` 内に完了しなかった場合、ステータスは期限切れになります。この時点で未処理のリクエストは実行されず、課金もされません。
推奨事項:モデル推論に厳密なリアルタイム要件があるシナリオでは、リアルタイム呼び出しを使用してください。大規模なデータ処理を行い、ある程度の遅延を許容できるシナリオでは、バッチ呼び出しを使用してください。