服务提供方透传

当某个服务提供方原生端点没有被建模为一等网关路由时，服务提供方透传允许应用通过 AISIX 调用该端点。

AISIX 为这类请求暴露 ANY /passthrough/:provider/*rest。透传会保留网关认证和上游凭证注入，但相比模型化代理路由执行更少请求和响应处理。

本指南将发送一次服务提供方透传请求，并说明何时适合使用这条备用路径。

准备工作

请先准备以下内容：

一个可以处理代理请求的 AISIX 网关。
一个调用方 API Key，允许访问所请求服务提供方下至少一个模型。
一个服务提供方密钥，其 api_base 可访问服务提供方原生端点；如果服务提供方有内置默认 base URL，则可省略。

发送透传请求

在路径中指定上游服务提供方即可发送透传流量。以下示例通过 AISIX 调用上游 OpenAI models 端点：

curl -sS -X GET "http://127.0.0.1:3000/passthrough/openai/v1/models" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -o aisix-passthrough-models.json

AISIX 会认证调用方 API Key，并为请求的服务提供方选择一个可访问模型。它会注入该模型的服务提供方密钥作为上游认证，剥离不安全请求头，保留查询字符串，并在不做端点专属标准化的情况下转发剩余路径和请求体。

响应是上游服务提供方响应，不是标准化后的 AISIX 模型列表：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model"
    }
  ]
}

检查响应是否作为上游列表返回：

jq -r '.object' aisix-passthrough-models.json

命令应输出：

list

仅在必要时选择透传

透传适合尚未暴露为一等网关路由的服务提供方专属 API。你可以将它用于探索性集成工作，或在评估是否需要原生网关端点期间提供临时访问。

如果 AISIX 已经支持对应能力，应优先使用模型化代理路由。模型化路由会解析面向调用方的模型别名，并能应用路由专属行为，例如响应标准化、Token 用量归因、缓存行为和端点专属服务提供方检查。

内容安全护栏会同时适用于两条路径。模型化路由会扫描解析后的请求，并在路由支持输出检查时扫描响应。透传会将原始请求体和响应体作为文本扫描。更多路由覆盖范围请参见安全护栏检查位置。

透传行为

透传会尽量保持服务提供方原生请求不变：

接受任意 HTTP 方法，并保留查询字符串和请求体。
转发安全请求头，并剥离 hop-by-hop 头以及服务提供方密钥中配置的 strip_headers。
从选中的服务提供方密钥中注入上游认证信息。
使用所选模型附加的安全护栏扫描完整请求体和响应体文本。如果请求体命中安全护栏，AISIX 会在请求到达服务提供方前返回 422；如果响应体命中安全护栏，AISIX 会在转发上游响应体前返回 422。
在请求离开网关前执行限流。调用方 API Key 限制始终适用。当 JSON 请求正文的顶层 model 字段指定了该服务提供方下已配置的模型时，该模型的限制也会适用。参见透传的模型限流。
透传上游状态码、响应体和安全响应头。

转发的上游响应会保留服务提供方原生状态码和响应体。AISIX 生成的失败（包括安全护栏阻断、服务提供方解析失败和传输失败）使用 OpenAI 风格的代理错误信封。

路径中的 provider 片段会用于查找服务提供方标签匹配、且当前调用方 API Key 有权访问的已配置模型。该路由以服务提供方为作用域，而不是以模型为作用域；它不会像 Chat Completions 请求那样选择某个具体模型别名。如果多个可访问模型共享同一个服务提供方但使用不同服务提供方密钥，生产流量不应依赖这种隐式选择。凭证选择会忽略请求正文，但限流不会：正文指定已配置模型时，即使凭证来自同一服务提供方下的其他模型，也会执行该模型的限制。

上游认证会使用服务提供方期望的形式。Anthropic 透传使用 API Key 请求头和 Anthropic 版本请求头；大多数其它内置服务提供方默认使用 bearer 认证。

如果选中的服务提供方密钥没有设置 base URL，AISIX 只会对 OpenAI、Anthropic、Google、DeepSeek 等已知服务提供方使用内置默认值。对于其它服务提供方标签，请显式配置服务提供方密钥的 base URL。当 base URL 和透传路径都包含相同 API 版本片段时，AISIX 会在转发前移除重复片段。

透传的模型限流

当 JSON 请求正文包含顶层 model 字段时，透传请求会计入模型限流。AISIX 会在所访问服务提供方的已配置模型中匹配该值：先按模型别名（display_name）匹配，再按模型服务提供方原生模型名称（model_name）匹配。匹配模型的 rate_limit 和所有模型作用域限流策略会在请求离开网关前执行，并与建模路由使用同一组计数器，因此访问同一模型的透传流量和建模流量共享配额。

如果正文不是 JSON、没有 model 字段，或指定的模型未配置在所访问的服务提供方下，则只执行调用方级限制。

这主要影响没有建模路由的模型服务提供方原生端点。对于 Alibaba、Zhipu、Volcengine Ark、Runway 和 OpenAI 视频生成，现在推荐使用建模的视频生成端点；以下透传示例仍适用于隧道流量以及 AISIX 尚未建模的服务提供方端点。示例将 Alibaba Model Studio 视频模型限制为每分钟提交一次。Alibaba 没有内置默认 Base URL，因此必须在模型服务提供方密钥上显式设置 api_base；模型的 rate_limit 字段定义上限：

{
  "display_name": "wan-video-prod",
  "provider": "alibaba",
  "model_name": "wan2.7-t2v",
  "provider_key_id": "YOUR_PROVIDER_KEY_ID",
  "rate_limit": {
    "rpm": 1
  }
}

通过透传提交两个视频生成任务。请求正文指定模型服务提供方原生模型，窗口内的第二次提交会在到达服务提供方前被拒绝：

for i in 1 2; do
  printf "request %s: " "${i}"
  curl -sS -o /dev/null -w "%{http_code}\n" -X POST \
    "http://127.0.0.1:3000/passthrough/alibaba/api/v1/services/aigc/video-generation/video-synthesis" \
    -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
    -H "X-DashScope-Async: enable" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.7-t2v",
      "input": {"prompt": "A miniature city built from cardboard comes alive at night."},
      "parameters": {"resolution": "720P", "duration": 5}
    }'
done

输出应显示第二个请求被拒绝：

request 1: 200
request 2: 429

被拒绝的请求带有 Retry-After HTTP 响应头，正文使用与建模路由相同的限流错误封装：

{
  "error": {
    "message": "request limit exceeded (requests)",
    "type": "rate_limit_exceeded"
  }
}

任务状态轮询不计入模型配额。GET /passthrough/alibaba/api/v1/tasks/{task_id} 等轮询请求没有请求正文，因此不会占用模型提交预算；客户端提交任务后即使触及上限，仍可轮询该任务直至完成。

备注

透传流量不会增加 Token 计数器（tpm、tpd）：AISIX 会原样转发透传正文，不会在此路由解析模型服务提供方报告的 Token 用量。对同一模型而言，如果 Token 窗口已被建模流量耗尽，则重置前仍会拒绝透传请求，但透传请求本身不会填充该窗口。请使用请求计数字段（rps、rpm、rph、rpd）限制透传流量；concurrency 也适用，透传请求会一直占用并发槽位，直到完整接收上游响应。

透传检查

当透传请求没有到达预期上游时，请先检查路径中的 provider 片段。然后检查 AISIX 可以为该服务提供方标签选择哪个已配置模型和服务提供方密钥。透传不会使用请求正文选择上游凭证，因此选中的服务提供方密钥来自该服务提供方下某个可访问模型。

当调用方 API Key 有效但不能访问请求服务提供方下的任何模型时，AISIX 会返回 403。当没有已配置模型匹配该服务提供方标签时，AISIX 会返回 404。如果 AISIX 提示没有已知默认 base URL，请在选中的服务提供方密钥上设置 base URL。

下一步

你已经了解什么时候应使用服务提供方透传，而不是模型化端点。当客户端依赖受支持端点族之上的流式响应或工具调用行为时，请继续阅读流式响应和工具调用。

准备工作​

发送透传请求​

仅在必要时选择透传​

透传行为​

透传的模型限流​

透传检查​

下一步​