版本：Dev

透传路由

透传路由（passthrough route）将匹配到的请求转发到一个上游目标，不转换请求正文。它适用于 AISIX 尚未建模为一等路由的服务提供方原生端点，也适用于携带原始 Host 请求头的正向代理流量。

每条路由定义流量如何匹配、发送到何处、AISIX 如何认证调用方，以及 AISIX 是注入服务提供方凭证还是转发调用方凭证。AISIX 仍可围绕中继流量实施调用方访问控制、请求限制、护栏和遥测。

必须显式配置路由

每个透传路径或主机都必须由显式路由认领。未被任何路由认领的 /passthrough/* 路径遵循普通的空正文 404 处理流程。请先创建并验证路由，再迁移客户端流量。

透传路由不会改写模型标识符。如果服务提供方原生请求在正文、路径、查询参数或请求头中指定模型，请发送该服务提供方预期的标识符。

准备工作

请准备以下内容：

一个 AISIX 部署：
- 对于 AISIX Enterprise 或 AISIX Cloud，需要一个已挂载网关的环境和具备写入权限的管理员 Token。
- 对于开源 AISIX 网关，需要一个已配置为加载声明式资源文件的网关。
inject 路由所需的上游服务提供方凭证。示例使用 OpenAI；forward_client 路由则会中继调用方的上游凭证。
curl 和 jq。

了解透传流程

AISIX 保留请求正文，同时处理网关身份认证、目标构造、有意的请求头过滤、护栏和遥测：

每个匹配请求只会尝试一次上游调用。遇到传输故障或上游 5xx 响应时，AISIX 不会重试透传请求。路由不会解析模型，因此路由失败也不会让任何已配置模型进入冷却状态。

URL 重写先于路由匹配执行。下面两个阶段均使用重写后的路径；重写规则的可选 hosts 条件可以让其他主机的路径保持不变。之后，路由匹配分两个阶段进行：

入站 host 命中某条路由 hosts 白名单的请求，会在网关的类型化路由之前分发。这样，正向代理便可中继 /v1/messages 之类的上游路径，而不会被网关当作自身端点处理。
路径前缀匹配在类型化路由之后运行，因此纯路径路由无法遮蔽网关的 /v1、/mcp 或 /a2a 端点。

多条路由同时匹配时，主机名匹配优先于纯路径匹配，较长的匹配前缀优先于较短的前缀。

主机名匹配会接管整个主机。该主机上的请求不会落到网关自身的 API，包括 /v1/*、/mcp、/a2a、/livez 和 /readyz。只配置 hosts 的路由认领该主机的所有路径。同时配置 hosts 和 path_prefix 的路由只认领前缀下的路径，该主机上的其他路径返回 404（除非有其他路由匹配），请求不会回落到类型化路由。

配置服务提供方原生路由

以下示例在 /passthrough/openai/v1/models 暴露 OpenAI 的原生模型列表端点。AISIX 注入已配置的 OpenAI 凭证，并要求调用方 Key 已获得 openai-tunnel 授权。

AISIX Enterprise 或 AISIX Cloud

导出控制面连接信息和服务提供方凭证：

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

创建一个可供该环境使用的 OpenAI 服务提供方 Key：

PROVIDER_KEY_ID=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "OpenAI passthrough",
    "provider": "openai",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -er '.provider_key.id')

使用服务提供方 Key ID 创建路由：

ROUTE_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/passthrough_routes" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-tunnel",
    "path_prefix": "/passthrough/openai",
    "target_url": "https://api.openai.com/v1",
    "credential_mode": "inject",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }')

export ROUTE_ID=$(printf '%s' "$ROUTE_RESPONSE" | jq -er '.passthrough_route.id')
printf '%s' "$ROUTE_RESPONSE" | jq '.warnings // []'

保留 ROUTE_ID，以便更新路由或挂载路由作用域的护栏。

创建专用调用方 Key，并在同一请求中授予该路由。明文 Key 只返回一次：

CALLER_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "OpenAI passthrough caller",
    "allowed_models": [],
    "allowed_routes": ["openai-tunnel"]
  }')

export AISIX_API_KEY=$(printf '%s' "$CALLER_RESPONSE" | jq -er '.plaintext')
printf '%s' "$CALLER_RESPONSE" | jq '.warnings // []'

控制面会将服务提供方 Key、路由和调用方授权下发到已挂载的网关。上线前请检查返回的所有兼容性警告。警告仅供参考，因此请通过每个网关验证流量。在控制台中，可分别通过 服务商密钥、环境的 透传路由 以及调用方 Key 的 透传路由权限 部分完成相同操作。

如果改为授权现有调用方，请包含其应保留的全部路由授权。更新 allowed_routes 字段时，AISIX Cloud Admin API 会替换完整列表。

开源 AISIX 网关

在完整资源文件中准备一个 openai-prod 服务提供方 Key，然后选择一个专用调用方凭证：

export PASSTHROUGH_CALLER_KEY="YOUR_CALLER_API_KEY"

将路由和调用方条目添加到相应集合中。保持服务提供方 Key 和其他资源不变：

resources.yaml（路由和调用方 Key）
passthrough_routes:
  - name: openai-tunnel
    path_prefix: /passthrough/openai
    target_url: https://api.openai.com/v1
    provider_key: openai-prod

api_keys:
  - display_name: passthrough-caller
    key_env: PASSTHROUGH_CALLER_KEY
    allowed_models: []
    allowed_routes: [openai-tunnel]

AISIX 加载文件时，会将 provider_key 名称解析为服务提供方 Key 的派生 ID。未知名称会导致验证失败。allowed_routes 中的精确条目也会根据文件中定义的路由进行检查；允许使用通配符模式。

加载前，验证组装好的完整文件：

aisix validate --resources resources.yaml

由于本示例引入了 PASSTHROUGH_CALLER_KEY，请在网关进程环境中设置该变量，然后启动或重新创建网关。加载完成后，使用同一个值进行验证请求：

export AISIX_API_KEY="$PASSTHROUGH_CALLER_KEY"

验证路由

导出末尾不带斜杠的网关源地址：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 请求 OpenAI 的原生模型列表：

curl --fail-with-body -sS \
  "$AISIX_PROXY/passthrough/openai/v1/models" \
  -H "Authorization: Bearer $AISIX_API_KEY"

该路由会剥离其 path_prefix，避免重复添加 target_url 中已有的 /v1 路径段，注入 OpenAI 服务提供方凭证，并中继上游响应。

比较 Cloud 与资源文件引用

大多数路由字段在两种管理方式中使用相同名称。服务提供方凭证和调用方凭证的引用方式有所不同：

用途	AISIX Cloud Admin API	推荐的资源文件字段	资源文件接受的显式 ID
注入的服务提供方凭证	`provider_key_id`（UUID）	`provider_key`（`display_name`）	`provider_key_id`
匿名调用方主体	`anonymous_key_id`（UUID）	`anonymous_key`（`display_name`）	`anonymous_key_id`

资源文件中的名称引用在加载时会受到更严格的检查，引用未知时还会给出候选名称。应优先使用名称引用，而非显式 ID。AISIX Cloud Admin API 会验证服务提供方 Key 对该环境可见，并验证匿名调用方 Key 属于该环境。

在 AISIX Enterprise 和 AISIX Cloud 中，路由 name 创建后便固定不变。在资源文件中，更改名称会改变路由身份，因此必须同时更新每个调用方的 allowed_routes 条目。

配置参考

字段	行为
`name`	路由身份，由调用方的 `allowed_routes` 模式引用，并记录在用量事件中。
`path_prefix`	网关路径前缀，按路径段边界匹配。`target_url` 路由会先剥离前缀，再将剩余路径拼接到目标；`preserve_host` 路由则保留完整路径。纯路径路由不能占用 `/v1`、`/mcp`、`/a2a`、`/admin`、`/livez`、`/readyz` 或 `/metrics`；同时匹配 `hosts` 的路由可以使用这些归上游所有的路径。
`hosts`	入站 host 白名单，不区分大小写并忽略端口。入站 host 优先取请求 URI 的 authority（例如来自其他代理的 absolute-form 请求），否则取 `Host` 请求头。前导 `*.` 通配符匹配一个额外标签，且必须保留至少两个字面标签。
`target_url`	显式上游基础 URL。必须且只能配置一种目标形式：`target_url` 或 `preserve_host: true`。
`preserve_host`	将 `https://<matched-host>` 推导为目标。仅可与 `hosts` 一同配置，由 `hosts` 限定推导出的目的地。
`auth_mode`	`gateway_key`（默认）、`header_key` 或 `anonymous`。
`auth_header_name`	`header_key` 模式下包含网关凭证的小写专用请求头。除非 `forward_client_headers` 完整写出它的名称，否则 AISIX 会在转发前将其剥离；`x-*` 这类通配符触及不到它。`authorization`、`proxy-authorization`、`cookie`、`set-cookie` 和 `x-api-key` 会被拒绝。
`source_cidrs`	客户端来源白名单。`anonymous` 模式要求该列表非空；其他模式可将其作为可选的安全加固措施。
`credential_mode`	`inject`（默认）或 `forward_client`。
`forward_client_headers`	即使该路由本会剥离，也仍要中继给上游的入站客户端请求头，取值为精确名称或含一个 `` 的通配符，匹配不区分大小写。默认为空。PATCH 会整体替换已存储的列表；发送 `null` 可清空。在控制台中，它是高级下的转发客户端请求头*，每行一个条目。参见上游请求头。
`identity_header`	可选的小写设备注入身份请求头。AISIX 将长度受限的值记录为 `client_identity`，并在转发前剥离该请求头（除非 `forward_client_headers` 完整写出它的名称；`x-*` 这类通配符触及不到它）。仅应在可信设备之后配置，并由该设备删除并替换客户端提供的任何值。`authorization`、`proxy-authorization`、`cookie`、`set-cookie` 和 `x-api-key` 会被拒绝。AISIX Cloud Admin API 还会拒绝 `x-aisix-api-key`，因为它会把调用方的网关 Key 记录为身份。
`timeout_ms`	限制上游响应头和非 SSE 正文的读取时长。对于 SSE，它限制等待第一个原始上游正文块的时间，以及相邻原始正文块之间的等待时间。它不限制健康中继的总生命周期，也不要求在该间隔内组装完整的 SSE 帧。省略时，路由使用 `upstream.stream_timeout_ms`，再回退到 `upstream.timeout_ms`。
`enabled`	停用的路由不匹配任何请求。默认值：`true`。

必须至少配置一个匹配维度：path_prefix 或 hosts。同时配置两者时，请求必须同时满足两项条件。

网关身份认证模式

gateway_key 按 x-aisix-api-key、Authorization: Bearer、x-api-key 的优先级读取标准网关凭证，与 /v1/* 完全相同。由其中第一个出现的请求头决定，AISIX 绝不会回落到下一个：存在但为空或格式错误的 Authorization，例如 Basic … 或 Bearer 后没有 Token，即使 x-api-key 中是有效的 Key，也会返回 401。若要把 Authorization 留给上游，请在 x-aisix-api-key 中发送网关 Key。参见在 x-aisix-api-key 中发送网关 Key。
header_key 从 auth_header_name 读取网关凭证，从而将 Authorization 留给调用方的上游凭证。这是正向代理中 forward_client 的标准搭配。
anonymous 不接收网关凭证。请求以配置的调用方 Key 主体运行，并且必须来自 source_cidrs 范围内。

解析出的任一主体仍须通过 allowed_routes 获得路由名称授权；* 授予全部路由。条目是路由名称或单个 * 的 glob，例如 openai-*。AISIX Cloud Admin API 会以 400 拒绝含两个及以上 * 的条目；在 resources 文件中，这类条目不授予任何路由。有效 Key 缺少匹配授权时会收到 403。

在 AISIX Enterprise 和 AISIX Cloud 中，已适用于解析后调用方的预算会在分发前检查。透传用量目前不携带模型 ID，按零成本记录，也不会增加这些预算的支出。开源 AISIX 网关没有本地预算资源。

类型化策略与 Host 匹配

透传路由不走类型化端点基于模型的策略，而主机名匹配决定了哪些请求会进入透传路由：

模型策略不生效。路由不会按模型授权请求，因此即使请求体写明了模型，也不会检查调用方 Key 的 allowed_models，模型级护栏也不会运行。唯一的模型查找用于 inject 路由的请求限制。
访问由 allowed_routes 控制，且默认拒绝。调用方 Key 没有 allowed_routes 或列表为空时，不能使用任何路由。授权覆盖上游提供的全部内容，没有模型层面的限制。
其他护栏照常运行。附加到调用方 Key、其团队、环境或路由上的护栏照常生效。
健康探针不要使用路由的主机名。入站 host 命中路由时，/livez 和 /readyz 不会到达网关的健康检查端点。只配置 hosts 的路由会把探针转发到上游；path_prefix 不包含探针路径的路由则返回 404。
入站 host 由客户端提供。任何能连到监听端口的客户端，都可以通过请求 URI 的 authority 或 Host 请求头选中主机名匹配路由，因此 hosts 不能限制谁可以使用路由。要做这种限制，请使用 source_cidrs：来源不在列表内的请求会在身份认证之前收到 403。比较时使用的是解析后的客户端 IP。
auth_mode: anonymous 不理会调用方凭证。路由既不读取也不校验它们。来自 source_cidrs 内的请求一律以配置的调用方 Key 运行，无论携带什么 Authorization。

上游凭证模式

inject 从请求中移除全部凭证槽位，然后注入已配置的服务提供方 Key，这与服务提供方 Key 的 strip_headers 内容和 auth_mode 都无关。这些槽位是 authorization、proxy-authorization、x-api-key、api-key、x-goog-api-key、cookie、x-amz-security-token、x-amz-date 和 x-amz-content-sha256。AISIX 还会移除 strip_headers 列出的其他请求头，服务提供方 Key 的 TLS 设置也会生效。注入只有两种形式：Anthropic 使用 x-api-key，并且仅在调用方未发送 anthropic-version 请求头时补上 anthropic-version: 2023-06-01；其他服务提供方（包括 Azure 和 Gemini 类服务提供方 Key）一律使用 Authorization: Bearer。因此，调用方自带的 api-key 或 x-goog-api-key 不会被中继，除非 forward_client_headers 精确点名。
forward_client 不需要任何 forward_client_headers 条目就会中继调用方的凭证，配置通配符也是如此。AISIX 只移除 proxy-authorization、路由的 identity_header，以及用来认证调用方而被消费的槽位：gateway_key 下的 authorization 和 x-api-key，或 header_key 下的 auth_header_name。在 gateway_key 下，如果调用方改用 x-aisix-api-key 发送网关 Key（该请求头永远不会转发），其 Authorization 和 x-api-key 会保留给上游。被消费的槽位如果被 forward_client_headers 精确点名，同样会转发。

两种模式下，路由都默认中继调用方的其他请求头，只剥离一小部分：逐跳请求头和传输请求头、host、content-length、x-aisix-* 命名空间、proxy-authorization，以及调用方的 W3C 链路请求头。AISIX 会使用有效的 W3C 上下文建立自身的 OTLP 链路，并向上游发送网关请求 ID。

forward_client_headers 会覆盖该剥离行为，也是把路由本会移除的请求头放回去的唯一方式。路由移除的凭证槽位只有被模式精确点名才会放回，* 和 x-* 不算。在 inject 路由上，点名路由注入的槽位（Anthropic 服务提供方 Key 是 x-api-key，其他是 authorization）时，上游收到的是调用方的值而不是注入的值；调用方没有发送该槽位时，上游仍收到注入的凭证。点名其他槽位时，调用方的值会与注入的凭证一起发送，上游会同时收到两者。因此，使用非 Anthropic 服务提供方 Key 时，在 auth_mode: gateway_key 下点名 authorization，会中继调用方自己的凭证——正是网关刚刚用来认证该调用方的那个请求头——取代注入的那份；这就是让按最终用户授权的内网服务能够继续这样工作的方式。无论模式如何，host、content-length、逐跳请求头和 x-aisix-* 都会被剥离；凭证或链路上下文请求头必须精确点名，通配符不会匹配到它们。路由自己的 auth_header_name 和 identity_header 同理：AISIX 会消费掉这两个请求头，因此通配符触及不到，完整写出名称才会转发它。路由剥离的其他任何名称，通配符都足以放回去，包括服务提供方密钥 strip_headers 里的条目——不过该列表四个默认值中有三个（authorization、cookie、x-api-key）属于凭证槽位，仍需单独点名，只有 set-cookie 是通配符能放回的默认项。

凭证不存在回退机制：inject 路由没有可解析的服务提供方 Key 时会拒绝请求，forward_client 路由则不能携带服务提供方 Key 引用。

信封识别与用量

AISIX 识别每次交换的协议仅用于提取；识别不会改变中继的正文。请求正文的顶层载体字段决定信封。如果出现多个可识别的载体字段，则按以下顺序识别：

messages，用于聊天流量。携带 anthropic-version 请求头或路径以 /messages 结尾的请求识别为 Anthropic Messages，其他 messages 正文识别为 OpenAI 兼容聊天。
字符串或数组形式的 input，用于 OpenAI Responses 形态。
prompt，用于旧式 completions 或 fill-in-the-middle 流量。
其余所有正文均按不透明内容处理，包括 JSON-RPC、REST、非 JSON 和空正文。

信封还决定安全护栏的内容规则。有关异常、不透明和补充内容的安全边界，请参阅透传护栏扫描范围。

各请求形态记录的用量

对于已识别协议的交换，AISIX 使用服务同一协议的类型化端点自身的解析器读取用量，因此对同一上游回复，透传路由记录的 Token 计数与该端点相同。每个 Token 字段都保持其协议赋予的含义，AISIX 从不根据字段名推断含义。协议解析器无法读取用量的回复不记录用量，与类型化端点一致。

有两种界面的正文携带的是另一种信封的键，因此请求路径优先于正文：路径以 /embeddings 结尾的按向量嵌入计量，以 /images/generations 或 /images/edits 结尾的按图像生成计量。在没有信封的正文中，AISIX 还会计量 rerank 正文和阿里云 DashScope 原生正文，只读取其 model 字段和 Token 计数；安全护栏会检查这些 JSON 正文中已解码的字符串值。

协议	识别依据	用量读取方式
OpenAI 兼容聊天	`messages` 信封。	按 `/v1/chat/completions` 的方式读取缓冲响应或每个流式分块。
Anthropic Messages	带 `anthropic-version` 或 `/messages` 路径的 `messages` 信封。	按 `/v1/messages` 的方式读取，包括流中的 `message_start` 和 `message_delta` 事件。缓存读取和缓存创建 Token 与输入 Token 分开记录。
Responses	`input` 信封。	按 `/v1/responses` 的方式读取。流只在终止事件上报告用量。
Completions	`prompt` 信封。	按 `/v1/completions` 的方式读取。
向量嵌入	路径以 `/embeddings` 结尾，或缓冲回复是由 `object: "embedding"` 项组成的 `object: "list"`。	按 `/v1/embeddings` 的方式读取：输入 Token 取 `prompt_tokens`，没有时取 `total_tokens`。流不记录用量。
图像生成与编辑	路径以 `/images/generations` 或 `/images/edits` 结尾。	按图像生成的方式读取。流不记录用量。
Rerank	顶层 `query` 加 `documents` 数组。适用于 Cohere、Jina 和阿里云百炼的兼容 rerank API。	按 rerank 端点的方式读取：输入 Token 取自 `usage.prompt_tokens`、`usage.input_tokens` 或 `usage.total_tokens`，或 Cohere 的 `meta.billed_units.input_tokens`。流不记录用量。
DashScope 原生	顶层 `model` 字符串加 `input` 对象。适用于原生 rerank、文本与多模态向量，以及原生生成。	见 DashScope 原生 Token 计数。
其他任何正文	以上均不匹配。	不记录，下文所述的 Agent 用量帧除外。

对已识别请求的缓冲回复，回复自身声明的信封优先于请求：type: "message" 按 Anthropic Messages 读取，output 按 Responses 读取，choices 按聊天或 completions 读取。在流中，message_start 或 message_delta 事件按 Anthropic Messages 读取。因此即使请求未携带上述任一信号，Anthropic 回复也能被正确计量。

不透明流只通过服务端标记为 event: token_usage 或 event: usage 的帧中的扁平 Token 报告来上报用量，这是 IDE Agent 后端发送的形态。AISIX 把其中的 prompt_tokens 读作全部输入，并把 cache_read_input_tokens 和 cache_creation_input_tokens 记录为包含在其中的缓存命中和缓存写入 Token，因为这类后端报告的总数为 prompt_tokens + completion_tokens。不透明流其他帧上的 usage 对象不会被读取。

已识别协议的流由该协议自己的解析器计量。如果解析器在整个流的任何帧上都没有读到用量，AISIX 会改用流中的 event: token_usage 或 event: usage 帧计量，读取方式与上文相同。这些帧的用量不会叠加到解析器已读到的用量之上。

透传请求的访问日志 total_tokens 包含缓存创建和缓存读取 Token，与每个类型化端点的日志行一致。用量事件的 total_tokens 仍是上游上报的总数，因此 Anthropic Messages 交换不记录该值，与 /v1/messages 相同。

无论正文形态如何，透传用量事件的操作类型都是 passthrough，参见区分请求类型。对于可识别的形态，requested_model 是请求正文中的 model 值，即调用方发送的上游模型 ID，而不是 AISIX 模型别名，因为路由不解析模型。其他正文不记录模型。model_id 始终为空，因此透传用量按零成本记录：计价以 AISIX 模型为键。

已识别协议的指标

识别为聊天、Anthropic Messages、Responses、completions、向量嵌入、图像生成或编辑、rerank 的交换，在网关指标中按模型推理计数，标签为 endpoint="/passthrough_route" 和 inbound_protocol="passthrough"：

aisix_llm_requests_total 和 aisix_llm_request_duration_seconds 对其计数一次，同时也计入代理请求指标族。
aisix_llm_*_tokens_total 计数器、aisix_llm_tokens_by_client_total 和 aisix_tokens_consumed_total 记录其 Token。
流式回复在 aisix_llm_time_to_first_token_seconds 和 aisix_request_ttft_seconds 中记录首 Token 时间。

在这些序列上（包括请求指标族），model 是请求正文中的 model：它是已配置的模型名称时取该名称，或取覆盖它的通配符模型；其他取值报告 unresolved，正文没有 model 时报告 unknown。upstream_model 为 unknown。DashScope 原生正文、Agent 用量帧和不透明中继只计入代理请求指标族，model="passthrough"。

每个透传请求，无论协议是否被识别，都会以 endpoint="/passthrough_route" 记录 aisix_request_e2e_latency_seconds，请求被转发到上游时还会记录 upstream 一侧；流式回复会在两个首 Token 时间序列中记录到首帧的时间。1.7.1 及更早版本的网关只为聊天、Anthropic Messages 和 Responses 交换记录端到端直方图，且只为被识别出协议的流记录首 Token 时间。

相对 1.6.0 及更早版本的变化

1.6.0 及更早版本的网关以不同方式计量透传流量。请检查读取透传用量的查询和报表：

每个透传请求只计入代理请求指标族，model="passthrough"，且不记录任何 Token 或延迟序列。在更新的网关上，请用 endpoint="/passthrough_route" 而不是 model="passthrough" 来选取透传流量。
用量按字段名而不是按协议读取。向量嵌入和图像正文按 Responses 和 completions 的字段名读取，不透明流任意帧上的 usage 对象都会被读取。
Agent 用量帧的 cache_read_input_tokens 和 cache_creation_input_tokens 被记录为与 prompt_tokens 分开的 Anthropic 式缓存 Token，因此把这些计数器加到输入 Token 上的总数会重复计算缓存。
访问日志的 total_tokens 不包含缓存创建和缓存读取 Token。

DashScope 原生 Token 计数

对于 DashScope 原生正文，AISIX 按以下方式读取响应的顶层 usage 对象：

输出 Token 取自 output_tokens 或 completion_tokens。
存在 total_tokens 时，输入 Token 为 total_tokens 减去输出 Token。
没有 total_tokens 时，输入 Token 为 input_tokens（或 prompt_tokens）加上顶层的 image_tokens。嵌套的 input_tokens_details.image_tokens 已包含在 input_tokens 中，不会再累加。
缓存命中输入 Token 和推理 Token 按标准字段名从同一对象读取，例如 prompt_tokens_details.cached_tokens 和 output_tokens_details.reasoning_tokens。

这样无论服务把图片 Token 计入 input_tokens 之内还是之外，都只会计算一次：

服务	上游 `usage`	记录的输入	记录的输出
原生多模态 rerank，`qwen3-vl-rerank`	`input_tokens: 146`、`image_tokens: 64`、`total_tokens: 210`	210	0
多模态向量，`multimodal-embedding-v1`	`input_tokens: 4`、`image_tokens: 128`	132	0
原生多模态生成	`input_tokens: 79`、`image_tokens: 66`、`output_tokens: 14`、`total_tokens: 93`	79	14

示例：计量阿里云原生 Rerank

以下控制面示例通过 /passthrough/dashscope 中继中国内地地域的 DashScope 原生 API。为 DashScope 凭证创建一个 alibaba-cn 服务提供方密钥。国际地域请使用 alibaba 服务提供方和 https://dashscope-intl.aliyuncs.com/api/v1。服务提供方密钥的 api_base 不影响这条路由，因为上游由路由的 target_url 决定：

export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

DASHSCOPE_KEY_ID=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "DashScope native",
    "provider": "alibaba-cn",
    "api_key": "'"${DASHSCOPE_API_KEY}"'",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -er '.provider_key.id')

curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/passthrough_routes" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashscope-native",
    "path_prefix": "/passthrough/dashscope",
    "target_url": "https://dashscope.aliyuncs.com/api/v1",
    "credential_mode": "inject",
    "provider_key_id": "'"${DASHSCOPE_KEY_ID}"'"
  }' | jq '.warnings // []'

在资源文件中声明同一条路由时，将 provider_key 设为某个 alibaba-cn 服务提供方密钥的 display_name。服务提供方密钥条目的写法见 Qwen：

resources.yaml（路由）
passthrough_routes:
  - name: dashscope-native
    path_prefix: /passthrough/dashscope
    target_url: https://dashscope.aliyuncs.com/api/v1
    provider_key: dashscope-cn

按照配置服务提供方原生路由中的方式，在调用方 Key 的 allowed_routes 中授予 dashscope-native。然后使用上游模型 ID 发送原生 rerank 请求：

curl --fail-with-body -sS \
  "$AISIX_PROXY/passthrough/dashscope/services/rerank/text-rerank/text-rerank" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gte-rerank-v2",
    "input": {
      "query": "What does a passthrough route record?",
      "documents": [
        "A passthrough route relays provider-native requests.",
        "Usage events carry token counts and the route name."
      ]
    },
    "parameters": {"top_n": 2}
  }'

AISIX 剥离前缀，携带注入的凭证将正文中继到 https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank，并原样返回 DashScope 的响应。正文的顶层 model 和 input 对象使其被识别为 DashScope 原生正文，因此用量事件将 gte-rerank-v2 记录为 requested_model，并将响应的 usage.total_tokens 记录为输入 Token。

限流

调用方 API Key、团队和成员的请求限制会在分发前生效。在 inject 路由上，如果顶层 JSON model 解析为同一服务提供方下已配置的 AISIX 模型，还会预留该模型的请求限制。forward_client 路由不执行此模型查找。

AISIX 会强制执行请求数维度限制（rps、rpm、rph 和 rpd）。当适用的 tpm 或 tpd 计数器已经耗尽时，AISIX 也会拒绝请求，但透传 Token 用量不会增加这些计数器。记录的用量应只用于遥测，而不是透传 Token 配额执行。

并发检查在向上游分发之前执行。每个匹配的 SSE 并发预留都会在整个流的生命周期内保持。Redis 支持的限制会从获取预留开始续约，直到流结束，并使用 concurrency_ttl_secs 回收不再续约的预留。如果 Redis 报告某个活跃预留已不存在，AISIX 会结束中继。此时调用方已收到 200，而最终用量事件记录状态 429、error_class="rate_limit_lease_lost" 和 error_message="distributed concurrency lease was lost"。有关故障和发布行为，请参阅 Redis 支持的并发租约。

透传路由没有限流字段或策略作用域。若要对不同路由应用不同的请求限制，请将路由授予不同的调用方 Key，并为这些调用方身份配置限制。

护栏与流式传输

在 AISIX Enterprise 和 AISIX Cloud 中，可以通过选择 透传路由 作用域，将护栏挂载到一条透传路由。挂载使用路由 UUID。环境、调用方 Key 和团队护栏也可同时生效。

开源资源文件通过 guardrail_attachments 集合声明挂载关系，因此文件中定义的安全护栏只有在绑定将其作用域覆盖到透传流量时才会生效：可以使用 scope_type: env 覆盖整个环境，也可以使用 scope_type: passthrough_route 并指定该路由。

输入护栏在向上游分发前运行。拦截会返回 422，且不会联系上游。缓冲响应在交付前检查。SSE 响应一旦开始，拦截会以 SSE content_filter 错误帧结束流，无法再将 HTTP 状态码改为 422。

除非安全护栏暂存帧以进行检查，否则 SSE 响应会增量中继。AISIX 不会改写服务提供方原生正文来应用脱敏。对于内置 pii 护栏，仅配置掩码动作时，匹配内容会在不掩码的情况下转发，并记录为 mask_unsupported（监控模式下为 would_mask_unsupported）；如果匹配内容不得发送到上游，请使用拦截动作。Presidio 和 Lakera 等其他护栏类型在透传没有回写通道时，会改为拦截可掩码的结果。参见无法执行脱敏的接入面。

透传护栏扫描范围

安全护栏使用协议感知提取。对于成功解码的请求，它们还会检查与协议规范字段一起转发的普通 JSON 字符串，包括嵌套值。输出扫描只适用于成功的上游响应。AISIX 会原样中继非 2xx 缓冲正文和 SSE 流，不检查其中的内容。成功响应的覆盖范围仍特定于协议，并且仅限于下表列出的字段。

带有非 identity Content-Encoding 的成功响应无法检查。若适用的输出安全护栏中有任何一项采用 fail-closed 策略，AISIX 会以 unscannable_body 拒绝该响应。若所有适用的输出安全护栏都采用 fail-open 策略，AISIX 会原样中继编码后的正文，并记录一次 unscannable_body 绕过。此行为同时适用于缓冲响应和 SSE 响应。

工具调用 ID 是不透明的句柄，不是调用方内容，因此请求扫描会在可识别的信封中跳过它们：

Chat 和 Anthropic Messages：每个工具调用的 id、call_id、tool_use_id 和 tool_call_id，以及 tool 消息的 tool_call_id。
Responses：每个输入项上的 call_id 和 approval_request_id；任何 *_call 或 *_call_output 项，以及 item_reference、mcp_approval_request 或 reasoning 项的 id；以及 reasoning 项的 encrypted_content。因此，透传的 Responses 正文与 /v1/responses 请求的扫描方式相同。

函数名称、参数和工具结果仍会被扫描，下文列出的响应侧字段也从不包含 ID。只匹配上述某个值内部文本的护栏规则不会触发。其他任意正文一行不受影响，仍会读取每个已解码的字符串。

如果 AISIX 识别出信封但无法解码，它不会回退到扫描原始正文。顶层 model 是路由元数据，而不是调用方内容。类型化的不透明内容不会被重新解释为文本，包括图像、音频、文档和文件载荷，以及 redacted_thinking 数据。因此，Chat 行同时覆盖 OpenAI 兼容的 Chat 和 Anthropic Messages 流量：

信封	请求	响应
Chat 或 Anthropic Messages	消息文本和承载文本的内容块、Anthropic 顶层 `system`、`tool_result` 内容、Chat `tool_calls`，以及回放的 `tool_use` 输入、`thinking` 和 `reasoning_content`。回放的推理内容部件贡献每个条目的 `text`：Mistral 的 `thinking` 数组、Databricks `reasoning` 部件的 `summary`，以及 Anthropic 形式的 `thinking` 字符串。它们的 `signature` 和 `encrypted_content` 不会被扫描。	Chat 消息文本和 refusal，以及 function 和 custom tool 的名称与参数。对于 Anthropic，缓冲回复会扫描 `text` 块、`tool_use` 名称和输入；流会扫描 `tool_use` 开始事件，以及 `text` 和 `partial_json` delta。
Responses	`/v1/responses` 端点读取的每一个输入项，包括回放工具调用的名称、参数和输入。	输出文本、refusal 和工具调用：消息文本与 refusal 片段；`function_call` 和 `mcp_call` 的名称与参数；以及缓冲回复中 `custom_tool_call` 的名称和输入。流式载体包括对应的 delta 和 done 事件、内容片段和输出项快照，以及最终响应快照。
Completions	`prompt` 和 `suffix`。	补全 `text`。
其他任意正文	JSON 正文中每个已解码的字符串值；非 JSON 时为文本正文。	缓冲 JSON 正文提供其已解码的字符串值；其他缓冲文本直接扫描。不透明 SSE 流只能扫描单独的 JSON 字符串。其他承载内容的载荷形态无法评估，因为 AISIX 无法可靠地将其文本与之前的流内容关联。

1.7.0 及更早版本的网关无法评估回放了 Mistral thinking 数组的请求，也从不读取 Databricks reasoning 的 summary。

在可识别的 Responses 信封中，已知媒体、推理和未知输出项仍按不透明内容处理。格式错误的可识别缓冲输出无法评估，并按已配置的失败策略处理。未知的 Responses 流事件仍不透明。

声明了两种信封的缓冲回复同样无法评估：Responses 的 output 与聊天的 choices 并存，或聊天的 choices 与 Anthropic 的 type: "message" 正文并存。每条提取规则只读取自己的载体，因此 fail-closed 的输出安全护栏会以 unscannable_body 拒绝这类回复，fail-open 的安全护栏则放行。1.6.0 及更早版本的网关对 choices 与 Anthropic 正文并存的回复只扫描聊天载体。参见 AISIX 无法读取的内容会如何处理。

模型生成的推理内容（例如 reasoning_content、Anthropic thinking 和 Responses 推理摘要）在响应侧不会被扫描，但仍计入被保留流的 max_buffer_bytes。

审计捕获

对于成功中继的流量，配置了 content_mode: full 的可观测性导出器会以字符串形式接收请求正文，并受导出器内容上限约束。缓冲响应与受支持的提取形态匹配时记录提取出的文本，否则将正文记录为文本。流式响应记录累积的提取文本；不透明数据载荷保留为文本。这些内容中的 base64 媒体都会被替换，详见采集内容中的 Base64 媒体。捕获的内容仅发送给导出器，绝不会通过控制面遥测路径发送。

用量事件包含路由名称、调用方、记录的 Token 数量和 client_identity。外部导出器可以公开这些值。当前控制面日志视图显示调用方和 Token 元数据，但不显示 passthrough_route_name 或 client_identity。

错误

状态码或信号	含义
`401`	按路由身份认证模式缺失或提供了无效的网关凭证。
`403`	解析出的调用方 Key 未授予该路由，或客户端来源不在 `source_cidrs` 范围内。
`404`	未被认领的 `/passthrough/*` 路径，以及在命中某条路由 `hosts` 的主机上没有路由认领的路径，进入普通的空正文未找到处理流程。
`422`	护栏在分发前拦截了请求，或在交付前拦截了缓冲响应。
SSE `content_filter` 帧	护栏在流开始后拦截了内容。
`429`	网关请求限制或预算检查拒绝了请求，或上游返回了被中继的 `429`。
SSE 开始后的最终用量状态 `429`	调用方收到 `200` 后，Redis 支持的并发租约消失。用量事件记录 `error_class="rate_limit_lease_lost"`；请参阅在响应头之后失败的流。
其他上游状态码	AISIX 过滤响应头后，中继上游状态码和正文。

未匹配的 404 响应正文为空。AISIX 生成的其他失败使用网关错误信封；上游错误状态码和正文经过响应头过滤后中继。

下一步

使用主机名匹配路由接收经 TLS 终止的 IDE 流量：IDE AI 流量正向代理。
配置护栏行为：护栏行为。
导出请求和响应内容：可观测性导出器。

准备工作​

了解透传流程​

配置服务提供方原生路由​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

验证路由​

比较 Cloud 与资源文件引用​

配置参考​

网关身份认证模式​

类型化策略与 Host 匹配​

上游凭证模式​

信封识别与用量​

各请求形态记录的用量​

已识别协议的指标​

相对 1.6.0 及更早版本的变化​

DashScope 原生 Token 计数​

示例：计量阿里云原生 Rerank​

限流​

护栏与流式传输​

透传护栏扫描范围​

审计捕获​

错误​

下一步​