资源文件参考

开源 AISIX 网关可以从声明式 resources.yaml 文件加载服务提供方凭证、模型、调用方凭证和运行时策略。本参考涵盖该文件的 YAML 规则、跨资源命名、环境变量插值和所有受支持的资源集合。

在启动配置中设置 resources_file 以选择该文件。如需创建并加载可用配置，请从开源 AISIX 网关快速入门开始。使用 CLI 参考校验变更，并通过配置状态检查已启用或被拒绝的配置。

文件格式

AISIX 从一个资源文件中只加载一个 YAML 文档。文件名并不固定：本文档约定使用 resources.yaml，但 resources_file 可以指向任意可读文件路径。

该设置只接受一个路径。AISIX 不会加载目录、解析 include 或 import 指令，也不会合并多个资源文件。如果你以多个源文件片段维护配置，请在校验和加载前将它们组装成一个 YAML 文档。

安全应用资源示例

保留完整的活动快照

AISIX 不会把资源文件与之前加载的配置合并。每次成功加载都会替换活动资源快照。新增或更改资源时，请从网关当前使用的完整文件开始；组装后的文件中省略的条目和集合将从活动配置中消失。

代码块标题用于区分完整文档与局部配置块：

• 标题为 resources.yaml 的代码块是包含 _format_version 的自包含文档。请结合上下文判断它是新网关配置还是参考示例。
• resources.yaml（OIDC 服务提供方） 之类的标题表示不含 _format_version 的局部配置块。括号中的简短说明标识其内容；上下文会说明应添加、替换、更新还是仅检查该配置块。

应用局部配置块时，请从网关当前使用的完整文件开始。每个受影响的集合只更新或创建一次，保留无关条目和集合，不要重复创建已有的顶层集合键。

组装完所有局部配置块后，请验证完整文件，而不是单独验证局部配置块。

文档顶层是一个映射，其中必须包含 _format_version，并且最多包含十四个资源集合：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-prod
    provider: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o-2024-11-20
    provider_key: openai-prod

api_keys:
  - display_name: ci-bot
    key_env: CI_BOT_KEY
    allowed_models: ["gpt-4o"]

rate_limit_policies:
  - name: cap-gpt4o
    scope: model
    scope_ref: gpt-4o
    window: minute
    max_requests: 300

集合	用途	标识字段
provider_keys	存储上游服务提供方凭证和连接设置。	display_name
models	定义面向调用方的模型别名和分发行为。	display_name
api_keys	对调用方进行身份认证，并控制其模型、MCP 工具和 A2A Agent 访问权限。	display_name
oidc_providers	信任用于调用方身份认证的 JWT 签发者。	name
mcp_auth_settings	配置 OAuth Discovery 以及 MCP 客户端可选的匿名访问。	单例；无标识字段
claim_mappings	把验证通过的 JWT Claims 解析到调用方 API Key。	name
guardrails	检查或转换请求和响应内容。	name
guardrail_attachments	把安全护栏绑定到它要检查的流量。	guardrail_id + scope_type + scope_id
mcp_servers	将 MCP 服务器或 OpenAPI 操作公开为工具。	name 或 display_name
a2a_agents	为 A2A 调用方注册上游 Agent。	name 或 display_name
passthrough_routes	将匹配的 HTTP 流量在网关审计和策略下中继到服务提供方端点。	name 或 display_name
cache_policies	缓存匹配的非流式模型响应。	name
observability_exporters	将请求遥测数据导出到外部系统。	name
rate_limit_policies	应用条件式或单作用域的请求和 Token 限制。	name

YAML 结构

_format_version 必须是字符串 "1"，需要加引号以确保 YAML 将其解析为字符串。缺少版本或版本无法识别会导致加载错误；未加引号的 1 会触发专用错误，提示你为它添加引号。

网关会应用以下 YAML 约束：

• 文件必须只包含一个 YAML 文档。使用 --- 分隔的多个文档会导致加载错误。
• 顶层映射和所有嵌套映射都必须使用字符串 Key。
• 每个存在的资源集合都必须是映射序列。不存在或值为 null 的集合按空集合加载。
• 未知顶层集合和资源中的未知字段都会导致加载错误。
• YAML 锚点和别名可以复用值。合并 Key（<<）不会展开，并会在 Schema 校验时被视为未知字段而失败。

标识与派生 ID

除 mcp_auth_settings 和 guardrail_attachments 外，每个条目的标识字段都必须是非空字符串，并且在集合中唯一；重复会导致加载错误，并指出两个冲突条目。对于 mcp_servers、a2a_agents 和 passthrough_routes，可以使用 name 或 display_name 作为标识；同时包含两种写法会导致加载错误，只能使用其中一种。mcp_auth_settings 采用固定的单例标识，因此文件在该集合中最多只能包含一个条目。guardrail_attachments 条目由 guardrail_id + scope_type + scope_id 三元组标识，因此把同一个安全护栏挂到同一个目标两次属于重复条目。

所有条目都不接受 id 字段。条目 ID 根据 <kind>/<identity>，在命名空间 63e50ab2-677a-54d3-8d1e-c0cb29ceae94 中以 UUIDv5 确定性派生，因此相同文件在重新加载和不同进程中始终生成相同 ID。例如，api_keys/anonymous-mcp 会派生出 d6869ae7-741a-598e-8213-16672e922546。由 ID 标识的引用和限流计数器因此可以跨 SIGHUP 重新加载保留。

名称引用

条目通常通过名称选择关联资源。加载器会按以下方式检查每种关系：

关系	使用的引用	校验行为
模型到服务提供方凭证	服务提供方密钥的显示名称（推荐），或其确定性 ID	provider_key 会解析显示名称；名称未知时，错误会列出可用密钥。provider_key_id 必须匹配同一文件中已定义服务提供方密钥的派生 ID。两字段互斥。
调用方或虚拟模型到目标模型	模型的显示名称	必须匹配文件中定义的模型。包含 * 的值是 Glob 模式，不检查是否精确匹配。
限流策略到其主体	模型或调用方 API Key 的显示名称	对于 model 和 api_key 作用域，名称会解析为目标；对于其它作用域，该值原样传递。
安全护栏绑定到安全护栏	安全护栏 name	必须匹配已定义的安全护栏；未知名称会导致加载错误，并列出可用的安全护栏。
安全护栏绑定到作用目标	目标集合各自的标识——模型的 display_name，MCP 服务器或透传路由的 name，调用方 API Key 的 display_name	必须匹配该集合中的条目。scope_type: team 原样保留，因为文件中没有团队集合可供校验。
调用方身份到 JWT 签发者	OIDC 服务提供方名称	保留为名称，而不解析成派生 ID。
透传路由到注入凭证	经 provider_key 引用的服务提供方密钥显示名称	必须匹配已定义的服务提供方密钥；未知名称会导致加载错误，并列出可用的密钥。与 provider_key_id 互斥。
透传路由到匿名主体	经 anonymous_key 引用的调用方 Key 显示名称	必须匹配已定义的调用方 API Key。与 anonymous_key_id 互斥。
调用方 Key 到透传路由	经 allowed_routes 引用的路由名称	条目是单 * Glob；不含 * 的条目必须匹配文件中定义的路由。

环境变量插值

${VAR} 引用只会在字符串标量中根据网关进程环境解析。替换发生在已解析的 YAML 树中，因此环境变量值无法注入 YAML 结构，映射 Key 也不会被插值。

此插值用于用户自定义的进程变量。有关 AISIX 定义的启动和连接变量，请参见环境变量。

