语义缓存

[!注意]
本项目处于实验阶段。

我们将此项目声明为实验性的，以明确设定您使用时的预期。可能存在已知或未知的错误，API可能会发生变化，或者如果没有得到社区的采纳，项目可能会被终止。虽然我们无法为实验性项目提供专业支持，但如果您认为这个项目有价值，我们很乐意听取您的意见！

语义缓存是一种基于语义相似性缓存自然文本的工具。它非常适用于任何涉及基于含义查询或检索信息的任务，比如自然语言分类或缓存AI响应。两段文本可能在语义上相似但并不完全相同（例如，"西班牙值得一看的好地方"与"西班牙最佳旅游地点"）。传统的缓存无法识别这种语义相似性，从而错过了重用的机会。

语义缓存允许您：

轻松地将自然文本分类到预定义的类别中
通过缓存AI响应来避免重复的LLM工作
通过使用已缓存的值响应相似查询来减少API延迟

亮点

使用语义相似性：根据意义而非字面字符存储缓存条目
处理同义词：识别并处理同义词
多语言支持：跨不同语言工作（如果配置了多语言向量模型）
复杂查询支持：理解长篇和嵌套的用户查询
易于集成：在Node.js应用中使用的简单API
可定制：设置自定义接近度阈值以过滤掉相关性较低的结果

入门

前提条件

一个Upstash Vector数据库（在此处创建）

安装

安装软件包：

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

设置

首先，在此处创建一个Upstash Vector数据库。您需要url和token凭据来连接您的语义缓存。重要：创建数据库时选择任何预制的嵌入模型。

[!注意]
不同的嵌入模型适用于不同的用例。例如，如果低延迟是优先考虑的因素，请选择维度较小的模型，如bge-small-en-v1.5。如果准确性很重要，请选择维度更多的模型。

在项目的根目录下创建一个.env文件，并添加您的Upstash Vector URL和令牌：

UPSTASH_VECTOR_REST_URL=https://example.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your_secret_token_here

使用语义缓存

以下是如何在Node.js应用程序中使用语义缓存：

import { SemanticCache } from "@upstash/semantic-cache";
import { Index } from "@upstash/vector";

// 👇 您的向量数据库
const index = new Index();

// 👇 您的语义缓存
const semanticCache = new SemanticCache({ index, minProximity: 0.95 });

async function runDemo() {
  await semanticCache.set("土耳其的首都", "安卡拉");
  await delay(1000);

  // 👇 输出："安卡拉"
  const result = await semanticCache.get("土耳其的首都是什么？");
  console.log(result);
}

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

runDemo();

`minProximity`参数

minProximity参数范围从0到1。它允许您定义确定缓存命中的最小相关性分数。这个数字越高，您的用户输入必须与缓存内容越相似才能命中。实际上，0.95的分数表示非常高的相似度，而0.75的分数已经表示较低的相似度。例如，1.00这个最高可能值，只会接受用户查询与缓存内容的完全匹配作为缓存命中。

命名空间支持

您可以使用命名空间将数据分隔成不同的分区。

import { SemanticCache } from "@upstash/semantic-cache";
import { Index } from "@upstash/vector";

// 👇 您的向量数据库
const index = new Index();

// 👇 您的语义缓存
const semanticCache = new SemanticCache({ index, minProximity: 0.95, namespace: "user1" });

await semanticCache.set("土耳其的首都", "安卡拉");

示例

以下示例演示了如何在各种用例中使用语义缓存：

[!注意]
我们在设置数据后添加了1秒的延迟，以便为向量索引更新留出时间。这个延迟是必要的，以确保数据可供检索。

基本语义检索

await semanticCache.set("法国的首都", "巴黎");
await delay(1000);

// 👇 输出"巴黎"
const result = await semanticCache.get("法国的首都是什么？");

处理同义词

await semanticCache.set("美国人口最多的城市", "纽约");
await delay(1000);

// 👇 输出"纽约"
const result = await semanticCache.get("美国哪个城市人口最多？");

多语言查询

注意：您的嵌入模型需要支持您打算使用的语言。

await semanticCache.set("德国总理", "奥拉夫·朔尔茨");
await delay(1000);

// 👇 "谁是德国总理？" -> 输出"奥拉夫·朔尔茨"
const result = await semanticCache.get("Wer ist der Bundeskanzler von Deutschland?");

复杂查询

await semanticCache.set("柏林墙倒塌的年份", "1989");
await delay(1000);

// 👇 输出"1989"
const result = await semanticCache.get("柏林墙被摧毁的年份是什么时候？");

不同上下文

await semanticCache.set("水的化学式", "H2O");
await semanticCache.set("炎热天气最健康的饮品", "水");

await delay(1000);

// 👇 输出"水"
const result = await semanticCache.get("天气炎热时我应该喝什么？");

// 👇 输出"H2O"
const result = await semanticCache.get("告诉我水的化学式");