响应缓存

响应缓存允许 AISIX 在后续请求拥有相同缓存键时，复用之前的非流式 Chat Completions 响应。它是网关侧响应缓存，不是服务提供方提示词缓存，也不是托管配置快照缓存。

本指南将创建缓存策略，使用 x-aisix-cache 响应头验证缓存未命中和命中行为，并介绍缓存作用域和后端设置的工作方式。

响应缓存的工作方式

AISIX 只缓存完全匹配的非流式 Chat Completions 响应。流式响应和其它代理 API 族不会使用该响应缓存路径。

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

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

缓存键匹配

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

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

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

选择缓存后端

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

后端	行为
Memory	默认。使用处理未命中的网关实例上的进程内缓存。
Redis	当启动时配置了 `cache.redis`，使用共享 Redis 缓存。

单实例部署或可以接受节点本地缓存条目的策略可以使用 memory。当多个网关实例需要为同一策略共享缓存响应时，请使用 Redis。

Redis 缓存存储可以连接单个 Redis 端点、Redis Cluster 或 Redis Sentinel。

配置缓存策略

下面的示例展示如何为模型作用域策略配置并验证 memory 或 Redis 缓存存储。每次只为示例模型别名使用一个后端。如果另一个已启用的缓存策略已经匹配相同请求，请在尝试下一个示例前禁用或删除它。

准备工作

在开始任一示例之前，请准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可以发送非流式 Chat Completions 请求的模型别名和调用方 API Key。

配置内存缓存策略

下面的示例创建一个使用默认进程内内存缓存的模型作用域策略。

设置示例请求要使用的值：

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export CACHE_PROMPT="cache-check-$(date +%s)"

为示例模型别名创建缓存策略：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/cache_policies" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default-chat-cache",
    "enabled": true,
    "backend": "memory",
    "applies_to": "model:'"${AISIX_MODEL}"'",
    "ttl_seconds": 3600
  }'

你应该会看到类似下面的响应：

{
  "id": "8d86d1cf-4a46-4a71-b4ef-c01e51f77f21",
  "value": {
    "name": "default-chat-cache",
    "enabled": true,
    "backend": "memory",
    "ttl_seconds": 3600,
    "applies_to": "model:gpt-4o-mini"
  },
  "revision": 1
}

如果之后需要更新或删除该策略，请保存返回的 ID。

验证内存缓存行为

使用缓存提示词发送请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [{"role": "user", "content": "'"${CACHE_PROMPT}"'"}]
  }'

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

x-aisix-cache: miss

miss 表示 AISIX 调用了上游服务提供方，并把响应写入缓存。

使用相同请求体和模型别名重复请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [{"role": "user", "content": "'"${CACHE_PROMPT}"'"}]
  }'

重复请求应该包含以下响应头：

x-aisix-cache: hit

hit 表示 AISIX 直接返回了缓存副本，没有调用上游服务提供方。

修改提示词，确认缓存键与请求体绑定：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [{"role": "user", "content": "'"${CACHE_PROMPT}"' different"}]
  }'

变更后的请求应该返回缓存未命中。

配置 Redis 缓存策略

当多个网关实例需要为同一策略共享缓存响应时，请使用 Redis。

在启动网关之前，请确保已有一个 Redis 实例在运行。然后使用 Redis 连接详情配置 AISIX：

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

添加 Redis 配置后启动或重启网关。

仅设置 cache.backend: redis 不会让 Redis 可用；缺少 Redis 配置块时 AISIX 启动会失败。

设置示例请求要使用的值：

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export CACHE_PROMPT="redis-cache-check-$(date +%s)"

创建选择 Redis 后端的策略：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/cache_policies" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "shared-chat-cache",
    "enabled": true,
    "backend": "redis",
    "applies_to": "model:'"${AISIX_MODEL}"'",
    "ttl_seconds": 3600
  }'

如果之后需要更新或删除该策略，请保存返回的 ID。

验证 Redis 缓存行为

使用缓存提示词发送请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [{"role": "user", "content": "'"${CACHE_PROMPT}"'"}]
  }'

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

x-aisix-cache: miss

miss 表示 AISIX 调用了上游服务提供方，并把响应写入 Redis。

使用相同请求体和模型别名重复请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [{"role": "user", "content": "'"${CACHE_PROMPT}"'"}]
  }'

重复请求应该包含以下响应头：

x-aisix-cache: hit

hit 表示 AISIX 从 Redis 直接返回了缓存副本，没有调用上游服务提供方。

如果匹配策略选择 Redis，但网关进程启动时没有配置 cache.redis，AISIX 会禁用该策略匹配请求的缓存，不会静默回退到 memory。

调整策略作用域

验证基本缓存流程后，请针对你想要缓存的流量模式调整策略作用域。

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

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

建议先从较窄的策略开始，例如模型作用域或调用方 Key 作用域策略。只有当环境中所有符合条件的 Chat Completions 请求都应该参与响应缓存时，才使用全局策略。

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

请避免使用不支持的匹配前缀。网关会把未知形式当作全局作用域处理，因此拼写错误可能让策略范围比预期更宽。

下一步

你已经配置了响应缓存策略，并验证了未命中与命中行为。接下来继续阅读安全护栏，在服务提供方调用前后添加请求和响应检查。

响应缓存的工作方式​

缓存键匹配​

选择缓存后端​

配置缓存策略​

准备工作​

配置内存缓存策略​

验证内存缓存行为​

配置 Redis 缓存策略​

验证 Redis 缓存行为​

调整策略作用域​

下一步​