版本：Dev

响应缓存

当后续请求具有相同缓存 Key 时，响应缓存允许 AISIX 复用先前的非流式 Chat Completions 响应。这是网关侧响应缓存，不是模型服务提供方的提示词缓存，也不是控制面的配置快照缓存。如需为 Anthropic 模型配置模型服务提供方侧缓存，请参阅 Anthropic 提示词缓存。若要为相似而非完全相同的提示词返回缓存响应，可在策略上叠加语义缓存。

本指南介绍如何通过 AISIX Cloud Admin API 或声明式资源文件配置模型作用域缓存策略、验证缓存未命中和命中、选择共享范围、绕过与清空缓存条目，并按需使用 Redis 在多个网关实例间共享缓存响应。

响应缓存的工作原理

AISIX 会缓存完全匹配的非流式 Chat Completions 响应。流式响应和其他代理 API 类型不会使用此响应缓存路径。带生成 images 的响应（无论来自哪个上游）因体积原因不会写入缓存。

缓存策略可以应用于所有符合条件的请求、一个模型别名或一个调用方 API Key。每个策略把响应存储在网关的进程内 Memory 缓存中；如果启动时配置了 Redis，也可以存储在 Redis 中。

AISIX 缓存响应之前，网关必须能够使用所选后端，并且请求必须匹配一个已启用的缓存策略。

缓存 Key 匹配

AISIX 根据会影响上游响应的规范化 Chat Completions 请求创建缓存 Key。只有模型别名、消息角色和规范化内容、采样设置、响应长度以及额外的兼容 OpenAI 请求选项都相同时，两个请求才会共享缓存条目。

JSON 对象 Key 的顺序不会影响缓存匹配，包括嵌套对象中的 Key。数组顺序会影响匹配，因此工具定义相同但顺序不同的两个请求会使用不同缓存条目。

如果存在 temperature 和 top_p，则以 0.001 的精度比较，而不是按浮点数精确相等比较。因此，在其他所有字段都匹配时，位于同一千分位区间内的两个显式值会使用同一个缓存 Key。省略字段与显式设置该字段仍视为不同。

对于多目标模型，缓存 Key 使用调用方请求的别名，而不是处理未命中请求的目标模型。请求 ID 和请求头不参与缓存 Key。

调用方 API Key 是否分隔缓存由策略的 scope 字段控制。默认的 scope: api_key 下条目仅对写入它的 API Key 可见；scope: env 则在环境内所有调用方之间共享。见选择共享范围。

选择缓存后端

每个缓存策略都要选择匹配响应的存储位置：

后端	行为
Memory	默认。使用处理未命中请求的网关实例上的进程内缓存。
Redis	使用网关启动时配置的共享 Redis 缓存。

单实例部署或可以接受节点本地缓存条目时使用 Memory。多个网关实例需要共享同一策略的缓存响应时使用 Redis。AISIX 支持单个 Redis 端点、Redis Cluster 和 Redis Sentinel。

配置 Memory 缓存策略

以下示例使用默认的进程内 Memory 后端创建模型作用域策略。请选择控制面或开源配置路径，再使用通用验证步骤。如果已有其他已启用的缓存策略匹配示例请求，请先将其禁用或删除。

准备工作

开始前，请准备以下内容：

以下配置路径之一：
- AISIX Enterprise 或 AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
可以发送非流式 Chat Completions 请求的模型别名和调用方 API Key。
curl。控制面路径还会使用 jq。

导出两种路径都会使用的网关连接和资源参数：

# AISIX_PROXY 不含尾部斜杠或 /v1 等端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export CACHE_PROMPT="cache-check-$(date +%s)"

AISIX Enterprise 或 AISIX Cloud

导出控制面连接参数：

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

为示例模型别名创建 Memory 缓存策略。保存策略 ID，因为后面的 Redis 步骤会替换该策略：

CACHE_POLICY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/cache_policies" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "default-chat-cache",
    "enabled": true,
    "backend": "memory",
    "applies_to": "model:${AISIX_MODEL}",
    "ttl_seconds": 3600
  }
EOF
)

