upstash-vector-db-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

链接

Docs: https://upstash.com/docs/vector
Getting Started: https://upstash.com/docs/vector/overall/getstarted
Semantic Search Tutorial: https://upstash.com/docs/vector/tutorials/semantic_search
Namespaces: https://upstash.com/docs/vector/features/namespaces
Embedding Models: https://upstash.com/docs/vector/features/embeddingmodels
MixBread AI: https://www.mixbread.ai/ (preferred embedding provider)

文档: 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/ （推荐的嵌入服务提供商）

Quick Setup

快速配置

1. Create Vector Index (Upstash Console)

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

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

.env

访问 Upstash控制台
创建向量索引：设置名称、区域（选择离应用最近的）、类型（语义搜索选择Dense）
选择嵌入模型：推荐使用MixBread AI（或使用Upstash内置模型）

将

UPSTASH_VECTOR_REST_URL

和

UPSTASH_VECTOR_REST_TOKEN

复制到

.env

文件中

2. Install SDK

2. 安装SDK

pnpm add @upstash/vector

pnpm add @upstash/vector

3. Environment

3. 环境配置

env

UPSTASH_VECTOR_REST_URL=your_url
UPSTASH_VECTOR_REST_TOKEN=your_token

env

UPSTASH_VECTOR_REST_URL=your_url
UPSTASH_VECTOR_REST_TOKEN=your_token

Code Examples

代码示例

Initialize Client (Node.js / TypeScript)

初始化客户端（Node.js / TypeScript）

typescript

import { Index } from "@upstash/vector";

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

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:

typescript

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

当索引中配置了嵌入模型时，文本会自动进行嵌入处理：

typescript

// 单个文档
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" } },
]);

Query / Semantic Search

查询 / 语义搜索

typescript

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

typescript

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

typescript

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

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

typescript

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

Full Semantic Search Example (Vercel Function)

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

typescript

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

typescript

// api/search.ts（Vercel边缘函数或无服务器函数）
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" });
  }
}

Index Operations

索引操作

typescript

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

typescript

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

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

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

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

Embedding Models

嵌入模型

Available in Upstash

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)

```
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维度，稀疏+密集混合模型）

Recommended: MixBread AI

Best Practices

最佳实践

For Vercel Deployment

针对Vercel部署

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.

将凭证存储在Vercel环境变量中（项目设置或
```
.env.local
```
文件）
使用边缘函数或无服务器函数以实现低延迟访问
实现请求速率限制，避免超出Upstash配额

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.

使用命名空间按租户、领域或用例隔离数据
示例：
```
namespace("user-123")
```
用于用户专属搜索
清理旧命名空间，避免存储冗余

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.

合理设置
```
topK
```
（通常5-10即可满足需求）
如有可能，使用元数据过滤预先筛选结果
Upstash为最终一致性模型；插入新数据后可能需要等待1-2秒再查询

Error Handling

错误处理

typescript

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

typescript

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)

RAG（检索增强生成）

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.

typescript

const docs = await index.query({ data: userQuestion, topK: 3 });
const context = docs.map((d) => d.metadata?.text).join("\n");
// Pass context to LLM

将文档/知识库插入Upstash向量数据库
用户查询时，通过语义搜索检索最相似的前k个文档
将检索到的文档+用户查询传入大语言模型，以获得更具上下文的结果

typescript

const docs = await index.query({ data: userQuestion, topK: 3 });
const context = docs.map((d) => d.metadata?.text).join("\n");
// 将上下文传入大语言模型

Multi-Tenant Search

多租户搜索

Use namespaces to isolate each tenant's vectors:

typescript

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

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

typescript

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

Batch Indexing

批量索引

For bulk imports, upsert in batches:

typescript

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

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

typescript

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
```
""
```
.

无结果返回：确保文档已完成索引，且嵌入模型处于激活状态
查询缓慢：检查配额限制；考虑升级套餐或缩小数据集规模
数据过时：Upstash为最终一致性模型；插入新数据后等待1-2秒再查询
命名空间无法工作：确保命名空间已存在（首次插入时自动创建）或使用默认空命名空间
```
""
```

upstash-vector-db-skills

Original

Translation

Links

链接

Quick Setup

快速配置

1. Create Vector Index (Upstash Console)

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

2. Install SDK

2. 安装SDK

3. Environment

3. 环境配置

Code Examples

代码示例

Initialize Client (Node.js / TypeScript)

初始化客户端（Node.js / TypeScript）

Upsert Documents (Auto-Embed)

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

Query / Semantic Search

查询 / 语义搜索

Using Namespaces (Data Isolation)

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

Full Semantic Search Example (Vercel Function)

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

Index Operations

索引操作

Embedding Models

嵌入模型

Available in Upstash

Upstash支持的模型

Recommended: MixBread AI

推荐：MixBread AI

Best Practices

最佳实践

For Vercel Deployment

针对Vercel部署

Namespace Strategy

命名空间策略

Query Performance

查询性能

Error Handling

错误处理

Common Patterns

常见模式

RAG (Retrieval Augmented Generation)

RAG（检索增强生成）

Multi-Tenant Search

多租户搜索

Batch Indexing

批量索引

Troubleshooting

故障排除