Upstash向量数据库技能：快速实现语义搜索与AI应用开发

upstash-vector-db-skills by gocallum/nextjs16-agent-skills

158 周安装量

19 GitHub Stars

GitHub

安装命令

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

AI/机器学习云服务数据库

🇨🇳中文介绍

链接

文档：https://upstash.com/docs/vector
快速开始：https://upstash.com/docs/vector/overall/getstarted
语义搜索教程：https://upstash.com/docs/vector/tutorials/semantic_search
命名空间：https://upstash.com/docs/vector/features/namespaces
嵌入模型：https://upstash.com/docs/vector/features/embeddingmodels
MixBread AI：https://www.mixbread.ai/（推荐的嵌入提供商）

快速设置

1. 创建向量索引（Upstash 控制台）

前往 Upstash 控制台
创建向量索引：名称、区域（选择离应用最近的）、类型（用于语义搜索选择 Dense）
选择嵌入模型：推荐使用 MixBread AI（或使用 Upstash 内置模型）
将 UPSTASH_VECTOR_REST_URL 和 UPSTASH_VECTOR_REST_TOKEN 复制到 .env 文件中

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

初始化客户端（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,
});

插入/更新文档（自动嵌入）

当索引中配置了嵌入模型时，文本会自动被嵌入：

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

// 批量
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" } },
]);

查询 / 语义搜索

// 带自动嵌入的语义搜索
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);
});

使用命名空间（数据隔离）

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

// 在 "blog" 命名空间中插入/更新
await index.namespace("blog").upsert({
  id: "post-1",
  data: "Next.js tutorial for Vercel deployment",
  metadata: { author: "user-123" },
});

// 仅查询 "blog" 命名空间
const blogResults = await index.namespace("blog").query({
  data: "Vercel deployment",
  topK: 3,
  includeMetadata: true,
});

// 列出所有命名空间
const namespaces = await index.listNamespaces();
console.log(namespaces);

// 删除命名空间
await index.deleteNamespace("blog");

完整语义搜索示例（Vercel 函数）

// api/search.ts (Vercel Edge Function 或 Serverless Function)
import { Index } from "@upstash/vector";

export const config = {
  runtime: "nodejs", // 或 "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" });
  }
}

// 重置（清除索引或命名空间中的所有向量）
await index.reset();

// 或重置特定命名空间
await index.namespace("old-data").reset();

// 删除单个向量
await index.delete("doc-1");

// 删除多个向量
await index.delete(["doc-1", "doc-2", "doc-3"]);

Upstash 内置模型

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

针对 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（检索增强生成）

将文档/知识库插入到 Upstash 中。
根据用户查询，通过语义搜索检索 top-k 相似文档。
将检索到的文档 + 用户查询传递给 LLM 以获得更好的上下文。

const docs = await index.query({ data: userQuestion, topK: 3 });
const context = docs.map((d) => d.metadata?.text).join("\n");
// 将上下文传递给 LLM

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

const userNamespace = `tenant-${userId}`;
await index.namespace(userNamespace).upsert({ id, data, metadata });
// 查询仅能看到该租户的数据

对于批量导入，分批进行插入/更新：

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 秒。
命名空间不工作：确保命名空间存在（在首次插入/更新时创建）或使用默认的 ""。

🇺🇸English

Quick Setup

1. Create Vector Index (Upstash Console)

Go to Upstash Console
Create Vector Index: name, region (closest to app), type (Dense for semantic search)
Select embedding model: MixBread AI recommended (or use Upstash built-in models)
Copy UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN to .env

2. Install SDK

pnpm add @upstash/vector

3. Environment

UPSTASH_VECTOR_REST_URL=your_url
UPSTASH_VECTOR_REST_TOKEN=your_token

Code Examples

Initialize Client (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,
});

Upsert Documents (Auto-Embed)

When using an embedding model in the index, text is embedded automatically:

// 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" } },
]);

Query / Semantic Search

// 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);
});

Using Namespaces (Data Isolation)

Namespaces partition a single index into isolated subsets. Useful for multi-tenant or multi-domain apps.

// 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");

Full Semantic Search Example (Vercel Function)

// 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" });
  }
}

Index Operations

// 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"]);

Embedding Models

Available in Upstash

BAAI/bge-large-en-v1.5 (1024 dim, best performance, ~64.23 MTEB score)
BAAI/bge-base-en-v1.5 (768 dim, good balance)
BAAI/bge-small-en-v1.5 (384 dim, lightweight)
BAAI/bge-m3 (1024 dim, sparse + dense hybrid)

Recommended: MixBread AI

If using MixBread as your embedding provider:

Create a MixBread API key at https://www.mixbread.ai/
When creating your Upstash index, select MixBread as the embedding model.
MixBread handles tokenization and semantic quality automatically.
No extra setup needed in your code; use index.upsert() / index.query() with text directly.

Best Practices

For Vercel Deployment

Store credentials in Vercel Environment Variables (project settings or .env.local).
Use Edge Functions or Serverless Functions for low-latency access.
Implement request rate limiting to stay within Upstash quotas.

Namespace Strategy

Use namespaces to isolate data by tenant, domain, or use case.
Example: namespace("user-123") for per-user search.
Clean up old namespaces to avoid storage bloat.

Query Performance

Keep topK reasonable (5–10 typically sufficient).
Use metadata filtering to pre-filter results if possible.
Upstash is eventually consistent; expect slight delays after upserts.

Error Handling

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);
  }
}

Common Patterns

RAG (Retrieval Augmented Generation)

Upsert documents / knowledge base into Upstash.
On user query, retrieve top-k similar docs via semantic search.
Pass retrieved docs + user query to LLM for better context.

const docs = await index.query({ data: userQuestion, topK: 3 });

const context = docs.map((d) => d.metadata?.text).join("\n");
// Pass context to LLM

Multi-Tenant Search

Use namespaces to isolate each tenant's vectors:

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

Batch Indexing

For bulk imports, upsert in batches:

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}`);
}

Troubleshooting

No results returned : Ensure documents are indexed and embedding model is active.
Slow queries : Check quota limits; consider upgrading plan or reducing dataset size.
Stale data : Upstash is eventually consistent; wait 1–2 seconds before querying new inserts.
Namespace not working : Ensure namespace exists (created on first upsert) or use the default "".

Weekly Installs

146

Repository

gocallum/nextjs…t-skills

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode108

gemini-cli106

codex106

github-copilot101

cursor99

claude-code90

Azure 配额管理指南：服务限制、容量验证与配额增加方法

107,600 周安装

Upstash向量数据库技能：快速实现语义搜索与AI应用开发

🇨🇳中文介绍

链接

快速设置

1. 创建向量索引（Upstash 控制台）

相关 Skills

2. 安装 SDK

3. 环境变量

代码示例