ai-cache

描述

ai-cache 插件缓存 LLM 响应，并在后续解析到相同提示词的请求中重放这些响应，从而为重复性工作负载（FAQ 机器人、文档问答、翻译等）降低上游的 Token 消耗与延迟。

该插件支持两个缓存层：

• 精确缓存（L1）： 对有效提示词计算 SHA-256 指纹并用作 Redis 键。完全相同的提示词始终命中同一条缓存条目。
• 语义缓存（L2）： 当 L1 未命中时，将提示词向量化，并通过最近邻搜索检索相似度在阈值以上的历史响应。L2 默认关闭；在 layers 中加入 "semantic" 即可启用。

ai-cache 插件必须与 ai-proxy 或 ai-proxy-multi 插件一起使用。

流式响应

插件支持缓存并回放流式（SSE）响应。流式响应仅在完成后才写入缓存，即接收到客户端协议对应的终止事件（OpenAI 为 data: [DONE]，Anthropic 为 message_stop，OpenAI Responses 为 response.completed）。被中断的流（客户端断开连接，或触发 ai-proxy 的 max_stream_duration_ms / max_response_bytes 限制）不会被缓存，因此不会回放不完整的响应。命中缓存时，存储的响应会作为单个 text/event-stream 响应体完整回放，并保留其终止事件。

对于相同的提示词，流式请求与非流式请求会在两个缓存层中分别存储为独立的条目，因此流式客户端始终收到流式响应，非流式客户端始终收到单个 JSON 响应。无论流式是由客户端请求（"stream": true）还是由路由通过 options.stream 强制开启，均是如此。

限制：不含 SSE 终止事件的二进制流式格式（例如 Bedrock ConverseStream）不会被缓存；回放是即时的（一次性发送完整的存储响应），而非按 token 重新计时逐个发送。

属性

语义缓存（L2）属性

当 layers 中包含 "semantic" 时，semantic 对象为必填项，其属性如下：

示例

以下示例使用 OpenAI 作为上游 LLM 服务提供商。请获取 OpenAI API key，并将其与 Admin API key 一起保存到环境变量中：

export OPENAI_API_KEY=your-openai-api-key
export admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

在配置的 redis_host 上必须有一个可访问的 Redis 实例。

缓存 LLM 响应

使用 ai-proxy 和 ai-cache 插件创建一个指向 LLM 聊天补全端点的路由。

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "ai-cache-route",
    "uri": "/anything",
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": { "header": { "Authorization": "Bearer '"$OPENAI_API_KEY"'" } },
        "options": { "model": "gpt-4o" }
      },
      "ai-cache": {
        "redis_host": "127.0.0.1"
      }
    }
  }'

adc

services:
  - name: ai-cache-service
    routes:
      - name: ai-cache-route
        uris:
          - /anything
        methods:
          - POST
        plugins:
          ai-proxy:
            provider: openai
            auth:
              header:
                Authorization: "Bearer ${OPENAI_API_KEY}"
            options:
              model: gpt-4o
          ai-cache:
            redis_host: 127.0.0.1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: ai-cache-plugin-config
spec:
  plugins:
    - name: ai-cache
      config:
        redis_host: 127.0.0.1
    - name: ai-proxy
      config:
        provider: openai
        auth:
          header:
            Authorization: "Bearer your-openai-api-key"
        options:
          model: gpt-4o
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: ai-cache-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
          method: POST
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: ai-cache-plugin-config

将配置应用到您的集群：

kubectl apply -f ai-cache-ic.yaml

apisix-crd

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: ai-cache-route
spec:
  ingressClassName: apisix
  http:
    - name: ai-cache-route
      match:
        paths:
          - /anything
        methods:
          - POST
      plugins:
        - name: ai-cache
          enable: true
          config:
            redis_host: 127.0.0.1
        - name: ai-proxy
          enable: true
          config:
            provider: openai
            auth:
              header:
                Authorization: "Bearer your-openai-api-key"
            options:
              model: gpt-4o

将配置应用到您的集群：

kubectl apply -f ai-cache-ic.yaml

