资源文件参考

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

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

文件格式

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

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

集合	用途	标识字段
provider_keys	存储上游服务提供方凭证和连接设置。	display_name
models	定义面向调用方的模型别名和分发行为。	display_name
api_keys	对调用方进行身份认证，并控制其模型、MCP 工具和 A2A Agent 访问权限。	display_name
oidc_providers	信任用于调用方身份认证的 JWT 签发者。	name
claim_mappings	把验证通过的 JWT Claims 解析到调用方 API Key。	name
guardrails	检查或转换请求和响应内容。	name
mcp_servers	将 MCP 服务器或 OpenAPI 操作公开为工具。	name 或 display_name
a2a_agents	为 A2A 调用方注册上游 Agent。	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_servers 和 a2a_agents，可以使用 name 或 display_name 作为标识；同时包含两种写法会导致加载错误，只能使用其中一种。

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

名称引用

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

关系	使用的名称	校验行为
模型到服务提供方凭证	服务提供方密钥的显示名称	必须匹配已定义的服务提供方密钥。未知名称会导致加载错误，并列出可用的服务提供方密钥。资源文件不能改用 provider_key_id。
调用方或虚拟模型到目标模型	模型的显示名称	必须匹配文件中定义的模型。包含 * 的值是 Glob 模式，不检查是否精确匹配。
限流策略到其主体	模型或调用方 API Key 的显示名称	对于 model 和 api_key 作用域，名称会解析为目标；对于其它作用域，该值原样传递。
调用方身份到 JWT 签发者	OIDC 服务提供方名称	保留为名称，而不解析成派生 ID。

环境变量插值

${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 选择服务提供方密钥。每个嵌套层级都会拒绝未知字段。

字段	类型	必填	说明
display_name	string	是	条目标识，在 provider_keys 中唯一。模型通过此名称引用该 Key。
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。
strip_headers	字符串数组	否	透传转发前删除的入站请求头。默认：authorization、cookie、set-cookie、x-api-key。条目会去除首尾空格、转成小写并去重。显式 [] 会禁用删除，不会回退到默认值。
tls	object	否	此 Key 端点的 TLS 设置。省略时使用部署级 upstream.tls 设置。
tls.ca_cert	string	否	此端点额外信任为签发者的 PEM 编码 CA 证书。一个证书包可以包含多张证书。参见 TLS 和 mTLS。
tls.verify	boolean	否	是否验证上游证书。默认：true。设为 false 会接受任意证书，仅用于测试环境。
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 转发的请求头，但不能替换网关自身设置的同名请求头。网关还会丢弃保留的身份认证、签名、会话和路由名称。参见上游请求头。
request.forward_client_headers	字符串数组	否	转发到上游的入站客户端请求头，可以是精确名称或 x-trace-* 之类的单 * Glob，匹配不区分大小写。空值（默认）不转发任何请求头。身份认证、传输、x-aisix-* 和 x-stainless-* 请求头绝不会转发。参见上游请求头。
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。

_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	最大进行中请求数。它是信号量，不是窗口。

直接模型

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

字段	类型	必填	说明
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	否	发生可重试上游失败后的请求路径冷却，见下文。
auto_prompt_caching	object	否	自动注入 Anthropic 提示词缓存标记。仅支持服务提供方为 anthropic 的直接模型。存在该对象时 enabled 必填；ttl 可设为 5m（默认）或 1h。参见 Anthropic 提示词缓存。

可选的 cooldown 对象接受以下设置：

字段	默认值	行为
cooldown.enabled	true	启用请求路径冷却跟踪。
cooldown.default_seconds	30	没有可用 Retry-After 请求头时设置冷却 TTL。
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	上游传输失败后触发冷却。

只有直接模型可以配置 embedding、background_model_check、cooldown 和 auto_prompt_caching。自动提示词缓存还要求服务提供方为 anthropic。

路由模型

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	否	故障转移前每个目标的默认重试次数。目标模型的 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.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 工具访问权限。
mcp_rate_limits	object	否	此 Key 按 MCP 服务器设置的请求和并发限制。Key 为已注册的 MCP 服务器名称，见下文。
mcp_access	object	否	为兼容 AISIX Cloud 配置而接受的策略驱动 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	否	仅用于遥测标签的可读所有者名称。

MCP 工具访问权限和限额

对于使用资源文件配置的网关，请通过 allowed_tools 授予 MCP 工具访问权限。尽管为兼容 AISIX Cloud 配置而接受 mcp_access，但资源文件部署没有 mcp_policies 集合，因此它无法授予工具访问权限。请省略 mcp_access。

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

字段	限制
rps	每秒请求数。
rpm	每分钟请求数。
rph	每小时请求数。
rpd	每日请求数。
concurrency	最大进行中工具调用数。

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

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

_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"]
    allowed_tools: ["github__*"]
    rate_limit:
      rpm: 60
      concurrency: 5
    mcp_rate_limits:
      github:
        rpm: 30
        concurrency: 2

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 认证。

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

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

_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

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 列表会导致加载失败。

_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（默认）。
direction	string	否	用于兼容基于挂载配置的字段。它不会选择资源文件安全护栏的运行位置；执行位置由 hook_point 控制。新资源文件应省略此字段。
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 决定条目还接受哪些字段：

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、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}）、latency_mode（{kind: serial} 或 {kind: timed, timeout_ms: 100–5000}）	—

