批量请求
Batch API 允许你提交大量请求并进行异步处理。这非常适合不需要立即响应的任务，例如数据处理、评测和向量嵌入生成。
工作原理
- 创建批量任务 — 上传包含请求的 JSONL 文件
- 提交批量任务 — 开始处理
- 监控进度 — 检查状态直到完成
- 获取结果 — 下载输出文件
创建批量输入文件
准备一个 JSONL 文件，其中每一行都是一个合法的请求对象：
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek/deepseek-v4-pro", "messages": [{"role": "user", "content": "Hello!"}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek/deepseek-v4-pro", "messages": [{"role": "user", "content": "How are you?"}]}}
{"custom_id": "request-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "z-ai/glm-5.1", "messages": [{"role": "user", "content": "Translate to French: Hello"}]}}请求格式
| 字段 | 类型 | 说明 |
|---|---|---|
custom_id | string | 你自定义的标识符，用于跟踪该请求 |
method | string | HTTP 方法（POST） |
url | string | API 端点路径（例如 /v1/chat/completions） |
body | object | 请求载荷（与同步 API 相同） |
上传并创建批量任务
# Step 1: Upload the input file
curl https://openapi.linkwo.ai/v1/files \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "purpose=batch" \
-F "file=@batch_input.jsonl"
# Step 2: Create the batch
curl https://openapi.linkwo.ai/v1/batches \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-abc123",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'检查批量任务状态
curl https://openapi.linkwo.ai/v1/batches/batch_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"状态值
| 状态 | 说明 |
|---|---|
validating | 正在校验输入文件 |
in_progress | 请求正在处理中 |
completed | 所有请求已完成 |
failed | 批量任务失败 |
expired | 批量任务超出了完成窗口 |
获取结果
批量任务完成后，下载输出文件：
curl https://openapi.linkwo.ai/v1/files/file_output_abc123/content \
-H "Authorization: Bearer YOUR_API_KEY" > batch_output.jsonl输出文件中的每一行对应一个输入请求：
{"id": "batch_req_abc", "custom_id": "request-1", "response": {"status_code": 200, "body": {"id": "chatcmpl-abc", "choices": [{"message": {"content": "Hello! How can I help you?"}}]}}}限制
| 限制项 | 值 |
|---|---|
| 每个批量任务的最大请求数 | 50,000 |
| 最大输入文件大小 | 200 MB |
| 完成窗口 | 最长 24 小时 |
| 最大并发批量任务数 | 10 |
使用场景
- 数据集评测 — 在基准数据集上运行提示词
- 批量向量嵌入 — 为大型文档语料库生成向量嵌入
- 内容生成 — 批量处理模板
- 模型对比 — 在不同模型上运行相同的提示词
最佳实践
- 使用
custom_id将输出与你的输入记录一一对应 - 先用小批量任务验证，再逐步扩大规模
- 监控批量任务状态，并采用指数退避策略进行轮询
- 将超大的工作负载拆分为多个批量任务