Upstash Vector 存储

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

构造函数选项

url:

string

Upstash Vector 数据库 URL

token:

string

Upstash Vector API 的 token

方法

createIndex()

注意：对于 Upstash，此方法不执行任何操作，因为索引会自动创建。

indexName:

string

要创建的索引名称

dimension:

number

Vector 维度（必须与你的嵌入模型匹配）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

用于相似度搜索的距离度量

upsert()

indexName:

string

要向其中执行 upsert 的索引名称

vectors:

number[][]

嵌入 Vector 数组

sparseVectors?:

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

用于混合搜索的稀疏 Vector 数组。每个稀疏 Vector 的 indices 和 values 数组必须相互对应。

metadata?:

Record<string, any>[]

每个 Vector 的元数据

ids?:

string[]

可选的 Vector ID（未提供时自动生成）

query()

indexName:

string

要查询的索引名称

queryVector:

number[]

用于查找相似 Vector 的查询 Vector

sparseVector?:

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

用于混合搜索的可选稀疏 Vector。其 indices 和 values 数组必须相互对应。

topK?:

number

= 10

要返回的结果数量

filter?:

Record<string, any>

查询所用的元数据过滤条件

includeVector?:

boolean

= false

是否在结果中包含 Vector

fusionAlgorithm?:

FusionAlgorithm

在混合搜索中用于合并稠密与稀疏搜索结果的算法（例如 RRF，即 Reciprocal Rank Fusion）

queryMode?:

QueryMode

搜索模式：'DENSE' 表示仅稠密搜索，'SPARSE' 表示仅稀疏搜索，'HYBRID' 表示组合搜索

listIndexes()

以字符串数组形式返回索引名称（namespace）。

describeIndex()

indexName:

string

要描述的索引名称

返回：

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

deleteIndex()

indexName:

string

要删除的索引（namespace）名称

updateVector()

indexName:

string

要更新的索引名称

id:

string

要更新的项目 ID

update:

object

包含 Vector、稀疏 Vector 和/或元数据的更新对象

update 对象可包含以下属性：

• vector（可选）：表示新稠密 Vector 的数字数组。
• sparseVector（可选）：用于混合索引的稀疏 Vector 对象，其中包含 indices 和 values 数组。
• metadata（可选）：由元数据键值对组成的记录。

deleteVector()

indexName:

string

要从中删除项目的索引名称

id:

string

要删除的项目 ID

尝试按 ID 从指定索引中删除项目。如果删除失败，则记录一条错误消息。

混合 Vector 搜索

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

混合搜索基本用法

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

高级混合搜索选项

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

更新混合 Vector

// 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' },
  },
})

响应类型

查询结果以以下格式返回：

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

错误处理

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

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

环境变量

必需的环境变量：

• UPSTASH_VECTOR_URL：你的 Upstash Vector 数据库 URL
• UPSTASH_VECTOR_TOKEN：你的 Upstash Vector API token

用法示例

使用 fastembed 生成本地嵌入

嵌入是 memory 的 semanticRecall 用来按语义（而非关键词）检索相关消息的数值 Vector。此设置使用 @mastra/fastembed 生成 Vector 嵌入。

安装 fastembed 以开始使用：

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

将以下内容添加到你的 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.6-sol',
  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,
      },
    },
  }),
})

相关内容

• 元数据过滤器