1. 概述

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

2. 使用流程

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

批量推理任务输入文件格式为 .jsonl,其中每一行都是一个完整的 API 请求的消息体,需满足以下要求:

  • 每一行必须包含custom_id,且每个custom_id须在当前文件中唯一;
  • 每一行的body中的必需包含messages对象数组,且数组中消息对象的rolesystemuserassistant之一,并且整个数组以user消息结束;
  • 您可以为每一行数据按需设置相同或不同的推理参数,如设定不同的temperaturetop_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_idbodymessages是必须内容,其他部分为非必需内容。

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 只能使用充值余额进行支付,具体价格如下: