Batch API 教程

本教程将指导用户如何在 GenStudio 上使用 Batch API 进行离线推理任务。

概述

GenStudio 支持两种 Batch 任务执行方式：

• 方式 1：使用 GenStudio 专用 Batch API 创建 batch 任务实现离线推理，完成批量任务后返回结果文件，Batch API 兼容 OpenAI Python SDK。
• 方式 2：使用 OpenAI ChatCompletion API 通过批量推理接入点 batch-deepseek-r1 或 batch-deepseek-v3。

警告

• 当前批量推理任务暂不支持单独调整 API 限频，会受到租户下 API 限频影响。具体限频请参考 API 限频。
• 使用方式 1 时，无需担心超过 API 频率限制错误（429 错误），GenStudio 将自动适应，确保请求成功。
• 使用方式 2 时，如遇到 429 错误，需要您自行在代码中实现重试逻辑。

批量推理模型

批量推理必须使用专用模型。无论哪种方式，都需要使用以下专用模型：

• batch-deepseek-r1
• batch-deepseek-v3

重要

批量推理专用模型需在申请开通后使用，请联系商务或售后。

方式 1：使用 Batch API

使用 GenStudio 专用 Batch API 创建 batch 任务实现离线推理。

准备 Batch 任务的输入文件

Batch 任务的输入文件格式为 .jsonl，其中每个请求占据一行（JSON 对象）。每个请求必须包含：

• 一个唯一的 custom_id，用来将结果和输入进行匹配。
• 单个 batch 文件只能包含对单个模型的请求。

.jsonl 文件最多支持 50,000 个请求，且大小不超过 200MB。以下是一个包含 2 个请求的示例：

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "batch-deepseek-v3", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "batch-deepseek-v3", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

初始化 OpenAI 客户端

• GENSTUDIO_API_KEY：GenStudio API key
• DEFAULT_BASE_URL：GenStudio API URL，请使用 https://cloud.infini-ai.com/maas/v1

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.getenv("GENSTUDIO_API_KEY"), 
    base_url=os.getenv("DEFAULT_BASE_URL")
)

上传 Batch 任务的输入文件

使用 OpenAI Python SDK 上传输入文件，并记录返回的文件 ID 以便创建 batch 任务。

# client 为上一步初始化的 OpenAI 客户端
batch_input_file = client.files.create(
    file=open("batchinput.jsonl", "rb"),
    purpose="batch"
)
print(batch_input_file.data['id'])  # 获取文件上传后的id

创建 Batch 任务

成功上传输入文件后，使用文件 ID 创建 Batch 任务。在本示例中，假设文件 ID 为 lbuf-123，生成的 batch 任务 ID 为 lbj-123。

# client 为上一步初始化的 OpenAI 客户端
batch_job = client.batches.create(
    input_file_id="lbuf-123",  # 传入从上一步中获取的file id
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={"description": "数据蒸馏任务01"},  # metadata参数可以用于备注一些额外的任务信息
    extra_body={"replace": {"model": "batch-deepseek-r1"}}  # 如果extra_body中设置的模型与jsonl中的model不一致，则任务使用extra_body中模型推理
)
print(batch_job)
print(batch_job.id)  # batch任务的id

该请求将创建一个批量推理任务，并返回任务的状态信息。

查询 Batch 任务状态

检查 batch 任务状态，状态为 "completed" 表示任务已完成。

# client 为第一步初始化的 OpenAI 客户端
batch = client.batches.retrieve("lbj-123")
print(batch)

返回的推理任务状态信息如下：

{
    "id": "lbj-123",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "lbuf-123",
    "completion_window": "24h",
    "status": "completed",
    "output_file_id": "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123",
    "error_file_id": "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/321",
    "created_at": 1751427145,
    "in_progress_at": 1751427427,
    "expires_at": 1751513544,
    "completed_at": 1751427428,
    "failed_at": null,
    "expired_at": null,
    "request_counts": {
        "total": 10,
        "completed": 0,
        "failed": 10
    },
    "metadata": {
        "description": "数据蒸馏任务01"
    }
}

其中 status 包含以下几种状态：

• in_queue：任务在排队中
• in_progress：任务正在进行中
• completed：任务已完成
• cancelling：任务取消中
• cancelled：任务已取消

下载结果文件

系统将批量推理的结果文件按请求状态分别保存：

• output_file_id：包含所有成功请求的输出结果文件。
• error_file_id：包含所有失败请求的错误信息文件。

警告

系统将保留结果文件 30 天。请务必在有效期内及时下载并备份相关数据。超过保存期限的文件将被自动删除，且无法恢复。

可以使用 wget 或 curl 下载：

# 采用wget
wget -O output.jsonl "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123"

# 采用curl
curl -o output.jsonl "https://infini-imagegen-userupload.oss-cn-beijing.aliyuncs.com/123"

注意

若 OSS 链接过期返回 403 Forbidden，请重新执行上一步查询 Batch 状态以获取新的 OSS URL。

取消 Batch 任务

如有必要，可以取消正在进行的批量处理任务。任务状态将变为 cancelling，直到在途的请求完成（该过程最长为5分钟），之后状态将变为 cancelled。

# client 为第一步初始化的 OpenAI 客户端
client.batches.cancel("lbj-123")

获取所有 Batch 任务列表

支持查看用户下的所有 Batch 任务列表。

# client 为第一步中初始化的 OpenAI 客户端
client.batches.list()

方式 2：使用 Chat Completions API 接入批量推理

使用 Chat Completions API 接入批量推理时，仅需更改 model 字段即可，结果直接在 reponse 中返回。当平台有资源剩余，请求成功。如超过限频，会被暂时拒绝并收到 429 Too Many Requests，被拒后可通过代码参考租户的具体限频进行重试。

curl --request POST \
  --url https://cloud.infini-ai.com/maas/v1/chat/completions \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
      "model": "batch-deepseek-r1",
      "messages": [
        {"role": "user", "content":"你是谁"}
      ]
    }'

提示

该接口根据流量实际情况动态调整，日间繁忙时段允许并发低，夜间空闲时段允许并发高。

支持模型列表

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

• batch-deepseek-v3
• batch-deepseek-r1

费用说明

Batch 任务有特定的定价，具体价格如下：

模型名称	批量推理 - 输入	批量推理 - 输出
batch-deepseek-v3	¥2	¥8
batch-deepseek-r1	¥1	¥4

GenStudio 推理模型价格单位：￥/百万 Tokens。

重要

• 在发起批量推理任务前，建议您自行计算输入和输出价格，确保您的账户余额充足。 批量推理专用模型需在申请开通后使用，请联系商务或售后。

常见问题

如果在批量任务执行过程中账户欠费，会导致任务状态变更吗？比如任务会直接结束吗？

不会，欠费是请求的状态，而不是任务的状态。批量任务的状态（如 in_queue、in_progress、completed、cancelling、cancelled）不会因为欠费而发生变更。即使账户一开始就处于欠费状态，任务本身依然会成功创建并执行，只不过所有请求可能会返回欠费状态。

在批量任务执行过程中欠费，能否获取中间结果？比如获取已处理的数据，放弃未处理的数据？

欠费状态下，任务会继续执行。但欠费后， API 请求结果可能无法正常返回。

如果在欠费状态下补足余额，批量任务会自动恢复吗？

不会。您需要重新发起任务，但仅需处理未完成的请求。