批量推理
批量推理（Batch）让支持一次性提交大量推理请求。你可以将请求整理成 JSONL 文件，由 wylon 后台异步执行，并在完成窗口内回传结果。 相比实时 对话请求，批量推理的并发限制更宽松、成本更优，适合离线评估、数据生成、文档批处理等非实时场景。
推荐场景
为大批量历史数据生成摘要、分类、标签或翻译。
使用固定输入集测试多个模型或参数组合，便于对比效果。
基于种子提示批量生成训练样本或测试样本。
适合对延迟不敏感、希望避开白天实时额度峰值的任务。
如果业务需要立即返回结果，例如在线对话、Agent 或 RAG 实时问答等，请使用 对话请求。
实时 vs. 批量
| 对话补全（实时） | 批量推理（异步） | |
|---|---|---|
| 调用方式 | 同步 HTTP/SSE | 异步任务（轮询或回调） |
| 响应时延 | 毫秒级 | 分钟到小时级，需在窗口期内完成 |
| 定价 | 按 Token 标准价 | 按 Token 批量折扣价 |
| 速率限制 | 受 RPM/TPM 限制，详见 速率限制 | 独立配额，并发更宽松 |
| 支持的接口 | chat completions / completions | chat completions / completions |
使用流程
批量推理的核心是将请求整理成 JSONL 文件，上传后由 wylon 后台异步执行。整个流程包含四个步骤：
-
准备 JSONL 文件
每行一个请求对象，结构与单次
/v1/chat/completions请求一致，并通过外层custom_id标识结果。 -
上传文件
调用
POST /v1/files上传 JSONL 输入文件，获取对应的file_id。 -
创建批量任务
适用
file_id调用POST /v1/batches，并指定目标接口与完成期限。 -
轮询状态并下载结果
通过
GET /v1/batches/{id}查询任务进度。任务完成后，下载output_file_id对应的结果文件。结果文件中每一行对应一个输入请求。
输入文件格式
输入文件的每一行都是一个完整请求对象。method 与 url 用于指定目标接口，body 与普通对话补全请求体保持一致。
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "moonshotai/Kimi-K2", "messages": [{"role": "user", "content": "用一句话解释 KV 缓存。"}]}}
{"custom_id": "req-002", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "moonshotai/Kimi-K2", "messages": [{"role": "user", "content": "用一句话解释推测解码。"}]}}API 调用
批量推理流程包含三个端点：上传文件、创建任务、查询状态。所有调用均使用账户级 API 密钥。
如下以 Python 和 cURL 为例展示了如何上传输入文件、创建批量任务、轮询状态并下载结果。
from openai import OpenAI
import os, time
client = OpenAI(
api_key=os.environ["WYLON_API_KEY"],
base_url="https://api.wylon.cn/v1",
)
# 1. 上传输入文件
file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
# 2. 创建批量任务
batch = client.batches.create(
input_file_id=file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
# 3. 轮询完成
while batch.status in {"validating", "in_progress", "finalizing"}:
time.sleep(30)
batch = client.batches.retrieve(batch.id)
# 4. 下载结果
result = client.files.content(batch.output_file_id)
open("results.jsonl", "wb").write(result.read())# 1. 上传输入文件
curl https://api.wylon.cn/v1/files \
-H "Authorization: Bearer $WYLON_API_KEY" \
-F purpose=batch \
-F file=@requests.jsonl
# 响应：{ "id": "file-abc...", ... }
# 2. 创建批量任务
curl https://api.wylon.cn/v1/batches \
-H "Authorization: Bearer $WYLON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-abc...",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'
# 3. 轮询状态
curl https://api.wylon.cn/v1/batches/batch_xxx \
-H "Authorization: Bearer $WYLON_API_KEY"
# 4. 状态变为 completed 后下载结果
curl https://api.wylon.cn/v1/files/file-out.../content \
-H "Authorization: Bearer $WYLON_API_KEY" -o results.jsonl任务状态
| 状态 | 含义 |
|---|---|
validating | 正在校验输入文件格式和配额。 |
in_progress | 任务正在调度或执行。 |
finalizing | 请求已处理完成，正在生成结果文件。 |
completed | 任务全部完成，可通过 output_file_id 下载结果。 |
failed | 任务整体失败，可通过errors 字段查看原因。 |
expired | 未在 completion_window 内完成，已完成的部分仍可获取。 |
cancelling / cancelled | 用户主动取消。 |
输出文件
输出文件每行是一条响应，并通过 custom_id 与输入请求一一对应。失败请求会写入 error_file_id，便于后续单独重试。
{"custom_id": "req-001", "response": {"status_code": 200, "body": {"id": "cmpl-...", "choices": [{"message": {"role": "assistant", "content": "…"}, "finish_reason": "stop"}], "usage": {"total_tokens": 128}}}
{"custom_id": "req-002", "response": {"status_code": 200, "body": {"id": "cmpl-...", "choices": [{"message": {"role": "assistant", "content": "…"}}], "usage": {"total_tokens": 96}}}