Azure 文本审核、阿里云内容审核和阿里云 AI 安全护栏类型支持以下流式输出控制：

字段	适用范围	行为
stream_processing_mode	三种流式安全护栏类型	window 以滑动窗口增量释放内容，也是默认值；buffer_full 会在释放前保留完整响应。
window_size	三种流式安全护栏类型	设置滑动窗口大小。
window_overlap_size	三种流式安全护栏类型	设置连续窗口之间的重叠大小。
max_buffer_bytes	PII、Lakera、Presidio，以及使用 buffer_full 模式的三种流式类型	为检查而保留的最大响应字节数。默认 262144。
on_buffer_exceeded	上述缓冲类型	fail_closed 在超过缓冲区限制时拒绝处理，也是默认值；fail_open 会释放内容。

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

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

_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 服务器条目以 <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 唯一受支持的传输方式，也是默认值。
auth_type	enum	否	网关向上游认证的方式：none（默认）、bearer（将 secret 作为 Authorization: Bearer 发送）、api_key（将 secret 作为 API Key 请求头发送），或 oauth2（客户端凭证授权；Token 会缓存到即将过期前）。
api_key_header	string	否	type: openapi 且 auth_type: api_key 时使用的请求头。默认 x-api-key。真实 MCP 服务器始终使用 x-api-key 进行 API Key 身份认证。
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 网关概览。

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

_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 的写入字段 spec_content 或 spec_url。

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

_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: Items returned successfully

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）的截止时间。对流式方法（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：

_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 认证的请求）。
scope	enum	否	缓存条目的共享边界，对两个匹配层同时生效：api_key（默认——条目仅对写入它的调用方 API Key 可见）或 env（环境内所有调用方共享条目）。
purge_generation	integer	否	服务端管理的失效计数器，默认 0。递增它会使该策略在更早取值下存储的所有条目失效——两个匹配层、所有网关实例。
semantic	object	否	在精确层之上启用向量相似度匹配。见下方子表。

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	否	embedding 调用的单次超时。超时后请求不经缓存直接发往上游。0 或缺省表示不设单独超时。

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

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

注意

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

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

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

对于 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 下方的带圈数字说明高亮字段会解析为何值。

_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 块相同。
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 拒绝，并且在资源文件中永不匹配。例如 days_of_week: [fri] 且时间为 22:00 至 09:00 时，窗口覆盖星期五 22:00 至星期六 09:00。

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

_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