​
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是统一的。 下面是一个包含 2 个请求的输入文件示例。
{"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}}
{"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}}

其中custom_id和body的messages是必须内容，其他部分为非必需内容。

​
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，作为后面创建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"
)
const 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 获取所有批量推理列表

支持查看用户下的所有批量推理任务列表,暂时不支持分页查询。

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY", 
    base_url="https://api.siliconflow.cn/v1"
)
client.batches.list()

​
3. 支持模型列表

目前仅支持端点/v1/chat/completions，且支持模型如下：

  • deepseek-ai/DeepSeek-V3
  • deepseek-ai/DeepSeek-R1

​
4. 输入限制：

Batch Job 输入限制与现有的按模型速率限制是分开的，参考如下条件：

  1. 每 batch 限制： 单个 batch 对应的输入文件的大小最大1 G。

说明：Batch Job 的请求不影响用户在线推理服务的 Rate Limits 使用。因此使用批量 API 不会消耗标准请求中的（用户，模型）维度的 Rate Limits的Request 或者 tokens 限制。

​
5. 费用说明

Batch 只能使用充值余额进行支付，具体价格如下：

模型微调Rate Limits