Batch API 教程
本教程将指导用户如何在 GenStudio 上使用 Batch API 进行离线推理任务。
概述
GenStudio 支持两种 Batch 任务执行方式:
- 方式 1:使用 Batch API 创建 batch 任务实现离线推理,完成批量任务后返回结果文件,Batch API 兼容 OpenAI Python SDK。
- 方式 2:使用 OpenAI ChatCompletion API 通过批量推理接入点
batch-deepseek-r1
或batch-deepseek-v3
。
警告
- 当前批量推理任务暂不支持单独调整 API 限频,会受到租户下 API 限频影响。具体限频请参考 API 限频。
- 使用方式 1 时,无需担心超过 API 频率限制错误(429 错误),GenStudio 将自动适应,确保请求成功。
- 使用方式 2 时,如遇到 429 错误,需要您自行在代码中实现重试逻辑。
批量推理模型
无论使用哪种方式,都需要使用批量推理模型,目前支持的模型如下:
batch-deepseek-r1
batch-deepseek-v3
方式 1:使用 Batch API
准备 Batch 任务的输入文件
Batch 任务的输入文件格式为 .jsonl
,其中每个请求占据一行(JSON 对象)。每个请求必须包含:
- 一个唯一的
custom_id
,用来将结果和输入进行匹配。 - 单个 batch 文件只能包含对单个模型的请求。
.jsonl
文件最多支持 50,000 个请求,且大小不超过 200MB。以下是一个包含 2 个请求的示例:
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "batch-deepseek-v3", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "batch-deepseek-v3", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
上传 Batch 任务的输入文件
使用 OpenAI Python SDK 上传输入文件,并记录返回的文件 ID 以便创建 batch 任务。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://cloud.infini-ai.com/maas/v1"
)
batch_input_file = client.files.create(
file=open("batchinput.jsonl", "rb"),
purpose="batch"
)
print(batch_input_file.data['id']) # 获取文件上传后的id
创建 Batch 任务
成功上传输入文件后,使用文件 ID 创建 Batch 任务。在本示例中,假设文件 ID 为 lbuf-123
,生成的 batch 任务 ID 为 lbj-123
。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://cloud.infini-ai.com/maas/v1"
)
batch_job = client.batches.create(
input_file_id="lbuf-123", # 传入从上一步中获取的file id
endpoint="/v1/chat/completions",
completion_window="24h",
metadata={"description": "数据蒸馏任务01"}, # metadata参数可以用于备注一些额外的任务信息
extra_body={"replace": {"model": "batch-deepseek-r1"}} # 如果extra_body中设置的模型与jsonl中的model不一致,则任务使用extra_body中模型推理
)
print(batch_job)
print(batch_job.id) # batch任务的id
该请求将创建一个批量推理任务,并返回任务的状态信息。
查询 Batch 任务状态
检查 batch 任务状态,状态为 "completed" 表示任务已完成。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://cloud.infini-ai.com/maas/v1"
)
batch = client.batches.retrieve("lbj-123")
print(batch)
返回的推理任务状态信息如下:
{
"id": "lbj-123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"errors": null,
"input_file_id": "lbuf-123",
"completion_window": "24h",
"status": "completed",
"output_file_id": "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123",
"error_file_id": "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/321",
"created_at": 1751427145,
"in_progress_at": 1751427427,
"expires_at": 1751513544,
"completed_at": 1751427428,
"failed_at": null,
"expired_at": null,
"request_counts": {
"total": 10,
"completed": 0,
"failed": 10
},
"metadata": {
"description": "数据蒸馏任务01"
}
}
其中 status
包含以下几种状态:
in_queue
:任务在排队中in_progress
:任务正在进行中completed
:任务已完成cancelling
:任务取消中cancelled
:任务已取消
下载结果文件
系统将批量推理的结果文件按请求状态分别保存:
output_file_id
:包含所有成功请求的输出结果文件。error_file_id
:包含所有失败请求的错误信息文件。
警告
系统将保留结果文件 30 天。请务必在有效期内及时下载并备份相关数据。超过保存期限的文件将被自动删除,且无法恢复。
可以使用 wget
或 curl
下载:
# 采用wget
wget -O output.jsonl "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123"
# 采用curl
curl -o output.jsonl "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123"
注意
若 OSS 链接过期返回 403 Forbidden,请重新执行上一步查询 Batch 状态以获取新的 OSS URL。
取消 Batch 任务
如有必要,可以取消正在进行的批量处理任务。任务状态将变为 cancelling
,直到在途的请求完成(该过程最长为5分钟),之后状态将变为 cancelled
。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://cloud.infini-ai.com/maas/v1"
)
client.batches.cancel("lbj-123")
获取所有 Batch 任务列表
支持查看用户下的所有 Batch 任务列表。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://cloud.infini-ai.com/maas/v1"
)
client.batches.list()
方式 2:批量推理接入点调用
使用 batch-deepseek-r1
与 batch-deepseek-v3
接入点调用方式和在线接口一致,仅需更改 model
字段即可。当平台有资源剩余,请求成功,否则被暂时拒绝 429 Too Many Requests
,请进行持续重试。
curl --request POST \
--url https://cloud.infini-ai.com/maas/v1/chat/completions \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "batch-deepseek-r1",
"messages": [
{"role": "user", "content":"你是谁"}
]
}'
提示
该接口根据流量实际情况动态调整,日间繁忙时段允许并发低,夜间空闲时段允许并发高。
支持模型列表
目前仅支持端点 /v1/chat/completions
,且支持模型如下:
batch-deepseek-v3
batch-deepseek-r1
费用说明
Batch 任务有特定的定价,具体价格如下:
模型名称 | 批量推理 - 输入 | 批量推理 - 输出 |
---|---|---|
batch-deepseek-v3 | ¥2 | ¥8 |
batch-deepseek-r1 | ¥1 | ¥4 |
GenStudio 推理模型价格单位:¥/百万 Tokens。
重要
在发起批量推理任务前,建议您自行计算输入和输出价格,确保您的账户余额充足。
常见问题
如果在批量任务执行过程中账户欠费,会导致任务状态变更吗?比如任务会直接结束吗?
不会,欠费是请求的状态,而不是任务的状态。批量任务的状态(如 in_queue
、in_progress
、completed
、cancelling
、cancelled
)不会因为欠费而发生变更。即使账户一开始就处于欠费状态,任务本身依然会成功创建并执行,只不过所有请求可能会返回欠费状态。
在批量任务执行过程中欠费,能否获取中间结果?比如获取已处理的数据,放弃未处理的数据?
欠费状态下,任务会继续执行。但欠费后, API 请求结果可能无法正常返回。
如果在欠费状态下补足余额,批量任务会自动恢复吗?
不会。您需要重新发起任务,但仅需处理未完成的请求。