兼容 OpenAI 的 Batch API

上传 JSONL 批量输入文件并通过 Model Gate 的持久队列处理与 OpenAI 兼容的批次。

兼容 OpenAI 的 Batch API

Model Gate 实现了 OpenAI Files + Batch 工作流程 https://api.model-gate.com/v1。这是一个兼容层：每个 JSONL 项都通过正常的 Model Gate 推理路径执行。模型门确实不是提交上游提供商原生 OpenAI 批次。

文件/批量读取/控制端点是一个控制平面：即使帐户余额当前为零或可重置的支出限制已用尽，其他有效的活动 API 凭证也可以列出/读取/下载/取消/删除现有资源。存储生成操作不同： POST /v1/files 和 POST /v1/batches 在 Model Gate 插入文件/作业/项目数据之前需要新的正余额/支出准入。因此，零余额密钥无法上传 JSONL 或创建新的批量存储。实际批次项目仍会在工人索赔时重新检查入场情况，并且如果资金稍后用完，则仍会保持排队状态。 JSONL 输入被增量读取并逐行验证/插入；创建批次时，Model Gate 不会保留完整的 200 MB 输入以及进程内存中的所有请求主体。每用户存储字节/文件/活动作业/队列项目配额提供独立的数据库滥用边界。

此版本中支持的批处理端点有：

/v1/responses
/v1/chat/completions
/v1/embeddings
/v1/images/generations

每个执行的项目都被标记 request_mode=batch, batch_protocol=openai，以其 batch_job_public_id 和 custom_id。

1.上传JSONL输入文件

每个非空行包含 custom_id, method, url，和 body。 URL 必须等于稍后提供给的端点 /v1/batches。

例子 batch.jsonl:

{"custom_id":"request-1","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.4","input":"Summarize this text."}}
{"custom_id":"request-2","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.4","input":"Classify this text."}}

要求

curl https://api.model-gate.com/v1/files \
  -H "Authorization: Bearer mg_live_..." \
  -F "purpose=batch" \
  -F "[email protected]"

回应 — 200

{
  "id": "file-01K...",
  "object": "file",
  "bytes": 322,
  "created_at": 1786610000,
  "filename": "batch.jsonl",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

2. 创建批次

completion_window 必须是 24h。

要求

curl https://api.model-gate.com/v1/batches \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id":"file-01K...",
    "endpoint":"/v1/responses",
    "completion_window":"24h",
    "metadata":{"job":"nightly-evaluation"}
  }'

回应 — 200

{
  "id": "batch_01K...",
  "object": "batch",
  "endpoint": "/v1/responses",
  "input_file_id": "file-01K...",
  "completion_window": "24h",
  "status": "in_progress",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "job": "nightly-evaluation"
  }
}

3. 检索批次

要求

curl https://api.model-gate.com/v1/batches/batch_01K... \
  -H "Authorization: Bearer mg_live_..."

回应——已完成

{
  "id": "batch_01K...",
  "object": "batch",
  "endpoint": "/v1/responses",
  "status": "completed",
  "output_file_id": "file-01KOUTPUT...",
  "error_file_id": null,
  "request_counts": {
    "total": 2,
    "completed": 2,
    "failed": 0
  },
  "usage": {
    "input_tokens": 240,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 90,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 330
  }
}

4. 下载结果

要求

curl https://api.model-gate.com/v1/files/file-01KOUTPUT.../content \
  -H "Authorization: Bearer mg_live_..."

回应 — 200

{"id":"batch_req_01K...","custom_id":"request-1","response":{"status_code":200,"request_id":"01K...","body":{"id":"resp_...","status":"completed"}},"error":null}

失败、取消或过期的项目将写入 error_file_id 作为 JSONL 记录 response:null 和一个 error 目的。

5. 列出批次

limit 默认为 20 并且必须来自 1 到 100。使用 after 用于光标分页。

要求

curl "https://api.model-gate.com/v1/batches?limit=20&after=batch_01K..." \
  -H "Authorization: Bearer mg_live_..."

回应 — 200

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

完成的批处理对象可能包括聚合 usage 当已解决的模型门请求记帐可用时对象。

6. 取消批次

取消可防止排队项目开始；已经处理的项目可能会完成。

要求

curl -X POST https://api.model-gate.com/v1/batches/batch_01K.../cancel \
  -H "Authorization: Bearer mg_live_..."

回应 — 200

{
  "id": "batch_01K...",
  "object": "batch",
  "status": "cancelling",
  "request_counts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  }
}

7. 文件元数据、列出和删除

检索元数据：

curl https://api.model-gate.com/v1/files/file-01K... \
  -H "Authorization: Bearer mg_live_..."

{
  "id": "file-01K...",
  "object": "file",
  "bytes": 322,
  "filename": "batch.jsonl",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1789202000
}

列出带有可选选项的文件 purpose, after，和 order=asc|desc; limit 默认为 10000 并且必须来自 1 到 10000:

curl "https://api.model-gate.com/v1/files?purpose=batch&order=desc&limit=100" \
  -H "Authorization: Bearer mg_live_..."

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

删除未引用/过期的兼容文件：

curl -X DELETE https://api.model-gate.com/v1/files/file-01K... \
  -H "Authorization: Bearer mg_live_..."

{
  "id": "file-01K...",
  "object": "file",
  "deleted": true
}

限制和恢复语义

Model Gate 最多接受 50,000 个 JSONL 项，并将上传的文件限制为配置的文件 OPENAI_BATCH_MAX_FILE_BYTES 值（默认为 200 MiB）。每个单独的批次项目也必须符合模型门的正常情况 MAX_REQUEST_BODY_BYTES 限制。 custom_id 值必须是唯一的。批量项目不能使用 stream:true 或嵌套 async:true。大型 JSONL 文件在内部保留为数据库块，而不是一个超大的 SQL 值。

执行恢复是 至少一次，不完全是一次。如果工作线程在接受上游请求之后但在持久记录其结果之前停止，则过期的租约可能会导致重试相同的 Model Gate 请求 ID。对于已经完成的请求行，结算仍然是幂等的，但模型发起的工具/外部副作用本身应该是幂等的。

每个 JSONL 项目在工作人员声明它之前立即被接纳。否则，当当前帐户余额为负数或密钥/组可重置支出限额已用完时，有效项目将保持排队状态。这种等待状态不会消耗尝试或创建错误记录；稍后充值、使用重置或限制增加会自动使剩余项目符合资格。 Model Gate 不保留理论上的最大批量成本。因此，即使并发工作导致最终余额为负值或产生小额支出限额超支，已接纳的项目也可能会全额结算，之后新项目仍将排队，直到帐户再次符合资格。

定价和会计

批处理适配器不使用提供程序本机批处理执行。每个项目都会经过正常的 Model Gate 模型路由和结算，然后收到定价模板的 批量请求价格系数。默认： 1。

如果系数是 0.5，正常模型门成本为的物品 0.02 借记为 0.01。官方参考价格保持不变。所应用的系数被快照并存储在审计请求中。

错误

{
  "error": {
    "message": "line 2 url must match batch endpoint /v1/responses",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_batch_file"
  }
}