资源文件参考

本文档逐字段说明开源 AISIX 网关可加载的声明式 resources.yaml 文件；启动配置需要设置 resources_file。有关编写、校验、加载和验证文件的操作说明，请参见开源 AISIX 网关快速入门、CLI 参考和配置状态。

文件格式

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

_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

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

每个存在的集合都必须是映射序列。不存在或值为 null 的集合按空集合加载。未知顶层 Key 会导致加载错误，并列出已知集合。

集合	条目标识	被以下位置引用
provider_keys	display_name	models[].provider_key
models	display_name	api_keys[].allowed_models、routing、ensemble 和 semantic 内部的模型间引用，以及 rate_limit_policies[].scope_ref
api_keys	display_name	rate_limit_policies[].scope_ref
oidc_providers	name	api_keys[].jwt_provider
guardrails	name	—
mcp_servers	name（或 display_name）	—
a2a_agents	name（或 display_name）	—
cache_policies	name	—
observability_exporters	name	—
rate_limit_policies	name	—

标识与派生 ID

每个条目的标识字段必须是非空字符串，并且在集合中唯一；重复会导致加载错误，并指出两个冲突条目。对于 mcp_servers 和 a2a_agents，可以使用 name 或 display_name 作为标识；同时包含两种写法会导致加载错误，只能使用其中一种。

所有条目都不接受 id 字段。条目 ID 根据 <kind>/<identity> 以 UUIDv5 确定性派生，因此相同文件在重新加载和不同进程中始终生成相同 ID。由 ID 标识的引用和限流计数器因此可以跨 SIGHUP 重新加载保留。

名称引用

文件中的条目通过名称相互引用，加载器会把每个引用解析为派生 ID：

• models[].provider_key 指定服务提供方密钥的 display_name。它与显式 provider_key_id 互斥；未知名称会导致加载错误，并列出已定义的服务提供方密钥。
• api_keys[].allowed_models、routing.targets[].model、ensemble.panel[].model、ensemble.judge.model 和所有 semantic 模型引用均指定模型的 display_name。无法解析到已定义模型的引用会导致加载错误；包含 * 的条目视为 Glob 模式，不执行存在性检查。
• 当 scope 为 model 或 api_key 时，rate_limit_policies[].scope_ref 指定模型或调用方 API Key；对于其它作用域，该值原样传递。

与上述其它引用不同，api_keys[].jwt_provider 会保留为名称，而不解析成派生 ID。请将它设为允许声明该 Key 的 jwt_subject 的 OIDC 服务提供方 name。

环境变量插值

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

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

加载、错误与重新加载

启动、SIGHUP 重新加载和 aisix validate 使用相同的加载流程：读取 → 解析 YAML → 插值 ${VAR} → 转换各条目并解析名称引用 → Schema 校验（与其它所有配置来源相同）→ 交叉引用检查。

错误会在整个文件范围内聚合，并定位到问题条目和字段，例如 models[2] ("gpt-4o")。加载为全有或全无：任何错误都会拒绝整个文件。启动时，网关会快速失败并退出；SIGHUP 重新加载时，网关会继续提供上一个有效快照，记录聚合报告，并通过 GET /status/config 报告被拒绝的加载。网关不会监视文件，必须显式重新加载。

服务提供方密钥

服务提供方密钥保存上游服务提供方凭证及其连接形式。模型通过 display_name 引用服务提供方密钥。每个嵌套层级都会拒绝未知字段。

字段	类型	必填	说明
display_name	string	是	条目标识，在 provider_keys 中唯一。模型通过此名称引用该 Key。
api_key	string	是	上游服务提供方 API Key。请以 ${VAR} 形式提供。也可以使用 secret 作为替代写法；两者必须且只能提供一个。对于凭证包含多个字段的服务提供方，例如 AWS Bedrock 或使用 Entra ID 的 Azure OpenAI，请通过一个环境变量提供 JSON 凭证文档；各凭证格式请参见服务提供方指南。
provider	string	否	上游服务提供方标识符，例如 openai 或 deepseek。这是用于服务提供方专用分发的开放字符串，默认为空。
adapter	enum	否	没有适用的服务提供方专用分发时所用的上游协议族：openai、anthropic、bedrock、vertex 或 azure-openai。参见适配器协议族。
api_base	string	否	覆盖上游服务提供方的基础 URL。私有 OpenAI 兼容端点实际上必须设置此字段。支持部分插值，例如 https://${UPSTREAM_HOST}/v1。
strip_headers	字符串数组	否	透传转发前删除的入站请求头。默认：authorization、cookie、set-cookie、x-api-key。条目会去除首尾空格、转成小写并去重。显式 [] 会禁用删除，不会回退到默认值。
tls	object	否	此 Key 端点的 TLS 设置。缺省时使用部署级 upstream.tls 设置。子字段：ca_cert（此端点额外信任为签发者的 PEM 编码 CA 证书，支持包含多张证书的证书包）和 verify（默认 true；false 接受任意证书，仅用于测试环境）。参见 TLS 和 mTLS。
telemetry_tags	object	否	通过该 Key 路由请求时发出的归因标签。
request	object	否	分发前应用的请求格式覆盖。
response	object	否	由支持的服务提供方桥接器应用的响应格式覆盖。

