Higress AI 网关系列 05|语义缓存

《Higress AI 网关全解析》是一个以Higress为例讲解AI网关的系列，第 05 篇是语义缓存与成本优化：命中那一刻网关到底做了什么、一条答案能被复用多远。Higress 在这一格只配了一个插件 ai-cache，但它和前四篇的每一个治理插件都有交集——因为它决定那些插件还有没有机会干活。

一、是什么

先拆一个特别容易混的概念。让 AI 网关「省钱」的能力至少有三种，它们在文章里都被叫过「缓存」，工程性质完全不同：

ai-cache插件的介绍简明扼要说明了它的作用:「缓存大语言模型的响应结果，显著降低相似问题的响应时延并节省成本」。

图 1：一条请求在 ai-cache 里要过的四道闸——绕过开关、Redis 精确查、语义开关、向量查与阈值判定。三种配置组合决定哪几道闸真的在干活

这一篇的判断句先摆在这里：

网关缓存的治理对象不是命中率，而是「一个答案被复用的半径」。 半径由四件事决定：key 里只有问题原文（不含模型、不含厂商、不含消费者）、语义阈值默认形同虚设、TTL 只管得住一半、还有一个客户端自己就能带的绕过开关。

判断标准也很直接：能不能接受这条答案在所有相似问题之间共享、直到你手动去两处把它删掉。 不能接受，就别开语义缓存，只开精确匹配，并且把 cacheTTL 配上。

二、怎么工作

2.1 一次请求的三种结局

ai-cache 把每条请求导向 hit、miss、skip 三种结局之一，而只有那一种结局会付钱。

第三行和最后一行的组合是本篇所有麻烦的来源：命中不产生任何一次上游调用，却产生一个和真实响应长得一模一样的 200。

2.2 截断线画在 priority 800 上

Higress 的插件就是链上的普通过滤器，位置由「执行阶段 + 优先级」决定。ai-cache 落在默认阶段、优先级 800，装完之后数据面的 wasm 链长这样：

命中时排在 800 之后的 ai-quota、ai-token-ratelimit、ai-security-guard、ai-proxy 的请求阶段一个都不执行，所以额度不扣、限流不加、内容不送审、上游不打。

但要说全：响应方向仍然逆向穿过所有插件。所以精确的说法是「治理插件跑了，可它们记不到这次调用」，而不是「一个插件都没看到」。

图 2：priority 数轴上的命中截断线——800 以下的 quota / ratelimit / security-guard / proxy 在命中时看不到这次调用，线上只剩 ai-statistics 亮着

2.3 命中返回的是网关自制的响应

缓存里存的不是响应，是答案文本。命中时插件把这段文本 JSON 转义后塞进模板，模板硬编码在配置默认值里：

2.4 复用半径之一：key 就是问题原文

读和写用的是同一个 key：cacheKeyPrefix + key，前缀默认 higress-ai-cache:，key 就是最后一条用户消息的原文。

这意味着 Redis 里的 key 就是用户问的那句话，而这句话里没有 model、没有 provider、没有消费者身份。三个后果：

• •换模型照样命中。
   同一条问题先在 DeepSeek 上打热，再发给通义，拿到的是 DeepSeek 那条答案，model 写着 from-cache。
• •换厂商照样命中。
   上面这条在两条不同的 AI 路由之间同样成立（本篇实操 Step 4 就是这一刀）。
• •换租户照样命中。
   两个不同的消费者问同一句话，共用同一条缓存。

2.5 复用半径之二：两级查找，和那个默认关掉的开关

配了 cache 和 vector 之后，查找是两级的：先拿问题原文做一次 Redis 精确查找，命中直接用；未命中才走向量。语义命中之后，插件会把当前这条问题原文再写一份进 Redis。

2.6 复用半径之三：阈值不是精度旋钮

七个向量库 provider 塞进 Score 这个字段的东西，语义是相反的：

而判定就是一个裸比较，默认参数是 threshold: 1000 + thresholdRelation: lt（填 0 会被改回 1000，所以「阈值设成 0」这条路也走不通）。

score < 1000 对相似度型恒真、对距离型几乎恒真。也就是说：只要库里躺着任何一条记录，就算命中。

