批量推理

更新时间：2026-02-06

功能介绍

批量推理可以⼀次性处理⼤量数据，并对这些数据进⾏统⼀推理预测，最后将结果输出到指定位置。适合⼤批量数据处理、分析的场景等。批量推理的计费仅为实时推理的40%，帮助您有效节省资源消耗成本。

1、前置准备

获取APikey：调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。
开通BOS：账户需要开通BOS对象存储，如您未开通BOS功能，可提前开通。

2、标准操作流程

整个批推过程分为四个步骤：准备数据 -> 上传文件 -> 创建 Batch 任务 -> 查询结果。

2.1、数据准备

创建一个.jsonl文件（例如batch_input.jsonl），每一行是一个独立的 JSON 对象，格式需严格符合 OpenAI 的 Batch 标准。 JSONL文件内容示例：

                Json
                
                {"custom_id": "request-1", "method": "POST", "url": "/v2/chat/completions", "body": {"model": "deepseek-v3.2", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello world!"}],"top_p": 0.95, "temperature": 1.0}}
{"custom_id": "request-2", "method": "POST", "url": "/v2/chat/completions", "body": {"model": "deepseek-v3.2", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello world!"}],"top_p": 0.95, "temperature": 1.0}}

注意：由于此jsonl文件会用于后续的批量推理任务，因此需要严格符合 OpenAI 的 Batch的文件格式要求
文件内字段说明：

字段	类型	必填	说明
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`中，参数之间通过英文逗号隔开。
replace	Array	否	在已有请求体的基础上，对指定字段进行覆盖。适用于针对单条请求修改公共 body 中的部分参数。

2.2、利用files接口上传文件

前置条件：

在 sdk 当中创建一个 OpenAI 连接 client，后续 SDK 示例当中统一使用此 client 对象。

                Python
                
            

                from openai import OpenAI
import os

# 从环境变量中获取您的API KEY，
api_key = os.getenv('QIANFAN_API_KEY')
base_url = os.getenv('QIANFAN_BASE_URL')

client = OpenAI(
    base_url=base_url,
    api_key=api_key
)
            

2.2.1 接口文档

查看详细参数：https://cloud.baidu.com/doc/qianfan-api/s/9mi6szj38

上传files文件校验:

文件格式必须为JSONL，每行一个JSON格式的请求
单个Batch最多包含5000个请求
单个Batch任务的所有请求必须选用同一个模型。
- 提示：用户如果要使用OpenAI SDK，需要保持同一batch任务中model统一，强制异步校验，model不统一会报错。可以在2.3创建批量推理任务中使用"replace":{"model":"deepseek-v3"} 统一替换jsonl文件中的model参数，用于统一覆盖输入文件中所有请求的模型参数。
单行的请求内容需遵循各模型上下文长度限制
Batch文件最大为1G
每一行的body中必须包含messages对象数组
可以为每一行数据按需设置相同或不同的推理参数，如设定不同的temperature、top_p

2.2.2调用示例

http 请求示例：

                Bash
                
            

                curl --location 'https://qianfan.baidubce.com/v2/files' \
--header 'Authorization: Bearer bce-v3/ALTAK-dy8TsIJ*****' \
--header 'content-type: multipart/form-data' \
--form 'purpose="batch"' \
--form 'file=@"batchinput.jsonl"'
            

sdk 请求示例：

                Python
                
                from openai import OpenAI

batch_input_file = client.files.create(
    file=open("batchinput.jsonl", "rb"),
    purpose="batch"
)

print(batch_input_file)

返回示例：

                Json
                
            

                {
    "id": "file-wbigmvy9mu",
    "object": "file",
    "bytes": 26285,
    "created_at": 1770300205,
    "filename": "batchinput.jsonl",
    "purpose": "batch"
}
            

2.3、创建批量推理任务

2.3.1 接口文档

查看详细参数：https://cloud.baidu.com/doc/qianfan-api/s/Vmimtsj8f

2.3.2调用示例

http 请求示例：

                Bash
                
            

                curl --location 'https://qianfan.baidubce.com/v2/batches' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-dy8Ts******' \
--data '{
    "completion_window": "1h",
    "endpoint": "/v2/chat/completions",
    "input_file_id": "file-wbigmvy9mu",
    "metadata": {
        "description": "nightly eval job"
    },
    "replace": {
        "model": "deepseek-v3"
    }
}'
            

sdk 请求示例：

                Python
                
            

                from openai import OpenAI

batch_input_file_id = batch_input_file.id
client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v2/chat/completions",
    completion_window="24h",
    metadata={
        "description": "nightly eval job"
    },
    extra_body={"replace":{"model": "deepseek-v3"}}
)
            

返回示例：

                Json
                
            

                {
    "id": "infer-1gc4wzdxphfd",
    "object": "batch",
    "endpoint": "/v2/chat/completions",
    "model": "deepseek-v3",
    "errors": null,
    "input_file_id": "file-wbigmvy9mu",
    "completion_window": "1h",
    "status": "Queuing",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1770300856,
    "in_progress_at": null,
    "expires_at": 1770304456,
    "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": {
        "description": "nightly eval job"
    }
}
            

2.4 获取批量推理任务详情

批量推理任务为异步任务，因此可以通过查询接口来获取批量推理任务详情

2.4.1 接口文档

详细参数参考：https://cloud.baidu.com/doc/qianfan-api/s/ymir8ggss

2.4.2调用示例

请求：

                Bash
                
                curl --location 'https://qianfan.baidubce.com/v2/batches/infer-1gc4wzdxphfd' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-dy8TsIJ*****' \
--data ''

sdk 请求示例：

                Python
                
                from openai import OpenAI

batch = client.batches.retrieve("infer-1gc4wzdxphfd")
print(batch)

                Json
                
            

                {
    "id": "infer-1gc4wzdxphfd",
    "object": "batch",
    "endpoint": "/v2/chat/completions",
    "model": "deepseek-v3",
    "errors": null,
    "input_file_id": "file-wbigmvy9mu",
    "completion_window": "1h",
    "status": "Done",
    "output_file_id": "file-07vha6gj46",
    "error_file_id": null,
    "created_at": 1770300856,
    "in_progress_at": 1770300867,
    "expires_at": 1770304456,
    "finalizing_at": 1770302944,
    "completed_at": 1770302944,
    "failed_at": null,
    "expired_at": null,
    "cancelled_at": null,
    "cancelling_at": null,
    "request_counts": {
        "total": 100,
        "completed": 100,
        "failed": 0
    },
    "usage": {
        "input_tokens": 1398,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 1875,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 3273
    },
    "metadata": {
        "description": "nightly eval job"
    }
}
            

2.5 利用files接口获取任务执行结果

通过files的retrieve content接口获取任务的执行结果，其中file.id为查询批量推理任务中返回的output_file_id。

2.5.1 接口文档

接口参数详情：https://cloud.baidu.com/doc/qianfan-api/s/Bmi6vu310

2.5.2调用示例

Http 调用示例：

                Bash
                
                curl --location 'https://qianfan.baidubce.com/v2/files/file-07vha6gj46/content' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bce-v3/ALTAK-dy****' \
--data ''

sdk 调用示例：

                Python
                
                from openai import OpenAI

file_response = client.files.content("file-07vha6gj46")
print(file_response.text)

返回结果：

                Json
                
                {"response": {"status_code": 200, "body": {"choices": [{"finish_reason": "stop", "flag": 0, "index": 0, "message": {"content": "Hello! How can I assist you today? ", "role": "assistant"}}], "created": 1770302934, "id": "as-v73juzcn8r", "model": "offline-tjzj-deepseekv3", "object": "chat.completion", "usage": {"completion_tokens": 11, "prompt_tokens": 14, "total_tokens": 25}}, "request_id": "as-v73juzcn8r"}, "custom_id": "request-81", "id": "as-v73juzcn8r"}
{"response": {"status_code": 200, "body": {"choices": [{"finish_reason": "stop", "flag": 0, "index": 0, "message": {"content": "Hello! How can I assist you today? ", "role": "assistant"}}], "created": 1770302934, "id": "as-6q6a66udc5", "model": "offline-tjzj-deepseekv3", "object": "chat.completion", "usage": {"completion_tokens": 11, "prompt_tokens": 14, "total_tokens": 25}}, "request_id": "as-6q6a66udc5"}, "custom_id": "request-65", "id": "as-6q6a66udc5"}
......

用量统计说明

FIM补全

百度智能云

千帆AI应用开发者中心-开始使用 qianfan-docs

千帆AI应用开发者中心-开始使用 qianfan-docs

批量推理

功能介绍

1、前置准备

2、标准操作流程

2.1、数据准备

2.2、利用files接口上传文件

2.2.1 接口文档

2.2.2调用示例

2.3、创建批量推理任务

2.3.1 接口文档

2.3.2调用示例

2.4 获取批量推理任务详情

2.4.1 接口文档

2.4.2调用示例

2.5 利用files接口获取任务执行结果

2.5.1 接口文档

2.5.2调用示例