telemetry_tags 的所有字段均可选：kind（catalog 或 byo）、featured（布尔值，默认 false）、branded_provider（目录条目的品牌 Slug）、pk_label 和 byo_label（运维人员定义的标签，例如 production 或团队名称）。

request 的所有字段均可选：

字段	类型	说明
request.param_renames	字符串到字符串的映射	分发前，把左侧指定的顶层请求体 Key 重命名为右侧 Key。
request.param_constraints.temperature_min、.temperature_max	number	Chat Completions 请求体中 temperature 的截断边界。省略某一边界表示不对该侧截断。
request.default_headers	字符串到字符串的映射	添加到出站请求的请求头。值可以使用 ${...} 变量引用请求上下文，例如 ${request.api_key.team_id}；某个请求中变量无值时，该请求头会被丢弃，而不是发送空值。它们的优先级高于 forward_client_headers 转发的请求头，但网关自身设置同名请求头时会跳过它们。保留的身份认证请求头会作为纵深防御被丢弃。参见上游请求头。
request.forward_client_headers	字符串数组	转发到上游的入站客户端请求头，可以是精确名称或 x-trace-* 之类的单 * Glob，匹配不区分大小写。空值（默认）不转发任何请求头。身份认证、传输、x-aisix-* 和 x-stainless-* 请求头绝不会转发。参见上游请求头。
request.default_body_fields	字符串到 JSON 值的映射	调用方未设置时添加到出站请求的顶层请求体字段。

response 的所有字段均可选：

字段	类型	说明
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	为兼容控制面配置而保留的错误信封首选项；代理目前不会应用。

_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-----

模型

模型条目是面向调用方的模型别名：调用方会把其 display_name 放入请求的 model 字段。直接、向量嵌入、合议和语义别名也会出现在 /v1/models 中；路由别名和通配符模式不会列出（参见模型别名）。每个条目只包含一种分发形态：直接模型三元组（provider + model_name + provider_key_id）、routing 块、ensemble 块或 semantic 块。在同一条目中混合不同形态会导致加载错误，每个嵌套层级也都会拒绝未知字段。

所有形态均接受以下字段：

字段	类型	必填	说明
display_name	string	是	条目标识，在 models 中唯一，也是面向调用方的别名。
timeout	整数（ms）	否	非流式上游调用的端到端截止时间。缺省时依次回退到路由模型的 timeout 和部署级 upstream.timeout_ms 默认值（6000000 ms，即 6000 s）。0 会对此模型禁用超时。
stream_timeout	整数（ms）	否	上游流式分块之间的最长间隔。0 或缺省时依次回退到路由模型的 stream_timeout、模型（或路由模型）的 timeout 和部署默认值。
rate_limit	object	否	按模型设置请求、Token 和并发限制，见下文。
allowed_cidrs	字符串数组	否	采用 CIDR 表示法的客户端 IP 允许列表（支持 IPv4 和 IPv6）。空值或缺省允许所有客户端。配置限制后，缺少或格式错误的源 IP 会被拒绝。
cost	object	否	用于预算跟踪和 least_cost 排序的每 Token 成本：input_per_1k 和 output_per_1k，单位均为每 1,000 个 Token 的美元；存在该块时两者都必填。

rate_limit 子字段均可选，缺省时不限制：rps、rpm、rph、rpd（分别为固定的 1 秒、60 秒、3,600 秒和 86,400 秒窗口内的请求数）、tpm、tpd（60 秒和 86,400 秒窗口内的 Token 数），以及 concurrency（最大进行中请求数；它是信号量，不是窗口）。

