创建批量预测任务
更新时间：2025-12-09
POST
https://qianfan.baidubce.com/v2/batches
本接口用于创建批量预测任务，通过已上传的请求文件创建并执行批量预测任务。
支持模型列表
详细模型列表请参见批量推理-支持模型列表。
权限说明
调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。
请求参数
Headers 参数
除公共头域外，无其它特殊头域
Body 参数
completion_window
string
批量推理任务需完成的时间范围，支持1-672小时。
必选
endpoint
string
批量推理任务中所有请求使用的接口，支持以下类型：
- chat与视觉理解模型：/v2/chat/completions
- 图像生成模型：/v2/images/generations
- 图像编辑模型：/v2/images/edits
必选
input_file_id
string
已上传的文件ID，该文件包含了所有需要进行预测的请求数据。
必选
metadata
object {0}
一组可以附加到对象的16个键值对。
可选
显示子属性
隐藏子属性
暂无参数
replace
string
替换文件中的 model 参数。如果是预置服务，填写接入点 model；如果是千帆平台模型可填写 modelVersionId。例：ernie-x1-turbo-32k。
可选
请求结构
POST /v2/batches HTTP/1.1
Host: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
"completion_window": "1h",
"endpoint": "/v2/chat/completions",
"input_file_id": "file-****7cz9",
"metadata":{
"model": "llama-3-8b",
"messages": [
{
"role": "user",
"content": "Tell me a joke about programming."
}
],
"temperature": 1.0
},
"replace": {"model": "deepseek-v3"}
}示例代码
请求示例
curl https://qianfan.baidubce.com/v2/batches \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Key>" \
-d '{
"completion_window": "1h",
"endpoint": "/v2/chat/completions",
"input_file_id": "file-b0rupz7cz9",
"metadata":{
"model": "llama-3-8b",
"messages": [
{
"role": "user",
"content": "Tell me a joke about programming."
}
],
"temperature": 1.0
},
"replace": {"model": "ernie-x1-turbo-32k"}
}'返回响应
Headers 参数
除公共头域外，无其它特殊头域
返回参数
id
string
批量推理任务的 id。
可选
object
string
对象类型，返回batch。
可选
endpoint
string
批量任务中所有请求使用的接口。例：/v2/chat/completions。需要与输入文件中的url字段保持一致
可选
model
string
用于处理批量预测的模型ID。如 ernie-x1-turbo-32k，千帆提供各种具有不同功能、性能特征和价格点的模型。请参考批量推理-支持模型列表，浏览和比较可用的模型。
可选
errors
object {2}
批量推理任务错误码。
可选
显示子属性
隐藏子属性
failureCode
number
标识错误类型的错误代码。
可选
failureReason
string
有关错误的详细原因。
可选
input_file_id
string
批量推理任务文件的 id 。
可选
completion_window
string
处理批量推理任务的时间范围。
可选
status
string
批量推理任务的当前状态。
- Running: 运行中
- Done: 运行完成
- Stopped: 运行中止
- Failed: 运行失败
- Expired: 运行超时
可选
output_file_id
string
成功处理后的文件 id。
可选
error_file_id
string
错误请求的文件 id。
可选
created_at
integer
创建批量推理任务时的Unix时间戳
可选
in_progrsss_at
integer
批量推理任务开始处理的Unix时间戳。
可选
expires_at
integer
批量推理任务将会到期的Unix时间戳。
可选
expired_at
string
批量推理任务到期时间的Unix时间戳。
可选
failed_at
string
批量推理任务处理失败时的Unix时间戳。
可选
finalizing_at
integer
批量推理任务开始完成的Unix时间戳。
可选
completed_at
integer
批量推理任务完成时间的Unix时间戳。
可选
cancelling_at
string
批量推理任务开始取消的Unix时间戳。
可选
cancelled_at
string
批量推理任务取消完成的Unix时间戳
可选
request_counts
object {3}
批量推理任务中不同状态下的请求数量。
可选
显示子属性
隐藏子属性
total
integer
批量推理任务中的请求总数。
可选
completed
integer
已成功完成的请求数量。
可选
failed
integer
失败的请求数量。
可选
usage
object {5}
表示 token 使用详情，包括输入 tokens、输出 tokens、输出 tokens 的明细以及使用的总 tokens 数。
可选
显示子属性
隐藏子属性
input_tokens
integer
输入 Tokens 的数量。
可选
input_tokens_details
object {1}
输入 Tokens 的详细信息。
可选
显示子属性
隐藏子属性
cached_tokens
string
命中缓存 Tokens 的数量。
可选
output_tokens
integer
输出 Tokens 的数量。
可选
output_tokens_details
object {1}
输出 Tokens 的数量。
可选
显示子属性
隐藏子属性
reasoning_tokens
string
深度思考Tokens数量
可选
total_tokens
integer
总Tokens数量
可选
metadata
object {0}
一组可以附加到对象的16个键值对。
可选
显示子属性
隐藏子属性
暂无参数
JSON
{
"id": "infer-abc123",
"object": "batch",
"endpoint": "/v2/chat/completions",
"model": "ernie-x1-turbo-32k",
"errors": null,
"input_file_id": "file-abc123",
"completion_window": "1h",
"status": "Queuing",
"output_file_id": null,
"error_file_id": null,
"created_at": 1764749391,
"in_progress_at": null,
"expires_at": 1764752991,
"finalizing_at": null,
"completed_at": null,
"failed_at": null,
"expired_at": null,
"cancelled_at": null,
"cancelling_at": null,
"request_counts": {
"total": 0,
"completed": 0,
"failed": 0
},
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"metadata": {
"messages": [
{
"content": "Tell me a joke about programming.",
"role": "user"
}
],
"model": "llama-3-8b",
"temperature": 1
}
}JSON
{
"requestId": "d2feeac6-****-58d01cf558df",
"code": "RetrieveInputFileErr",
"message": "File API Reerieve input file Error"
}输入文件数据格式
约束：上传files文件校验
- 文件格式必须为JSONL，每行一个JSON格式的请求
- 单个Batch最多包含5000个请求
- 单个Batch任务的所有请求必须选用同一个模型
- 补充："replace":{"model":"deepseek-v3"}指定
- 提示用户如果要使用openAI SDK，需要保持同一batch任务中model统一，强制异步校验
- 单行的请求内容需遵循各模型上下文长度限制
- Batch文件最大为1G
- 每一行的body中必须包含messages对象数组
- 可以为每一行数据按需设置相同或不同的推理参数，如设定不同的
temperature、top_p
- JSONL文件内容示例
json
{"custom_id": "request-1", "method": "POST", "url": "/v2/chat/completions", "body": {"model": "ernie-4.5-turbo-32k", "messages": [{"role": "system", "content": "你是一个旅游规划小助手，可以帮助游客们做攻略"}, {"role": "user", "content": "介绍一下北京"}, {"role": "assistant", "content": "北京，简称“京”，古称燕京、北平，中华民族的发祥地之一，是中华人民共和国首都、直辖市、国家中心城市、超大城市，也是国务院批复确定的中国政治中心、文化中心、国际交往中心、科技创新中心，中国历史文化名城和古都之一，世界一线城市。"}, {"role": "user", "content": "我在上海，周末可以去哪里玩？"}, {"role": "assistant", "content": "上海是一个充满活力和文化氛围的城市，有很多适合周末游玩的地方。以下是几个值得推荐的地方：\n\n上海迪士尼乐园：上海迪士尼乐园是世界上最大的迪士尼主题公园之一，有许多精彩的游乐项目和演出，可以让您尽情享受娱乐和欢乐。\n上海野生动物园：上海野生动物园是一个以自然保护为主题的野生动物园，有许多珍稀动物和植物，可以让您近距离接触大自然。\n\n这些地方都是上海周末游玩的好去处，可以根据自己的兴趣和需求选择合适的行程。"}, {"role": "user", "content": "上海有哪些美食"}], "top_p": 0.5, "temperature": 0.9, "penalty_score": 1.1}}
{"custom_id": "request-2", "method": "POST", "url": "/v2/chat/completions", "body": {"model": "ernie-4.5-turbo-32k", "messages": [{"role": "system", "content": "你是一个旅游规划小助手，可以帮助游客们做攻略"}, {"role": "user", "content": "推荐上海最适合旅游的5个景点"}, {"role": "assistant", "content": "外滩：黄浦江畔的标志性景点，欣赏历史建筑群与现代摩天大楼的交融景色。南京路步行街：繁华的商业街，购物、美食、观光一应俱全。豫园：古典江南园林，领略精美园林风光和古老建筑。东方明珠：上海的标志性建筑，可俯瞰整个城市的美景。上海博物馆：了解上海历史文化的绝佳去处，藏品丰富。"}, {"role": "user", "content": "帮我计划上海一日游"}], "top_p": 0.5, "temperature": 0.9, "penalty_score": 1.1}}- 文件内字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| custom_id | String | 是 | 每一行请求的唯一标识。由于批量任务是异步且可能乱序处理的，结果文件将通过此ID与您的原始请求进行关联对应。 |
| method | String | 是 | HTTP请求方法，仅支持POST. |
| url | String | 是 | API关联的URL，需和创建batch任务时的endpoint保持一致。 chat与视觉理解模型为：/v2/chat/completions. 图像生成为：/v2/images/generations. 图像编辑为：/v2/images/edits. |
| body | Object | 是 | 模型调用的请求体，包含调用模型所需的全部参数，如model、messages、enable_thinking，thinking_budget等。请求体中的参数与实时推理接口所支持的参数保持一致。 如果需要进一步扩展支持更多参数（如 max_tokens, temperature等），也可以添加到body中，参数之间通过英文逗号隔开。 |
| extra_body | Object | 否 | 额外的请求体字段。其内容会与当前请求的默认 body 合并，同名字段以 extra_body 中的值为准。 |
| extra_body.replace | Array | 否 | 在已有请求体的基础上，对指定字段进行覆盖。适用于针对单条请求修改公共 body 中的部分参数。 |