Semantic Cache：让 AI 应用学会「举一反三」的语义缓存

想象这样一个场景：你的 AI 助手刚刚回答过「法国的首都是什么」，用户下一秒又问「法国最大的城市是哪个」——人类很容易理解这其实是在问同一件事，但传统缓存只能死板地等待「法国的首都是什么」再次出现。这种语义上的「隔靴搔痒」，正是 Semantic Cache 要解决的核心痛点。

图1：Semantic Cache 工作原理

背景：为什么需要语义缓存

在 LLM 应用的世界里，重复调用 API 是成本的大头。一个客服机器人可能每天收到上万次询问，其中相当一部分在语义上高度重叠——「怎么重置密码」「忘记密码怎么办」「密码丢了」——本质上问的是同一件事。

传统键值缓存（如 Redis）按精确键名匹配，get("怎么重置密码") 和 get("忘记密码怎么办") 在 Redis 眼里是两个完全不同的 key，永远不会命中。这种「字面至上」的匹配策略，在 AI 应用场景下等于把语义相近的请求白白放走，每次都去问 LLM，既费钱又费时。

Semantic Cache 则换了一个思路：不是比较字符串，而是把输入转化为向量（embedding），在向量空间里找「最相近」的历史记录。用数学的话说，就是用余弦相似度或点积，判断两条文本在语义上有多接近，从而决定是否命中缓存。

核心技术：向量检索驱动的缓存淘汰机制

整个项目的技术架构可以用一句话概括：基于 Upstash Vector 向量数据库的语义相似度缓存。代码只有两个核心文件（src/semantic-cache.ts + src/semantic-cache.test.ts），逻辑清晰到令人舒适。

核心参数 minProximity：这个参数控制「多像才算命中」。默认 0.9，意味着相似度超过 90% 才算 cache hit。如果设成 1.0，就退化成了精确匹配（传统 HashMap）；设成 0.0 则永远返回相似度最高的条目（类全文搜索）。这个参数让开发者可以在「精确」和「模糊」之间自由调节，非常实用。

双重 set/get 接口：既支持单条操作（set(key, value) / get(key)），也支持批量操作（set([k1, k2], [v1, v2]) / get([k1, k2])）。批量接口内部用 Promise.all 并行查询，对性能敏感的场景很有价值。

Namespace 隔离：支持给缓存划分命名空间（类似 Redis 的 DB 选择），可以做到多用户/多场景数据隔离。比如在 SaaS 应用中，不同租户的缓存互不干扰，逻辑清晰又安全。

上手体验：npm 装上就能跑

安装只需一行命令：

npm install @upstash/semantic-cache @upstash/vector

使用也非常直观：创建一个 Upstash Vector 实例作为向量数据库，再套上一层 SemanticCache，就能用 set 存、 get 取。唯一需要注意的是：Upstash Vector 是云服务（免费层足够个人项目用），需要在 console.upstash.com/vector 注册并创建数据库，获取 REST URL 和 Token 后填入 .env 文件。

官方推荐的 embedding 模型是预制的（如 bge-small-en-v1.5），低延迟场景选小维度模型，追求精度选大维度模型，这个设计对新手非常友好。

局限性：不完美但诚实

这个项目有一个明显的设计局限：依赖 Upstash 生态，无法独立使用。如果你已经在用 Upstash Vector，那这是完美的补强；但如果你想用 Qdrant/Milvus/Weaviate 等其他向量数据库，这套 SDK 就鞭长莫及了。另外，它是纯 Node.js SDK，没有 Docker 支持，也不适合在浏览器端直接使用。

从代码规模看，核心逻辑不过 100 多行，测试覆盖率虽然完整（vitest），但功能本身相对单一，不适合作为大型系统的核心组件——它更像是 Upstash 生态里的一个「效率小工具」。

行业意义：RAG 时代的基础设施思维

Semantic Cache 反映了一个趋势：在 LLM 应用层，可控成本的工程化手段正在成熟。与其花大价钱让每个请求都经过 LLM 推理，不如在语义层面做预过滤，把真正需要回答的问题留给模型。从这个角度看，语义缓存是 RAG（检索增强生成）流水线上的一个自然延伸。

Upstash 作为 Serverless 数据库的专业户，一直在补全 AI 应用的基础设施拼图。Semantic Cache 与其现有的 Redis/Vector/Kafka 产品线形成协同，用极小的代码体量解决了 LLM 应用中的高频痛点，这种「小而美」的定位值得肯定。

作者：Enes Akar（Upstash 团队）| 许可证：MIT | 当前版本：v1.0.3

图2：Upstash 官方 logo