大模型服务平台 TokenHub 批量推理

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

一、BaseURL

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

二、支持的模型

三、步骤一：准备推理数据

支持 JSONL 格式文件，每行一条。需将文件上传到用户自有 腾讯云 COS 桶（支持公开桶和私有桶模式），通过 cos:// 路径引用。

数据参考如下：

{"custom_id":"req-001","method":"POST","url":"/v1/chat/completions","body":{"model":"hy4","messages":[{"role":"user","content":"你好，请介绍一下你自己"}],"max_tokens":200}}{"custom_id":"req-002","method":"POST","url":"/v1/chat/completions","body":{"model":"hy4","messages":[{"role":"user","content":"请用一句话总结机器学习"}],"max_tokens":200}}

注意：当前暂不支持在同一个数据文件中使用不同的模型，请确保同一个 JSONL 文件中 body.model 的唯一性。

字段说明：

四、步骤二：创建批量任务

请求参数：

输入示例：

API_KEY="sk-xxxxx" # 请替换为实际的 API KeyBASE_URL="https://tokenhub.tencentmaas.com"# 国内站：tokenhub.tencentmaas.com# 替换为你的 COS 信息INPUT_BUCKET="your-bucket-1250000000" # COS bucket 名（含 appid 后缀）INPUT_REGION="ap-guangzhou" # bucket 所在地域INPUT_KEY="inputs/batch-data.jsonl" # 输入文件对象 keyOUTPUT_PREFIX="outputs/" # 结果回写目录（必须以 / 结尾）curl -X POST "${BASE_URL}/v1/batches" \\ -H "Authorization: Bearer ${API_KEY}" \\ -H "Content-Type: application/json" \\ -d '{ "input_source": "user_cos", "input_file_id": "cos://'"${INPUT_BUCKET}"'.'"${INPUT_REGION}"'/'"${INPUT_KEY}"'", "output_target": "user_cos", "output_user_cos_path": "cos://'"${INPUT_BUCKET}"'.'"${INPUT_REGION}"'/'"${OUTPUT_PREFIX}"'", "completion_window": "24h", "name": "my-batch-cos" }'

响应示例（HTTP 202）：

{ "id": "batch_a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "object": "batch", "endpoint": "/v1/chat/completions", "input_file_id": "cos://your-bucket-1250000000.ap-guangzhou/inputs/batch-data.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" # 替换为创建时返回的 idcurl "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}}

状态说明：

六、步骤四：下载结果

# 针对特定的 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_user_cos_path 目录，output_file_id 返回对应的 cos:// 路径，可直接在 COS 控制台或通过 COS SDK 下载。

output.jsonl 每行格式（兼容 OpenAI）：

{ "id": "batch_req_req-001", "custom_id": "req-001", "response": { "status_code": 200, "body": { "id": "chatcmpl-xxx", "object": "chat.completion", "model": "hy4", "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。

九、接口频率限制

超出限频返回 HTTP 429，建议使用指数退避策略重试。