批量任务推理

批量任务推理适合离线评测、批量摘要、数据清洗等无需即时返回结果的场景。你需要先把请求保存为 JSONL 文件并提供可公开访问的 URL，再提交异步任务；任务完成后，通过结果文件中的 custom_id 关联输入与输出。

信息

Batch 是 Modelink 平台提供的异步任务能力，并非底层模型的原生接口。实时对话仍应使用对应的聊天或原厂协议接口。

接入点与模型协议

当前批量推理仅开放国内接入点：

https://api.qnaigc.com/v1

海外域名暂未开放。无论使用国内模型还是 Claude、Gemini 等海外模型，批量任务管理接口均通过上述国内接入点调用；不同模型类型的 JSONL 请求结构仍有差异。

项目	国内模型	Claude、Gemini 等海外模型
JSONL 请求字段	`body`，使用 OpenAI 风格消息结构	`request`，使用目标厂商的原生请求结构
任务管理路径	`/batchjob/...`	`/batchjob/...`
结果获取	读取 `output_files_url`	读取 `output_files_url`

支持 Batch 的模型会随平台资源变化。请以控制台当前可用模型为准，不要把实时推理可用等同于支持批量推理。

支持批量推理的模型列表

目前支持以下模型：

模型系列	支持的模型 ID
Claude	`claude-4.7-opus`、`claude-4.6-opus`、`claude-4.6-sonnet`、`claude-4.5-opus`、`claude-4.5-sonnet`、`claude-4.5-haiku`、`claude-4.1-opus`、`claude-4.0-opus`、`claude-4.0-sonnet`
Gemini	`gemini-3.1-pro-preview`、`gemini-3.1-flash-image-preview`、`gemini-3.1-flash-lite-preview`、`gemini-3.0-pro-image-preview`、`gemini-3.0-flash-preview`、`gemini-2.5-pro`、`gemini-2.5-flash-image`、`gemini-2.5-flash`、`gemini-2.5-flash-lite`、`gemini-2.0-flash`、`gemini-2.0-flash-lite`
DeepSeek	`deepseek-r1`、`deepseek-r1-32b`、`deepseek-v3`

准备工作

先配置接入点和 API Key。完整认证要求请参阅认证与请求。

export MODELINK_API_KEY="替换为你的 Modelink API Key"
export MODELINK_BASE_URL="https://api.qnaigc.com/v1"

所有接口使用 Bearer 认证：

Authorization: Bearer <api_key>

准备 JSONL 输入文件

输入文件需要满足以下要求：

文件格式为 JSONL，每行是一个独立 JSON 对象。
每行必须包含唯一的 custom_id；重复值会导致任务失败。
文件 URL 必须能被服务端公开访问，不能依赖 Cookie、登录态或内网地址。
单个文件不超过 100 MB。
每行的请求结构必须与所选模型协议匹配。

国内模型示例

国内模型使用 body 包裹 OpenAI 风格的请求：

{"custom_id":"request-001","body":{"messages":[{"role":"user","content":"总结这段文本"}],"max_tokens":1000}}
{"custom_id":"request-002","body":{"messages":[{"role":"user","content":"提取其中的关键实体"}],"max_tokens":1000}}

海外 Claude 模型示例

Claude 模型使用 request 包裹 Anthropic 风格的请求：

{"custom_id":"request-001","request":{"messages":[{"role":"user","content":"Summarize this document."}],"max_tokens":2000,"temperature":0.2}}

海外 Gemini 模型示例

Gemini 模型使用 request 包裹 Gemini 原生请求：

{"custom_id":"request-001","request":{"contents":[{"role":"user","parts":[{"text":"Summarize this document."}]}],"generationConfig":{"temperature":0.2,"maxOutputTokens":2000}}}

创建任务

调用 POST /batchjob/inference：

curl "$MODELINK_BASE_URL/batchjob/inference" \
  -H "Authorization: Bearer $MODELINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "离线摘要任务",
    "model": "<控制台中的 Batch 模型 ID>",
    "description": "2026-07 文档摘要",
    "input_files_url": "https://example.com/batch/input.jsonl"
  }'

创建成功后会返回任务 ID：

{
  "id": "bat-<task-id>"
}

保存该 ID。后续查询、停止、恢复和删除都需要它。

查询任务

查询单个任务

export BATCH_ID="bat-<task-id>"

curl "$MODELINK_BASE_URL/batchjob/inference/$BATCH_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

任务常见状态如下：

状态	含义	建议操作
`Queued`	等待调度	继续轮询
`Running`	正在处理	继续轮询
`Completed`	已完成	读取 `output_files_url`
`Failed`	执行失败	查看 `status_message`，修正后新建或恢复任务
`Terminating`	正在停止	等待进入终态
`Terminated`	已停止	确认条件后恢复或删除

建议采用退避轮询，避免以固定高频请求持续查询。

查询任务列表

列表接口使用复数路径 GET /batchjob/inferences：

curl "$MODELINK_BASE_URL/batchjob/inferences?page=1&page_size=20" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

page 从 1 开始，page_size 最大为 100。

获取结果

任务进入 Completed 后，详情中的 output_files_url 指向结果文件：

{
  "id": "bat-<task-id>",
  "status": "Completed",
  "status_message": "任务已完成",
  "output_files_url": "https://example-download-host/output.jsonl"
}

警告

结果地址包含临时访问凭证，不要公开传播。当前结果地址通常有效 7 天，请在任务完成后及时下载并存入自己的受控存储。

逐行解析结果文件，并通过 custom_id 与输入记录关联。不要依赖结果行顺序与输入顺序完全一致。

停止、恢复和删除

停止尚未完成的任务：

curl -X POST "$MODELINK_BASE_URL/batchjob/inference/stop/$BATCH_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

恢复已停止或失败且允许恢复的任务：

curl -X POST "$MODELINK_BASE_URL/batchjob/inference/resume/$BATCH_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

删除任务记录：

curl -X DELETE "$MODELINK_BASE_URL/batchjob/inference/$BATCH_ID" \
  -H "Authorization: Bearer $MODELINK_API_KEY"

不同状态允许的操作不同。收到状态冲突错误时，先重新查询任务状态，不要盲目重试写操作。

失败处理

常见错误包括：

错误类型	排查方向
`authentication_error`	API Key 无效、过期或无目标能力权限
`invalid_request_error`	请求字段、文件 URL 或任务状态不符合要求
`invalid_model_error`	模型不存在或不支持 Batch
`file_processing_failed`	文件无法下载、超过限制、不是合法 JSONL 或行结构错误
`create_batch_job_failed`	平台创建任务失败，保留请求 ID 后联系支持

提交前建议在本地逐行解析 JSONL，并检查 custom_id 唯一性。业务侧为每次提交生成自己的幂等标识并保存任务 ID，避免客户端超时后直接重复创建相同任务。

批量任务不占用常规聊天接口的 RPM、TPM 或并发配额，但仍可能受到任务队列、API Key 权限和平台策略限制，详见限流与配额。