直接模型

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

字段	类型	必填	说明
provider	string	是	服务提供方标识，例如 openai 或 anthropic。首字符必须为小写字母或数字；后续可使用 .、_ 和 -；长度 1–64 个字符。
model_name	string	是	在服务提供方请求中发送的上游模型标识，例如 gpt-4o-2024-11-20。
provider_key	string	是*	provider_keys 条目的名称。与 provider_key_id 互斥；在资源文件中请使用 provider_key。
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	否	发生可重试上游失败后的请求路径冷却，见下文。

cooldown 子字段均可选：enabled（默认 true）、default_seconds（没有可用 Retry-After 请求头时的 TTL，默认 30）、max_seconds（使用 Retry-After 时的上限，默认 600）、honor_retry_after（默认 true）、trigger_statuses（默认 [401, 408, 429, 500, 502, 503, 504]；设置该字段会替换整个列表）、trigger_on_timeout（默认 true）和 trigger_on_transport（默认 true）。

只有直接模型可以配置 embedding、background_model_check 和 cooldown。

路由模型

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

字段	类型	必填	说明
routing.targets	array	是	有序目标集合，至少一个条目。targets[].model 指定直接模型；targets[].weight（默认 1）用于 weighted 策略；targets[].tags 把目标限定到携带匹配路由标签的请求，其中 default 标签保留为回退标记。
routing.strategy	enum	否	round_robin、weighted、failover（默认）、least_cost、least_latency 或 least_busy。位置策略会选择一个起始目标，并在失败时向后遍历；指标策略会按最佳优先对所有目标排序。
routing.retries	integer	否	故障转移前在当前目标上的重试次数。默认 0。
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.sticky	boolean	否	确定性 weighted 选择：把 x-aisix-routing-key 请求头（缺省时使用调用方 API Key）哈希到权重分布，让同一 Key 落到同一目标。默认 false。

行为和完整示例请参见多目标模型。

合议模型

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（通过 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>" }（路由到指定模型）。

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

_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: weighted
      sticky: true
      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。空数组拒绝所有模型。
rate_limit	object	否	按 Key 设置限制，子字段与模型的 rate_limit 相同：rps、rpm、rph、rpd、tpm、tpd、concurrency。
allowed_tools	字符串数组	否	此 Key 可以调用的 MCP 工具，使用 <server>__<tool> 名称，并按单 * Glob 匹配："github__*" 授予某个服务器上的所有工具。省略、null 或空值表示无 MCP 工具访问权限。
allowed_agents	字符串数组	否	此 Key 可以访问的 A2A Agent，按注册名称和单 * Glob 匹配。省略、null 或空值表示无 A2A Agent 访问权限。
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	否	仅用于遥测标签的可读所有者名称。

_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

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

OIDC 服务提供方

OIDC 服务提供方条目定义网关在调用方认证中信任的外部签发者及其 JWT Token。已验证身份会映射到 jwt_provider 和 jwt_subject 字段分别与服务提供方和 Token 匹配的调用方 API Key。

字段	类型	必填	说明
name	string	是	条目标识，在 oidc_providers 中唯一。调用方 API Key 通过此名称引用服务提供方。
issuer	string	是	预期的 JWT iss 声明，进行精确比较。每个已启用服务提供方必须使用不同签发者。
audiences	字符串数组	是	接受的 JWT aud 值。Token 必须至少包含一个已配置值；列表至少包含一个条目。
jwks_uri	string	否	获取签名 Key 的 JWKS 端点。省略时，AISIX 从 <issuer>/.well-known/openid-configuration 解析。
identity_claim	string	否	其字符串值用于选择调用方 API Key jwt_subject 的声明。Key 中的点用于遍历嵌套对象。默认：sub。
required_scopes	字符串数组	否	必须全部出现在 Token scope 声明中的作用域。该声明可以是空格分隔字符串或数组。默认：不要求作用域。
bound_claims	object	否	必须全部满足的额外声明要求。Key 中的点用于遍历嵌套声明。每个值可以是字符串或非空数组；字符串声明必须等于某个接受值，数组声明必须包含一个接受值。
leeway_secs	integer	否	exp 和 nbf 的时钟偏差容许值，范围为 0 到 300 秒。默认 0。
enabled	boolean	否	服务提供方是否参与身份认证。默认 true。

