服务提供方透传

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

AISIX 为此类请求提供 ANY /passthrough/:provider/*rest。透传保留网关身份认证和上游凭证注入，转发服务提供方原生请求体而不执行端点专属转换，并原样中继上游状态码和响应体。AISIX 生成的错误使用网关的 OpenAI 风格错误信封。

信息

透传不会改写模型标识符。如果服务提供方原生请求在正文、路径、查询字符串或请求头中标识模型，请发送服务提供方预期的标识符。顶层正文 model 可以与 AISIX 模型匹配以执行限流，但 AISIX 仍会转发原值，不会把 display_name 替换为配置的上游 model_name。

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

准备工作

请先准备以下内容：

一个能够处理代理请求且正在运行的 AISIX 网关。
一个允许访问所请求服务提供方下至少一个模型的调用方 API Key。
一个 api_base 可访问服务提供方原生端点的服务提供方密钥；如果服务提供方有内置默认基础 URL，则无需设置。

了解透传流程

透传会保留服务提供方原生请求 schema，同时由 AISIX 处理网关级流程，包括调用方身份认证、上游 URL 构造、请求头管理和网关控制：

路径中的 :provider 选择一个已配置的服务提供方，而不是请求中的某个具体模型。AISIX 会移除 /passthrough/:provider 前缀，将剩余路径拼接到解析出的上游 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": "model-id-0",
      "object": "model",
      "created": 1686935002,
      "owned_by": "openai"
    }
  ]
}

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

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

命令应输出：

list

使用服务提供方模型标识符

透传请求中的任何模型标识符都属于服务提供方原生 API 契约。为执行限流，AISIX 可以将顶层正文 model 与已配置的模型别名或上游模型名称匹配。该查找不会改写请求，也不会选择其服务提供方密钥。

例如，假设一个直连 AISIX 模型具有以下名称：

display_name: ali-happyhorse-1.1-t2v
model_name: happyhorse-1.1-t2v

AISIX 的建模路由会为其支持的能力解析面向调用方的 display_name 别名。通过透传调用以下 Alibaba 视频合成 API 时，AISIX 不会把 ali-happyhorse-1.1-t2v 替换为已配置的上游名称；应直接发送 Alibaba 模型 ID：

curl -sS -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 "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "happyhorse-1.1-t2v",
    "input": {
      "prompt": "A miniature cardboard city at night"
    },
    "parameters": {
      "duration": 5,
      "ratio": "16:9",
      "resolution": "720P"
    }
  }'

如果请求改为包含 "model": "ali-happyhorse-1.1-t2v"，AISIX 会原样转发该值。服务提供方可能拒绝它，因为它不是服务提供方模型 ID。

对于支持的视频服务提供方，应优先使用已建模的视频生成端点；该端点接受 AISIX 模型别名，并解析上游模型和服务提供方密钥。只有需要服务提供方原生字段或 AISIX 尚未建模的端点时，才使用透传。

当服务提供方在正文之外标识目标时，同样适用该规则。例如，服务提供方可以把模型放在 URL 路径中、使用 Deployment 名称，或把模型绑定到端点。透传会保留该服务提供方原生选择机制，而不会将其转换成 AISIX model 字段。

仅在必要时选择透传

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

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

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

透传行为

透传会保留服务提供方原生请求 schema 和转发的上游响应，但仍受以下网关级行为约束：

接受任意 HTTP 方法，并保留查询字符串和请求体，不做 schema 或模型名称转换。
转发安全请求头，并剥离 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 和所有模型作用域限流策略会在请求离开网关前执行，并与建模路由使用同一组计数器，因此访问同一模型的透传流量和建模流量共享配额。

该匹配只影响限流。它不会改写转发的 model 值，也不会改变由哪个可访问模型提供服务提供方密钥。

如果正文不是 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 窗口，AISIX 会在窗口重置前拒绝透传请求；透传请求本身不会消耗 Token 配额。

请使用请求计数字段（rps、rpm、rph、rpd）限制透传流量；concurrency 也适用，透传请求会一直占用进行中的槽位，直到 AISIX 完整接收上游响应。

透传检查

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

如果服务提供方报告模型不存在，请将转发的模型标识符与服务提供方 API 参考进行比较。除非 AISIX display_name 同时也是服务提供方接受的精确标识符，否则不要发送它。

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

下一步

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

准备工作​

了解透传流程​

发送透传请求​

使用服务提供方模型标识符​

仅在必要时选择透传​

透传行为​

透传的模型限流​

透传检查​

下一步​