Batch、Files 与 Fine-tuning

AISIX AI 网关将兼容 OpenAI 的 Files、Batch 和 Fine-tuning API 作为一等代理路由暴露。客户端继续使用标准 OpenAI SDK 调用，由网关负责调用方认证、服务提供方凭证和已完成批处理的用量归因。

本指南将演示如何上传批处理输入文件、创建和跟踪批处理任务，并了解网关如何把每次调用路由到正确的服务提供方。

支持的路由

类型	路由
Files	`POST /v1/files`、`GET /v1/files`、`GET /v1/files/{id}`、`DELETE /v1/files/{id}`、`GET /v1/files/{id}/content`
Batch	`POST /v1/batches`、`GET /v1/batches`、`GET /v1/batches/{id}`、`POST /v1/batches/{id}/cancel`
Fine-tuning	`POST /v1/fine_tuning/jobs`、`GET /v1/fine_tuning/jobs`、`GET /v1/fine_tuning/jobs/{id}`、`POST /v1/fine_tuning/jobs/{id}/cancel`

目前支持兼容 OpenAI 的服务提供方（适配器为 openai，包括自定义 api_base 部署）和 Azure OpenAI（适配器为 azure-openai，使用资源作用域路由和 api-key 认证）。Vertex AI、Bedrock 和 Anthropic 原生批处理流程使用不同的传输协议和存储模型，暂不通过这些路由提供。

前提条件

开始前请准备：

一个可处理代理请求的 AISIX 网关。
一个可访问目标模型别名的调用方 API Key。
一个由兼容 OpenAI 或 Azure OpenAI 服务提供方支持的模型别名。

路由机制

创建批处理任务时，请求引用的是之前上传的文件 ID，请求体中没有可供网关路由的 model 字段。AISIX 通过网关编码的资源 ID 解决这一点：

上传文件时，通过 model multipart 字段、?model= 查询参数或 x-aisix-model 请求头指定一次路由模型。
网关返回的文件 ID 以 aisix- 开头，并编码了该模型。之后任何引用这个 ID 的调用，例如创建批处理、查询或下载文件、Fine-tuning 的 training_file，都会自动路由。
创建和查询响应返回的 ID（批处理 ID、输出文件 ID、Fine-tuning 任务 ID）也使用相同方式编码，后续调用不需要额外提示。

原始服务提供方 ID 仍然可用：网关会依次回退到显式 model 查询参数或请求头，再回退到调用方 Key 可访问的第一个兼容 OpenAI 模型。生产流量建议显式传入模型，确保路由可预测。

上传文件并运行批处理

通过网关上传批处理输入文件，并在请求中指定路由模型：

curl -sS -X POST "http://127.0.0.1:3000/v1/files" \\
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \\
  -H "x-aisix-model: gpt-4o-prod" \\
  -F purpose=batch \\
  -F file=@batch-input.jsonl

响应中的 id 以 aisix- 开头，并包含路由模型信息。使用该 ID 创建批处理任务：

curl -sS -X POST "http://127.0.0.1:3000/v1/batches" \\
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "input_file_id": "aisix-…",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

使用响应中的 ID 跟踪批处理并下载结果：

curl -sS "http://127.0.0.1:3000/v1/batches/aisix-…" \\
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

curl -sS "http://127.0.0.1:3000/v1/files/aisix-…/content" \\
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

官方 OpenAI SDK 可以保持原有调用方式：将 base_url 指向网关，并在 files.create 请求头中传入路由提示。

Fine-tuning 任务

Fine-tuning 任务通过编码后的 training_file ID 路由。任务请求体中的 model 字段是服务提供方要微调的基础模型，会原样转发，不是网关模型别名：

curl -sS -X POST "http://127.0.0.1:3000/v1/fine_tuning/jobs" \\
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "gpt-4o-mini-2024-07-18",
    "training_file": "aisix-…"
  }'

用量与成本归因

管理类调用（上传、创建、列表、取消）会记录 0 Token 的用量事件，便于在日志中追踪。

当批处理查询首次观察到 status: "completed" 时，网关会下载批处理输出文件，按服务提供方计费模型汇总每一行的 Token 用量，并发出包含真实 Token 数的用量事件。这些事件使用确定性的请求 ID（batch-<id>），因此重复查询或网关重启不会重复计量。

治理行为

这一组路由会应用完整策略边界：调用方 API Key 认证和模型访问列表、按模型的客户端 IP 限制、预算和限流，以及对传输载荷的输入/输出安全护栏扫描。上游调用遵循模型请求超时时间；传输失败会计入模型冷却。

下一步

你已经通过网关运行了文件上传、批处理和 Fine-tuning 任务。接下来可阅读服务提供方透传，了解该接口面之外的服务提供方原生端点。

支持的路由​

前提条件​

路由机制​

上传文件并运行批处理​

Fine-tuning 任务​

用量与成本归因​

治理行为​

下一步​