阿里云百炼提供与 OpenAI 兼容的 Batch File API,支持通过文件批量提交请求。系统异步处理所有请求,在全部完成或达到最长等待时间后返回结果,费用仅为实时调用的 50% 。适用于数据分析、模型评测等时效性要求不高但需大批量处理的场景。
工作流程
前提条件
支持通过 OpenAI SDK(Python、Node.js)或HTTP API调用 Batch File 接口。
- 获取API Key:获取并配置API Key 到环境变量
- 安装 SDK(可选):如需使用SDK调用,请安装 OpenAI SDK
-
服务端点
- 华北2(北京):
https://dashscope.aliyuncs.com/compatible-mode/v1 - 新加坡:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- 华北2(北京):
适用范围
- 华北2(北京)
- 新加坡
-
文本生成模型
- 千问 Max:qwen3.8-max、qwen3.7-max、qwen3-max
- 千问 Plus:qwen3.7-plus、qwen3.6-plus、qwen3.5-plus、qwen-plus、qwen-plus-latest
- 千问 Flash:qwen3.7-flash、qwen3.6-flash、qwen3.5-flash、qwen-flash
- 千问 Long:qwen-long、qwen-long-latest
- 第三方模型:deepseek-r1、deepseek-v3.2、deepseek-v3
-
多模态模型
- 图像与视频理解:qwen3.8-max、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen3-vl-plus、qwen3-vl-flash
- 文字提取:qwen-vl-ocr、qwen-vl-ocr-latest
- 全模态:qwen3.5-omni-plus
- 向量模型:text-embedding-v1、text-embedding-v2、text-embedding-v3、text-embedding-v4、qwen3.7-text-embedding
快速开始
在处理正式任务前,使用测试模型batch-test-model进行全链路闭环测试。该模型跳过推理过程,直接返回固定的成功响应,用于验证API调用链路和数据格式是否正确。
- 测试文件需满足输入文件要求,且文件大小不超过 1 MB,行数不超过100行。
- 并发限制:最大并行任务数 2 个。
- 费用:测试模型不产生模型推理费用。
第 1 步:准备输入文件
准备一个名为test_model.jsonl的文件,内容如下:
第 2 步:运行代码
根据使用的编程语言,选择以下示例代码并保存到输入文件的同一目录下,然后运行。代码将完成文件上传、创建任务、轮询状态和下载结果的完整流程。
如需调整文件路径或其他参数,请根据实际情况修改代码。
file-batch-xxx)可重复使用。如果输入内容不变,无需每次重新上传,直接用已有 ID 创建任务即可:client.files.list(purpose="batch") 接口查询已上传的 Batch 文件 ID。示例代码
示例代码
第 3 步: 验证测试结果
任务成功完成后,结果文件result.jsonl包含固定响应{"content":"This is a test result."}:
执行正式任务
输入文件要求
- 格式:UTF-8 编码的 JSONL(每行一个独立JSON对象)
- 规模限制:单文件最多 50,000 个请求,且不超过 500 MB
- 单行限制:每个JSON对象不超过 6 MB,且不超过模型上下文长度
- 一致性要求:同一文件内所有请求须使用相同的模型及思考模式(如适用)
- 唯一标识:每个请求必须包含文件内唯一的 custom_id 字段,用于匹配请求与结果
示例中的 Base64 字符串已省略,使用下方 Python 代码生成完整编码即可。
传入 Base64 编码字符串(以图像为例)
传入 Base64 编码字符串(以图像为例)
- 将本地文件转换为 Base64 编码:
-
构建Data URL格式:
data:[MIME_type];base64,{base64_image};MIME_type需替换为实际的媒体类型,确保与MIME Type的值匹配(如image/jpeg、image/png);base64_image为上一步生成的 Base64 字符串。
使用方式
- 将以下代码保存为
generate_batch_jsonl.py - 修改脚本中
TASKS列表的请求内容 - 运行
python generate_batch_jsonl.py - 生成的
batch_input.jsonl文件可直接用于 Batch 推理任务
文本生成模型 JSONL 生成脚本
多模态模型请求格式
多模态模型的 content 字段为数组格式,包含媒体对象和文本提问。每行请求中的媒体URL需为同一类型(图片、视频或音频)。将上方脚本中的 TASKS 替换为以下格式即可:
向量模型请求格式
向量模型使用 /v1/embeddings 接口,请求格式不同于文本生成模型。可使用以下独立脚本生成:
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):每一行对应一个成功的原始请求,包含custom_id和response。
- 失败请求详情(
error_file_id):包含处理失败的请求行信息和错误原因,可参考错误码进行排查。
具体流程
Batch API使用流程分为四步:上传文件、创建任务、查询任务状态、下载结果。
1. 上传文件
1. 上传文件
file_id。上传文件,purpose必须是batch。
file-batch-xxx)可重复使用。如果输入内容不变,无需每次重新上传,直接用已有 ID 创建任务即可:client.files.list(purpose="batch") 接口查询已上传的 Batch 文件 ID。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
请求示例
返回示例
2. 创建 Batch 任务
2. 创建 Batch 任务
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
请求示例
输入参数
字段 | 类型 | 传参 方式 | 必选 | 描述 |
|---|---|---|---|---|
input_file_id | String | Body | 是 | 用于指定文件ID、OSS文件URL或OSS文件资源标识符,作为Batch任务的输入文件。您可以通过以下任一方式提供此参数:
|
endpoint | String | Body | 是 | 访问路径,须与输入文件中的URL字段一致。
|
completion_window | String | Body | 是 | 等待时间,最短 24h,最长 336h,仅支持整数。 支持"h"和"d"两个单位,如"24h"或"14d"。 |
metadata | Map | Body | 否 | 任务扩展元数据,以键值对形式附加额外信息。 |
metadata.ds_name | String | Body | 否 | 任务名称。 示例: 限制:长度不超过100个字符。 若重复定义该字段,以最后一次传入的值为准。 |
metadata.ds_description | String | Body | 否 | 任务描述。 示例: 限制:长度不超过200个字符。 若重复定义该字段,以最后一次传入的值为准。 |
返回示例
返回参数
字段 | 类型 | 描述 |
|---|---|---|
id | String | 本次创建的 Batch 任务 ID。 |
object | String | 对象类型,固定值 |
endpoint | String | 访问路径。 |
errors | Map | 错误信息。 |
input_file_id | String | 文件ID 或OSS文件URL或OSS文件资源标识符。 |
completion_window | String | 等待时间,支持最短等待时间24h,最长等待时间336h,仅支持整数。 支持"h"和"d"两个单位,如"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. 查询 与管理 Batch 任务
3. 查询 与管理 Batch 任务
查询指定任务状态
查询指定任务状态
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
请求示例
返回示例
查询成功后返回 Batch 任务的详细信息。以下为 completed 状态的返回示例:字段 | 类型 | 描述 |
|---|---|---|
id | String | Batch 任务 ID。 |
status | String | 任务状态,可能的值包括:
|
output_file_id | String | 成功结果文件的 ID,任务完成后生成。 |
error_file_id | String | 失败结果文件的 ID,任务完成且有失败请求时生成。 |
request_counts | Object | 请求数量统计对象,包含 total、completed、failed 字段。 |
查询任务列表
查询任务列表
batches.list() 方法查询 Batch 任务列表,通过分页机制逐步获取完整的任务列表。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
请求示例
输入参数
字段 | 类型 | 传参方式 | 必选 | 描述 |
|---|---|---|---|---|
after | String | Query | 否 | 用于分页的游标,值为上一页最后一个任务的ID。 |
limit | Integer | Query | 否 | 每页返回的任务数量,范围[1, 100],默认20。 |
ds_name | String | Query | 否 | 按任务名称进行模糊匹配。 |
input_file_ids | String | Query | 否 | 按文件ID筛选,多个ID用逗号分隔,最多20个。 |
status | String | Query | 否 | 按任务状态筛选,多个状态用逗号分隔。 |
create_after | String | Query | 否 | 筛选在此时间点之后创建的任务,格式: |
create_before | String | Query | 否 | 筛选在此时间点之前创建的任务,格式: |
返回示例
返回参数
字段 | 类型 | 描述 |
|---|---|---|
object | String | 类型,固定值list。 |
data | Array | Batch任务对象,参见创建Batch任务的返回参数。 |
first_id | String | 当前页第一个 Batch任务 ID。 |
last_id | String | 当前页最后一个Batch任务 ID。 |
has_more | Boolean | 是否有下一页。 |
取消Batch任务
取消Batch任务
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
请求示例
返回示例
取消任务成功后返回 Batch 任务的详细信息。以下是一个 cancelling 状态的返回示例:取消任务后,状态会先变为cancelling,等待正在执行的请求完成;最终会变为cancelled。已完成的请求结果仍会保存在输出文件中。
4. 下载Batch结果文件
4. 下载Batch结果文件
file-batch_output开头的file_id对应的文件。- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
content方法获取Batch任务结果文件内容,并通过write_to_file方法将其保存至本地。请求示例
返回示例
返回示例
单条响应结果:返回参数
字段 | 类型 | 描述 |
|---|---|---|
id | String | 请求 ID。 |
custom_id | String | 用户自定义的 ID。 |
response | Object | 请求结果。 |
status_code | Integer | 状态码。200表示请求成功。 |
request_id | String | 服务端为这次请求生成的唯一ID。 |
completion_tokens | Integer | 模型生成的回复内容(completion)所消耗的Token数量。 |
prompt_tokens | Integer | 发送给模型的输入内容( |
reasoning_tokens | Integer | 深度思考模型的思考过程token数。 |
total_tokens | Integer | 本次调用总共消耗的Token数量。 |
model | String | 本次调用所使用的模型名称。 |
reasoning_content | String | 深度思考模型的思考过程。 |
error | Object | 错误信息对象。如果API调用成功,该值为 |
error.code | String | 错误行信息和错误原因,可参考错误码进行排查。 |
error.message | String | 错误信息。 |
进阶功能
使用OSS文件创建 Batch 任务
大型文件推荐存储在阿里云OSS中,通过 input_file_id 直接引用,避免本地上传限制。
方式一:使用文件 URL
将具有公共读权限或预签名授权的OSS文件URL直接作为 input_file_id:
获取文件URL
获取文件URL
-
OSS 控制台
- 进入Bucket列表页面,找到目标Bucket并单击名称;
-
在文件列表中定位目标文件,单击右侧详情按钮;
您可在 文件列表 中新建子文件夹如 Batch/20260101 并上传文件 。
- 在弹出面板中,单击复制文件URL。
- SDK:生成OSS文件 URL,参考使用预签名URL下载(Java SDK V1)。
- 完成OSS授权 参阅从OSS导入文件配置说明的授权和添加标签步骤。
-
参数配置
使用
oss:{region}:{bucket}/{file_path}格式的OSS资源标识符:
- 使用与阿里云百炼服务同地域 Bucket(
cn-beijing)可利用阿里云内网传输,降低网络延迟、提升稳定性并避免跨地域流量费用。 - 方式二更安全,基于RAM授权而非公开 URL。
配置任务完成通知
长时间运行的任务使用轮询会消耗不必要的资源。建议配置异步通知,系统在任务完成后主动通知。
- Callback 回调:在创建任务时指定一个公网可访问的 URL
- EventBridge 消息队列:与阿里云生态深度集成,无需公网 IP
方式一:Callback 回调
方式一:Callback 回调
metadata 指定一个公网可访问的 URL。任务完成后,系统向该URL发送包含任务状态的 POST 请求:- OpenAI Python SDK
- curl(HTTP)
方式二:EventBridge 消息队列
方式二:EventBridge 消息队列
- 事件源 (Source):
acs.dashscope - 事件类型 (Type):
dashscope:System:BatchTaskFinish
应用于生产环境
-
文件管理
- 定期调用 OpenAI-File删除文件接口删除不需要的文件,避免达到文件存储上限(10000个文件或100GB)
- 对于大型文件,推荐将其存储在阿里云OSS中
-
任务监控
- 优先使用 Callback 或 EventBridge 异步通知
- 轮询间隔 > 1分钟,使用指数退避策略
-
错误处理
- 实现完整的异常处理机制,涵盖网络错误、API 错误等
- 下载并分析
error_file_id的错误详情 - 对于常见错误码,参考错误码进行解决
-
成本优化
- 将时效性要求不高的任务迁移到 Batch API
- 合并小任务到一个批次
- 合理设置
completion_window提供更多调度灵活性
实用工具
CSV 转 JSONL
CSV 转 JSONL
如需调整文件路径或其他参数,请根据实际情况修改代码。
JSONL 结果转 CSV
JSONL 结果转 CSV
result.jsonl 文件解析为易于在Excel中分析的 result.csv 文件。如需调整文件路径或其他参数,请根据实际情况修改代码。
- 可使用文本编辑器(如Sublime)将 CSV 文件的编码转换为GBK,然后再用Excel打开。
- 或在Excel中新建一个Excel文件,并在导入数据时指定正确的编码格式 UTF-8。
接口限流
接口 | 限流(主账号级别) |
|---|---|
创建任务 | 1000 次/分钟,最大并行 1000 个 |
查询任务 | 1000 次/分钟 |
查询任务列表 | 100 次/分钟 |
取消任务 | 1000 次/分钟 |
计费说明
- 计费单价: 所有成功请求的输入和输出Token,单价均为对应模型实时推理价格的50% ,具体请参见模型列表。
-
计费范围:
- 仅对成功执行的请求计费。
- 文件解析失败、任务执行失败或行级错误请求均不产生费用 。
- 已取消的任务中,取消前已成功完成的请求仍正常计费。
错误码
调用失败时,请参见错误码进行解决。
常见问题
- 如何选择使用 Batch Chat 还是Batch File? 处理包含大量请求的单个大文件且可异步获取结果时,选择 Batch File。需要以API同步调用方式高并发提交大量独立对话请求时,选择 Batch Chat。
- Batch File调用如何计费?需要单独购买吗? 答:Batch 是一种调用方式,采用后付费模式,按成功请求的 Token 用量计费,无需额外购买套餐。
- 提交的Batch File是按顺序执行的吗? 答:不是。系统采用动态调度机制,根据计算资源负载安排任务执行,不保证严格遵循提交顺序。资源紧张时,任务启动和执行可能延迟。
- 提交的Batch File需要多长时间完成? 答:执行时间取决于系统资源分配和任务规模。若任务在设定的 completion_window 内未完成,状态变为 expired,未处理的请求不再执行,也不产生费用。 场景建议:对时效性有严格要求的场景,建议使用实时调用;对时效性有一定容忍度的大规模数据处理场景,推荐使用 Batch 调用。