• 支持部分插值：api_base: https://${UPSTREAM_HOST}/v1。
• 变量未设置或值为空都会导致加载错误；错误只指出变量名，绝不会包含变量值。
• 不支持 ${VAR:-default} 和 ${VAR:?message} 等 Shell 风格的回退值和必填值表达式。
• $$ 生成字面量 $；没有大括号的 $VAR 原样保留；未闭合的 ${ 或空的 ${} 会导致错误。
• 整数、浮点数、布尔值和 null 等非字符串标量不会被插值。

加载、错误与重新加载

启动、SIGHUP 重新加载和 aisix validate 使用相同的加载流程。网关会读取文件、解析 YAML、插值 ${VAR} 引用、转换各条目、解析名称引用、执行 Schema 校验并检查交叉引用。所有配置来源使用相同的 Schema 校验。

错误会在整个文件范围内聚合，并定位到问题条目和字段，例如 models[2] ("gpt-4o")。加载为全有或全无：任何错误都会拒绝整个文件。

启动时，被拒绝的文件会使网关立即停止。SIGHUP 重新加载时，网关会继续提供上一个有效快照，记录聚合报告，并通过 GET /status/config 暴露被拒绝的加载。网关不会监视文件变化，必须显式重新加载。

服务提供方密钥

服务提供方密钥保存上游凭证及该服务提供方使用的连接设置。模型通常通过 display_name 选择服务提供方密钥；直接模型也可以按照直接模型所述改用该密钥的确定性 ID。每个嵌套层级都会拒绝未知字段。

字段	类型	必填	说明
display_name	string	是	条目标识，在 provider_keys 中唯一。这是推荐的模型引用；直接模型也可以改用该密钥的确定性 ID。
api_key	string	视情况而定	上游服务提供方 API Key。请以 ${VAR} 形式提供。也可以使用 secret 作为替代写法；两者必须且只能提供一个。部分服务提供方的凭证包含多个字段。对于这些服务提供方，请通过一个环境变量提供 JSON 凭证文档。有关凭证格式，请参见 AWS Bedrock 和使用 Entra ID 的 Azure OpenAI。
provider	string	否	上游服务提供方标识符，例如 openai 或 deepseek。这是用于服务提供方专用分发的开放字符串，默认为空。
adapter	enum	否	没有适用的服务提供方专用分发时所用的上游协议族：openai、anthropic、bedrock、vertex 或 azure-openai。参见适配器协议族。
api_base	string	否	覆盖上游服务提供方的基础 URL。私有 OpenAI 兼容端点实际上必须设置此字段。支持部分插值，例如 https://${UPSTREAM_HOST}/v1。
apis	object	否	该端点原生提供哪些 API 协议面、分别在哪个地址。写了 apis 但省略某个协议面，表示该协议面不是原生提供的，网关会改为转换成 chat completions。完全省略该块则从 provider 和 adapter 推导所有协议面，这是默认行为。bedrock、vertex 和 azure-openai 适配器不接受该字段。见声明 API 协议面。
apis.responses	object	否	该端点原生提供 /v1/responses。apis 一旦存在，此项即为权威依据：不写它就是在声明该端点没有这个接口。
apis.messages	object	否	该端点原生提供 /v1/messages 和 /v1/messages/count_tokens。此项是叠加的——adapter 为 anthropic 的密钥无论是否列出都提供这两个接口；列出它是为了给适配器是其他协议的密钥补上这两条路由。
apis.<surface>.base	string	否	该协议面的基础 URL，用于端点把它放在与 api_base 不同的路径上的情况。形式要求与 api_base 相同。该协议面就在 api_base 上时省略此字段。
strip_headers	字符串数组	否	使用此密钥的 inject 模式透传路由转发前删除的入站请求头，这些路由始终移除的凭证槽位不受此列表影响。默认：authorization、cookie、set-cookie、x-api-key。条目会去除首尾空格、转成小写并去重。显式 [] 会清空此列表，但不会放行任何凭证槽位：inject 模式恒剥离 authorization、proxy-authorization、x-api-key、api-key、x-goog-api-key、cookie、x-amz-security-token、x-amz-date 和 x-amz-content-sha256。这并不是绝对禁令：路由自己的 forward_client_headers 会覆盖它，凭证槽位需要模式精确点名，对于既非凭证也非链路上下文的名称，x-* 这类通配符就足以把请求头放回传输上。
tls	object	否	HTTP 服务提供方分发使用的端点级 TLS 设置。Amazon Bedrock 和 Realtime 分发会忽略此配置块；请改用适用的部署级 upstream.tls 设置。
tls.ca_cert	string	否	此 HTTP 端点额外信任为签发者的 PEM 编码 CA 证书。一个证书包可以包含多张证书。参见 TLS 和 mTLS。
tls.verify	boolean	否	是否验证此 HTTP 端点的证书。默认：true。设为 false 会接受任意证书，仅用于测试环境。
resolve_addresses	array	否	网关连接此密钥 api_base 主机时直接使用的 IP 地址，不再通过 DNS 解析该主机。每个条目都是 IPv4 或 IPv6 地址字面量，不带端口，也不带方括号；按列出的顺序依次尝试。Host、TLS 服务器名、证书校验、协议和端口仍然来自 api_base。Amazon Bedrock、/v1/realtime，以及网关通过正向代理访问上游时都不会生效。见固定端点地址。
telemetry_tags	object	否	通过该 Key 路由请求时发出的归因标签。
telemetry_tags.kind	enum	否	归因类别：catalog 或 byo。
telemetry_tags.featured	boolean	否	是否突出显示该服务提供方密钥。默认：false。
telemetry_tags.branded_provider	string	否	目录条目的品牌服务提供方 Slug。
telemetry_tags.pk_label	string	否	运维人员定义的服务提供方密钥标签，例如 production。
telemetry_tags.byo_label	string	否	运维人员定义的自带服务提供方标签，例如团队名称。
request	object	否	分发前应用的请求格式覆盖。
request.param_renames	字符串到字符串的映射	否	分发前，把左侧指定的顶层请求体 Key 重命名为右侧 Key。
request.param_constraints	object	否	Chat Completions 请求体中 temperature 的截断边界。
request.param_constraints.temperature_min	number	否	接受的最小 temperature。省略时不应用下限。
request.param_constraints.temperature_max	number	否	接受的最大 temperature。省略时不应用上限。
request.default_headers	字符串到字符串的映射	否	添加到出站请求的请求头。由于加载器会先从环境中解析 ${...}，请求上下文引用需要写成 $${...}，例如 $${request.api_key.team_id} 加载后会变成 ${request.api_key.team_id}，用于按请求渲染。某个请求中变量无值时，该请求头会被丢弃，而不是发送空值。除凭证槽位外，这些请求头的优先级高于 forward_client_headers 转发的请求头——在凭证槽位上转发值胜出；它们也不能替换网关自身设置的同名请求头。无论来自哪里，host、逐跳请求头和 x-aisix-* 都会被丢弃；保存服务提供方密钥时，AISIX Cloud Admin API 拒绝的也正是这些名称。凭证名称在两种路径下都被接受，且只有在服务提供方桥接留空该槽位时才会到达上游。request 块的这一半在 /v1/realtime 上并不生效，那里只有 forward_client_headers 起作用。参见上游请求头。
request.forward_client_headers	字符串数组	否	中继给上游的入站客户端请求头，取值为精确名称或含一个 * 的通配符（例如 x-trace-*），匹配不区分大小写。为空（默认值）时不转发任何请求头，唯一的例外是：在发往 Anthropic 或 Anthropic 兼容端点的 /v1/messages 和 /v1/messages/count_tokens 上，调用方的 anthropic-beta 会按原样转发，包括它的每个值，无需在此列出。default_headers 为请求设置的 anthropic-beta 会取代它。在此列出 anthropic-beta 时（无论是写出名称，还是用 *、anthropic-* 等能匹配它的模式），发送的仍只是调用方的值，但按已列出请求头的规则处理，因此只转发第一个值。凭证槽位以及链路上下文请求头 traceparent/tracestate 只有在模式精确点名时才会中继，通配符永远不会匹配到它们，x-amz-* 也不例外。中继的凭证会占用该密钥本会注入的槽位，而不是与之并存。host、逐跳请求头、x-aisix-*，以及网关会重新序列化的请求体与内容协商请求头（content-type、content-length、accept、accept-encoding、content-encoding、expect）、set-cookie、anthropic-version 和 x-stainless-* 绝不会被中继。在 Bedrock 形态的密钥上，SigV4 签名涉及的名称（authorization、x-amz-date、x-amz-content-sha256、x-amz-security-token、x-amz-target、x-amzn-bedrock-accept）会被丢弃而不是投递。发往 Amazon Bedrock 或 Vertex AI 上的 Claude 时，anthropic-beta 只保留该平台支持的 beta，Bedrock 在请求体的 anthropic_beta 中接收，而不是作为请求头；在 /v1/messages 上，即使没有任何模式点名该请求头，调用方的 beta 也会到达平台。参见 Claude 的 beta 值。在 /v1/realtime 上，该面拥有的握手槽位（sec-websocket-accept、sec-websocket-extensions、sec-websocket-key、sec-websocket-protocol、sec-websocket-version）即使被模式完整点名也会被拒绝。参见上游请求头。
request.default_body_fields	字符串到 JSON 值的映射	否	调用方未设置时添加到出站请求的顶层请求体字段。
response	object	否	由支持的服务提供方桥接器应用的响应格式覆盖。
response.stream_done_marker	enum	否	上游 SSE 流是否应发出 data: [DONE]：required、optional 或 none。省略时两种情况均可接受。
response.content_list_to_string	boolean	否	为 true 时，在分发前把 messages[*].content 文本块数组展平为一个字符串。默认 false。
response.reasoning_field	string	否	从服务提供方响应中提取推理内容的路径，例如 delta.reasoning_content。
response.error_envelope	string	否	为兼容控制面配置而保留的错误信封首选项；代理目前不会应用。

以下示例综合使用了这些设置。它定义一个 OpenAI 服务提供方密钥和一个私有 OpenAI 兼容端点。私有端点声明 openai 适配器，从环境变量构建基础 URL，并信任一个额外的 CA。

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-prod
    provider: openai
    api_key: ${OPENAI_API_KEY}
  - display_name: internal-vllm
    provider: internal-vllm
    adapter: openai
    api_base: https://${UPSTREAM_HOST}/v1
    api_key: ${INTERNAL_LLM_KEY}
    # 仅当此端点的证书由私有或企业 CA 签发时，
    # 才需要配置以下内容。
    tls:
      ca_cert: |
        -----BEGIN CERTIFICATE-----
        MIIB...
        -----END CERTIFICATE-----

模型

模型条目定义一个面向调用方的别名。直接、向量嵌入、路由、合议和语义别名都会出现在 /v1/models 中；通配符模式不会列出（参见模型别名）。每个条目只使用一种分发形态：直接、路由、合议或语义。在同一条目中混合不同形态会导致加载错误，每个嵌套层级也都会拒绝未知字段。

以下超时、重试、访问、成本和内联限额字段在各模型形态间共享，但每个字段只在网关会解析它的 kind 上被接受——适用 kind 列列出这些 kind；在不解析该字段的 kind 上设置它会作为加载错误被拒绝：

字段	类型	适用 kind	说明
display_name	string	全部	条目标识，在 models 中唯一，也是面向调用方的别名。每种形态都必填。
timeout	整数（ms）	direct、embedding、routing、semantic	非流式上游调用的端到端截止时间。在路由模型或语义路由器上，这是应用于未自行设置该值的每个目标的组/路由器级槽位；缺省时依次回退到该槽位和部署级 upstream.timeout_ms 默认值（6000000 ms，即 6000 s）。0 禁用超时。ensemble 不接受此字段——其每次调用的截止时间是 ensemble.timeout_ms。
stream_timeout	整数（ms）	direct、embedding、routing、semantic	上游流式分块之间的最长间隔。0 或缺省时依次回退到组/路由器的 stream_timeout、timeout 和部署默认值。ensemble 不接受此字段。
retries	integer	direct、embedding、semantic	发生可重试的上游失败后，对此模型执行的重试次数。在语义路由器上这是路由器级槽位。0 禁用对同一目标的重试。路由模型不接受顶层 retries——其组级槽位是下文的 routing.retries；路由目标自身的 retries 会覆盖它。ensemble 不接受此字段。
rate_limit	object	全部	按调用方所寻址的条目强制执行的请求、Token 和并发限制，见下文。
allowed_cidrs	字符串数组	全部	采用 CIDR 表示法的客户端 IP 允许列表（支持 IPv4 和 IPv6）。空值或缺省允许所有客户端。配置限制后，缺少或格式错误的源 IP 会被拒绝。
cost	object	direct、embedding	用于 least_cost 排序的每 Token 价格元数据：input_per_1k 和 output_per_1k，单位均为每 1,000 个 Token 的价格；存在该块时两者都必填。设置在组所分发到的 direct 或 embedding 模型上，而非组本身。

rate_limit 中的每个字段均可选，省略时不限制：

字段	限制
rate_limit.rps	固定 1 秒窗口内的请求数。
rate_limit.rpm	60 秒窗口内的请求数。
rate_limit.rph	3,600 秒窗口内的请求数。
rate_limit.rpd	86,400 秒窗口内的请求数。
rate_limit.tpm	60 秒窗口内的 Token 数。
rate_limit.tpd	86,400 秒窗口内的 Token 数。
rate_limit.concurrency	最大进行中请求数。它是信号量，不是窗口。
rate_limit.window_type	fixed（默认）或 sliding。决定 rpm、rph、rpd、tpm 和 tpd 如何计数；不影响 rps 和 concurrency。参见选择窗口类型。需要网关 1.10.0 或更高版本。

在默认的 fixed 下，窗口按 UTC 时钟对齐，在每个边界整体重置：整秒、整分或整点，rpd 和 tpd 在 00:00 UTC。

直接模型

直接模型指定一个服务提供方密钥背后的一个上游模型：

字段	类型	必填	说明
provider	string	是	服务提供方标识，例如 openai 或 anthropic。首字符必须为小写字母或数字；后续可使用 .、_ 和 -；长度 1–64 个字符。
model_name	string	是	在服务提供方请求中发送的上游模型标识，例如 gpt-4o-2024-11-20。
provider_key	string	是*	provider_keys 条目的名称。这是资源文件中的推荐引用。与 provider_key_id 互斥。
provider_key_id	string	是*	同一文件中已定义 provider_keys 条目的确定性 ID。与 provider_key 互斥。ID 与同一文件中的任何服务提供方密钥都不匹配时会发生加载错误。
embedding	object	否	将模型标记为支持向量嵌入：dimensions（必填，向量维度）和 normalize（默认 true，端点是否已经返回 L2 归一化向量）。随后该模型可以服务 /v1/embeddings 并支持语义路由器。
background_model_check	object	否	后台健康检查，参见健康检查。存在该块时，子字段 enabled、interval_seconds（最小 5）、timeout_seconds、prompt、max_tokens 和 stale_after_seconds 必填；ignore_statuses（状态码数组）可选。
cooldown	object	否	发生可重试上游失败后的请求路径冷却。冷却需要显式开启：省略该块，或不设置其中的 enabled，请求路径失败都不会让模型退出轮转。见下文。
auto_prompt_caching	object	否	自动注入 Anthropic 提示词缓存标记。适用于使用 anthropic 适配器访问 Anthropic API 的直连 Claude 模型，以及 Amazon Bedrock 或 Vertex AI 上的直连 Claude 模型。存在该对象时 enabled 必填；ttl 可设为 5m（默认）或 1h。具体模型标识要求参见 Anthropic 提示词缓存。
effort_mapping	值为字符串或 null 的对象	否	直接模型的请求力度改写。键是调用方取值，值是上游取值，值为 null 表示移除力度。键 "" 匹配未设置力度的请求，键 "*" 匹配其他所有没有单独条目的取值。最终目标选定后只查找一次——先精确键，再 "*"；省略或设为空对象即关闭。参见推理力度映射。

必须且只能设置 provider_key 与 provider_key_id 其中一个。

可选的 cooldown 对象接受以下设置。只有 enabled: true 才会开启冷却；其余设置是冷却开启后使用的参数，单独设置其中某一项并不会开启该功能：

字段	默认值	行为
cooldown.enabled	false	启用请求路径冷却跟踪。省略 cooldown 块或不设置该字段的模型，无论上游如何失败都会留在轮转中。
cooldown.default_seconds	30	没有可用 Retry-After 响应头时设置冷却 TTL。设为 0 不是把冷却时长设为零，而是彻底关闭该模型的冷却，包括走 Retry-After 的那条路径。
cooldown.max_seconds	600	限制根据 Retry-After 得出的冷却时间。
cooldown.honor_retry_after	true	存在有效的 Retry-After 值时使用该值。
cooldown.trigger_statuses	[401, 408, 429, 500, 502, 503, 504]	触发冷却的状态码。设置该字段会替换完整默认列表。
cooldown.trigger_on_timeout	true	上游超时后触发冷却。
cooldown.trigger_on_transport	true	上游传输失败，或不带状态的带内错误发生后触发冷却。在 /v1/realtime 上，被拒绝的握手带有状态，走 trigger_statuses；拨号超过 upstream.connect_timeout_ms 走 trigger_on_timeout。1.8.0 及更早版本的网关对这两种情况都使用本设置。

只有直接模型可以配置 embedding、background_model_check、cooldown 和 auto_prompt_caching。自动提示词缓存还要求直连 Claude 模型；支持的适配器和模型范围参见 Anthropic 提示词缓存。

路由模型

routing 条目会为每个请求选择一个目标，并通过该目标模型的上游配置分发：

字段	类型	必填	说明
routing.targets	array	是	有序目标集合，至少一个条目。每请求的路由标签和 allowed_cidrs 过滤器会先缩小该集合，再由配置的策略对保留目标排序。
routing.targets[].model	string	是	可以接收路由流量的现有直接模型名称。
routing.targets[].weight	integer	否	默认：1。在 round_robin 下设置轮转份额，在 consistent_hash 下设置哈希环份额，在 least_busy 下设置分数的分母 max(weight, 1)。运行时会把 0 视为 1。failover、least_cost 和 least_latency 接受但忽略此值。
routing.targets[].priority	integer	否	默认：0。把符合条件的目标划分为层级，值越高越优先。更高层级没有可用目标后才尝试较低层级；使用 -1 可设置备用层级。
routing.targets[].tags	字符串数组	否	用于按请求筛选资格的标签。如果所有目标都没有标签，则不启用标签筛选，所有目标均符合条件。否则，携带标签的请求会保留至少一个标签匹配的目标；没有匹配项时回退到带 default 标签的目标。未携带标签的请求优先选择 default 目标；不存在该类目标时，所有目标仍符合条件。
routing.strategy	enum	否	round_robin（平滑加权轮询）、consistent_hash、failover（默认）、least_cost、least_latency 或 least_busy。位置策略在每个优先级层内选择一个起始目标，并在失败时向后遍历；指标策略在每层内按最佳优先排序。
routing.retries	integer	否	故障转移前每个目标的默认重试次数。目标模型的 retries 会覆盖此值。如果两处都未设置，AISIX 会直接移至下一个符合条件的目标，并且仅对最后一个目标应用部署级默认值。
routing.max_fallbacks	integer	否	初始目标失败后最多尝试的后续目标数。默认：所有后续目标。0 禁用故障转移。
routing.retry_on_429	boolean	否	上游 429 是否参与重试和故障转移。默认 false。
routing.fallback_on_statuses	整数数组	否	额外视为可重试的 4xx 状态码，适用于使用这些状态表示暂时性情况的服务提供方，例如 [408, 409]。5xx 已默认可重试。
routing.when_all_unavailable	enum	否	fail（默认）：健康状态和冷却状态排除所有目标时返回 503；try_anyway：无论状态如何，都按声明顺序尝试所有目标。
routing.hash_on	array	否	仅用于 consistent_hash：有序的哈希键来源链，取第一个非空值。每个条目形如 {type, name?}，type 为 header、cookie（两者通过 name 指定名称）、api_key 或 client_ip 之一。默认：x-aisix-routing-key 请求头，其次调用方 API Key。

配置、路由行为和可运行的故障测试请参见多目标路由与故障转移。

合议模型

ensemble 条目会把每个请求并发分发给所有合议成员，再由评审模型合成一个答案：

字段	类型	必填	说明
ensemble.panel	array	是	合议成员，至少一个。panel[].model 指定直接模型；可选的 panel[].temperature 和 panel[].seed 覆盖每个成员的采样参数；panel[].weight 可以配置，但目前忽略。
ensemble.judge	object	是	judge.model 指定执行合成的直接模型；可选 judge.synthesis_prompt 覆盖内置合成提示词。
ensemble.min_responses	integer	否	合成前要求的最少成功成员响应数。默认是 2 与成员数中的较小值，上限为成员数，下限为 1。
ensemble.timeout_ms	整数（ms）	否	每个合议成员调用和评审调用的截止时间。0 或缺省时禁用。

行为和响应格式请参见合议模型。

语义路由器

semantic 条目会对请求中最新的用户文本进行向量嵌入，根据每条路由的示例向量计算分数，并分发到达到阈值的最佳路由；如果没有路由达到阈值，则分发到 default：

字段	类型	必填	说明
semantic.embedding_model	string	是	支持向量嵌入的直接模型名称（即包含 embedding 块的模型）。
semantic.routes	array	是	至少一条路由。每条路由必须包含 name（记录在访问日志的 semantic_route 字段中；当 proxy.expose_debug_headers 为 true 时也通过 x-aisix-route 响应头暴露）、target（直接模型或模型组的名称）和 examples（至少一条示例话语；在第一个需要它的请求到达时计算并缓存向量）；可选 description（仅用于文档）和 threshold（覆盖该路由的 match.threshold）。
semantic.default	string	是	没有路由匹配时接收请求的直接模型或模型组。
semantic.match	object	是	共享匹配参数：threshold（必填，0.0–1.0，越高越严格）、distance_metric（仅支持 cosine）和 aggregation（仅支持 max，路由分数取最匹配的示例）。
semantic.embedding_timeout_ms	整数（ms）	否	向量嵌入调用的截止时间。0 或缺省时禁用。
semantic.on_embedding_failure	enum 或 object	否	向量嵌入调用失败时的处理方式：default（路由到 default 模型，也是默认行为）、fail（以 503 拒绝），或 { target: "<alias>" }（路由到指定的直接模型或模型组）。
semantic.session_affinity	object	否	让会话保持在其首个命中请求所走的路由上：enabled（默认 false）和 ttl_seconds（默认 3600，取值 60–604800），即固定在最后一次被使用后保持多久。不配置时每个请求都会分类。参见会话固定。

行为和调优请参见语义路由。

以下完整示例展示四种模型形态的关系。三个直接模型是可复用目标；其余条目将它们组合成会话绑定路由、合议模型和语义路由器。

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o
    provider_key: openai-main
    timeout: 30000
    rate_limit:
      rpm: 100
      tpm: 100000
    cost:
      input_per_1k: 0.0025
      output_per_1k: 0.01
  - display_name: gpt-4o-mini
    provider: openai
    model_name: gpt-4o-mini
    provider_key: openai-main
  - display_name: text-embed
    provider: openai
    model_name: text-embedding-3-small
    provider_key: openai-main
    embedding:
      dimensions: 1536
  - display_name: balanced
    routing:
      strategy: consistent_hash
      targets:
        - model: gpt-4o
          weight: 90
        - model: gpt-4o-mini
          weight: 10
      retries: 1
      retry_on_429: true
  - display_name: council
    ensemble:
      panel:
        - model: gpt-4o
        - model: gpt-4o-mini
          temperature: 0.2
      judge:
        model: gpt-4o
      min_responses: 2
      timeout_ms: 45000
  - display_name: smart-router
    semantic:
      embedding_model: text-embed
      routes:
        - name: coding
          target: gpt-4o
          examples:
            - "Write a Python function that parses CSV"
            - "Debug this stack trace"
          threshold: 0.8
      default: gpt-4o-mini
      match:
        threshold: 0.75
      on_embedding_failure: default

调用方 API Key

调用方 API Key 条目用于认证调用网关的应用。文件绝不会保存明文 Key：请通过 key_env 提供，或预先哈希到 key_hash。

字段	类型	必填	说明
display_name	string	是	条目标识，在 api_keys 中唯一。
key_env	string	是*	保存明文调用方 Key 的环境变量名称，例如不带 ${VAR} 的 MY_APP_KEY。加载时，网关会使用 SHA-256 哈希该值并丢弃明文；明文绝不会出现在已加载文档、错误或日志中。与 key_hash 互斥，两者必须且只能提供一个。变量名不要以 AISIX_ 开头，该前缀保留给启动配置覆盖。
key_hash	string	是*	明文 Key 的小写十六进制 SHA-256 哈希，原样传递。两个条目解析到相同凭证时会导致加载错误；错误只指出条目，绝不会包含哈希。
allowed_models	字符串数组	否	此 Key 可以使用的模型。条目是单 * Glob："*" 授予所有模型，"team-a/*" 授予匹配名称；不包含 * 的条目必须匹配同一文件中定义的模型 display_name。省略该字段或给出空数组，此 Key 不会获得任何模型访问权限——模型访问始终需要显式授予。
rate_limit	object	否	按 Key 设置限制，子字段与模型的 rate_limit 相同：rps、rpm、rph、rpd、tpm、tpd、concurrency。
mcp_rate_limits	object	否	此 Key 按 MCP 服务器设置的请求和并发限制。Key 为已注册的 MCP 服务器名称，见下文。
mcp_access	object	否	此 Key 可以调用的 MCP 工具：必填的 allow 列表和可选的 deny 列表，使用 <server>__<tool> 名称并按单 * Glob 匹配——"github__*" 覆盖某个服务器上的所有工具。省略该配置块表示此处无 MCP 工具访问权限，见下文。
allowed_agents	字符串数组	否	此 Key 可以访问的 A2A Agent，按注册名称和单 * Glob 匹配。省略、null 或空值表示无 A2A Agent 访问权限。
allowed_routes	字符串数组	否	此 Key 可以使用的透传路由，按路由名称和单 * Glob 匹配。省略、null 或空值表示无透传路由访问权限。
jwt_subject	string	否	从已验证 JWT 中选择的外部身份。与 jwt_provider 一起设置；该组合在文件中必须唯一。
jwt_provider	string	否	允许声明 jwt_subject 的 oidc_providers 条目名称。设置 jwt_subject 时必填。
expires_at	string	否	RFC 3339 时间戳；超过该时间后，Key 会停止认证并返回 401。省略表示永不过期。格式错误的时间戳会在加载时拒绝条目，而不是被静默视为永不过期。
disabled	boolean	否	管理性禁用 Key：重新启用前，请求会返回 401。默认 false。
team_id	string	否	团队归因，由 scope: team 的 rate_limit_policies 原样匹配。
user_id	string	否	所属成员归因，由成员作用域策略原样匹配。
user_name	string	否	仅用于遥测标签的可读所有者名称。

MCP 工具访问权限和限额

请通过 mcp_access 授予 MCP 工具访问权限。在 AISIX Enterprise 和 AISIX Cloud 中，该配置块是三层 ACL 中的一层，会与环境和团队的访问策略取交集；资源文件没有策略集合，因此这里该配置块是这把 Key 唯一的一层，没有该配置块的 Key 无法访问任何 MCP 工具。allow 为必填——不需要收窄、只依赖 deny 的 Key 请发送 ["*"]，完全不允许调用的 Key 请发送 []。

使用 mcp_rate_limits 为一个调用方 Key 分别设置每个已注册 MCP 服务器的限额。每个服务器条目支持以下字段：

字段	限制
rps	每秒请求数。
rpm	每分钟请求数。
rph	每小时请求数。
rpd	每日请求数。
concurrency	最大进行中工具调用数。
window_type	fixed（默认）或 sliding。决定 rpm、rph 和 rpd 如何计数。需要网关 1.10.0 或更高版本。

这些限额与 Key 的常规 rate_limit 一起应用于 tools/call 请求；初始化和工具列表请求不计数。

以下示例允许一个调用方访问一个模型以及 github MCP 服务器公开的所有工具。常规 rate_limit 与工具限额同时生效，mcp_rate_limits.github 则进一步限制该服务器的工具调用。

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o
    provider_key: openai-main

mcp_servers:
  - name: github
    type: mcp
    url: https://api.example.com/mcp

api_keys:
  # MY_APP_KEY 是保存明文调用方 Key 的环境变量名称；
  # 加载时会被哈希，且绝不会存储明文。
  - display_name: my-app
    key_env: MY_APP_KEY
    allowed_models: ["gpt-4o"]
    mcp_access:
      allow: ["github__*"]
    rate_limit:
      rpm: 60
      concurrency: 5
    mcp_rate_limits:
      github:
        rpm: 30
        concurrency: 2

OIDC 服务提供方

oidc_providers 条目定义网关如何验证外部 Token 签发者提供的 JWT。已验证身份会映射到 jwt_provider 和 jwt_subject 字段分别与服务提供方和 Token 匹配的调用方 API Key。

字段	类型	必填	说明
name	string	是	条目标识，在 oidc_providers 中唯一。调用方 API Key 通过此名称引用服务提供方。
issuer	string	是*	预期的 JWT iss 声明，进行精确比较。已配置的签发者在已启用的服务提供方中必须唯一。使用 JWKS 验证时必填；设置 hmac_secret 时可选。未指定签发者的共享密钥服务提供方不会校验 iss。
audiences	字符串数组	是*	接受的 JWT aud 值。使用 JWKS 验证时必须至少配置一个值，且 Token 必须包含匹配值。设置 hmac_secret 时，省略该字段或使用空列表即可跳过受众校验。
jwks_uri	string	否	获取签名 Key 的 JWKS 端点。省略时，AISIX 从 <issuer>/.well-known/openid-configuration 解析。设置 hmac_secret 时不能设置此字段。
hmac_secret	string	否	HMAC 签名 Token 所用的共享密钥。设置后该条目改用 HMAC 验证：仅接受 HS256、HS384 或 HS512 签名的 Token，不获取任何签名 Key，issuer 和 audiences 变为可选。其 UTF-8 字节会原样作为 HMAC Key——不做 base64 解码，也不做任何派生——且长度至少为 32 字节。请以 ${VAR} 形式提供。默认：不设置，即使用 JWKS 验证。
identity_claim	string	否	其字符串值用于选择调用方 API Key jwt_subject 的声明。整个字符串先当作一个完整的声明名读取，再用点遍历嵌套对象。默认：sub。
required_scopes	字符串数组	否	必须全部出现在 Token scope 声明中的作用域。该声明可以是空格分隔字符串或数组。默认：不要求作用域。
bound_claims	object	否	必须全部满足的额外声明要求。每个 Key 先当作一个完整的声明名读取，再用点遍历嵌套声明。每个值可以是字符串或非空数组；字符串声明必须等于某个接受值，数组声明必须包含一个接受值。
tag_claims	object	否	每个请求从已验证的 Token 读取的成本归属标签，形式为标签键到声明路径的对象。按标签键逐个比较，这样读取的值优先于调用方 API Key、其团队和其成员上的值。键须匹配 ^[a-z][a-z0-9_]{0,62}$，路径不能为空，最多 32 条。详见 Claim 如何变成标签值。
leeway_secs	integer	否	exp 和 nbf 的时钟偏差容许值，范围为 0 到 300 秒。默认 0。
login	object	否	网关让只配置了 URL 的 MCP 客户端的用户登录时所用的 OAuth 客户端：client_id（必填）、client_secret（通过 ${VAR} 提供）和 scopes。需要 issuer 且不能有 hmac_secret，只能有一个已启用的条目带有它。参见 MCP 交互式登录。
enabled	boolean	否	服务提供方是否参与身份认证。默认 true。

issuer 和 jwks_uri 不得包含疑似凭证的查询参数，例如 access_token 或 client_secret。

URL 用户信息不是受保护的 Secret

这些 URL 中的用户信息（user:password@）会被接受并按原样使用，网关日志也可能包含 issuer。请优先使用不含凭证的 HTTPS 端点，或使用网络层访问控制。

未设置 hmac_secret 的条目使用 JWKS 验证：issuer 和 audiences 必填，接受非对称 JWT 签名算法，并拒绝 HMAC 签名 Token。支持的算法、请求行为和 Key 轮换请参见 JWT 认证。

以下条目会被 AISIX 拒绝：同时设置 jwks_uri 和 hmac_secret；未设置 hmac_secret 却缺少 issuer 或至少一个受众；hmac_secret 短于 32 字节。

以下配置会信任 corp-keycloak 签发者，并将 JWT 主体 agent-billing-01 映射到 billing-agent 调用方条目。

即使启用 JWT 身份认证，每个调用方条目仍需要 key_env 或 key_hash。加载以下示例前，请在网关进程环境中设置 BILLING_AGENT_KEY。空的 allowed_models 列表会拒绝模型访问；当此身份需要调用模型端点时，请添加模型别名。

resources.yaml

_format_version: "1"

oidc_providers:
  - name: corp-keycloak
    issuer: https://sso.example.com/realms/agents
    audiences: ["aisix-gateway"]
    required_scopes: ["ai.access"]
    bound_claims:
      department: ai-lab

api_keys:
  - display_name: billing-agent
    key_env: BILLING_AGENT_KEY
    allowed_models: []
    jwt_subject: agent-billing-01
    jwt_provider: corp-keycloak

下面的条目则信任一个使用共享密钥签名的签发者。密钥由网关进程环境中的 JWT_HMAC_SECRET 提供，明文不会出现在文件里。该条目未指定 issuer 和 audiences，因此不会校验这两项声明；当签发者会设置它们且你希望强制校验时，请补充配置。

resources.yaml（OIDC 服务提供方）

oidc_providers:
  - name: partner-hmac
    hmac_secret: ${JWT_HMAC_SECRET}
    required_scopes: ["ai.access"]

请为每个未指定签发者的共享密钥条目配置各自不同的密钥。两个共用同一密钥的条目都能验证同一个 Token，因此按名称排在前面的那个始终胜出。

MCP 身份认证设置

可选的 mcp_auth_settings 集合控制客户端如何在 /mcp 和 /mcp/{server} 上进行身份认证。它在每个环境中是单例，因此资源文件最多只能包含一个条目；第二个条目会导致加载错误。该条目包含两项互相独立的设置：同时启用 OIDC 服务提供方时，resource_url 会启用 OAuth Discovery；anonymous 则允许来自可信网络且未提供凭证的调用方访问所选 MCP 条目。

字段	类型	必填	说明
resource_url	string	否	网关 /mcp 端点的规范公共 URL。当该值能解析为绝对 http 或 https URL、不含查询参数或片段、路径以 /mcp 结尾时，OAuth 发现才会启用。请使用经过百分号编码且不含空段、. 或 .. 的路径，以免前方网关对它的规范化与 AISIX 发布的资源 URL 不一致。/mcp 之前的前缀（例如 /team-a/mcp）用于由 AISIX 前面的网关在转发前剥离的场景，参见在按路径前缀路由的网关后运行。该 URL 会按原样发布在一个无需认证的端点上，用户信息也不例外，因此不要在其中写入凭证。网关不会将它与 Token 的 aud 比较；audiences 应列出哪些值，参见 OAuth 登录。
anonymous	object	否	匿名访问设置。省略时，每个 MCP 请求都必须提供有效的网关 API Key 或可信 OAuth Access Token。
anonymous.enabled	boolean	否	是否启用匿名访问。默认：true。设为 false 可在关闭匿名访问的同时保留设置。
anonymous.api_key_id	string	是*	匿名请求以其身份运行的 api_keys 条目确定性 ID。该 Key 的 MCP 授权、限额、安全护栏和用量归因照常生效。设置 anonymous 时必填。
anonymous.source_cidrs	字符串数组	是*	允许匿名进入的非空客户端来源 CIDR 列表。AISIX 会匹配通过 Real IP 配置解析出的客户端地址，而不是调用方提供的不可信请求头。设置 anonymous 时必填。
anonymous.servers	字符串数组	是*	匿名调用方可以访问的非空 MCP 服务器名称列表。该列表也是此主体通过聚合 /mcp 端点访问内容的上限。设置 anonymous 时必填。
anonymous.aggregate_entry	boolean	否	聚合 /mcp 端点是否也为匿名调用方提供服务。默认：false。启用后，不带凭证的客户端不会收到原本用于启动 OAuth Discovery 的 401。

以下示例会启用 OAuth Discovery，并允许一个可信网络匿名访问 docs 服务器。API Key ID 与根据显示名称 anonymous-mcp 派生的确定性 ID 一致：

resources.yaml

_format_version: "1"

oidc_providers:
  - name: corp-sso
    issuer: https://sso.example.com/realms/agents
    audiences:
      - https://gateway.example.com/mcp
    required_scopes:
      - mcp:tools

api_keys:
  - display_name: anonymous-mcp
    key_env: ANONYMOUS_MCP_KEY
    allowed_models: []
    mcp_access:
      allow:
        - docs__*

mcp_servers:
  - name: docs
    type: mcp
    url: https://docs.example.com/mcp

mcp_auth_settings:
  - resource_url: https://gateway.example.com/mcp
    anonymous:
      api_key_id: d6869ae7-741a-598e-8213-16672e922546
      source_cidrs:
        - 10.0.0.0/8
      servers:
        - docs
      aggregate_entry: false

请在网关进程环境中设置 ANONYMOUS_MCP_KEY。有关身份认证流程和安全影响，请参阅客户端身份认证。

Claim 映射

Claim 映射在没有 Key 直接绑定 Token Subject 时，把 JWT 中已验证的声明解析到一把既有的调用方 API Key。命中提供方的已启用映射按 priority 顺序求值（数值小者在前，同值按 name 排序）；第一条条件全部成立的映射决定所用的 Key，未命中任何映射的 Token 会被拒绝。求值语义参见 JWT Claim 映射。

字段	类型	必填	说明
name	string	是	条目标识，在 claim_mappings 中唯一。也是同优先级时的求值决胜依据。
jwt_provider	string	是	此映射作用的 oidc_providers 条目名称。必须引用文件中已定义的提供方。
priority	integer	否	在该提供方的映射中的求值顺序；数值小者先求值。默认：0。
match	array of objects	是	声明条件，全部成立才算命中。每个条件包含 claim（先当作一个完整的声明名读取，再用点号遍历嵌套对象）、op（exact 匹配字符串声明，contains 匹配数组声明；非字符串数组元素被忽略）和 values（任一匹配即可的备选值）。列表至少一个条件。
resolve.api_key	string	见下	命中请求所运行的调用方 API Key 的 display_name。加载时解析为对应条目。
resolve.api_key_id	string	见下	Key 引用的规范形式，用于按规范 schema 直接编写的文档。resolve.api_key / resolve.api_key_id 必须恰好设置一个。配置导出会像其他引用一样，把存储的 ID 转换回 Key 名称并输出 resolve.api_key。
enabled	boolean	否	映射是否参与求值。默认：true。

引用的提供方和 API Key 必须定义在同一文件中；未知引用或空的 match 列表会导致加载失败。

resources.yaml

_format_version: "1"

oidc_providers:
  - name: corp-keycloak
    issuer: https://sso.example.com/realms/agents
    audiences: ["aisix-gateway"]

api_keys:
  - display_name: finance-policy-key
    key_env: FINANCE_POLICY_KEY
    allowed_models: []

claim_mappings:
  - name: finance-dept
    jwt_provider: corp-keycloak
    priority: 100
    match:
      - claim: department
        op: exact
        values: ["finance"]
    resolve:
      api_key: finance-policy-key

安全护栏

安全护栏条目用于检查请求或响应内容。它只在绑定指定的范围内运行——没有任何绑定的安全护栏会被加载、会计入资源总数，但不检查任何流量。kind 字段标识安全护栏类型，并决定条目还接受哪些字段。这些字段直接位于条目中，不存在嵌套 config 对象。所选类型的未知字段会被拒绝。

安全护栏条目的通用字段如下；除非特别说明，均与类型无关：

字段	类型	必填	说明
name	string	是	条目标识，在 guardrails 中唯一，并显示在指标标签和错误原因中。
kind	enum	是	安全护栏类型，见下方类型表。
enabled	boolean	否	false 会暂存规则但不运行。默认 true。
hook_point	enum	否	规则运行位置：input（请求负载，在上游调用前）、output（上游响应）或 both（默认）。
input_messages	enum	否	输入检查可用的消息窗口。all（默认）提供整个请求；latest_turn 只保留最后一条 assistant 消息之后的消息，并排除 system 和 developer 消息。安全护栏类型可能只读取该窗口中的特定角色。只作用于输入检查；输出检查始终读取完整响应。参见选择输入消息窗口。
direction	string	否	用于兼容基于挂载配置的字段。它不会选择资源文件安全护栏的运行位置；执行位置由 hook_point 控制。新资源文件应省略此字段。
enforcement_mode	string	否	block（默认）执行匹配判定；monitor 允许内容原样通过，并记录安全护栏本应阻断或脱敏的结果。参见执行模式。
fail_open	boolean	否	所有类型在输入侧无法完成检查时的行为。true 允许请求并记录绕过；在阻断模式下，false（默认）拒绝请求。在监控模式下，后端故障始终放行：fail_open: false 记录为 would_block，fail_open: true 记录为绕过；由网关发起的不可读内容处理仍遵循该策略。对于 keyword 和 pii，此字段还管辖输出侧，因为这两个类型不接受 output_fail_open。参见安全护栏无法完成检查时。
output_fail_open	boolean	否	除 keyword 和 pii 外所有类型的输出侧失败策略。true 允许响应并记录绕过；在阻断模式下，false（默认）拒绝响应。无论该设置如何，保留式流故障仍可能拒绝响应。
timeout_ms	integer	否	安全护栏每一次后端调用的时限，覆盖从发送请求到读完整个响应体的全过程，而不是整个检查的时限；没有整体时限，因此需要多次调用的检查耗时可能是该值的数倍。openai_moderation 和 lakera 每次检查调用一次。presidio 对每个文本片段依次调用一次分析器，并对每个需要脱敏的片段再调用一次匿名化器。azure_content_safety 和 azure_content_safety_text_moderation 将文本切分为不超过 10,000 个字符的分块，aliyun_text_moderation 和 aliyun_ai_guardrail 切分为不超过 2,000 个字符的分块；每个分块单独调用一次，调用依次执行，分块数量没有上限。对于 semantic，它限制每一次 embedding 请求：一次用于尚未缓存的示例文本，另一次用于该请求所有待筛查的文本。对于 custom，它限制整个钩子调用，包括脚本发出的每一次调用。默认值：5000。keyword、pii 和 bedrock 不接受该字段；Bedrock 改用 latency_mode。
created_at	string	否	RFC 3339 时间戳。存在时，安全护栏按最早时间优先求值；没有此字段的条目排在最后。

所选 kind 决定条目还接受哪些字段：

kind	必填字段	重要选项
keyword	patterns：进程内求值的 {kind: literal | regex, value} 阻断模式数组。空列表可以加载，但不会匹配任何内容。	—
semantic	embedding_model；deny_examples 非空时还需 deny_threshold，allow_examples 非空时还需 allow_threshold	要执行检查，至少需要一个非空的 deny_examples 或 allow_examples 列表。两者都为空时，安全护栏可以加载，但保持不活动。两个阈值都没有默认值——余弦分数在不同向量嵌入模型之间不可比较，因此文件中列了示例却没有对应阈值会导致校验失败，且被拒绝的是整个文件而不是那一个条目。取值方式参见校准语义筛查安全护栏。其他选项：text_source（默认 user_messages，也可为 all_messages）、max_screened_texts（默认 8）、timeout_ms、max_buffer_bytes、on_buffer_exceeded、output_fail_open。同一钩子的候选消息会在一次批量请求中生成向量嵌入。
custom	script：非空 ES 模块	导出 checkInput、checkOutput 或两者来检查对应钩子；未导出的钩子会跳过。其他选项：secrets、timeout_ms（整个调用默认 5000）、max_memory_bytes（默认 16777216）、stream_processing_mode（默认 window，也可为 buffer_full）、window_size、window_overlap_size、max_buffer_bytes、on_buffer_exceeded、output_fail_open。
pii	—	detectors（内置检测器列表：email、china_mobile、china_id_card、bank_card、us_ssn、ip_address、api_key、jwt、private_key，每个检测器可选 action）、custom_patterns（运维人员正则表达式，包含 name、regex，另可选填每个模式各自的 action 与 replacement）、default_action（默认 mask，或 block）。脱敏片段变为 [<DETECTOR>_REDACTED]，除非该模式设置了 replacement——它按字面量使用（$1 不会展开），且正则带捕获组时只替换第 1 组（参见 PII 脱敏）。该安全护栏自身的拒绝响应和日志行不包含匹配值；其他可能带出匹配值的文本参见网关记录的内容。
presidio	analyzer_url、anonymizer_url：客户自行运行的 Presidio 容器基础 URL。	entities（Presidio 实体类型，每个实体可选 action）、default_action、operator（默认 replace，也可为 mask、hash、redact）、language（默认 en）、score_threshold。
openai_moderation	api_key	model（默认 omni-moderation-latest）、category_thresholds（按类别配置分数；空值采用服务提供方的 flagged 判定）、endpoint 覆盖。仅检测，不会改写内容。
lakera	api_key	project_id，以及用于区域或自托管部署的 endpoint 覆盖。
azure_content_safety	endpoint、api_key	Cognitive Services 端点上的 Azure Prompt Shield。
azure_content_safety_text_moderation	endpoint、api_key	categories（默认包含 Hate、Sexual、SelfHarm、Violence 四项）、severity_threshold（默认 2）、severity_threshold_by_category、output_type、blocklist_names、halt_on_blocklist_hit、text_source（默认 concatenate_user_content，或 concatenate_all_content），以及下文的流式控制。text_source 只影响输入钩子。
aliyun_text_moderation	region、access_key_id、access_key_secret	endpoint 覆盖、risk_level_threshold（low、medium、high，默认 high），以及下文的流式控制。
aliyun_ai_guardrail	region、access_key_id、access_key_secret	endpoint 覆盖、service_level（默认为 pro，也可设为 basic），以及下文的流式控制。所选服务等级必须已在阿里云中开通。
bedrock	guardrail_id、guardrail_version、region、aws_credentials（{kind: static, access_key_id, secret_access_key, session_token?}、{kind: api_key, api_key} 或 {kind: default_chain}；static 和 default_chain 还接受 role_arn、external_id 和 role_session_name，参见选择安全护栏凭证）、latency_mode（{kind: serial} 或 {kind: timed, timeout_ms: 100–5000}）	—

可选择流式处理模式的类型包括 Azure 文本审核、阿里云内容审核、阿里云 AI 安全护栏和 custom。它们支持窗口处理或完整缓冲。语义检查必须比较完整文本，因此始终缓冲完整输出。

字段	适用范围	行为
stream_processing_mode	可选择流式处理模式的类型	window 以滑动窗口增量释放内容，也是默认值；buffer_full 会在释放前保留完整响应。
window_size	可选择流式处理模式的类型	设置滑动窗口大小。
window_overlap_size	可选择流式处理模式的类型	设置连续窗口之间的重叠大小。
max_buffer_bytes	PII、Lakera、Presidio、semantic，以及使用 buffer_full 模式且可选择流式处理模式的类型。可选择流式处理模式的类型在 window 模式下，凡是输出被整体保留之处（/v1/messages 和 /v1/responses 上的整个流，以及 /v1/chat/completions 上的流式工具调用参数），且链路中没有输出安全护栏使用 buffer_full，也会使用该字段。	为检查而保留的模型生成内容的最大字节数，计入助手文本、推理内容和工具调用参数，不计入 SSE 和 JSON 帧结构。保留的原始字节另有上限，为该值的 128 倍。超过任一上限都按 on_buffer_exceeded 处理。默认 262144。
on_buffer_exceeded	上述缓冲类型	fail_closed 在超过缓冲区限制时拒绝处理，也是默认值；fail_open 会不经扫描释放内容，并记录绕过原因 output_buffer_exceeded。

服务提供方凭证（api_key、access_key_secret、aws_credentials.secret_access_key、aws_credentials.session_token、aws_credentials.api_key）和自定义脚本的 secrets 值属于敏感信息，请以 ${VAR} 形式提供。各类型的行为请参见安全护栏指南。

以下示例将本地输入检查与远程内容审核组合起来。block-secrets 会在上游调用前拒绝匹配的请求文本；content-moderation 则在默认的 both 钩子上使用 OpenAI Moderation API 检查请求和响应。

resources.yaml

_format_version: "1"

guardrails:
  # 仅作用于请求侧的进程内关键词阻断列表。
  - name: block-secrets
    kind: keyword
    hook_point: input
    patterns:
      - kind: literal
        value: internal-project-codename
      - kind: regex
        value: '\bAKIA[0-9A-Z]{16}\b'

  # 远程内容审核；所列类别达到阈值时阻断。
  - name: content-moderation
    kind: openai_moderation
    api_key: ${OPENAI_API_KEY}
    category_thresholds:
      violence: 0.5

安全护栏绑定

绑定关系将一个安全护栏关联到它要检查的流量。没有任何绑定的安全护栏会正常加载、计入资源总数，但不检查任何流量——网关会为它记录一次包含其名称的警告，aisix validate 也会列出它，但退出码仍为 0。这是一个合法状态：绑定通过标识引用目标，而该目标可能已从文件中移除。

字段	类型	必填	说明
guardrail_id	string	是	要绑定的安全护栏名称，必须匹配 guardrails 中的条目。
scope_type	string	是	env、model、mcp_server、api_key、team、passthrough_route 之一。
scope_id	string	条件必填	作用目标的标识。scope_type: env 时省略，其余作用域必填。
priority	integer	是	同一请求的多条绑定选中同一个安全护栏时，数值大的优先。
enabled	boolean	否	默认为 true。已禁用的绑定不产生作用范围，但仍算作该安全护栏已被附加，因此不会被报告为「未附加」。

scope_id 使用目标集合自身的标识书写——模型的 display_name、MCP 服务器或透传路由的 name、调用方 API Key 的 display_name——加载器会把它解析成与目标条目相同的派生 ID。scope_type: team 在文件中没有对应集合，因此其 scope_id 原样保留，与调用方 API Key 声明的 team_id 直接比较。

更新 guardrails 和 guardrail_attachments；如果顶层集合不存在，则各创建一次。请保留不相关的条目和集合，不要重复创建任何一个顶层 Key。

resources.yaml（安全护栏和绑定）

guardrails:
  - name: no-secrets
    kind: keyword
    patterns:
      - kind: literal
        value: supersecret-banned-token

guardrail_attachments:
  # 检查该网关处理的每个请求。
  - guardrail_id: no-secrets
    scope_type: env
    priority: 100
  # ……或只检查发往某个模型的流量。
  - guardrail_id: no-secrets
    scope_type: model
    scope_id: gpt-4o
    priority: 100

上面两条绑定指向同一个安全护栏，因此发往 gpt-4o 的请求只会执行它一次：优先级最高的匹配生效，重复项被丢弃。

MCP 服务器

MCP 服务器条目以 <name>__<tool> 的形式向 MCP 客户端公开工具。它可以连接上游 MCP 服务器，也可以根据内联 OpenAPI 文档生成工具。两种情况下，上游凭证均由网关保存；该凭证不会从调用方客户端转发，也不会暴露给调用方。

字段	类型	必填	说明
name	string	是	条目标识，在 mcp_servers 中唯一，也是该服务器工具的命名空间前缀。不得包含保留分隔符 __，也不得包含 *——已注册的服务器名称永远不是模式。可以使用 display_name 作为替代写法，但只能使用其中一种。
type	enum	否	mcp（默认）连接真实 MCP 服务器；openapi 根据 OpenAPI 文档生成工具，并将调用作为常规 HTTP 请求发送。
url	string	是	对于 type: mcp，这是上游 MCP 端点；对于 type: openapi，这是生成工具调用所用的 REST API 基础 URL。
spec	object	是*	内联 OpenAPI 3.x 文档，type: openapi 时必填，type: mcp 时忽略。在资源文件中，将文档写成嵌套 YAML 映射。
transport	enum	否	streamable_http，这是 type: mcp 唯一受支持的传输方式，也是默认值。
protocol_version	enum	否	上游会话使用的 MCP 协议修订版，仅对 type: mcp 有效。除非服务器要求无状态的 2026-07-28 修订版，否则不要设置：默认的 initialize 握手会自动协商修订版，对保持向后兼容的 2026-07-28 服务器同样适用。请为该值加引号，使 YAML 将其解析为字符串。
auth_type	enum	否	网关向上游认证的方式：none（默认）、bearer（将 secret 作为 Authorization: Bearer 发送）、api_key（将 secret 作为 API Key 请求头发送），oauth2（客户端凭证授权；Token 会缓存到即将过期前）、oauth_delegate（调用方在 x-aisix-api-key 中发送网关 Key 时，原样转发调用方自己的 Authorization；无凭证字段），或 oauth2_token_exchange（在 token_url 交换调用方经验证的 JWT；参见 Entra 代理（On-Behalf-Of）Token 交换）。oauth_delegate 和 oauth2_token_exchange 需要 1.7.1 之后发布的网关。oauth2_authorization_code 让每个用户自行登录，仅限 type: mcp，需要 1.8.0 之后发布的网关；参见 MCP 交互式登录。
api_key_header	string	否	type: openapi 且 auth_type: api_key 时使用的请求头。默认 x-api-key。真实 MCP 服务器始终使用 x-api-key 进行 API Key 身份认证。
forward_client_headers	字符串数组	否	中继给该服务器的入站客户端请求头，取值为精确名称或含一个 * 的通配符（例如 x-trace-*），匹配不区分大小写。为空（默认值）时不转发任何请求头。type: mcp 和 type: openapi 均适用，因此以工具形式暴露的 REST API 在每次工具调用时都会收到它们。凭证槽位以及 traceparent/tracestate 只有在模式精确点名时才会中继。中继的凭证会占用 auth_type 本会填入的槽位，而不是与之并存，其中包括 api_key_header 指定的那个请求头——只要它被改成该清单之外的名称，通配符就能匹配到它。host、逐跳请求头、x-aisix-*、网关会重新序列化的请求体与内容协商请求头、set-cookie、anthropic-version、x-stainless-*，以及 MCP 会话槽位（mcp-session-id、mcp-protocol-version、last-event-id）绝不会被中继。参见上游请求头。
secret	string	否	根据 auth_type，表示 Bearer Token、API Key 或 OAuth 客户端 Secret。bearer、api_key、oauth2 和 oauth2_token_exchange 必填。请以 ${VAR} 形式提供。
client_id	string	否	OAuth 客户端标识符，auth_type: oauth2 或 oauth2_token_exchange 时必填。oauth2_authorization_code 时可选，省略时网关会将自身注册为公共客户端。
token_url	string	否	网关获取上游访问 Token 的 OAuth Token 端点，auth_type: oauth2 或 oauth2_token_exchange 时必填。oauth2_authorization_code 时可选，省略时从上游发现。
authorization_url	string	否	用户被发送到的 OAuth 授权端点，用于 auth_type: oauth2_authorization_code。省略时从上游发现。
registration_url	string	否	OAuth 动态客户端注册端点，用于 auth_type: oauth2_authorization_code 且没有 client_id 时。省略时从上游发现。
scopes	字符串数组	否	OAuth 作用域，会以空格连接后写入 Token 请求。oauth2 和 oauth2_authorization_code 时可选；oauth2_token_exchange 时至少需要一个。
token_exchange_profile	enum	否	auth_type: oauth2_token_exchange 使用的交换协议，此时必填。唯一取值为 entra_obo，即 Microsoft Entra ID 代理（On-Behalf-Of）流程。
timeout_ms	integer	否	每个上游操作（建立会话、列出工具、调用工具）的截止时间。最小 1，默认 30,000 ms。
enabled	boolean	否	false 会从列表和调用中移除该服务器的工具。默认 true。

通过每个 Key 的 api_keys[].mcp_access 授予调用方工具访问权限。调用方连接流程请参见 MCP 网关概览。

以下条目将远程 MCP 服务器公开为 github 工具命名空间，并通过环境变量中的 Bearer Token 向上游进行身份认证：

resources.yaml

_format_version: "1"

mcp_servers:
  - name: github
    type: mcp
    url: https://api.example.com/mcp
    auth_type: bearer
    secret: ${GITHUB_MCP_TOKEN}

基于 OpenAPI 的服务器

对于 type: openapi，受支持的 HTTP 操作会成为 MCP 工具。存在 operationId 时，AISIX 使用它作为工具名称；否则根据 HTTP 方法和路径派生名称。资源文件直接在 spec 下接受文档，不接受 AISIX Cloud Admin API 的写入字段 spec_content 或 spec_url。

以下示例中，listItems 操作成为 inventory 命名空间中的 MCP 工具。工具调用会携带插值后的 API Key，通过 X-Inventory-Key 发送到已配置的 REST API。

resources.yaml

_format_version: "1"

mcp_servers:
  - name: inventory
    type: openapi
    url: https://inventory.example.com/api
    auth_type: api_key
    api_key_header: X-Inventory-Key
    secret: ${INVENTORY_API_KEY}
    spec:
      openapi: 3.0.0
      info:
        title: Inventory API
        version: 1.0.0
      paths:
        /items:
          get:
            operationId: listItems
            responses:
              "200":
                description: 已成功返回条目

A2A Agent

A2A Agent 条目注册一个上游 Agent，网关通过 /a2a/<name> 向调用方暴露它，并提供已将 URL 重写到网关的 Agent Card。与 MCP 服务器一样，上游凭证会保留在网关中。

字段	类型	必填	说明
name	string	是	条目标识，在 a2a_agents 中唯一，也是面向调用方的路径片段。可以使用 display_name 作为替代写法，但只能使用其中一种。
url	string	是	上游 Agent 基础 URL。
protocol_version	enum	否	A2A 传输格式："1.0"（默认）或 "0.3"。请为值添加引号，确保 YAML 将其保留为字符串。
auth_type	enum	否	none（默认）、bearer 或 api_key，语义与 MCP 服务器相同。
secret	string	否	根据 auth_type 使用的上游凭证。请以 ${VAR} 形式提供。
forward_client_headers	字符串数组	否	中继给该 Agent 的入站客户端请求头，取值为精确名称或含一个 * 的通配符（例如 x-trace-*），匹配不区分大小写。为空（默认值）时不转发任何请求头。它对 /a2a/<name>/.well-known/agent-card.json 上的 Agent Card 拉取，以及 /a2a/<name> 上的每个 JSON-RPC 方法都生效，因此 message/send、message/stream 和各类 task 操作都会收到它们。凭证槽位以及 traceparent/tracestate 只有在模式精确点名时才会中继。中继的凭证会占用 auth_type 本会填入的槽位——bearer 填 authorization，api_key 填 x-api-key——而不是与之并存。host、逐跳请求头、x-aisix-*、网关会重新序列化的请求体与内容协商请求头、set-cookie、anthropic-version、x-stainless-*，以及 a2a-version 绝不会被中继。参见上游请求头。
timeout_ms	integer	否	每个上游操作（包括获取 Agent Card）的截止时间。对流式方法（message/stream、tasks/resubscribe）而言，它约束的是建立流的过程而非流的时长，因此长任务不会被中断。最小 1，默认 30,000 ms。
enabled	boolean	否	false 会停止提供该 Agent。默认 true。

通过每个 Key 的 api_keys[].allowed_agents 授予调用方访问权限。完整的调用方连接流程请参阅配置 Agent 网关。

以下条目在 /a2a/invoice-processor 发布上游 Agent，并从环境变量提供其 Bearer Token：

resources.yaml

_format_version: "1"

a2a_agents:
  - name: invoice-processor
    url: https://agents.example.com/a2a
    auth_type: bearer
    secret: ${INVOICE_AGENT_TOKEN}

透传路由

透传路由将匹配的 HTTP 流量中继到服务提供方端点，AISIX 不对正文做归一化，但仍然应用调用方身份认证、路由授权、护栏、限流和遥测。正文信封（chat、completions、Responses API 或不透明）会按请求识别，无需任何配置。SSE 响应会增量中继，除非输出安全护栏为执行检查而暂存帧。匹配、认证、凭证与识别模型的说明见透传路由；本表覆盖文件形式。

以下局部配置块展示一个透传路由。它假定完整资源文件中已经定义了 openai-prod：

resources.yaml（透传路由）

passthrough_routes:
  - name: openai-raw
    path_prefix: /passthrough/openai
    target_url: https://api.openai.com
    provider_key: openai-prod

字段	类型	必填	说明
name	string	是	条目标识，在 passthrough_routes 中唯一。也接受 display_name 写法；只能使用其中一种。调用方 Key 通过 allowed_routes 授予对该名称的访问。
path_prefix	string	条件	路由认领的 URL 路径前缀，例如 /passthrough/openai。path_prefix 和 hosts 至少必须设置其一。不带 hosts 的路由不得认领保留的网关命名空间（/v1、/mcp、/a2a、/admin、/livez、/readyz、/metrics）——网关自身的端点会遮蔽它；带 hosts 的路由则可以，因为 host 匹配的请求在这些端点之前分发。在 target_url 路由上前缀是挂载点，转发前会被剥离；在 preserve_host 路由上前缀仅用于筛选该路由认领哪些请求，完整路径原样转发。
hosts	字符串数组	条件	路由认领的入站 host 值，在路径路由之前匹配。入站 host 优先取请求 URI 的 authority（例如来自其他代理的 absolute-form 请求），否则取 Host 请求头，并忽略端口。条目是精确 host，或带单个前导 *. 通配符且保留至少两个字面标签（*.example.com 可以，*.com 不行）。
target_url	string	条件	匹配请求中继到的上游基础 URL。target_url 和 preserve_host: true 必须恰好设置其一。
preserve_host	boolean	条件	以 https://<matched host> 推导目标，替代固定 target_url。要求设置 hosts。默认 false。
auth_mode	enum	否	网关认证调用方的方式：gateway_key（标准 Authorization 调用方 Key）、header_key（从 auth_header_name 读取调用方 Key，不动 Authorization），或 anonymous（无凭证；路由以 anonymous_key 主体运行）。默认 gateway_key。
auth_header_name	string	条件	携带网关 Key 的小写请求头。header_key 模式必填，其他 auth_mode 下设置会被拒绝。authorization、proxy-authorization、cookie、set-cookie 和 x-api-key 会被拒绝。除非 forward_client_headers 完整写出它的名称，否则会在转发前剥离；通配符触及不到它。
anonymous_key	string	条件	匿名流量以其身份、限流和归因运行的调用方 Key 显示名称。anonymous 模式必填（需同时设置 source_cidrs），其他模式下设置会被拒绝。
source_cidrs	字符串数组	条件	客户端 CIDR 白名单。anonymous 模式必填；其他模式可选。来源不在列表内时以 403 和 error.code: ip_restricted 拒绝。
credential_mode	enum	否	上游凭证处理：inject（移除全部凭证槽位并发送所引用服务提供方密钥的凭证；要求 provider_key）或 forward_client（经过身份认证模式和固定请求头剥离后，中继调用方的上游凭证；禁止设置 provider_key）。在 forward_client 模式下采用 gateway_key 时，除非网关 Key 通过 x-aisix-api-key 传入，否则 AISIX 会剥离 authorization 和 x-api-key；上游凭证使用其中任一槽位时，请改用该请求头、header_key 或 anonymous。默认 inject。
provider_key	string	条件	注入到上游的服务提供方密钥显示名称。inject 必填，forward_client 禁止。
identity_header	string	否	其值记录为用量事件 client_identity 并在转发前剥离的小写请求头，除非 forward_client_headers 完整写出它的名称；通配符触及不到它。authorization、proxy-authorization、cookie、set-cookie 和 x-api-key 会被拒绝。
forward_client_headers	字符串数组	否	即使该路由本会剥离，也仍要中继给上游的入站客户端请求头，取值为精确名称或含一个 * 的通配符（例如 x-trace-*），匹配不区分大小写。为空（默认值）时不覆盖任何剥离行为。路由默认就会中继调用方的请求头，因此该字段只对它会删除的那些有意义：credential_mode: inject 下的全部凭证槽位和服务提供方密钥的 strip_headers，以及 forward_client 下网关用来认证调用方的那个槽位。在 inject 路由上，点名路由注入的槽位（Anthropic 服务提供方密钥是 x-api-key，其他是 authorization）会把调用方自己的凭证放到上游请求上，取代注入的那份；点名其他槽位时，调用方的凭证会与注入的那份一起发送。路由移除的凭证槽位以及 traceparent/tracestate 只有在模式精确点名时才会放回，该路由自己的 auth_header_name 和 identity_header 同理。路由剥离的其他任何名称，通配符都足以放回去，包括 strip_headers 条目——不过该列表四个默认值中有三个属于凭证槽位，仍需单独点名，只有 set-cookie 是通配符能放回的默认项。无论模式如何，host、content-length、逐跳请求头和 x-aisix-* 都会被剥离。参见上游请求头。
timeout_ms	integer	否	响应头阶段和非流式正文读取的上游超时（毫秒）。对于 SSE，它限制等待第一个原始上游正文块的时间，以及相邻原始正文块之间的等待时间；不限制健康中继的总生命周期，也不要求在该间隔内组装完整的 SSE 帧。省略时使用 upstream.stream_timeout_ms，再回退到 upstream.timeout_ms。
enabled	boolean	否	不删除路由而将其停用；停用的路由停止匹配。默认 true。

缓存策略

缓存策略会缓存其匹配请求中符合条件的非流式 Chat Completions 响应；其它端点族和流式响应不会缓存。代理会为每个请求选择第一个匹配且已启用的策略。Key 匹配和验证请参见响应缓存。

字段	类型	必填	说明
name	string	是	条目标识，在 cache_policies 中唯一，长度 1–120 个字符，并显示在指标标签和缓存响应头中。
enabled	boolean	否	false 会暂存策略而不应用。默认 true。
backend	enum	否	memory（默认）或 redis。redis 后端需要网关静态 cache.redis 配置；缺少时，匹配请求不会缓存。
ttl_seconds	integer	否	条目生存时间，1–604,800 秒（7 天）。默认 3600。
applies_to	string	否	资格选择器：all（默认）、model:<alias>（以路由分发前的模型别名为目标的请求），或 api_key:<id>（由该资源 ID 的调用方 API Key 认证的请求）。
scope	enum	否	缓存条目的共享边界，对两个匹配层同时生效：api_key（默认——条目仅对写入它的调用方 API Key 可见）或 env（环境内所有调用方共享条目）。
purge_generation	integer	否	失效计数器，默认 0。递增它会使该策略在更早取值下存储的所有条目失效——两个匹配层、所有网关实例。
semantic	object	否	在精确层之上启用向量相似度匹配。见下方子表。

控制面通过清空操作管理 purge_generation。在资源文件中，请让该值单调递增，并在每次更新时保留当前值。降低或省略该值可能会使更早的精确缓存条目重新可用，直至其 TTL 过期。

semantic 字段：

字段	类型	必填	说明
embedding_model	string	是	本文件中带 embedding 块的模型条目的 display_name。其 dimensions 值固定该策略条目的向量维度。
threshold	number	是	条目被返回所需的最小余弦相似度，取值 0–1，越高越严格；低于约 0.9 时错误答案风险显著上升。
max_entries	integer	否	memory 后端下的条目上限，1–10,000，默认 1000，最旧的先被淘汰。共享后端按 TTL 控制规模并忽略此值。
embedding_timeout_ms	integer	否	向量嵌入调用的单次超时。超时后请求不经缓存直接发往上游。0 或缺省表示不设单独超时。

只有消息内容全部为文本的请求才参与相似度匹配。在 backend: redis 上，语义层需要 Redis 8+（向量检索）、RESP2，以及 single 或 sentinel 模式。不满足这些要求时，策略只提供精确匹配并记录警告。参见语义缓存。

applies_to 值在请求时匹配，不会在加载时解析。对于 api_key，资源加载器不会解析 display_name，请使用派生 ID。不匹配任何内容的模型别名不会产生缓存。与之不同，semantic.embedding_model 引用必须指向同一文件中的向量嵌入模型条目——悬空的名字会在记录警告后禁用语义层，精确缓存继续工作。

注意

无法识别的 applies_to 前缀按 all 处理。因此，前缀拼写错误会扩大缓存范围，而不是禁用策略。

以下完整示例在内存中缓存 gpt-4o 别名的非流式响应，缓存时间为 10 分钟：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-prod
    provider: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o-2024-11-20
    provider_key: openai-prod

cache_policies:
  - name: gpt-4o-cache
    backend: memory
    ttl_seconds: 600
    applies_to: "model:gpt-4o"

可观测性导出器

可观测性导出器会把请求遥测发送到外部系统。kind 字段选择后端，该类型的字段直接位于条目中。每种类型都是封闭的，因此会拒绝未知字段，包括任何明文凭证字段。

所有类型共享以下字段：

字段	类型	必填	说明
name	string	是	条目标识，在 observability_exporters 中唯一，长度 1–120 个字符。
kind	enum	是	otlp_http、aliyun_sls、datadog 或 object_store。
enabled	boolean	否	已禁用的导出器保留配置，但不会接收遥测。默认 true。

所选 kind 还会添加该后端的专用字段：

kind	必填字段	可选字段
otlp_http	endpoint：包含接收器路径的完整 OTLP/HTTP 链路 URL，例如 https://api.honeycomb.io/v1/traces。可使用任意主机的 https:// 或 http://；1.7.0 及更早版本的网关仅对回环和测试主机接受 http://。	headers（每个导出请求的静态请求头，请把 API Key 放在 ${VAR} 值中）、sample_rate（0.0–1.0；省略时，不会通过采样丢弃任何已发出的请求链路）、content_mode、content_max_bytes。
aliyun_sls	endpoint（区域 *.aliyuncs.com 主机，不带协议）、project、logstore、credential_ref	content_mode、content_max_bytes。
datadog	site（已知 Datadog 站点，例如 datadoghq.com 或 datadoghq.eu）、service、credential_ref	ddsource（默认 aisix-ai-gateway）、tags（渲染为 ddtags）、content_mode、content_max_bytes。
object_store	provider（s3、gcs 或 azure_blob）、bucket、prefix	region（S3 签名作用域）、endpoint（后端覆盖：s3 为 MinIO、OSS 或 R2 等 S3 兼容主机；gcs 为 Cloud Storage XML API 基础 URL，例如私有端点，必须提供上传所用的 XML API，并优先于服务账号 JSON 中的 gcs_base_url；azure_blob 为 Blob 端点。可使用任意主机的 https:// 或 http://；1.7.0 及更早版本的网关仅对回环和测试主机接受 http://。与 auth_mode: cloud_identity 同时设置的导出器可以加载，但永远不会上传，网关会为其报告永久性投递错误）、compression（默认 gzip，或 none）、auth_mode、credential_ref。

对于 otlp_http、aliyun_sls 和 datadog，content_mode 控制导出记录是省略提示词和响应内容（metadata_only，默认值），还是包含这些内容（full）。在 full 模式下，content_max_bytes 将每个捕获内容字段限制为 1–1,048,576 字节，默认 131,072。object_store 类型不接受这两个字段。

有关投递和内容捕获行为，请参见可观测性导出器。

远程凭证绝不会直接保存在导出器资源中。在下列变量名中，<REF> 是把导出器的 credential_ref 转成大写，并将非字母数字字符替换为下划线后的结果，例如 datadog-prod 会变成 DATADOG_PROD。

导出器	凭证来源
OTLP/HTTP	将 API Key 放在插值后的 headers 值中。
阿里云 SLS	名为 <REF> 的凭证引用会解析 SLS_CRED_<REF>_AK_ID 和 SLS_CRED_<REF>_AK_SECRET。
Datadog	名为 <REF> 的凭证引用会解析 DD_CRED_<REF>_API_KEY。
对象存储	名为 <REF> 的凭证引用会解析适用的 OBJSTORE_CRED_<REF>_* 变量。对于 S3 和 GCS，cloud_identity 使用主机挂载的身份，不需要凭证引用。

以下示例比较三种凭证加载方式：直接在 OTLP 请求头中插值、使用命名的 Datadog 凭证引用，以及为 S3 使用挂载的云身份。YAML 下方的带圈数字说明高亮字段会解析为何值。

resources.yaml

_format_version: "1"

observability_exporters:
  - name: honeycomb-prod
    kind: otlp_http
    endpoint: https://api.honeycomb.io/v1/traces
    headers:
      x-honeycomb-team: ${HONEYCOMB_API_KEY}
    sample_rate: 0.25

  - name: datadog-prod
    kind: datadog
    site: datadoghq.com
    credential_ref: datadog-prod
    service: ai-gateway
    tags: ["team:platform", "tier:prod"]

  - name: s3-events
    kind: object_store
    provider: s3
    bucket: acme-aisix-events
    prefix: ai-gateway
    region: us-east-1
    auth_mode: cloud_identity

❶ 标准资源插值会从 HONEYCOMB_API_KEY 提供 Honeycomb API Key。

❷ datadog-prod 引用会从 DD_CRED_DATADOG_PROD_API_KEY 解析 API Key；该凭证绝不会出现在资源文件中。

❸ cloud_identity 使用主机挂载的云身份，而不是静态 Key。此模式支持 S3 和 GCS 导出器。

限流策略

限流策略独立于模型和调用方 API Key 上的内联 rate_limit 块，对请求数或 Token 数施加上限。需要匹配多个请求属性或按维度拆分计数器时，请使用条件式；针对一个主体和一个固定窗口时，请使用经典形式。每个条目必须且只能使用一种形式；混用两种形式的字段会导致加载错误。有关配置路径和验证方法，请参见限流策略。

条件式

新策略请使用条件式。它通过条件树匹配请求，可以按维度拆分计数器，并支持请求、Token 和并发限制。

字段	类型	必填	说明
name	string	是	条目标识，在 rate_limit_policies 中唯一。计数器以派生 ID 为 Key，因此可以跨重新加载保留。
conditions	array	否	请求必须满足的条件节点。顶层节点全部生效（AND）；空数组或省略表示匹配所有请求。每个节点可以是条件（dimension、operator、可选 negate、value），也可以是分组（logic: and | or、可选 negate、children）。每条策略最多嵌套 3 层并包含 16 个条件。节点字段见下文。
group_by	array	否	用于拆分桶的维度，可以是 team、member、api_key、model、provider 的任意子集。每种不同的值组合使用独立计数桶和相同的限制；空数组或省略表示使用一个共享桶。如果匹配的请求缺少其中某个维度，则该策略不适用于该请求。
limits	object	是	至少包含 rps、rpm、rph、rpd、tpm、tpd、concurrency 中的一项，最小值均为 1；其结构和语义与内联 rate_limit 块相同，包括可选的 window_type。
action	enum	否	超限行为。目前仅支持 reject（返回 HTTP 429），也是默认值。
schedules	array	否	周期性暂停窗口，与经典形式相同，见下文。

conditions 节点可以是条件或分组。条件接受以下字段：

字段	类型	必填	说明
dimension	enum	是	team、member、api_key、model、model_name 或 provider。对于 api_key 和 model，值为同一文件中所定义条目的 display_name；加载时会解析它，未知名称会导致加载错误。team/member 值与调用方 API Key 的 team_id/user_id 原样匹配。model 和 model_name 匹配分发模型，并且——当请求经由模型组、语义路由器或合议模型路由时——同时匹配调用方所指向的父条目：组名可以选中所有经由该组路由的请求，成员名无论直接调用还是经组调用都会被选中；negate 会同时排除两个身份。provider 匹配分发模型的服务提供方 ID。
operator	enum	是	==、~=（不等于）、in、~~（正则表达式）或 ~*（不区分大小写的正则表达式），即 lua-resty-expr Token。正则表达式运算符仅适用于 model_name 和 provider；模式最长 256 个字符且必须能够编译。
negate	boolean	否	对条件取反，即 lua-resty-expr 的 ! 前缀；negate 与 in 组合表示“不在其中”。不携带该维度的请求既不匹配原条件，也不匹配其取反。
value	string 或 array	是	标量运算符使用一个字符串；in 使用包含 1–64 个字符串的数组。

如需使用嵌套布尔逻辑，请使用分组节点：

字段	类型	必填	说明
logic	enum	是	and 或 or，决定 children 的组合方式。
negate	boolean	否	对分组结果取反（!AND/!OR）。
children	array	是	至少包含一个嵌套节点，可以是条件或更深一层的分组。

经典形式

针对一个主体的策略仍然完整支持经典形式。

字段	类型	必填	说明
scope	enum	是	主体类型：api_key、model、team（整个团队共享一个桶）、member，或 team_member（团队限制，但每个成员使用独立计数器）。
scope_ref	string	是	指定主体。对于 scope: api_key 或 scope: model，填写同一文件中所定义条目的 display_name；加载时会解析它，未知名称会导致加载错误。对于 team、member 和 team_member，填写团队或用户 ID，并与调用方 API Key 的 team_id 或 user_id 原样匹配。
window	enum	是	second、minute、hour 或 day。
max_requests	integer	否*	每个窗口允许的请求数，最小 1。max_requests 和 max_tokens 至少配置一个。
max_tokens	integer	否*	每个窗口允许的 Token 数，最小 1。Token 上限在 minute 和 day 窗口执行；在 second 和 hour 窗口中，该值可以接受但不会应用。请将 max_tokens 与 minute 或 day 窗口配合使用，参见管理经典单作用域策略。
schedules	array	否	周期性挂钟时间窗口，窗口内暂停执行该策略。窗口结束后会在相同计数器上自动恢复执行。条目字段见下文，也可参阅按时间表暂停策略。

每个 schedules 条目按星期（days_of_week）或显式日期（dates）选择生效日，两者必须且只能配置一个：

字段	类型	必填	说明
timezone	string	是	用于解释该条目挂钟时间字段的 IANA 时区，例如 Asia/Shanghai。
days_of_week	array	否*	每周重复，可包含 mon、tue、wed、thu、fri、sat、sun；与 dates 互斥。
dates	array	否*	timezone 时区下显式指定的 YYYY-MM-DD 日期，用于节假日或其他不规则日期；与 days_of_week 互斥。
start_time	string	是	窗口开始时间，采用 HH:MM 挂钟时间，包含该时刻。
end_time	string	是	窗口结束时间，采用 HH:MM 挂钟时间，不包含该时刻；24:00 表示当天结束。结束时间早于开始时间表示跨越午夜，窗口归属于其开始日。相同的起止时间会被 AISIX Cloud Admin API 拒绝，并且在资源文件中永不匹配。例如 days_of_week: [fri] 且时间为 22:00 至 09:00 时，窗口覆盖星期五 22:00 至星期六 09:00。

以下示例以两种形式设置每分钟 300 个请求的限额。条件式策略为 gpt-4 模型系列的每个团队创建独立计数器；经典策略为 gpt-4o 模型别名创建一个计数器。

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: openai-prod
    provider: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o-2024-11-20
    provider_key: openai-prod

rate_limit_policies:
  # 条件式：gpt-4 系列按团队共享一个 300 RPM 的配额池。
  - name: gpt4-family-per-team
    conditions:
      - dimension: model_name
        operator: "~~"
        value: "^gpt-4"
    group_by: [team]
    limits:
      rpm: 300
  # 经典形式（旧版）：每条策略对应一个主体。
  - name: cap-gpt4o
    scope: model
    scope_ref: gpt-4o
    window: minute
    max_requests: 300
    max_tokens: 100000