阿里云百炼提供了与OpenAI兼容的Batch接口。您可以通过文件方式提交批量任务,任务将异步执行,在24小时内返回结果,费用为实时调用的50%。在任务运行结束前,您可以通过API进行任务状态查询,当任务结束后,可以通过API获取结果。
前提条件
请开通阿里云百炼服务并获得API-KEY:获取API Key。
如果您通过OpenAI Python SDK使用,请通过以下命令安装最新版OpenAI SDK。
pip3 install -U openai
我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险,配置方法可参考配置API Key到环境变量。
支持的模型
qwen-turbo
qwen-plus
qwen-max
计费
Batch调用的费用为实时调用的50%,具体请参见模型列表。
创建Batch任务
创建Batch任务前需要准备输入文件,通过上传文件上传后获取file_id(文件的purpose属性需要为batch),输入文件格式参考本文档后续章节。单个Batch任务最多包含50k个请求,Batch文件的大小最大100 MB。
Python
请求示例
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", # 填写DashScope服务的base_url
)
batch = client.batches.create(
input_file_id="file-abc123",
endpoint="/v1/chat/completions",
completion_window="24h"
)
print(batch)
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
input_file_id | String | Body | 是 | 上传文件的id,以file-batch开头 文件的purpose属性需要为batch |
endpoint | string | Body | 是 | 访问路径 |
completion_window | String | Body | 是 | 超时时间,当前只支持24h |
metadata | Map | Body | 否 | 附加信息,键值对 |
返回示例
{
"id": "batch_cf957e2b-3295-4357-83af-5fb22ac17e81",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-ADvrUmLWW8TFuKNjGDUUig1c",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"created_at": 1722503223,
"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": {}
}
返回参数
字段 | 类型 | 描述 |
id | String | batch任务id |
object | String | 对象类型,固定值batch |
endpoint | String | 访问路径 |
errors | Map | 错误信息 |
input_file_id | String | 上传的文件id |
completion_window | String | 超时时间,当前只支持24h |
status | String | 任务状态:validating, in_progress, finalizing, completed, expired, cancelling, cancelled, failed |
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 | 附加信息,键值对 |
HTTP
需要配置的endpoint
POST https://dashscope.aliyuncs.com/compatible-mode/v1/files
请求示例
curl https://dashscope.aliyuncs.com/compatible-mode/v1/batches \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-abc123",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
input_file_id | String | Body | 是 | 上传文件的file_id,以file-batch开头 文件的purpose属性为batch |
endpoint | string | Body | 是 | 访问路径 |
completion_window | String | Body | 是 | 超时时间,当前只支持24h |
metadata | Map | Body | 否 | 附加信息,键值对 |
返回示例
{
"id": "batch_cf957e2b-3295-4357-83af-5fb22ac17e81",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-ADvrUmLWW8TFuKNjGDUUig1c",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"created_at": 1722503223,
"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": {}
}
返回参数
字段 | 类型 | 描述 |
id | String | batch任务id |
object | String | 对象类型,固定值batch |
endpoint | String | 访问路径 |
errors | Map | 错误信息 |
input_file_id | String | 上传的文件id |
completion_window | String | 超时时间,当前只支持24h |
status | String | 任务状态:validating, in_progress, finalizing, completed, expired, cancelling, cancelled, failed |
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 | 附加信息,键值对 |
查询Batch任务
Python
请求示例
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", # 填写DashScope服务的base_url
)
batch = client.batches.retrieve("batch_abc123")
print(batch)
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
batch_id | String | Path | 是 | 需要查询的batch任务id |
返回示例
参见创建Batch任务返回示例。
返回参数
参见创建Batch任务返回示例。
返回参数中output_file_id和error_file_id可以通过下载文件获取内容。
HTTP
需要配置的endpoint
GET https://dashscope.aliyuncs.com/compatible-mode/v1/batches/{batch_id}
请求示例
curl --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_xxx' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
batch_id | String | Path | 是 | 需要查询的batch任务id |
返回示例
参见创建Batch任务返回示例
返回参数
参见创建Batch任务返回示例
取消Batch任务
Python
请求示例
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", # 填写DashScope服务的base_url
)
batch = client.batches.cancel("batch_abc123")
print(batch)
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
batch_id | String | Path | 是 | 需要取消的batch任务id |
返回示例
参见创建Batch任务返回示例。
返回参数
参见创建Batch任务返回示例。
HTTP
需要配置的endpoint
POST https://dashscope.aliyuncs.com/compatible-mode/v1/batches/{batch_id}/cancel
请求示例
curl --request POST 'https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_xxx/cancel' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
batch_id | String | Path | 是 | 需要取消的batch任务id |
返回示例
参见创建Batch任务返回示例
返回参数
参见创建Batch任务返回示例
查询Batch任务列表
Python
请求示例
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"), # 如果您没有配置环境变量,请在此处用您的API Key进行替换
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", # 填写DashScope服务的base_url
)
batches = client.batches.list()
print(batches)
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
after | String | Query | 否 | 查询此batch id之前的任务,翻页查询时把返回结果中的last_id设置到此参数中 |
limit | Integer | Query | 否 | 返回数量,范围[1,100],默认20 |
返回示例
{
"object": "list",
"data": [
{
"id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-IvxTEDheD70YmyXfqrkE2t64",
"completion_window": "24h",
"status": "completed",
"output_file_id": "file-batch_output-fUy6gxJCyHzT0WHDg2SInyTp",
"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_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
"last_id": "batch_ca912d83-e9e8-4cf2-89a4-d29743e334e4",
"has_more": true
}
返回参数
字段 | 类型 | 描述 |
object | String | 类型,固定值list |
data | Array | batch任务对象,参见创建batch任务出参 |
first_id | String | 当前页第一个id |
last_id | String | 当前页最后一个id |
has_more | Boolean | 是否有下一页 |
HTTP
需要配置的endpoint
GET https://dashscope.aliyuncs.com/compatible-mode/v1/batches?limit=2&after={batch_id}
请求示例
curl --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/batches?limit=2&after=batch_xxx' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
输入参数配置
字段 | 类型 | 传参方式 | 必选 | 描述 |
after | String | Query | 否 | 查询此batch id之前的任务,翻页查询时把返回结果中的last_id设置到此参数中 |
limit | Integer | Query | 否 | 返回数量,范围[1,100],默认20 |
返回示例
{
"object": "list",
"data": [
{
"id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "file-batch-IvxTEDheD70YmyXfqrkE2t64",
"completion_window": "24h",
"status": "completed",
"output_file_id": "file-batch_output-fUy6gxJCyHzT0WHDg2SInyTp",
"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_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
"last_id": "batch_ca912d83-e9e8-4cf2-89a4-d29743e334e4",
"has_more": true
}
返回参数
字段 | 类型 | 描述 |
object | String | 类型,固定值list |
data | Array | batch任务对象,参见创建batch任务出参 |
first_id | String | 当前页第一个id |
last_id | String | 当前页最后一个id |
has_more | Boolean | 是否有下一页 |
输入文件格式
JSONL文件,每一行一个JSON。
示例
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "qwen-turbo", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}]}}
参数
字段 | 类型 | 必选 | 描述 |
custom_id | String | 是 | 用户自定义的请求id,文件中唯一 |
method | String | 是 | 请求方法,当前只支持POST |
url | String | 是 | API关联的URL,当前支持:/v1/chat/completions |
body | Object | 是 | 模型调用的请求体 |
输出文件格式
JSONL文件,每一行一个JSON。
示例
{"id": "batch_req_wnaDys", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_c187b3", "body": {"id": "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, "model": "qwen-max", "choices": [{"index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 24, "completion_tokens": 15, "total_tokens": 39}, "system_fingerprint": null}}, "error": null}
参数
字段 | 类型 | 必选 | 描述 |
id | String | 是 | 请求id |
custom_id | String | 是 | 用户自定义的请求id |
response | Object | 否 | 请求结果 |
error | Object | 否 | 异常响应结果 |
error.code | String | 否 | 错误码 |
error.message | String | 否 | 错误信息 |
常见问题
这几个模块的Batch定价,对应的模型也有基础限流吗?
答:实时调用才会有QPM(Queries Per Minute:每分钟处理请求数)限流,Batch调用没有 QPM 限流。
使用Batch调用,是否需要下单,在哪里下单?
答:Batch是一种调用方式,无需额外下单。该调用方式为后付费计价模式,按照Batch接口调用直接付费。
提交的Batch调用请求,后台如何处理? 是根据提交请求的先后顺序来执行吗?
答:不是排队机制,是调度机制,根据资源情况来调度和执行Batch请求任务。
报错如何处理?
答:请参见错误码。