export CACHE_POLICY_ID=$(printf '%s' "$CACHE_POLICY_RESPONSE" | jq -r '.cache_policy.id')
printf '%s' "$CACHE_POLICY_RESPONSE" | jq

策略会自动投射到已接入的网关。响应包含策略 ID、环境 ID、所选后端、作用域、TTL 和时间戳。

如果 model: 选择器本身就是通配符模式，例如 model:openai/*，控制面会以 400 拒绝——调用方寻址的是该别名所承载的具体名称，而不是别名本身。环境中没有任何模型能应答的名称同样会被拒绝：只有当某个模型以该名称作为其 display_name，或某个通配符别名承载该名称时，这个名称才成立。

开源 AISIX 网关

在已定义示例模型和调用方 API Key 的资源文件中添加缓存策略：

resources.yaml（缓存策略）
cache_policies:
  - name: default-chat-cache
    enabled: true
    backend: memory
    applies_to: "model:gpt-4o-mini"
    ttl_seconds: 3600

applies_to 中的模型名称是调用方在请求中使用的名称：对于具体配置的模型，即其 display_name；而当某个命名空间由 openai/* 这类通配符别名承载时，则是调用方在该命名空间下使用的具体名称（openai/gpt-4o），而不是别名模式本身。验证完整资源文件，然后重新加载网关。可运行的 Docker 工作流参见重新加载资源文件。

验证缓存未命中和命中

以下步骤读取 x-aisix-cache 响应头，网关只有在启动配置将 proxy.expose_debug_headers 设为 true 时才会发送它。请在用于测试的网关上开启该设置，或者按 x-aisix-request-id 找到每个请求的访问日志行，从其 cache_status 字段读取同样的判定结果。

定义一个每次都发送相同请求正文的辅助函数：

send_cache_request() {
  curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
    -H "Authorization: Bearer ${AISIX_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
    {
      "model": "${AISIX_MODEL}",
      "messages": [{"role": "user", "content": "${CACHE_PROMPT}"}]
    }
EOF
}

发送一次请求：

send_cache_request

第一个匹配请求应包含以下响应头：

x-aisix-cache: miss

未命中表示 AISIX 调用了上游模型服务提供方，并把响应写入缓存。在不更改模型或正文的情况下重复请求：

send_cache_request

重复请求应包含：

x-aisix-cache: hit

命中表示 AISIX 未调用上游模型服务提供方，直接返回了已存储的响应。在 AISIX Enterprise 和 AISIX Cloud 中，命中不产生费用，也不计入预算支出：其用量事件记录重放的 Token 计数和缓存节省计数，费用为 0。较早版本的控制面会对直连模型的命中按模型全价计费。

更改提示词，确认请求正文参与缓存 Key 的计算：

CACHE_PROMPT="${CACHE_PROMPT}-different" send_cache_request

更改后的请求应返回 x-aisix-cache: miss。

Redis 允许多个网关实例共享条目。请确保 Redis 正在运行，且每个参与的网关都能访问它，然后把连接信息添加到 config.yaml：

config.yaml
cache:
  redis:
    mode: single
    url: redis://127.0.0.1:6379/

添加 Redis 配置后，启动或重启每个网关。配置 backend: redis 的策略不会建立 Redis 连接。如果匹配策略选择 Redis，但未配置 cache.redis，AISIX 会禁用这些请求的缓存，而不会静默回退到 Memory。

启动时连不上 Redis 不会导致网关启动失败，但有界的启动连接尝试可能延迟所有监听器。尝试结束后，Redis 不再阻止监听器启动。代理监听器可用后，在 Redis 恢复应答之前，每条 backend: redis 缓存策略都按未命中处理。网关会输出一条 WARN 日志，其中包含后端、配置的端点值、原因和连接错误，并每 5 分钟重述一次。后台任务会在 Redis 恢复应答后立即接入缓存后端，此后 backend: redis 策略重新正常提供服务。

Redis 端点值可能暴露凭据

WARN 日志会原样包含配置的端点值：单机模式中的 url、集群模式中的 nodes，以及 Sentinel 模式中的 sentinels。嵌入这些值的所有凭据也会被记录。请使用单独的 username 和 password 字段配置数据节点凭据。Sentinel 节点凭据仍会包含在 Sentinel URL 中，因此请限制对网关日志的访问。

Redis 明确应答并拒绝连接配置时走的是同一条降级路径，包括凭据被拒绝、服务端返回 NOAUTH 或 DENIED，以及服务端没有所配置的 database。此时告警带的是 reason=refused 而不是 reason=unreachable，后台重新接入的行为不变。无法在后台恢复的本地配置和解析错误会导致启动失败，包括：无法解析的 url；AISIX 无法读取或解析的 TLS 材料；仅配置客户端证书或密钥之一；缺少所选模式要求的字段；timeout_secs: 0；或主机名无法解析到任何地址。

cache.redis.username 和 cache.redis.password 在所有模式下都生效，且这些显式字段会覆盖内嵌在 url 中的凭据。凭据请作为一对设置，只设置其中一半会同时替换两半。cache.redis.database 在 single 和 sentinel 模式下生效；Redis Cluster 只有 DB 0。

是否支持向量检索是另一个问题，只有服务端真正应答探测时网关才会做出判定。没有得到应答的探测会在后台重试，因此启动时连不上的 Redis 并不会永久关闭语义匹配。参见使用 Redis 共享语义条目。

存储的响应会保留每个 choice 及其 logprobs。共享同一 Redis 的 1.7.0 及更早版本网关无法读取含有多个 choice 或 logprobs 的条目，会把它当作缓存错误处理。其他条目的写法与之前相同，因此混合版本的网关集群仍能正常共享它们。

Redis 可用后，通过前面使用的同一管理路径，用 Redis 策略替换 Memory 策略。

AISIX Enterprise 或 AISIX Cloud

现有控制面缓存策略的后端不能更改。请删除 Memory 策略，再创建使用 Redis 的替代策略，并保存新策略的 ID，以便后续更新和清空：

curl -sS -X DELETE \
  "$AISIX_CP/environments/$ENV_ID/cache_policies/$CACHE_POLICY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" | jq

CACHE_POLICY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/cache_policies" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "shared-chat-cache",
    "enabled": true,
    "backend": "redis",
    "applies_to": "model:${AISIX_MODEL}",
    "ttl_seconds": 3600
  }
EOF
)

export CACHE_POLICY_ID=$(printf '%s' "$CACHE_POLICY_RESPONSE" | jq -r '.cache_policy.id')
printf '%s' "$CACHE_POLICY_RESPONSE" | jq

开源 AISIX 网关

在 resources.yaml 中更改策略后端：

resources.yaml（缓存后端）
cache_policies:
  - name: shared-chat-cache
    enabled: true
    backend: redis
    applies_to: "model:gpt-4o-mini"
    ttl_seconds: 3600

验证完整资源文件，然后重新加载网关，再测试 Redis 策略。

验证 Redis 缓存行为

设置一个新的提示词，然后运行两次 send_cache_request。第一个请求应未命中，第二个请求应命中：

export CACHE_PROMPT="redis-cache-check-$(date +%s)"

send_cache_request
send_cache_request

验证多个网关实例共享缓存

要确认 Redis 已共享，请把第一个请求发送到一个网关实例，再把完全相同的请求发送到另一个实例。两个实例必须加载相同缓存策略，并连接到同一 Redis 部署。

export AISIX_PROXY_A="https://gateway-a.example.com"
export AISIX_PROXY_B="https://gateway-b.example.com"
export CACHE_PROMPT="shared-cache-check-$(date +%s)"

AISIX_PROXY="$AISIX_PROXY_A" send_cache_request
AISIX_PROXY="$AISIX_PROXY_B" send_cache_request

通过网关 A 的请求应未命中，通过网关 B 的请求应命中。使用 Memory 后端时，第二个网关拥有自己的空缓存，因此会再次未命中。

Redis 缓存后端故障时的行为

缓存查找或缓存写入时发生 Redis 错误或超时，会被当作一次缓存未命中处理，请求绝不会因此失败：查找失败的请求会像任何其他未命中一样继续转发到上游模型服务提供方；写入失败则该响应不入缓存，但仍照常返回给调用方。一次中断中，每个缓存层的首次故障记录为 WARN，该层在中断持续期间的后续故障记录为 DEBUG。故障计入 aisix_redis_failures_total，其 operation 标签区分精确匹配缓存（cache_get、cache_put）和语义缓存（semantic_acquire、semantic_lookup、semantic_store、semantic_index）。请以该计数器而不是缓存状态来观察后端是否降级，因为降级时报告的 miss 与冷缓存无法区分。

cache.redis.timeout_secs 约束单次 Redis 往返以及单次连接尝试在被放弃之前可以耗费多久，默认值为 5 秒，最小值为 1，取 0 会在启动时被拒绝并点名该字段。超时或连接故障会打开缓存子系统的短路并持续 30 秒；该窗口内的缓存操作立即返回，不发生任何往返，因此请求会直接落到上游，而不是每个请求再付一次超时代价。Redis 服务端返回的错误只会让当前缓存操作失败，不会打开短路。

这 30 秒到期时，由一个后台任务——而不是业务请求——向 Redis 发送一次 PING，成功则关闭短路，失败则重新计时 30 秒。在它关闭短路之前，请求会继续直接短路返回，因此没有任何请求会充当探测者。

精确匹配缓存与语义缓存背后的向量检索共用同一个短路，因为它们是指向同一个 cache.redis 块的两条连接。限流器有自己独立的短路，因此一次 Redis 中断会分别打开这两个。限流器一侧的同一机制，请参阅选择限流计数器存储。

调整策略作用域

验证基本缓存行为后，请为要缓存的流量调整策略作用域。

applies_to 字段控制哪些请求匹配缓存策略：

值	作用域
`all`	所有符合条件的非流式 Chat Completions 请求。
`model:<alias>`	使用调用方可见模型别名的请求。
`api_key:<id>`	使用该调用方 API Key 资源 ID 认证的请求。

对于 AISIX Enterprise 或 AISIX Cloud，请使用 Admin API 返回的调用方 API Key ID。在 resources.yaml 中，请使用该 Key 确定性的派生 ID；资源加载器不会在此字段中解析调用方 API Key 的 display_name。

请先使用模型作用域或调用方 Key 作用域等较窄策略。只有所有符合条件的 Chat Completions 请求都应参与响应缓存时，才使用全局策略。

在 AISIX Enterprise 和 AISIX Cloud 中，model: 选择器由能响应该名称的模型的资源 ID 来落实，因此重命名该模型时策略仍然绑定在它上面，选择器读回时显示新名称。删除该模型会让策略永久不再覆盖任何流量：之后以相同名称新建的模型是另一个资源，策略仍然列出且处于启用状态，却匹配不到任何流量。在选择器不变的情况下再保存一次该策略，会针对当前响应该名称的模型重新解析，这也是把被删除模型搁浅的策略指向替代模型的方式。如果选择器命名的具体名称只由通配符别名提供服务，则不携带资源 ID——没有模型以该名称作为自己的 display_name——它仍按名称匹配。

applies_to 选择器控制的是资格——策略覆盖哪些请求。被覆盖的请求之间是否共享条目，由下一节介绍的独立字段 scope 决定。

应避免为相同请求设置重叠的已启用策略。多个策略匹配时，AISIX 使用第一个匹配策略选择后端和 TTL，因此重叠策略会使缓存行为更难推断。

只使用受支持的匹配形式。网关会把无法识别的前缀视为 all，因此无论通过哪种管理路径创建，拼写错误都可能让策略作用域超出预期。

策略的 scope 字段选择缓存条目的共享边界：

Scope	行为
`api_key`	默认值。条目仅对写入它的调用方 API Key 可见。一个调用方的响应绝不会回放给另一个调用方。
`env`	环境内所有调用方 API Key 共享条目。相同的合格请求跨调用方复用同一条目。

一般流量保持默认的 api_key：响应常常嵌入调用方特有的上下文，按 Key 分隔可防止一个调用方的回答泄露给另一个。FAQ 机器人、文档问答等共享知识型流量——跨调用方复用正是目的、共享池能提升命中率——才选择 env。

scope 对语义层同样生效：在 scope: env 下，调用方可能拿到为另一个调用方的相似（而不仅是相同）请求存储的条目，启用前需要更审慎的评估。

scope 可修改，因此直接切换你已创建的策略，而不是再添加一个重叠策略（把 CACHE_POLICY_ID 设为当前覆盖该模型的策略 ID）：

curl -sS -X PATCH \
  "$AISIX_CP/environments/$ENV_ID/cache_policies/$CACHE_POLICY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"scope": "env"}' | jq

在 resources.yaml 中，在策略条目上设置同一字段（scope: env）。未设置该字段的既有策略使用 api_key。

按请求绕过缓存

调用方可以用标准的 Cache-Control 请求指令为单个请求跳过缓存，无需改动策略：

指令	行为
`Cache-Control: no-cache`	跳过缓存查找。全新的上游响应仍会刷新存储的条目。
`Cache-Control: no-store`	正常执行查找。如果未命中，则不把全新的上游响应写入缓存。

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [{"role": "user", "content": "${CACHE_PROMPT}"}]
  }
EOF

no-cache 请求会报告 bypass，而不是 hit 或 miss：开启调试响应头时体现在 x-aisix-cache 中，访问日志的 cache_status 则始终记录。no-store 请求仍可能报告 hit 并返回既有条目；如果未命中，则报告 miss，并且不会留下新条目。

使用 no-cache 强制刷新过期答案。需要防止存储全新响应时使用 no-store。如果既要强制从上游获取响应，又要防止存储该响应，请发送 Cache-Control: no-cache, no-store。

清空缓存条目

清空操作会使策略存储的所有条目失效——所有网关实例上，对配置了语义层的策略还包括两个匹配层——而不删除或禁用策略：

curl -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/cache_policies/$CACHE_POLICY_ID/purge" \
  -H "Authorization: Bearer $AISIX_TOKEN" | jq

响应包含策略递增后的 purge_generation。更新后的配置到达各网关后，更早代次存储的条目立即停止被返回；存储空间在后台回收。控制台在每个策略行上以 清空缓存条目 按钮提供同一操作。

在 resources.yaml 中，在策略条目上添加 purge_generation 字段，需要使该策略的条目失效时递增它：

resources.yaml（清空缓存）
cache_policies:
  - name: default-chat-cache
    enabled: true
    backend: memory
    applies_to: "model:gpt-4o-mini"
    ttl_seconds: 3600
    purge_generation: 1

警告

请将 purge_generation 视为单调递增值。递增后，请在每次完整的资源文件更新中保留该值，绝不能降低或删除。省略该字段会将其重置为 0，这可能使该代次中更早的精确缓存条目重新可用，直至其 TTL 过期。

当缓存的答案先于 TTL 过时——系统提示词变更、服务提供方侧模型更新、上游文档被修正——时执行清空。

后续步骤

你已经配置响应缓存，并验证了缓存未命中和命中行为。接下来：

叠加语义缓存，为相似而非完全相同的提示词也返回缓存响应。
如果希望通过重复的提示词前缀获得模型服务提供方侧折扣，而不是复用整个响应，请启用 Anthropic 提示词缓存。
继续配置安全护栏，在调用模型服务提供方之前和之后添加请求与响应检查。

响应缓存的工作原理​

缓存 Key 匹配​

选择缓存后端​

配置 Memory 缓存策略​

准备工作​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

验证缓存未命中和命中​

使用 Redis 共享缓存条目​

AISIX Enterprise 或 AISIX Cloud​

开源 AISIX 网关​

验证 Redis 缓存行为​

验证多个网关实例共享缓存​

Redis 缓存后端故障时的行为​

调整策略作用域​

选择共享范围​

按请求绕过缓存​

清空缓存条目​

后续步骤​

响应缓存的工作原理

缓存 Key 匹配

选择缓存后端

配置 Memory 缓存策略

准备工作

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

验证缓存未命中和命中

使用 Redis 共享缓存条目

AISIX Enterprise 或 AISIX Cloud

开源 AISIX 网关

验证 Redis 缓存行为

验证多个网关实例共享缓存

Redis 缓存后端故障时的行为

调整策略作用域

选择共享范围

按请求绕过缓存

清空缓存条目

后续步骤