issuer 和 jwks_uri 的用户信息或疑似凭证查询参数中不得包含嵌入凭证。AISIX 接受非对称 JWT 签名算法，并拒绝 HMAC 签名 Token。支持的算法、请求行为和 Key 轮换请参见 JWT 认证。

_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

加载文件前，请在网关进程环境中设置 BILLING_AGENT_KEY。当此身份需要调用模型端点时，请向 allowed_models 添加模型别名。

安全护栏

安全护栏条目用于检查请求或响应内容。资源文件没有挂载集合，因此每个已启用的安全护栏都会作用于所有请求。kind 字段选择服务提供方，该类型的配置字段直接位于条目中，不存在嵌套 config 对象。所选类型的未知字段会被拒绝。

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

字段	类型	必填	说明
name	string	是	条目标识，在 guardrails 中唯一，并显示在指标标签和错误原因中。
kind	enum	是	服务提供方鉴别器，见下方类型表。
enabled	boolean	否	false 会暂存规则但不运行。默认 true。
hook_point	enum	否	规则运行位置：input（请求负载，在上游调用前）、output（上游响应）或 both（默认）。
enforcement_mode	string	否	block（默认）会执行判定；monitor 记录本应发生的结果，但不阻断或脱敏。
fail_open	boolean	否	对于远程 API 类型，输入挂载点无法访问安全护栏服务提供方时的行为：true（默认）允许请求并记录绕过；false 返回 422 阻断。
output_fail_open	boolean	否	远程 API 类型输出挂载点的相同策略；keyword 和 pii 会拒绝此字段。默认 false，服务提供方中断时保留模型输出，而不是释放未经扫描的内容。
mandatory	boolean	否	true 会使安全护栏求值错误变为致命错误，并在失败路径上覆盖 fail_open。默认 false。
timeout_ms	integer	否	仅适用于远程 API 类型的单调用超时；keyword、pii 和 bedrock 会拒绝此字段（Bedrock 使用 latency_mode）。默认 5000。
created_at	string	否	RFC 3339 时间戳。存在时，安全护栏按最早时间优先求值；没有此字段的条目排在最后。

各类型的专用配置和必填字段：

kind	必填字段	重要选项
keyword	patterns：进程内求值的 {kind: literal | regex, value} 阻断模式数组。空列表可以加载，但不会匹配任何内容。	—
pii	—	detectors（内置检测器列表：email、china_mobile、china_id_card、bank_card、us_ssn、ip_address、api_key、jwt、private_key，每个检测器可选 action）、custom_patterns（包含 name 和 regex 的运维人员正则表达式）、default_action（默认 mask，或 block）。脱敏片段变为 [<DETECTOR>_REDACTED]；匹配值绝不会出现在日志或错误中。
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，以及下文的流式控制。
aliyun_text_moderation	region、access_key_id、access_key_secret	endpoint 覆盖、risk_level_threshold（low、medium、high，默认 high），以及下文的流式控制。
bedrock	guardrail_id、guardrail_version、region、aws_credentials（{kind: static, access_key_id, secret_access_key}）、latency_mode（{kind: serial} 或 {kind: timed, timeout_ms: 100–5000}）	—

对于流式输出，两种文本审核类型接受 stream_processing_mode（window：滑动窗口增量释放，默认；或 buffer_full：保留整个响应）、window_size 和 window_overlap_size。缓冲类型（pii、lakera、presidio，以及处于 buffer_full 模式的文本审核类型）接受 max_buffer_bytes（默认 262144）和 on_buffer_exceeded（默认 fail_closed，或 fail_open）。

服务提供方凭证（api_key、access_key_secret、aws_credentials.secret_access_key）属于机密，请以 ${VAR} 形式提供。各服务提供方的行为请参见安全护栏指南。

_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

MCP 服务器

MCP 服务器条目注册一个上游 MCP 服务器，网关以 <name>__<tool> 的形式向 MCP 客户端暴露其工具。网关保存上游凭证；该凭证不会从调用方客户端转发，也不会暴露给调用方。