向该路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -X POST \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "What is Apache APISIX? Answer in one sentence." }] }'

第一次请求是缓存未命中（MISS），会被代理到 LLM。响应中携带 X-AI-Cache-Status: MISS 响应头，响应体类似如下：

{
  "id": "chatcmpl-DtmdUDZeSZ0t62y6BvLkSk5qfH3zA",
  "object": "chat.completion",
  "created": 1782187368,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Apache APISIX is a dynamic, cloud-native API gateway that provides high performance, scalability, and security for API management."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 25,
    "total_tokens": 44
  }
}

再次发送相同的请求。该请求将直接由缓存返回，而不会调用 LLM，返回完全相同的响应体，并携带以下响应头：

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

绕过缓存

如需为特定请求跳过缓存，可添加 bypass_on 规则并更新路由：

curl "http://127.0.0.1:9180/apisix/admin/routes/ai-cache-route" -X PATCH \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "plugins": {
      "ai-cache": {
        "redis_host": "127.0.0.1",
        "bypass_on": [{ "header": "X-Cache-Bypass", "equals": "1" }]
      }
    }
  }'

发送带有匹配请求头的请求：

curl -i "http://127.0.0.1:9080/anything" -X POST \
  -H "Content-Type: application/json" \
  -H "X-Cache-Bypass: 1" \
  -d '{ "messages": [{ "role": "user", "content": "What is Apache APISIX? Answer in one sentence." }] }'

缓存被完全跳过（不查询、不回写），响应中携带 X-AI-Cache-Status: BYPASS 响应头。

使用语义匹配缓存 LLM 响应

以下示例启用语义缓存（L2）层，使措辞略有不同但语义相近的提示词也能命中缓存。除可用的 Redis Stack 实例外，还需要 OpenAI API 密钥用于向量化服务。

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "ai-cache-semantic-route",
    "uri": "/anything",
    "plugins": {
      "ai-proxy": {
        "provider": "openai",
        "auth": { "header": { "Authorization": "Bearer '"$OPENAI_API_KEY"'" } },
        "options": { "model": "gpt-4o" }
      },
      "ai-cache": {
        "redis_host": "127.0.0.1",
        "layers": ["exact", "semantic"],
        "semantic": {
          "similarity_threshold": 0.92,
          "embedding": {
            "openai": {
              "model": "text-embedding-3-small",
              "api_key": "'"$OPENAI_API_KEY"'"
            }
          },
          "vector_search": {
            "redis": {
              "index": "ai-cache"
            }
          }
        }
      }
    }
  }'

adc

services:
  - name: ai-cache-semantic-service
    routes:
      - name: ai-cache-semantic-route
        uris:
          - /anything
        methods:
          - POST
        plugins:
          ai-proxy:
            provider: openai
            auth:
              header:
                Authorization: "Bearer ${OPENAI_API_KEY}"
            options:
              model: gpt-4o
          ai-cache:
            redis_host: 127.0.0.1
            layers:
              - exact
              - semantic
            semantic:
              similarity_threshold: 0.92
              embedding:
                openai:
                  model: text-embedding-3-small
                  api_key: "${OPENAI_API_KEY}"
              vector_search:
                redis:
                  index: ai-cache

将配置同步到网关：

adc sync -f adc.yaml

发送初始请求：

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

首次请求同时未命中 L1 和 L2；插件将其代理到 LLM，对提示词进行向量化，并将精确缓存条目和向量分别存入 Redis。响应携带 X-AI-Cache-Status: MISS。

发送语义相近但措辞不同的请求：

curl -i "http://127.0.0.1:9080/anything" -X POST \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Can you explain what Apache APISIX is?" }] }'

该请求未命中 L1（指纹不同），但命中了 L2（向量相似度超过阈值）。响应由语义缓存直接返回，并携带以下响应头：

X-AI-Cache-Status: HIT
X-AI-Cache-Age: 12
X-AI-Cache-Similarity: 0.9487

X-AI-Cache-Similarity 响应头表示请求提示词与命中缓存条目之间的余弦相似度（1 − 距离）。