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 (北京):
サポート範囲
シンガポール
サポート対象モデル:
-
テキスト生成モデル
- Qwen Max:qwen3.8-max、qwen-max
- Qwen Plus:qwen3.7-plus、qwen-plus
- Qwen Flash:qwen-flash
-
マルチモーダルモデル
- 画像・動画理解:qwen3.8-max、qwen3.7-plus
中国 (北京)
サポート対象モデル:
-
テキスト生成モデル
- Qwen Max:qwen4-max、qwen3.8-max、qwen3.7-max、qwen-max、qwen-max-latest
- Qwen Plus:qwen3.7-plus、qwen3.6-plus、qwen3.5-plus、qwen-plus、qwen-plus-latest
- Qwen Flash:qwen3.8-flash、qwen3.7-flash、qwen3.6-flash、qwen3.5-flash、qwen-flash
- マルチモーダルモデル
-
テキスト埋め込みモデル:text-embedding-v4
重要
- バッチシナリオでは、
qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen3.5-omni-flash、およびqwen3.5-omni-plusは、リクエストあたり最大 256K のコンテキストトークンをサポートします。qwen3.5-omni-plusとqwen3.5-omni-flashは音声出力をサポートしていません。 - 一部のモデルは思考モードをサポートしています。有効にすると、思考
tokensが生成され、コストが増加します。 qwen3.8、qwen3.7、qwen3.6、およびqwen3.5シリーズのモデルでは、思考モードがデフォルトで有効になっています。ハイブリッド思考モデルを使用する場合は、enable_thinkingパラメーターを明示的に設定することをお勧めします (trueで有効 /falseで無効)。- JSONL リクエストボディでは、
enable_thinkingはbodyのトップレベルパラメーターであり、modelと同じレベルで渡す必要があります。extra_bodyに配置することはできません。
はじめに
本番タスクを処理する前に、テストモデル 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":"你好!有什么可以帮助你的吗?"}]}}
{"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?"}]}}
Base64 エンコードによる入力:
ステップ 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 をクエリできます。
サンプルコード
import os
from pathlib import Path
from openai import OpenAI
import time
# 初始化客户端
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域的base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1" # 阿里云百炼服务的base_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,创建Batch任务...")
# 请注意:此处endpoint参数值需和输入文件中的url字段保持一致.测试模型(batch-test-model)填写/v1/chat/ds-test,Embedding文本向量模型填写/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"Batch任务创建完成。 得到Batch任务ID: {batch.id}\n")
return batch.id
def check_job_status(batch_id):
print(f"正在检查Batch任务状态...")
batch = client.batches.retrieve(batch_id=batch_id)
print(f"Batch任务状态: {batch.status}\n")
return batch.status
def get_output_id(batch_id):
print(f"正在获取Batch任务中执行成功请求的输出文件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"正在获取Batch任务中执行错误请求的输出文件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"正在打印并下载Batch任务的请求成功结果...")
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"正在打印并下载Batch任务的请求失败信息...")
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:
# Step 1: 上传包含请求信息的JSONL文件,得到输入文件ID
input_file_id = upload_file(input_file_path)
# Step 2: 基于输入文件ID,创建Batch任务
batch_id = create_batch_job(input_file_id)
# Step 3: 检查Batch任务状态直到结束
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任务失败。错误信息为:{batch.errors}\n")
print(f"参见错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
return
# Step 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/model-studio/developer-reference/error-code")
except Exception as e:
print(f"An error occurred: {e}")
print(f"参见错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
if __name__ == "__main__":
main()
/**
* 阿里云百炼 Batch API 测试 - 使用 OpenAI Node.js SDK
*
* 安装依赖:npm install openai
* 运行:node test-nodejs.js
*/
const OpenAI = require('openai');
const fs = require('fs');
// 新加坡地域的 Base 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('=== 开始 Batch API 测试 ===\n');
// Step 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`);
// Step 2: 创建 Batch 任务
console.log('步骤 2: 创建 Batch 任务...');
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(`✓ Batch 任务创建成功,任务ID: ${batchId}\n`);
// Step 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`);
// Step 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✗ Batch 任务失败');
if (latestBatch.errors) {
console.error('错误信息:', latestBatch.errors);
}
console.error('\n请参考错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code');
} else {
console.log(`\n任务状态: ${status}`);
}
} catch (error) {
console.error('发生错误:', error.message);
console.error(error);
}
}
main();
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;
/**
* 阿里云百炼 Batch 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 {
// 新加坡地域的 Base 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 Key
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("=== 开始 Batch API 测试 ===\n");
try {
// Step 1: 上传文件
System.out.println("步骤 1: 上传包含请求信息的 JSONL 文件...");
String fileId = uploadFile("test_model.jsonl");
System.out.println("✓ 文件上传成功,文件ID: " + fileId + "\n");
// Step 2: 创建 Batch 任务
System.out.println("步骤 2: 创建 Batch 任务...");
String batchId = createBatch(fileId);
System.out.println("✓ Batch 任务创建成功,任务ID: " + batchId + "\n");
// Step 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);
// Step 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✗ Batch 任务失败");
System.err.println("任务信息: " + batchInfo);
System.err.println("\n请参考错误码文档: https://www.alibabacloud.com/help/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*\"([^\"]+)\"");
}
/**
* 创建 Batch 任务
*/
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*\"([^\"]+)\"");
}
/**
* 获取 Batch 任务信息
*/
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);
}
}
#!/bin/bash
# 阿里云百炼 Batch 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 Key
if [ -z "$API_KEY" ]; then
echo "错误: 请设置环境变量 DASHSCOPE_API_KEY"
exit 1
fi
echo "=== 开始 Batch API 测试 ==="
echo ""
# Step 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 ""
# Step 2: 创建 Batch 任务
echo "步骤 2: 创建 Batch 任务..."
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 "✓ Batch 任务创建成功,任务ID: ${BATCH_ID}"
echo ""
# Step 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 ""
# Step 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 "✗ Batch 任务失败"
echo "任务信息: ${BATCH_INFO}"
echo ""
echo "请参考错误码文档: https://www.alibabacloud.com/help/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}
正式なタスクの実行
入力ファイルの要件
- フォーマット:UTF-8 エンコードの JSONL (1行に1つの独立した JSON オブジェクト)。
- サイズ制限:ファイルあたり最大 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?"}]}}
シナリオ 2:画像・動画理解
Base64 エンコードによる入力方法。
上記の例の Base64 文字列は省略されています。完全なエンコーディングを生成するには、以下の Python コードを使用してください。
Base64 エンコードされた文字列を渡す (画像を例として)
- ローカルファイルを Base64 エンコーディングに変換します:
# 编码函数: 将本地文件转换为 Base64 编码的字符串
import base64
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
# 将xxxx/eagle.png替换为你本地图像的绝对路径
base64_image = encode_image("xxx/eagle.png")
-
Data URL フォーマットを構築します:
data:[MIME_type];base64,{base64_image};MIME_typeを実際のメディアタイプに置き換えます。これはMIME Typeの値 (例:image/jpeg、image/png) と一致する必要があります。base64_imageは、前のステップで生成された Base64 文字列です。
注記詳細 (ファイル制限、MIME タイプ、エンコーディング方式など) については、「ローカルファイルを渡す (Base64 エンコーディングまたはファイルパス)」をご参照ください。
バッチ推論では JSONL ファイルを構築する必要があり、各行が独立したリクエストとなります。以下の Python スクリプトは、そのまま実行して、形式要件に準拠した JSONL ファイルを生成できます。
使用方法
- 以下のコードを
generate_batch_jsonl.pyとして保存します - スクリプト内の
TASKSリストのリクエスト内容を変更します python generate_batch_jsonl.pyを実行します- 生成された
batch_input.jsonlファイルは、そのままバッチ推論タスクに使用できます
テキスト生成モデル用の JSONL 生成スクリプト
#!/usr/bin/env python3
"""
Batch 推理 JSONL 文件生成工具
支持的地域与模型请参见上方“适用范围”。
文件大小限制:单行 ≤6MB,总文件 ≤500MB,建议 ≤10000 行
使用方式:
1. 修改下方 TASKS 列表
2. 运行: python generate_batch_jsonl.py
3. 输出: batch_input.jsonl
"""
import json
# ═══════════════════════════════════════════════════════
# 配置区:修改以下内容来生成您需要的 JSONL
# ═══════════════════════════════════════════════════════
MODEL = "qwen-max" # 选择模型(参见上方“适用范围”)
ENABLE_THINKING = False # 是否开启思考模式(仅部分模型支持)
THINKING_BUDGET = 50 # 思考 token 预算(思考模式下生效)
# 任务列表:每个 dict 代表一条用户消息
TASKS = [
{"role": "user", "content": "你好!请介绍一下自己。"},
{"role": "user", "content": "What is 2+2?"},
{"role": "user", "content": "请用Python写一个快速排序算法"},
]
# ═══════════════════════════════════════════════════════
# 以下为生成逻辑,一般无需修改
# ═══════════════════════════════════════════════════════
def build_request(custom_id: str, model: str, messages: list,
enable_thinking: bool = False, thinking_budget: int = 50) -> dict:
"""构造单条 Batch 请求"""
body = {"model": model, "messages": messages}
if enable_thinking:
body["enable_thinking"] = True
body["thinking_budget"] = thinking_budget
body["stream"] = True # 思考模式需开启 stream
return {
"custom_id": custom_id,
"method": "POST",
"url": "/v1/chat/completions",
"body": body
}
def main():
output_file = "batch_input.jsonl"
with open(output_file, "w", encoding="utf-8") as f:
for i, task in enumerate(TASKS, 1):
messages = [
{"role": "system", "content": "You are a helpful assistant."},
task
]
req = build_request(
custom_id=f"request-{i}",
model=MODEL,
messages=messages,
enable_thinking=ENABLE_THINKING,
thinking_budget=THINKING_BUDGET
)
f.write(json.dumps(req, ensure_ascii=False) + "\n")
print(f"已生成 {output_file},共 {len(TASKS)} 条请求")
if __name__ == "__main__":
main()
マルチモーダルモデルのリクエスト形式
マルチモーダルモデルでは、content フィールドは配列形式で、メディアオブジェクトとテキストプロンプトが含まれます。各リクエスト行のメディア URL は同じタイプ (画像、動画、または音声) である必要があります。上記のスクリプトの TASKS を以下の形式に置き換えてください:
# 多模态模型配置示例
# 多模态任务:content 为数组格式
TASKS = [
{"role": "user", "content": [
{"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
{"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
{"type": "text", "text": "这些图描绘了什么内容?"}
]},
]
# {"type": "input_audio", "input_audio": {"data": "https://example.com/audio.wav", "format": "wav"}}
# {"type": "video_url", "video_url": "https://example.com/video.mp4"}
# 注意:
# - 其他多模态模型包含 system 角色,thinking_budget 设置为 50
# - 思考模式需额外设置 ENABLE_THINKING = True
テキスト埋め込みモデルのリクエスト形式
テキスト埋め込みモデルは /v1/embeddings API を使用し、そのリクエスト形式はテキスト生成モデルのものとは異なります。以下のスタンドアロンスクリプトを使用して生成できます:
#!/usr/bin/env python3
"""文本向量模型 Batch JSONL 生成(使用 /v1/embeddings 接口)"""
import json
MODEL = "text-embedding-v3" # 向量模型,可选型号参见上方“适用范围”
TEXTS = [
"衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买。",
"风急天高猿啸哀",
"The quick brown fox jumps over the lazy dog",
]
output_file = "batch_embedding.jsonl"
with open(output_file, "w", encoding="utf-8") as f:
for i, text in enumerate(TEXTS, 1):
req = {
"custom_id": f"emb-{i}",
"method": "POST",
"url": "/v1/embeddings",
"body": {"model": MODEL, "input": text, "encoding_format": "float"}
}
f.write(json.dumps(req, ensure_ascii=False) + "\n")
print(f"已生成 {output_file},共 {len(TEXTS)} 条请求")
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### 一、自然景观\n西湖三面环山,一面邻城,湖面面积约6.39平方公里,形似如意,碧波荡漾。湖中被孤山、白堤、苏堤、杨公堤等自然或人工分隔成多个水域,形成“一山二塔三岛三堤”的格局。\n\n主要景点包括:\n- **苏堤春晓**:北宋大文豪苏东坡任杭州知州时主持疏浚西湖,用挖出的淤泥堆筑成堤,后人称为“苏堤”。春天桃红柳绿,景色如画。\n- **断桥残雪**:位于白堤东端,是白蛇传中“断桥相会”的发生地,冬日雪后银装素裹,尤为著名。\n- **雷峰夕照**:雷峰塔在夕阳映照下金光熠熠,曾是“西湖十景”之一。\n- **三潭印月**:湖中小瀛洲上的三座石塔,中秋夜可在塔内点灯,月影、灯光、湖光交相辉映。\n- **平湖秋月**:位于白堤西端,是观赏湖上明月的绝佳地点。\n- **花港观鱼**:以赏花和观鱼著称,园内牡丹、锦鲤相映成趣。\n\n### 二、人文历史\n西湖不仅风景优美,还承载着丰富的历史文化:\n- 自唐宋以来,众多文人墨客如白居易、苏东坡、林逋、杨万里等在此留下诗篇。\n- 白居易曾主持修建“白堤”,疏浚西湖,造福百姓。\n- 西湖周边有众多古迹,如岳王庙(纪念民族英雄岳飞)、灵隐寺(千年古刹)、六和塔、龙井村(中国十大名茶龙井茶的产地)等。\n\n### 三、文化象征\n西湖被誉为“人间天堂”的代表,是中国传统山水美学的典范。它融合了自然美与人文美,体现了“天人合一”的哲学思想。许多诗词、绘画、戏曲都以西湖为题材,成为中国文化的重要符号。\n\n### 四、旅游建议\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. ファイルのアップロード
バッチタスクを作成する前に、形式要件を満たす JSONL ファイルをファイルアップロード API でアップロードし、file_id を取得します。
ファイルをアップロードする際、
purposeパラメーターはbatchである必要があります。
注記既存のファイル 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 をクエリできます。
OpenAI Python SDK
リクエスト例
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
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
リクエスト例
/**
* 阿里云百炼 Batch API - 上传文件
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 上传文件
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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 Key不同。
# 以下是新加坡地域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. バッチタスクの作成
ファイルのアップロード手順で取得したファイル ID を使用してバッチタスクを作成します。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
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':'任务描述'} # metadata数据,非必填字段,用于创建任务名称、描述
)
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* 阿里云百炼 Batch API - 创建Batch任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 创建Batch任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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("Batch任务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 Key不同。
# 以下是新加坡地域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 を指定します。 ファイルの準備とアップロード API によって返されるファイル ID (例: |
endpoint | String | Body | はい | API アクセスパス。入力ファイル内の url フィールドと一致する必要があります。
|
completion_window | String | Body | はい | 待機時間。最小 24h、最大 336h。整数のみサポートされています。 「h」と「d」の 2 つの単位をサポートしています (例:「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 | API アクセスパス。 |
errors | Map | エラー情報。 |
input_file_id | String | 入力ファイル ID 。 |
completion_window | String | 待機時間。最小 24h、最大 336h。整数のみサポートされています。 「h」と「d」の 2 つの単位をサポートしています (例:「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. バッチタスクのクエリと管理
タスクを作成した後、以下の API を使用してステータスのクエリ、過去のタスクのリスト表示、または進行中のタスクのキャンセルを行います。
特定のタスクステータスのクエリ
バッチタスク ID を渡して、指定したタスクの詳細をクエリします。現在、過去 30 日以内に作成されたバッチタスクのみクエリできます。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.retrieve("batch_id") # 将batch_id替换为Batch任务的id
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* 阿里云百炼 Batch API - 查询单个任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 查询单个任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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 Key不同。
# 以下是新加坡地域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"
レスポンス例
クエリが成功すると、詳細なバッチタスク情報が返されます。以下は、ステータスが completed のタスクのレスポンス例です:
{
"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": "Nightly eval job"
}
}
返された JSON オブジェクトには、タスクステータス、出力ファイル ID、リクエスト統計など、バッチタスクの完全な情報が含まれます。フィールドの説明については、以下の表をご参照ください。
フィールド | タイプ | 説明 |
|---|---|---|
id | String | バッチタスク ID。 |
status | String | タスクステータス。指定できる値:
|
output_file_id | String | 成功した結果を含む出力ファイルの ID。タスク完了後に生成されます。 |
error_file_id | String | 失敗したリクエストの詳細を含むエラーファイルの ID。リクエストが失敗した場合にタスク完了後に生成されます。 |
request_counts | Object | 合計、完了、失敗のカウントを含むリクエスト数の統計。 |
タスクリストのクエリ
batches.list() メソッドを使用してバッチタスクのリストをクエリし、ページネーションによって完全なタスクリストを漸進的に取得できます。
OpenAI Python SDK
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
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
リクエスト例
/**
* 阿里云百炼 Batch API - 查询任务列表
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 查询任务列表
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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 Key不同。
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_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 ページあたりのタスク数。範囲:[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": "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 | オブジェクトタイプ。固定値:list。 |
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(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.cancel("batch_id") # 将batch_id替换为Batch任务的id
print(batch)
OpenAI Node.js SDK
リクエスト例
/**
* 阿里云百炼 Batch API - 取消任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 取消任务
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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 Key不同。
# 以下是新加坡地域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を実際の値に置き換えます。
レスポンス例
タスクを正常にキャンセルすると、API は詳細なバッチタスク情報を返します。以下は、ステータスが cancelling のタスクのレスポンス例です:
{
"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) が生成されることがあります。両方のファイルタイプは、同じファイルダウンロード API を使用してダウンロードします。
file_id が file-batch_output で始まるファイルのみダウンロードできます。
OpenAI Python SDK
content メソッドを使用してバッチタスクの結果ファイルの内容を取得し、write_to_file メソッドを使用してローカルに保存します。
リクエスト例
import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
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 equals 4."}}],"object":"chat.completion"}},"error":null}
OpenAI Node.js SDK
content メソッドを使用して、バッチタスクの結果ファイルの内容を取得します。
リクエスト例
/**
* 阿里云百炼 Batch API - 下载结果文件
*
* 若没有配置环境变量,可在代码中硬编码API Key:apiKey: 'sk-xxx'
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 安装依赖: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 Key也需要对应更换
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;
/**
* 阿里云百炼 Batch API - 下载结果文件
*
* 若没有配置环境变量,可在代码中硬编码API Key:API_KEY = "sk-xxx"
* 但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
* 新加坡和北京地域的API Key不同。
*
* 地域配置:
* - 北京地域:https://dashscope.aliyuncs.com/compatible-mode/v1
* - 新加坡地域:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
* 注意:切换地域时,API Key也需要对应更换
*/
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 Key也需要对应更换
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 リクエストで file_id を指定して結果ファイルをダウンロードします。
リクエスト例
# ======= 重要提示 =======
# 新加坡和北京地域的API Key不同。
# 以下是新加坡地域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 | ユーザー定義のリクエスト識別子。 |
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:コールバック
タスクを作成する際に、metadata を介してパブリックにアクセス可能な URL を指定します。タスクが完了すると、システムはタスクステータスを含む POST リクエストを指定された URL に送信します。
OpenAI Python SDK
import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
# 新加坡和北京地域的API Key不同。
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下是北京地域base_url,如果使用新加坡地域的模型,需要将base_url替换为:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
# 注意:切换地域时,API Key也需要对应更换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.create(
input_file_id="file-batch-xxx", # 上传文件返回的 id
endpoint="/v1/chat/completions", # Embedding文本向量模型填写"/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 EventBridge にイベントを送信します。このイベントをリッスンし、指定されたターゲットにルーティングするように EventBridge ルールを設定します。
- イベントソース (Source):
acs.dashscope - イベントタイプ (Type):
dashscope:System:BatchTaskFinish
「イベントを Message Queue for RocketMQ にルーティングする」をご参照ください。
本番環境への適用
-
ファイル管理
- ストレージ制限 (10,000 ファイルまたは 100 GB) に達しないように、OpenAI File delete API を使用して不要なファイルを定期的に削除してください。
- サイズの大きいファイルは直接アップロードするのではなく、OSS に保存してください。
-
タスクのモニタリング
- Callback または 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:
"messages": messages_builder_example(row[1])}
# 选择Embedding文本向量模型进行调用时,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 を result.csv に変換し、Excel で分析します。
ファイルパスやその他のパラメーターをカスタマイズするには、必要に応じてコードを修正してください。
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 エンコーディングを指定します。
レート制限
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 内に完了しない場合、そのタスクは期限切れになります。期限切れになったタスク内の未処理のリクエストは実行されず、料金も発生しません。
シナリオの推奨事項: 厳密なリアルタイムのモデル推論が必要なシナリオでは、リアルタイム呼び出しを使用してください。遅延を許容できる大規模データ処理のシナリオでは、バッチ呼び出しを使用してください。