mcpField
U
upstash-vector-db-skills

upstash-vector-db-skills

github.com/gocallum数据与数据库23366 次安装40 周前更新
代码仓库

关于 upstash-vector-db-skills

upstash-vector-db-skills 是使用 Upstash Vector 及其 Node.js/TypeScript SDK 构建应用的指南，涵盖索引、语义检索、嵌入选项和命名空间隔离，适用于搜索与 RAG 实现。

主要功能

  1. 01写入向量和文本文档
  2. 02结合元数据执行语义查询
  3. 03通过命名空间隔离数据
  4. 04配置嵌入模型
  5. 05批量索引与向量维护

适用场景

  1. 01构建文档语义搜索
  2. 02为 RAG 工作流检索上下文
  3. 03按租户隔离搜索数据
  4. 04批量导入向量至索引

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gocallum/nextjs16-agent-skills --skill upstash-vector-db-skills

安装后在 Claude Code 中输入/upstash-vector-db-skills确认已加载。

详细介绍

链接

快速设置

1. 创建向量索引（Upstash 控制台）
  • 前往 Upstash 控制台
  • 创建向量索引：名称、区域（选择距离应用最近的区域）、类型（语义搜索选择 Dense）
  • 选择嵌入模型：建议使用 MixBread AI（或使用 Upstash 内置模型）
  • 将 UPSTASH_VECTOR_REST_URL 和 UPSTASH_VECTOR_REST_TOKEN 复制到 .env
2. 安装 SDK
pnpm add @upstash/vector
3. 环境配置
UPSTASH_VECTOR_REST_URL=your_url
UPSTASH_VECTOR_REST_TOKEN=your_token

代码示例

初始化客户端（Node.js / TypeScript）
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});
插入文档（自动嵌入）

在索引中使用嵌入模型时，文本会自动进行嵌入：

// Single document
await index.upsert({
  id: "doc-1",
  data: "Upstash provides serverless vector database solutions.",
  metadata: { source: "docs", category: "intro" },
});

// Batch
await index.upsert([
  { id: "doc-2", data: "Vector search powers semantic similarity.", metadata: { source: "docs" } },
  { id: "doc-3", data: "MixBread AI provides high-quality embeddings.", metadata: { source: "blog" } },
]);
查询 / 语义搜索
// Semantic search with auto-embedding
const results = await index.query({
  data: "What is semantic search?",
  topK: 5,
  includeMetadata: true,
});

results.forEach((result) => {
  console.log(`ID: ${result.id}, Score: ${result.score}, Metadata:`, result.metadata);
});
使用命名空间（数据隔离）

命名空间会将单个索引划分为彼此隔离的子集，适用于多租户或多领域应用。

// Upsert in namespace "blog"
await index.namespace("blog").upsert({
  id: "post-1",
  data: "Next.js tutorial for Vercel deployment",
  metadata: { author: "user-123" },
});

// Query only "blog" namespace
const blogResults = await index.namespace("blog").query({
  data: "Vercel deployment",
  topK: 3,
  includeMetadata: true,
});

// List all namespaces
const namespaces = await index.listNamespaces();
console.log(namespaces);

// Delete namespace
await index.deleteNamespace("blog");
完整语义搜索示例（Vercel 函数）
// api/search.ts (Vercel Edge Function or Serverless Function)
import { Index } from "@upstash/vector";

export const config = {
  runtime: "nodejs", // or "edge"
};

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

export default async function handler(req, res) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  const { query, namespace = "", topK = 5 } = req.body;

  try {
    const searchIndex = namespace ? index.namespace(namespace) : index;
    const results = await searchIndex.query({
      data: query,
      topK,
      includeMetadata: true,
    });

    return res.status(200).json({ results });
  } catch (error) {
    console.error("Search error:", error);
    return res.status(500).json({ error: "Search failed" });
  }
}
索引操作
// Reset (clear all vectors in index or namespace)
await index.reset();

// Or reset a specific namespace
await index.namespace("old-data").reset();

// Delete a single vector
await index.delete("doc-1");

// Delete multiple vectors
await index.delete(["doc-1", "doc-2", "doc-3"]);

嵌入模型

Upstash 提供的模型
  • BAAI/bge-large-en-v1.5（1024 维，性能最佳，MTEB 分数约为 64.23）
  • BAAI/bge-base-en-v1.5（768 维，平衡性良好）
  • BAAI/bge-small-en-v1.5（384 维，轻量级）
  • BAAI/bge-m3（1024 维，稀疏 + 稠密混合）
推荐：MixBread AI

如果使用 MixBread 作为嵌入提供商：

  1. 在 https://www.mixbread.ai/ 创建 MixBread API 密钥。
  2. 创建 Upstash 索引时，选择 MixBread 作为嵌入模型。
  3. MixBread 会自动处理分词和语义质量。
  4. 无需在代码中进行额外设置；直接使用 index.upsert() / index.query() 处理文本即可。

最佳实践

Vercel 部署
  • 将凭据存储在 Vercel 环境变量中（项目设置或 .env.local）。
  • 使用 Edge Functions 或 Serverless Functions 实现低延迟访问。
  • 实施请求速率限制，以确保不超出 Upstash 配额。
命名空间策略
  • 使用命名空间按租户、领域或使用场景隔离数据。
  • 示例：使用 namespace("user-123") 进行用户级搜索。
  • 清理旧命名空间，避免存储膨胀。
查询性能
  • 将 topK 设置为合理值（通常 5–10 即可）。
  • 尽可能使用元数据过滤预先筛选结果。
  • Upstash 采用最终一致性；插入后可能会有轻微延迟。
错误处理
try {
  const results = await index.query({
    data: userQuery,
    topK: 5,
    includeMetadata: true,
  });
} catch (error) {
  if (error.status === 401) {
    console.error("Invalid credentials");
  } else if (error.status === 429) {
    console.error("Rate limited");
  } else {
    console.error("Query error:", error);
  }
}

常见模式

RAG（检索增强生成）
  1. 将文档 / 知识库插入 Upstash。
  2. 收到用户查询时，通过语义搜索检索最相似的前 k 个文档。
  3. 将检索到的文档 + 用户查询传递给大模型，以提供更好的上下文。
const docs = await index.query({ data: userQuestion, topK: 3 });
const context = docs.map((d) => d.metadata?.text).join("\n");
// Pass context to LLM
多租户搜索

使用命名空间隔离每个租户的向量：

const userNamespace = `tenant-${userId}`;
await index.namespace(userNamespace).upsert({ id, data, metadata });
// Queries only see that tenant's data
批量索引

批量导入时，分批插入：

const batchSize = 100;
for (let i = 0; i < documents.length; i += batchSize) {
  const batch = documents.slice(i, i + batchSize);
  await index.upsert(batch);
  console.log(`Indexed batch ${i / batchSize + 1}`);
}

故障排除

  • 未返回结果：确保文档已编入索引且嵌入模型处于启用状态。
  • 查询缓慢：检查配额限制；考虑升级套餐或缩小数据集。
  • 数据过期：Upstash 采用最终一致性；查询新插入的数据前，请等待 1–2 秒。
  • 命名空间不起作用：确保命名空间存在（首次插入时创建），或使用默认值 ""。

评论

支持 Markdown