​
1. 概述

通过批量 API 发送批量请求到 SiliconCloud 云服务平台，不受在线的速率限制和影响，预期可以在 24 小时内完成，且价格降低 50%。该服务非常适合一些不需要立即响应的工作，比如大型的任务评估、信息分类与提取、文档处理等。批量处理结果文件的 URL 有效期为一个月，请及时转存，以防过期影响业务。

​
2. 使用流程

​
2.1 准备批量推理任务的输入文件

批量推理任务输入文件格式为 .jsonl，其中每一行都是一个完整的 API 请求的消息体，需满足以下要求：
  • 每一行必须包含custom_id，且每个custom_id须在当前文件中唯一；
  • 每一行的body中的必需包含messages对象数组，且数组中消息对象的role 为system、user或assistant之一，并且整个数组以user消息结束；
  • 您可以为每一行数据按需设置相同或不同的推理参数，如设定不同的temperature、top_p；
  • 如果您希望使用 OpenAI SDK 调用 SiliconCloud 批量推理，您需要保证同一输入文件中model是统一的。
  • 每 batch 限制：单个 batch 对应的输入文件的大小最大1 G
  • 批量推理输入限制：单个 批量推理 对应的输入文件的大小不超过 1 G，文件行数不超过 5000 行。 下面是一个包含 2 个请求的输入文件示例：
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek-ai/DeepSeek-V3", "messages": [{"role": "system", "content": "You are a highly advanced and versatile AI assistant"}, {"role": "user", "content": "How does photosynthesis work?"}], "stream": true, "max_tokens": 1514, "thinking_budget": 32768}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek-ai/DeepSeek-V3", "messages": [{"role": "system", "content": "You are a highly advanced and versatile AI assistant"}, {"role": "user", "content": "Imagine a world where everyone can fly. Describe a day in this world."}], "stream": true, "max_tokens": 1583, "thinking_budget": 32768}}
其中custom_id和body的messages是必须内容，其他部分为非必需内容。 对于推理模型，可以通过 thinking_budget 字段控制模型的思维链输出长度，示例如下： 
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek-ai/DeepSeek-R1", "messages": [{"role": "system", "content": "You are a highly advanced and versatile AI assistant"}, {"role": "user", "content": "How does photosynthesis work?"}], "stream": true, "max_tokens": 1514,"thinking_budget": 32768}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "deepseek-ai/DeepSeek-R1", "messages": [{"role": "system", "content": "You are a highly advanced and versatile AI assistant"}, {"role": "user", "content": "Imagine a world where everyone can fly. Describe a day in this world."}], "stream": true, "max_tokens": 1583,"thinking_budget": 32768}}

​
2.2 上传批量推理任务的输入文件

您需要首先上传输入文件，以便在启动批量推理时使用。以下为使用 OpenAI SDK 调用 SiliconCloud 输入文件的示例。 
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1"
)

batch_input_file = client.files.create(
    file=open("batch_file_for_batch_inference.jsonl", "rb"),
    purpose="batch"
)
print(batch_input_file)
# 获取文件上传后的id
file_id = batch_input_file.data['id']
print(file_id)
这里需要记录下返回结果中的id，作为后面创建batch时候的请求参数。

​
2.3 创建批量推理任务

成功上传输入文件后，使用输入文件对象的 ID 创建批量推理任务，并设置任务参数。
  • 对于对话模型，请求端点为/v1/chat/completions；
  • 完成窗口目前支持设置24 ～ 336 小时（14 ✕ 24 小时）；
  • 我们建议您通过extra_body设置任务需要使用的推理模型，如：extra_body={"replace":{"model": "deepseek-ai/DeepSeek-V3"}}，除非您的输入文件符合OpenAI的要求，文件中的每一行都具有相同的model；
  • 如果您的extra_body中设置的模型，与输入文件中的model不一致，则任务实际使用模型以extra_body为准；
  • metadata参数可以用于备注一些额外的任务信息，如任务描述等。 以下为使用 OpenAI SDK 调用 SiliconCloud 输入文件的示例，input_file_id 从上一步完成上传的文件对象中获取。
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1
)

batch_input_file_id = "file-abc123"
client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "description": "nightly eval job"
    },
    extra_body={"replace":{"model": "deepseek-ai/DeepSeek-V3"}}
)
该请求将创建一个批量推理任务，并返回任务的状态信息。

​
2.4 检查批量推理状态

您可以随时检查批量处理任务的状态，代码示例如下： 
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1"
)

batch = client.batches.retrieve("batch_abc123")
print(batch)
返回的推理任务状态信息如下： 
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}
其中status包含以下几种状态：
  • in_queue： 批量推理任务在排队中
  • in_progress： 批量推理任务正在进行中
  • finalizing： 批量推理任务已完成，正在准备结果
  • completed： 批量推理任务已完成，结果已准备就绪
  • expired： 批量推理任务没有在预期完成时间内执行完成
  • cancelling： 批量推理任务取消中（等待执行中结果返回）
  • cancelled： 批量推理任务已取消

​
2.5 取消正在进行中的批量推理任务

如有必要，您可以取消正在进行的批量处理任务。批量处理任务状态将变为cancelling，直到在途的请求完成，之后该任务的状态将变为cancelled。 
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1"
)
client.batches.cancel("batch_abc123")

​
2.6 获得批量推理结果

  1. 系统将批量推理的结果文件按请求状态分别保存：
  • output_file_id：包含所有成功请求的输出结果文件。
  • error_file_id：包含所有失败请求的错误信息文件。
  1. 系统将保留结果文件 30 天。请务必在有效期内及时下载并备份相关数据。超过保存期限的文件将被自动删除，且无法恢复。

​
2.7 获取所有批量推理列表

支持查看用户下的所有批量推理任务列表,暂时不支持分页查询。 
from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1"
)
client.batches.list()

​
2.8 批量推理任务超时（expired）

在指定时间未完成的批次最终会转入 expired 状态；该批次中未完成的请求会被取消，已完成请求的任何回复都会通过批量推理的输出文件提供。任何已完成的请求所消耗的tokens都将收取费用。 custom_id 已过期的请求将被写入错误文件，并显示如下信息。可以使用 custom_id 来检索已过期请求的请求数据。 
{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}

​
3. 支持模型列表

目前仅支持端点/v1/chat/completions，且支持模型如下：
  • deepseek-ai/DeepSeek-V3
  • deepseek-ai/DeepSeek-R1
  • Qwen/QwQ-32B

​
4. 输入限制：

Batch Job 输入限制与现有的按模型速率限制是分开的，参考如下条件：
  1. 每 batch 限制： 单个 batch 对应的输入文件的大小最大1 G。
说明：Batch Job 的请求不影响用户在线推理服务的 Rate Limits 使用。因此使用批量 API 不会消耗标准请求中的（用户，模型）维度的 Rate Limits的Request 或者 tokens 限制。

​
5. 费用说明

Batch 只能使用充值余额进行支付，具体价格如下：
SiliconCloud 平台推理模型价格表（单位：￥/百万 Tokens）
模型名称实时推理 - 输入实时推理 - 输出批量推理 - 输入批量推理 - 输出
DeepSeek-R1¥4¥16¥2¥8
DeepSeek-V3¥2¥8¥1¥4
Qwen/QwQ-32B¥1¥4¥0.5¥2
注：如有大规模使用需求，欢迎 联系我们 了解专属方案。