Upstash 向量存储

🌐 Upstash Vector Store

UpstashVector 类使用 Upstash Vector 提供向量搜索，这是一种无服务器向量数据库服务，提供带元数据过滤功能的向量相似搜索以及混合搜索支持。

🌐 The UpstashVector class provides vector search using Upstash Vector, a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.

构造函数选项

🌐 Constructor Options

url:

string

Upstash Vector database URL

token:

string

Upstash Vector API token

方法

🌐 Methods

createIndex()

注意：对于 Upstash，此方法无操作，因为索引是自动创建的。

🌐 Note: This method is a no-op for Upstash as indexes are created automatically.

indexName:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search

upsert()

indexName:

string

Name of the index to upsert into

vectors:

number[][]

Array of embedding vectors

sparseVectors?:

{ indices: number[], values: number[] }[]

Array of sparse vectors for hybrid search. Each sparse vector must have matching indices and values arrays.

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

Optional vector IDs (auto-generated if not provided)

query()

indexName:

string

Name of the index to query

queryVector:

number[]

Query vector to find similar vectors

sparseVector?:

{ indices: number[], values: number[] }

Optional sparse vector for hybrid search. Must have matching indices and values arrays.

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Metadata filters for the query

includeVector?:

boolean

= false

Whether to include vectors in the results

fusionAlgorithm?:

FusionAlgorithm

Algorithm used to combine dense and sparse search results in hybrid search (e.g., RRF - Reciprocal Rank Fusion)

queryMode?:

QueryMode

Search mode: 'DENSE' for dense-only, 'SPARSE' for sparse-only, or 'HYBRID' for combined search

listIndexes()

返回一个包含索引名称（命名空间）的字符串数组。

🌐 Returns an array of index names (namespaces) as strings.

describeIndex()

indexName:

string

Name of the index to describe

返回：

🌐 Returns:

interface IndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
}

deleteIndex()

indexName:

string

Name of the index (namespace) to delete

updateVector()

indexName:

string

Name of the index to update

id:

string

ID of the item to update

update:

object

Update object containing vector, sparse vector, and/or metadata

update 对象可以具有以下属性：

🌐 The update object can have the following properties:

• vector（可选）：一个表示新密集向量的数字数组。
• sparseVector（可选）：一个稀疏向量对象，包含用于混合索引的 indices 和 values 数组。
• metadata（可选）：用于存储元数据的键值对记录。

deleteVector()

indexName:

string

Name of the index from which to delete the item

id:

string

ID of the item to delete

尝试通过其ID从指定索引中删除项目。如果删除失败，会记录错误信息。

🌐 Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.

混合向量搜索

🌐 Hybrid Vector Search

Upstash Vector 支持混合搜索，将语义搜索（稠密向量）与基于关键词的搜索（稀疏向量）结合，以提高相关性和准确性。

🌐 Upstash Vector supports hybrid search that combines semantic search (dense vectors) with keyword-based search (sparse vectors) for improved relevance and accuracy.

基本混合使用

🌐 Basic Hybrid Usage

import { UpstashVector } from "@mastra/upstash";

const vectorStore = new UpstashVector({
  id: 'upstash-vector',
  url: process.env.UPSTASH_VECTOR_URL,
  token: process.env.UPSTASH_VECTOR_TOKEN,
});

// Upsert vectors with both dense and sparse components
const denseVectors = [
  [0.1, 0.2, 0.3],
  [0.4, 0.5, 0.6],
];
const sparseVectors = [
  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
];

await vectorStore.upsert({
  indexName: "hybrid-index",
  vectors: denseVectors,
  sparseVectors: sparseVectors,
  metadata: [{ title: "Document 1" }, { title: "Document 2" }],
});

// Query with hybrid search
const results = await vectorStore.query({
  indexName: "hybrid-index",
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  topK: 10,
});

高级混合搜索选项

🌐 Advanced Hybrid Search Options

import { FusionAlgorithm, QueryMode } from "@upstash/vector";

// Query with specific fusion algorithm
const fusionResults = await vectorStore.query({
  indexName: "hybrid-index",
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 10,
});

// Dense-only search
const denseResults = await vectorStore.query({
  indexName: "hybrid-index",
  queryVector: [0.1, 0.2, 0.3],
  queryMode: QueryMode.DENSE,
  topK: 10,
});

// Sparse-only search
const sparseResults = await vectorStore.query({
  indexName: "hybrid-index",
  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  queryMode: QueryMode.SPARSE,
  topK: 10,
});

更新混合向量

🌐 Updating Hybrid Vectors

// Update both dense and sparse components
await vectorStore.updateVector({
  indexName: "hybrid-index",
  id: "vector-id",
  update: {
    vector: [0.2, 0.3, 0.4],
    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
    metadata: { title: "Updated Document" },
  },
});

响应类型

🌐 Response Types

查询结果以此格式返回：

🌐 Query results are returned in this format:

interface QueryResult {
  id: string;
  score: number;
  metadata: Record<string, any>;
  vector?: number[]; // Only included if includeVector is true
}

错误处理

🌐 Error Handling

该存储会抛出可以被捕获的类型化错误：

🌐 The store throws typed errors that can be caught:

try {
  await store.query({
    indexName: "index_name",
    queryVector: queryVector,
  });
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details); // Additional error context
  }
}

环境变量

🌐 Environment Variables

所需的环境变量：

🌐 Required environment variables:

• UPSTASH_VECTOR_URL：你的 Upstash 向量数据库 URL
• UPSTASH_VECTOR_TOKEN：你的 Upstash 向量 API 令牌

使用示例

🌐 Usage Example

使用 fastembed 的本地嵌入

🌐 Local embeddings with fastembed

嵌入是由内存的 semanticRecall 用来按意义（而非关键词）检索相关信息的数字向量。这一设置使用 @mastra/fastembed 来生成向量嵌入。

🌐 Embeddings are numeric vectors used by memory's semanticRecall to retrieve related messages by meaning (not keywords). This setup uses @mastra/fastembed to generate vector embeddings.

安装 fastembed 以开始：

🌐 Install fastembed to get started:

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

将以下内容添加到你的代理中：

🌐 Add the following to your agent:

src/mastra/agents/example-upstash-agent.ts

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { UpstashStore, UpstashVector } from "@mastra/upstash";
import { fastembed } from "@mastra/fastembed";

export const upstashAgent = new Agent({
  id: "upstash-agent",
  name: "Upstash Agent",
  instructions:
    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
  model: "openai/gpt-5.1",
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    vector: new UpstashVector({
      id: 'upstash-agent-vector',
      url: process.env.UPSTASH_VECTOR_REST_URL!,
      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
});

相关

🌐 Related

• 元数据过滤器