拿真读数说话。锚点是一条已缓存的问题「Python 怎么反转字符串」，答案「用切片：s[::-1]。」，向量库 Qdrant（Cosine）、embedding 用 text-embedding-v3（1024 维）。六个探针，三种阈值配置各跑一轮，每轮之前把 Redis 和集合清空、只留锚点那一条：

默认那一列，六条全过——四条不相干的问题都拿回了 s[::-1]。「默认阈值等于没设阈值」这件事不用讲道理，给读数就行。

图 3：六个探针的 top1 相似度落在同一条轴上。gt 0.7 与「换个语言」那条之间只差 0.0536；而默认 threshold: 1000 + lt 的判定带盖住了整条轴

但真正的结论在 gt 0.7 那一列：想收下 0.7204 那条同义改写，线就只比「换语言」的 0.6667 高出 0.0536。 一根线切不开「措辞变了、答案还成立」和「语境变了、答案已失效」，因为相似度这个量里根本不含「答案是否仍然适用」这条信息。所以语义阈值不是精度旋钮，是风险旋钮：它调的是你愿意让多大比例的错答蒙混过去，而不是你希望多准。

顺带一条容易被读反的：那根线上没有安全的一侧。把线推到 0.9，只剩完全同句才命中——那语义缓存就已经退化成了精确匹配，你多付了一次 embedding 的钱，买回一个 Redis GET 本来就能干的事。

正确配法按 provider 语义分两种：相似度型 threshold: 0.8 + thresholdRelation: gt；距离型 threshold: 0.2 + lt。

2.7 复用半径之四：TTL 只管一半，失败面一声不响

cache.cacheTTL 默认 0，0 走 SET、非 0 走 SETEX。默认值就是永不过期。

配上 cacheTTL: 60 之后，Redis 那条 key 的 ttl 确实从 60 走到 -2（键没了）。但下一条同样的问题照样命中——答案在向量库的 payload 里还有一份，语义命中直接把它从 payload 里取出来返回，并且顺手按新的 60 秒写回 Redis。过期不等于失效：语义层那一份会把它复活。 向量点没有 TTL 概念，插件也不负责删。

于是失效只能手动，而手动是两个地方：Redis DEL 加向量库删点。插件没有任何清除/刷新接口。

图 4：同一份配置下的两趟路。miss 那趟走完上游、把答案写进两处存储；语义命中那趟断在 800，配额、限流、审查、代理一格没走，却返回一个 200

三、分步骤实操

这一节从零把 ai-cache 的两种模式都跑起来。

Step 0 · 加一台向量库

语义模式要有向量库。这里用 Qdrant，单机起服，只绑回环——它没有任何认证，别让它出现在局域网上：

起起来之后，在控制台「服务来源」里把它注册成一个 DNS 类型服务 qdrant、端口 6333，与第 03 篇注册 Redis 的手法一模一样。

embedding 一侧不新增任何服务：直接复用已有的那条通义服务，type: dashscope 走原生向量路径。

Step 1 · 先只开精确匹配

控制台 AI 路由管理 → 该路由行的「策略」→ 策略配置，找到「AI 缓存」卡片点「配置」。抽屉里有「表单视图 / YAML 视图 / 文档」三个页签——和第 03 篇那两个只能填 YAML 的限流插件不同，ai-cache 的 schema 是完整的，44 个表单项把向量数据库、向量化服务、缓存服务、相似度阈值、启用语义缓存、响应模板全铺开了，两种视图都填得下去。这一 Step 只给 cache 块：

生效范围选三条 AI 路由（路由级 matchRules 在 Go 插件上工作正常。三条路由各配一次之后，落库的是同一个 wasmplugins.ai-cache-2.0.1，里面三条 matchRules。

控制台：AI 路由「策略」页里 AI 缓存实例的抽屉，切到 YAML 视图，配置只有 cache 块（redis.dns:6379 + cacheTTL: 0）

Step 2 · 第一次与第二次

第一次是数秒级的真实生成；第二次 model 变成 from-cache、usage 三项全 0，耗时掉到几十毫秒。中间不需要任何客户端配合——同一条问题、同一个 key。