字段	类型	必填	说明
name	string	是	条目标识，在 mcp_servers 中唯一，也是该服务器工具的命名空间前缀。不得包含保留分隔符 __。可以使用 display_name 作为替代写法，但只能使用其中一种。
url	string	是	上游服务器 MCP 端点，例如 https://api.example.com/mcp。
transport	enum	否	streamable_http，这是唯一受支持的传输方式，也是默认值。
auth_type	enum	否	网关向上游认证的方式：none（默认）、bearer（将 secret 作为 Authorization: Bearer 发送）、api_key（将 secret 作为 x-api-key 发送），或 oauth2（客户端凭证授权；Token 会缓存到即将过期前）。
secret	string	否	根据 auth_type，表示 Bearer Token、API Key 或 OAuth 客户端 Secret。请以 ${VAR} 形式提供。
client_id	string	否	OAuth 客户端标识符，与 auth_type: oauth2 一起使用。
token_url	string	否	交换客户端凭证的 OAuth Token 端点，与 auth_type: oauth2 一起使用。
scopes	字符串数组	否	OAuth 作用域，会以空格连接后写入 Token 请求。
timeout_ms	integer	否	每个上游操作（建立会话、列出工具、调用工具）的截止时间。最小 1，默认 30,000 ms。
enabled	boolean	否	false 会从列表和调用中移除该服务器的工具。默认 true。

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

_format_version: "1"

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

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} 形式提供。
timeout_ms	integer	否	每个上游操作（包括获取 Agent Card）的截止时间。最小 1，默认 30,000 ms。
enabled	boolean	否	false 会停止提供该 Agent。默认 true。

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

_format_version: "1"

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

缓存策略

缓存策略会缓存其匹配请求中符合条件的非流式 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 认证的请求）。

applies_to 值在请求时匹配，不会在加载时解析：不匹配任何内容的模型别名不会产生缓存；无法识别的前缀按 all 处理，这种保守回退会保持缓存启用，而不是静默禁用。

_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	必填字段	可选字段
otlp_http	endpoint：包含接收器路径的完整 OTLP/HTTP Trace URL，例如 https://api.honeycomb.io/v1/traces。除回环和测试主机外必须使用 https://。	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（MinIO、OSS、R2 的 S3 兼容覆盖；除回环和测试主机外必须使用 https://）、compression（默认 gzip，或 none）、auth_mode、credential_ref。

content_mode（默认 metadata_only，或 full）控制导出记录是否包含提示词和响应内容；content_max_bytes（默认 131,072；范围 1–1,048,576）会在 full 模式下截断捕获内容。投递和内容捕获行为请参见可观测性导出器。

远程凭证绝不会保存在此资源中。credential_ref 是间接引用：网关从自身环境变量中解析它，环境变量名由 Ref 转成大写并将连字符替换为下划线：aliyun_sls 使用 SLS_CRED_<REF>_AK_ID 和 SLS_CRED_<REF>_AK_SECRET，datadog 使用 DD_CRED_<REF>_API_KEY，object_store 使用 OBJSTORE_CRED_<REF>_*。对于 object_store，auth_mode: cloud_identity（仅支持 S3 和 GCS）会使用主机挂载的云身份，此时 credential_ref 可选；默认的 credential_ref 模式要求配置它。

_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

  # Datadog API Key 来自网关环境变量
  # DD_CRED_DATADOG_PROD_API_KEY，绝不会来自此文件。
  - name: datadog-prod
    kind: datadog
    site: datadoghq.com
    credential_ref: datadog-prod
    service: ai-gateway
    tags: ["team:platform", "tier:prod"]

  # 使用主机挂载的云身份（无 Key）导出 S3 NDJSON。
  - name: s3-events
    kind: object_store
    provider: s3
    bucket: acme-aisix-events
    prefix: ai-gateway
    region: us-east-1
    auth_mode: cloud_identity

限流策略

限流策略会在固定窗口内限制一个主体的请求或 Token，用于补充模型和调用方 API Key 上的内联 rate_limit 块。未知字段会被拒绝。

字段	类型	必填	说明
name	string	是	条目标识，在 rate_limit_policies 中唯一。计数器以派生 ID 为 Key，因此可以跨重新加载保留。
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。
max_requests	integer	否*	每个窗口允许的请求数，最小 1。max_requests 和 max_tokens 至少配置一个。
max_tokens	integer	否*	每个窗口允许的 Token 数，最小 1。Token 上限仅在 minute 窗口执行；在 second 和 hour 窗口中，该值可以接受但不会应用。请将 max_tokens 与 window: minute 配合使用，参见限流。

_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:
  - name: cap-gpt4o
    scope: model
    scope_ref: gpt-4o
    window: minute
    max_requests: 300
    max_tokens: 100000