# 语义缓存

语义缓存让 AISIX 在新请求与先前请求的相似度达到阈值时返回缓存的响应，即使措辞不同。相似不等于含义相同：含义不同的两个请求也可能达到阈值，参见[了解误命中风险](#understand-the-risk-of-false-hits)。它是[响应缓存](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md)的扩展：精确匹配层始终先被检查，语义层负责处理精确层未命中的请求。

在本指南中，你将为缓存策略添加语义配置块，验证精确命中与语义命中，并清空缓存条目。你还将了解跨网关实例共享语义条目所需的 Redis 要求。

## 语义缓存的工作原理[​](#how-semantic-caching-works "语义缓存的工作原理的直接链接")

配置了 `semantic` 块的缓存策略会对每个符合条件的请求依次运行两个匹配层：

1. \*\*精确层。\*\*首先查找请求指纹——模型别名、规范化后的 messages、采样参数以及其他影响响应的选项。完全相同的重复请求在此命中，无需任何 向量嵌入调用。
2. \*\*语义层。\*\*精确层未命中时，AISIX 会向量化请求中所有消息的文本，包括 system prompt 和历史消息，每条消息一行，格式为 `role: content`。向量化使用策略配置的 向量嵌入模型，结果再与已存储的条目比较。相似度达到或超过阈值的最近条目会被返回；否则请求继续发往上游，响应连同其向量一起被存储。

只有 `messages` 内容参与相似度匹配，分数针对全部文本计算，而不只是最新的问题。因此，所有请求共用的长 system prompt 会抬高本来不同的问题之间的分数。模型别名和其他指纹字段仍必须匹配。如果存在 `temperature` 和 `top_p`，则以 `0.001` 的精度比较，因此同一千分位区间内的显式值视为相等。省略字段与显式设置该字段仍视为不同。消息中包含图片、音频或工具结果的请求永远不会做相似度匹配，它们只使用精确层。

语义命中也不会刷新条目：条目与精确条目一样按策略 TTL 过期。

### 向量嵌入失败时放行[​](#embedding-failures-fail-open "向量嵌入失败时放行的直接链接")

语义匹配是一种优化，绝不是一道闸门。如果 向量嵌入调用失败或超时，请求会不经缓存直接发往上游，失败会计入[缓存指标](https://docs.apiseven.com/ai-gateway/reference/metrics.md#cache-metrics)。如果 向量嵌入模型被删除或配置错误，策略会记录一条警告并继续只提供精确匹配。

## 准备工作[​](#prerequisites "准备工作的直接链接")

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

* 一套可用的[响应缓存](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md)配置：控制面路径（AISIX Enterprise 或 AISIX Cloud）或声明式资源文件、模型别名和调用方 API Key。
* 同一环境中的一个 **向量嵌入模型**。在 AISIX Enterprise 或 AISIX Cloud 中，这是 kind 为 `embedding` 的模型；在资源文件中则是带 `embedding` 块的模型条目。它负责将请求文本向量化以做相似度比较；其 `dimensions` 值固定了该策略条目的向量维度。
* 使用 Redis 后端的策略还需要支持向量检索的 Redis 部署——见[使用 Redis 共享语义条目](#share-semantic-entries-with-redis)。

导出共用的连接变量：

```
# 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"
```

## 配置语义缓存策略[​](#configure-a-semantic-cache-policy "配置语义缓存策略的直接链接")

`semantic` 块在现有缓存策略上启用相似度层。请把它添加到已覆盖该模型的策略中，而不是再创建一个重叠策略。当多个已启用的策略匹配同一请求时，首个匹配的策略生效，因此后面的语义策略可能永远不会运行。

阈值为必填项：它是条目被返回所需的最小余弦相似度，取值 `[0, 1]`，越高越严格。示例使用 `0.92` 作为初始基线，而不是通用建议。生产使用前，请用有代表性的提示词进行校准。

### AISIX Enterprise 或 AISIX Cloud[​](#aisix-enterprise-或-aisix-cloud "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"
```

保留[响应缓存](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md)流程中的 `CACHE_POLICY_ID`。如果要为另一个现有策略添加语义功能，请导出该策略的 ID：

```
export CACHE_POLICY_ID="YOUR_EXISTING_CACHE_POLICY_ID"
```

列出环境中的模型，并选择用于此缓存策略的 向量嵌入模型。以下命令会输出每个 向量嵌入模型的显示名称和 ID，避免任意选择一条匹配结果：

```
curl -fsS "$AISIX_CP/environments/$ENV_ID/models" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  | jq -e '

      [.data[] | select(.kind == "embedding") | {display_name, id}]

      | if length == 0 then error("No embedding models found") else .[] end

    '
```

导出所选模型的 ID：

```
export EMBED_MODEL_ID="YOUR_EMBEDDING_MODEL_ID"
```

如果环境中没有 向量嵌入模型，该命令会失败。请先创建一个模型，或确认 `ENV_ID` 指向配置了该模型的环境。

用 `semantic` 块修补现有策略。AISIX Cloud Admin API 通过资源 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-binary @- <<EOF | jq

  {

    "semantic": {

      "embedding_model_id": "${EMBED_MODEL_ID}",

      "threshold": 0.92

    }

  }

EOF
```

同样的配置也可以在控制台的 **缓存策略** 页面管理。编辑现有策略，启用 **语义匹配（向量相似度）**，选择 向量嵌入模型并调整阈值。

之后若想在不重建策略的情况下关闭语义层，在 `PATCH` 请求中发送 `"semantic": null`；省略该字段则保持配置不变。

### 开源 AISIX 网关[​](#open-source-aisix-gateway "开源 AISIX 网关的直接链接")

将 `text-embedder` 添加到 `models`，然后替换 `default-chat-cache` 策略。保持其他资源不变：

resources.yaml（语义缓存资源）

```
models:

  - display_name: text-embedder

    provider: openai

    model_name: text-embedding-3-small

    provider_key: openai-prod

    embedding:

      dimensions: 1536



cache_policies:

  - name: default-chat-cache

    enabled: true

    backend: memory

    applies_to: "model:gpt-4o-mini"

    ttl_seconds: 3600

    semantic:

      embedding_model: text-embedder

      threshold: 0.92
```

语义块通过 向量嵌入模型的 `display_name` 引用它。

校验完整的资源文件，然后重载网关。

该示例延续响应缓存流程中使用 Memory 后端的 `default-chat-cache` 策略。如果现有策略使用其他名称或 Redis 后端，请保持这些字段不变，只添加 `semantic` 块。

### 可选语义参数[​](#optional-semantic-settings "可选语�义参数的直接链接")

| 字段                   | 默认值 | 行为                                                                                                      |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `max_entries`          | `1000` | `memory` 后端下每个策略存储条目的上限（1–10000），最旧的条目先被淘汰。共享后端按 TTL 控制规模并忽略此值。 |
| `embedding_timeout_ms` | 无     | 向量嵌入调用的单次超时。超时后请求不经缓存直接发往上游。                                                  |

## 验证语义命中[​](#verify-semantic-hits "验证语义命中的直接链接")

先发送一个请求，然后用不同的措辞重复同一个意思。响应头会区分两个匹配层。网关只有在启动配置将 [`proxy.expose_debug_headers`](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md#expose-debug-response-headers) 设为 `true` 时才会发送这些响应头，请在用于测试的网关上开启该设置。未开启时，可按请求的 `x-aisix-request-id` 从访问日志的 `cache_status` 和 `cache_hit_layer` 字段读取命中结果和命中层，但访问日志不含相似度分数。

```
curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \

  -H "Authorization: Bearer ${AISIX_API_KEY}" \

  -H "Content-Type: application/json" \

  --data '{"model": "'"$AISIX_MODEL"'", "messages": [{"role": "user", "content": "How do I reset my password?"}]}'
```

第一个请求报告未命中并存储响应：

```
x-aisix-cache: miss
```

重复完全相同的请求，它命中精确层：

```
x-aisix-cache: hit

x-aisix-cache-layer: exact
```

现在改写提示词：

```
curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \

  -H "Authorization: Bearer ${AISIX_API_KEY}" \

  -H "Content-Type: application/json" \

  --data '{"model": "'"$AISIX_MODEL"'", "messages": [{"role": "user", "content": "What are the steps to reset a password?"}]}'
```

如果相似度超过阈值，响应来自语义层，不产生上游调用：

```
x-aisix-cache: hit

x-aisix-cache-layer: semantic

x-aisix-cache-similarity: 0.9714
```

`x-aisix-cache-similarity` 报告匹配条目的余弦相似度。如果改写反而未命中，请谨慎调低阈值，或确认两个请求使用了完全相同的采样参数。

语义命中还会把新措辞回填到精确层，因此重复同一改写会直接命中精确层。

## 了解误命中风险[​](#understand-the-risk-of-false-hits "了解误命中风险的直接链接")

语义命中后，AISIX 会直接返回已存储的响应，不会再校验它是否适用于新请求，因此分数达到阈值是唯一的条件。

只差一个关键词的问题最容易出错。“How many days of annual leave do I get?” 和 “How many days of personal leave do I get?” 的分数可能高于阈值，甚至高于其中任一问题的真正同义问法。这种情况下，没有阈值能把它们完全分开。

误命中还会持续。语义命中会回填精确层，因此在 TTL 到期或清空缓存之前，同样措辞的请求会一直收到错误的响应。

语义缓存适合答案稳定的 FAQ 和文档问答。如果答案取决于具体的实体、编号或日期，请只使用精确层，或在这类请求上发送 `Cache-Control: no-cache` 跳过两层查找。`no-cache` 请求仍会存储响应，之后未带该请求头的请求可能匹配到它。如果也不想把响应写入缓存，请发送 `Cache-Control: no-cache, no-store`。

## 调优阈值[​](#tune-the-threshold "调优阈值的直接链接")

从示例值 `0.92` 起步，再用自己的正例和负例评估，同时统计命中率和误命中率。负例中要包含只差一个词的问题，并且每个示例都要带上生产环境的 system prompt，因为它也是被向量化的文本。

然后调整阈值：

* **返回了错误答案**（不同的问题被当成同一个）：调高阈值并重复评估。调高后要[清空缓存](#purge-cached-entries)。缓存 key 不包含阈值，因此已回填到精确层的响应仍会继续返回。
* **同义改写未命中**（同一个问题重复走上游）：逐步调低，同时监控错误匹配。对于大多数 向量嵌入模型，低于 `0.9` 会明显增加返回错误答案的风险。
* 合适的取值取决于 向量嵌入模型。更换 向量嵌入模型后需要重新调优——不同模型的分数不可比。更换 向量嵌入模型同时会使既有语义条目失效，因为不同模型产生的向量无法比较。
* 可能不存在能分开所有问题对的阈值。这种情况下，请按能接受的误命中率取舍。

用 `x-aisix-cache-similarity` 响应头做校准：发送已知等价和已知不同的提示词对，观察它们的分数。该响应头需要开启 [`proxy.expose_debug_headers`](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md#expose-debug-response-headers)。

分数只在语义命中时返回，因此低于阈值的问题对没有分数。要观察低分样本，可以在测试策略上临时调低阈值，并在每对之间清空缓存。否则，查找可能匹配到上一对留下的条目，重复的提示词也会由回填的精确层应答，不返回分数。

## 选择共享范围[​](#choose-the-sharing-scope "选择共享范围的直接链接")

策略的 `scope` 决定谁可以共享缓存条目，对**两个**匹配层同时生效：

| Scope     | 行为                                                                                    |
| --------- | --------------------------------------------------------------------------------------- |
| `api_key` | 默认值。条目仅对写入它的调用方 API Key 可见——一个调用方的回答绝不会回放给另一个调用方。 |
| `env`     | 环境内所有调用方 API Key 共享条目。                                                     |

除非所有调用方等价，否则保持默认的 `api_key`。语义匹配让跨调用方复用比精确匹配风险更高：对*另一个用户*问题的同义改写，可能命中为那个用户的上下文生成的响应。只有 FAQ、文档问答这类共享知识型流量——跨调用方复用正是其目的——才选择 `env`。

## 按请求绕过缓存[​](#bypass-the-cache-per-request "按请求绕过缓存的直接链接")

标准的 `Cache-Control` 请求指令可以改变单个请求的缓存行为，而无需改动策略。`no-cache` 跳过两个匹配层并刷新存储的条目；`no-store` 保留两个查找层，但会在未命中后抑制写入。参见[按请求绕过缓存](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md#bypass-the-cache-per-request)。

## 清空缓存条目[​](#purge-cached-entries "清空缓存条目的直接链接")

清空操作会使策略存储的所有条目失效——两个匹配层、所有网关实例——而不删除策略本身：

```
curl -sS -X POST \

  "$AISIX_CP/environments/$ENV_ID/cache_policies/$CACHE_POLICY_ID/purge" \

  -H "Authorization: Bearer $AISIX_TOKEN" | jq
```

响应返回 `purge_generation` 递增后的策略。更新后的配置一经传播，网关就把更早代次的条目视为已删除；存储空间在后台回收。控制台在每个策略行上以 **清空缓存条目** 按钮提供同一操作。

资源文件部署方式下，在现有策略条目上添加 `purge_generation` 字段并在每次清空时递增：

resources.yaml（清空缓存）

```
cache_policies:

  - name: default-chat-cache

    # ...

    purge_generation: 1
```

请让该值单调递增。清空后绝不能降低或省略该值，否则可能会使更早的精确缓存条目重新可用，直至其过期。完整要求请参阅[清空缓存条目](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md#purge-cached-entries)。

## 使用 Redis 共享语义条目[​](#share-semantic-entries-with-redis "使用 Redis 共享语义条目的直接链接")

`memory` 后端下每个网关实例维护自己的条目。要跨实例共享两个缓存层，按[使用 Redis 共享缓存条目](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md#share-cache-entries-with-redis)的说明使用 `backend: redis` 加上网关的 `cache.redis` 启动配置。

语义层对 Redis 有额外要求：

* **Redis 8 或更高版本**（或带 search 模块的 Redis Stack 部署）。网关把向量存进向量索引并运行 KNN 相似度查询。
* \*\*`single` 或 `sentinel` 模式。\*\*语义条目不支持 Redis Cluster。
* \*\*RESP2。\*\*不要在 `cache.redis` URL 中添加 `protocol=resp3`。语义缓存探测会拒绝 RESP3，因为其向量检索响应解析器需要 RESP2。

网关启动时会探测 Redis 部署是否支持向量检索和 RESP2。Redis 版本过旧、缺少模块、使用 Cluster 模式或 RESP3 都会导致探测失败。此时，该后端上的策略继续**只提供精确匹配**并记录一条警告。精确层共享不受影响，仅相似度层被禁用。

上述结论是最终的，因为服务端明确给出了答案。而探测本身没有得到应答时——例如 Redis 不可达或响应过慢——网关会在后台重试，而不是就此判定不支持。重试成功后语义匹配随即启用；在问题尚未有答案期间，每个请求既不会触发向量化调用，也不会产生 Redis 往返。

精确层与语义层在 Redis 上保持一致：条目存储在同一键空间下，清空代次同时作用于两层，TTL 与策略一致。

## 可观测性[​](#observability "可观测性的直接链接")

缓存行为在三个层面可见：

* **响应头**：`x-aisix-cache`（`hit` / `miss` / `bypass`）、`x-aisix-cache-layer`（命中时为 `exact` / `semantic`）、`x-aisix-cache-similarity`（仅语义命中），仅在 [`proxy.expose_debug_headers`](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md#expose-debug-response-headers) 为 `true` 时发送。见[响应头与错误码](https://docs.apiseven.com/ai-gateway/reference/headers-and-error-codes.md#proxy-response-headers)。
* **Prometheus 指标**：`aisix_cache_requests_total` 按策略统计结果（`hit_exact` / `hit_semantic` / `miss` / `bypass`），`aisix_cache_semantic_*` 系列跟踪 向量嵌入延迟与失败模式。命中率查询见[指标参考](https://docs.apiseven.com/ai-gateway/reference/metrics.md#cache-metrics)。
* **用量事件**：缓存响应把命中层记录在 `cache_hit_layer`，语义命中的相似度记录在 `cache_similarity`。`object_store`、`datadog` 和 `aliyun_sls` [导出器](https://docs.apiseven.com/ai-gateway/observability/exporters.md)会携带这两个字段，其中 Datadog 会加上 `aisix.` 前缀。OTLP 链路和控制面的请求日志不包含这两个字段。

## 后续步骤[​](#next-steps "后续步骤的直接链接")

你已经启用语义缓存并验证了按层归因的缓存命中。接下来：

* 回顾[响应缓存](https://docs.apiseven.com/ai-gateway/traffic-controls/caching.md)中的后端选择、`applies_to` 作用域以及仍然约束语义匹配的精确层指纹规则。
* 通过[指标参考](https://docs.apiseven.com/ai-gateway/reference/metrics.md#cache-metrics)观察语义命中率，并在扩大策略范围之前调优阈值。