然后到 Redis 里看键空间，这是本篇最有说服力的一条输出：

用户问的原话就是 key。 keyspace 无上限增长、没有淘汰策略、value 是整段回答——这笔容量账留给第 11 篇，但今天就要知道它长这样。

Step 3 · 命中不扣账

把第 03 篇那三个插件打开（ai-token-ratelimit + ai-quota，额度给个够用的值），先读一次基线，再连打四条命中：

读到的基线是 266 / 3014。先放一条新问题出去，两个值各走 51（限流 key 加到 317、额度减到 2963）；等这条问题的答案进了缓存，再连打四条命中：

四条之后两个值一动不动：317 / 2963。

别把「值不涨」读成第 03 篇那个「越限即冻结」。 两种「不涨」原因相反：03 是不给扣（Redis 计数到阈

Step 4 · 换模型、换路由，照样命中

把 Step 2 那条已经打热的问题换一家问：

响应：

回来的还是那条通义写的 s[::-1]，model 是 from-cache，响应头里没有任何 DeepSeek 的厂商字段。这一刀是全篇爆炸半径最大的地方：共享范围是「所有相似问题 × 所有租户 × 直到你手动删除」，而 key 里没有任何能把它区分开的维度。正确顺序永远是先定 key 口径（cacheKeyStrategy / 前缀 / 路由范围），再开缓存，反过来就只能靠删 key 收拾。

Step 5 · 打开语义模式

把配置扩成三块，enableSemanticCache: true 这一行必须自己写（§2.5）：

控制台：同一个抽屉切到语义模式，enableSemanticCache: true，embedding 走 dashscope、vector 指向手工建的 ai_cache_p05；多出来的那行 cacheTTL: 60 是 Step 7 才改的，apiKey 已涂掉

图里 apiKey 那格照例涂掉——它是能直接换成人民币的推理额度；cacheTTL: 60 这一行是 Step 7 才动的那一个，此刻先跟着看。

先把这一行的开关效果看清楚：只配 vector + embedding 而不写 enableSemanticCache: true，日志停在 cache miss，六条探针全价；补上这一行，六条全部命中同一条锚点答案。

然后验证默认阈值有多虚。库里只留一条记录（锚点句），拿完全无关的问题去问：

similarity 只有 0.3326 的一条记录被判命中，返回的是「用切片：s[::-1]。」。把 §2.6 那张表的最后两列补进配置：

同一批探针立刻只剩同句命中；换成 0.7 / gt，0.7204 那条同义改写回到命中列，而 0.6667 那条「用 Go 反转一个切片」停在未命中——这两根线之间只差 0.0536，你要的效果和你的风险都挤在这 0.05 里。

Step 6 · 伪流式与绕过开关

命中时 SSE 只有一个data: 事件带全文，打字机效果消失。若这条链上开着 ai-data-masking，连收尾的 data:[DONE] 都不会有（§2.3）——这点务必在带流式客户端的回归里验一遍，不少前端是靠 [DONE] 收尾的。

绕过开关在客户端手里：

带这个头（值必须是 on，精确比较）就既不查也不写：真实 usage、真实模型名、ai_log 里 cache_status=skip，Redis 里也不会新增 key。同一把消费者 key，带这个头就是全价打上上游，不带就是 0 元命中——而限流在 600、位于缓存之后，它只能管到「没命中」的那部分。这个开关适合做「重新生成」，不适合被端上随意控制。

Step 7 · TTL 与「过期了还命中」

把 cache 块里的 cacheTTL 改成 60（别放到顶层，插件只从 cache 对象里读它），发一条新问题，看 Redis：

键确实没了。再把同一条问题发一遍：照样 200 命中，答案来自向量库的 payload，而且 Redis 里那条 key 复活、ttl 重新变回 60。手工作废一条要走两个地方：

四、小结

网关缓存治理的不是命中率，而是答案的复用半径；而半径的四个维度——key 里没有租户、阈值不含「是否仍适用」、TTL 拦不住语义层那一份、绕过开关在客户端手里——没有一个能靠指标暴露出来。