文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>大模型服务平台 TokenHub>调用指南>批量推理

批量推理

最近更新时间：2026-04-22 17:14:01

我的收藏

本页目录：

Tokenhub 支持以 API 的形式发起批量推理任务，以下介绍使用方法：

BaseURL

境内：https://tokenhub.tencentmaas.com/v1/chat/completions
境外：https://tokenhub-intl.tencentmaas.com/v1/chat/completions

支持的模型

模型名称
model 参数值
GLM-5
glm-5
GLM-5.1
glm-5.1

使用步骤

步骤一：准备推理数据

支持 JSONL 格式文件，每行一条，将文件上传到任意公开可访问的 HTTP 地址（如腾讯云 COS 公开桶），记录 URL。
数据参考如下：
{"custom_id":"req-001","method":"POST","url":"/v1/chat/completions","body":{"model":"glm-5","messages":[{"role":"user","content":"你好，请介绍一下你自己"}],"max_tokens":200}}
{"custom_id":"req-002","method":"POST","url":"/v1/chat/completions","body":{"model":"glm-5","messages":[{"role":"user","content":"请用一句话总结机器学习"}],"max_tokens":200}}
字段说明：
字段
必填
说明
custom_id
是
自定义请求 ID，文件内唯一，用于关联输出结果。
method
是
固定填 "POST"。
url
是
固定填 "/v1/chat/completions"。
body.model
是
模型名称，如 "glm-5"。
body.messages
是
对话消息，格式同 Chat Completions API。
body.max_tokens
否
最大输出 Token 数。

步骤二：创建批量任务

请求参数：
参数名
必选
类型
描述
input_file_id
是
String
批量任务处理文件下载路径，建议使用腾讯云 COS 公开桶。
completion_window
是
String
任务处理最大时长，如：24h，超出时长后，未处理的数据将不再处理。
name
是
String
任务名称。
输入示例：
# 请将 YOUR_API_KEY 替换为您的 API KEY（sk- 开头）
# 请将 YOUR_DATA_URL 替换为您步骤一上传的文件下载路径
API_KEY="YOUR_API_KEY"
BASE_URL="https://tokenhub.tencentmaas.com" 
INPUT_URL="YOUR_DATA_URL"

curl -X POST "${BASE_URL}/v1/batches" \\ 
  -H "Authorization: Bearer ${API_KEY}" \\ 
  -H "Content-Type: application/json" \\ 
  -d "{
    \\"input_file_id\\": \\"${INPUT_URL}\\",
    \\"completion_window\\": \\"24h\\",
    \\"name\\": \\"my-batch-job\\"
  }"
响应示例（HTTP 202）：
{
  "id": "batch_a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "https://your-bucket.cos.ap-guangzhou.myqcloud.com/input.jsonl",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1744689600,
  "expires_at": 1744948800,
  "request_counts": {"total": 1000, "completed": 0, "failed": 0}
}
注意：
1. 若 input_file_id 无法访问，创建会立即返回 400 input_file_unavailable。
2. 返回的 id（即 batch_id）可用于后续查询。

步骤三：查询任务状态

# 请将 YOUR_API_KEY 替换为您的 API KEY（sk- 开头）
BATCH_ID="batch_a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # 替换为创建时返回的 id
curl "https://tokenhub.tencentmaas.com/v1/batches/${BATCH_ID}" \\ 
  -H "Authorization: Bearer ${YOUR_API_KEY}"
任务完成后（status: "completed"）响应：
{
  "id": "batch_a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "completed",
  "output_file_id": "https://internal-cos.cos.ap-guangzhou.myqcloud.com/batch_.../output.jsonl?q-sign-algorithm=sha1&q-ak=...&q-signature=...",
  "error_file_id": null,
  "request_counts": {"total": 1000, "completed": 998, "failed": 2}
}
状态说明：
状态
说明
validating
已提交，正在验证和排队
in_progress
执行中，request_counts.completed 实时更新
completed
已完成，output_file_id / error_file_id 有效
cancelling
取消中
cancelled
已取消
failed
任务失败
expired
超过 completion_window 未完成

步骤四：下载结果

# 针对特定的 BATCH_ID，从查询响应中提取 output_file_id 并下载
# 请将 YOUR_API_KEY 替换为您的 API KEY（sk- 开头）
BATCH_RESP=$(curl -s "https://tokenhub.tencentmaas.com/v1/batches/${BATCH_ID}" \\ 
  -H "Authorization: Bearer ${API_KEY}")

OUTPUT_URL=$(echo "${BATCH_RESP}" | python3 -c \\ 
  "import sys,json; d=json.load(sys.stdin); print(d.get('output_file_id') or '')")

ERROR_URL=$(echo "${BATCH_RESP}" | python3 -c \\ 
  "import sys,json; d=json.load(sys.stdin); print(d.get('error_file_id') or '')")

# 下载成功结果
[ -n "${OUTPUT_URL}" ] && curl -o output.jsonl "${OUTPUT_URL}" && echo "已保存 output.jsonl"

# 下载失败记录（有失败行时才有）
[ -n "${ERROR_URL}" ] && curl -o error.jsonl "${ERROR_URL}" && echo "已保存 error.jsonl"
注意：
output_file_id 是预签名 URL，有效期 24 小时，过期后需要重新查询获取新链接。
output.jsonl 每行格式（兼容 OpenAI）：
{
  "id": "batch_req_req-001",
  "custom_id": "req-001",
  "response": {
    "status_code": 200,
    "body": {
      "id": "chatcmpl-xxx",
      "object": "chat.completion",
      "model": "glm-5",
      "choices": [{"message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}],
      "usage": {"prompt_tokens": 10, "completion_tokens": 50, "total_tokens": 60}
    }
  },
  "error": null
}
error.jsonl 每行格式（有失败行时）：
{"id":"batch_req_req-002","custom_id":"req-002","response":null,"error":{"code":"rate_limit","message":"429 Too Many Requests"}}

其他相关接口

列表查询

按创建时间倒序，支持游标翻页：
# 请将 YOUR_API_KEY 替换为您的 API KEY（sk- 开头）
# 第一页
curl "https://tokenhub.tencentmaas.com/v1/batches?limit=20" \\ 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# 翻页（使用上次响应的 last_id）
curl "https://tokenhub.tencentmaas.com/v1/batches?limit=20&after=batch_xxxxxxxx" \\ 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

取消任务

# 请将 YOUR_API_KEY 替换为您的 API KEY（sk- 开头）
curl -X POST "https://tokenhub.tencentmaas.com/v1/batches/${BATCH_ID}/cancel" \\ 
  -H "Authorization: Bearer ${YOUR_API_KEY}"
注意：
已处于终态（completed/cancelled/failed/expired）的任务无法取消，返回 409 Conflict。

接口频率限制

限制项
限额
创建任务
20 次/分钟/账号
并发活跃任务数
10 个/账号
超出限频返回 HTTP 429，建议使用指数退避策略重试。



中国站