跳到主要内容

ai-cache

ai-cache 插件会缓存 LLM 服务的响应，使相同的请求直接从缓存返回，而不再次调用上游模型。这可以降低重复提示词的响应延迟，并减少上游 token 用量。

该插件执行精确匹配缓存：仅当规范化后的请求（即消息、模型以及生效的 ai-proxy 实例配置）与此前缓存的某个请求完全相同时，才会复用其响应。缓存条目存储在 Redis 中，并具有可配置的存活时间（TTL）。

自 API7 企业版 version 3.10.2 起可用。

工作原理​

ai-cache 插件必须与同一路由上的 ai-proxy 或 ai-proxy-multi 插件一起使用，因为它缓存的是这些插件所代理的 LLM 流量。

对于每个请求，插件会根据请求体（消息和模型）以及所选 AI 实例的配置计算缓存键，其作用范围由 cache_key 配置决定。随后，它会将 X-AI-Cache-Status 响应头设置为以下值之一：

  • HIT：找到有效的缓存响应并直接返回，不调用上游。X-AI-Cache-Age 头会以秒为单位报告该缓存条目的存活时长。
  • MISS：未找到缓存响应。请求被代理到上游，且大小在 max_cache_body_size 以内的成功响应（HTTP 200）会被缓存以供后续请求使用。
  • BYPASS：此请求跳过缓存，例如因为它是流式请求、匹配了某条 bypass_on 规则，或未选中任何 AI 实例。

流式请求始终会被绕过，不会被缓存。

示例​

以下示例使用 OpenAI 作为上游 LLM 服务，并使用一个 Redis 实例来存储缓存。在开始之前，请创建一个 OpenAI 账号 和 API Key，并确保网关能够访问到一个 Redis 实例。你可以选择将密钥保存到环境变量中：

export OPENAI_API_KEY=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   # 替换为你的 API 密钥

如果你使用其他 LLM 提供商，请参考该提供商的文档获取 API Key。

缓存 LLM 响应​

以下示例演示如何将 ai-cache 与 ai-proxy 配合配置，使重复的相同请求由 Redis 提供响应。

创建一个使用 ai-proxy 代理到 OpenAI、并使用 ai-cache 缓存响应的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "ai-cache-route",
    "uri": "/anything",
    "methods": ["POST"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": {
          "header": {
            "Authorization": "Bearer '"$OPENAI_API_KEY"'"
          }
        },
        "options": {
          "model": "gpt-4"
        }
      },
      "ai-cache": {
        "redis_host": "127.0.0.1",
        "redis_port": 6379,
        "exact": {
          "ttl": 3600
        }
      }
    }
  }'

❶ 在 Authorization 头中以 Bearer token 形式附带 OpenAI API Key。

❷ 指定模型名称。

❸ 将缓存指向你的 Redis 实例。

❹ 将每个响应缓存一小时。

向该路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What is 1+1?" }
    ]
  }'

第一个请求是缓存未命中，会被代理到 OpenAI。你应该收到 HTTP/1.1 200 OK 响应，其中包含以下响应头：

X-AI-Cache-Status: MISS

再次发送相同的请求。这一次响应直接从缓存返回，不会调用上游，并包含缓存状态和存活时长响应头：

X-AI-Cache-Status: HIT
X-AI-Cache-Age: 2