语义缓存
语义缓存让 AISIX 在新请求与先前请求的相似度达到阈值时返回缓存的响应,即使措辞不同。相似不等于含义相同:含义不同的两个请求也可能达到阈值,参见了解误命中风险。它是响应缓存的扩展:精确匹配层始终先被检查,语义层负责处理精确层未命中的请求。
在本指南中,你将为缓存策略添加语义配置块,验证精确命中与语义命中,并清空缓存条目。你还将了解跨网关实例共享语义条目所需的 Redis 要求。
语义缓存的工作原理
配置了 semantic 块的缓存策略会对每个符合条件的请求依次运行两个匹配层:
- **精确层。**首先查找请求指纹——模型别名、规范化后的 messages、采样参数以及其他影响响应的选项。完全相同的重复请求在此命中,无需任何 向量嵌入调用。
- **语义层。**精确层未命中时,AISIX 会向量化请求中所有消息的文本,包括 system prompt 和历史消息,每条消息一行,格式为
role: content。向量化使用策略配置的 向量嵌入模型,结果再与已存储的条目比较。相似度达到或超过阈值的最近条目会被返回;否则请求继续发往上游,响应连同其向量一起被存储。
只有 messages 内容参与相似度匹配,分数针对全部文本计算,而不只是最新的问题。因此,所有请求共用的长 system prompt 会抬高本来不同的问题之间的分数。模型别名和其他指纹字段仍必须匹配。如果存在 temperature 和 top_p,则以 0.001 的精度比较,因此同一千分位区间内的显式值视为相等。省略字段与显式设置该字段仍视为不同。消息中包含图片、音频或工具结果的请求永远不会做相似度匹配,它们只使用精确层。
语义命中也不会刷新条目:条目与精确条目一样按策略 TTL 过期。
向量嵌入失败时放行
语义匹配是一种优化,绝不是一道闸门。如果 向量嵌入调用失败或超时,请求会不经缓存直接发往上游,失败会计入缓存指标。如果 向量嵌入模型被删除或配置错误,策略会记录一条警告并继续只提供精确匹配。
准备工作
开始之前,请准备以下内容:
- 一套可用的响应缓存配置:控制面路径(AISIX Enterprise 或 AISIX Cloud)或声明式资源文件、模型别名和调用方 API Key。
- 同一环境中的一个 向量嵌入模型。在 AISIX Enterprise 或 AISIX Cloud 中,这是 kind 为
embedding的模型;在资源文件中则是带embedding块的模型条目。它负责将请求文本向量化以做相似度比较;其dimensions值固定了该策略条目的向量维度。 - 使用 Redis 后端的策略还需要支持向量检索的 Redis 部署——见使用 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"
配置语义缓存策略
semantic 块在现有缓存策略上启用相似度层。请把它添加到已覆盖该模型的策略中,而不是再创建一个重叠策略。当多个已启用的策略匹配同一请求时,首个匹配的策略生效,因此后面的语义策略可能永远不会运行。
阈值为必填项:它是条目被返回所需的最小余弦相似度,取值 [0, 1],越高越严格。示例使用 0.92 作为初始基线,而不是通用建议。生产使用前,请用有代表性的提示词进行校准。
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"
保留响应缓存流程中的 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 网关
将 text-embedder 添加到 models,然后替换 default-chat-cache 策略。保持其他资源不变:
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 块。