> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # Upstash Vector 存储 UpstashVector 类使用 [Upstash Vector](https://upstash.com/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'`): 用于相似度搜索的距离度量 (Default: `cosine`) ### `upsert()` **indexName** (`string`): 要向其中执行 upsert 的索引名称 **vectors** (`number[][]`): 嵌入 Vector 数组 **sparseVectors** (`{ indices: number[], values: number[] }[]`): 用于混合搜索的稀疏 Vector 数组。每个稀疏 Vector 的 indices 和 values 数组必须相互对应。 **metadata** (`Record[]`): 每个 Vector 的元数据 **ids** (`string[]`): 可选的 Vector ID（未提供时自动生成） ### `query()` **indexName** (`string`): 要查询的索引名称 **queryVector** (`number[]`): 用于查找相似 Vector 的查询 Vector **sparseVector** (`{ indices: number[], values: number[] }`): 用于混合搜索的可选稀疏 Vector。其 indices 和 values 数组必须相互对应。 **topK** (`number`): 要返回的结果数量 (Default: `10`) **filter** (`Record`): 查询所用的元数据过滤条件 **includeVector** (`boolean`): 是否在结果中包含 Vector (Default: `false`) **fusionAlgorithm** (`FusionAlgorithm`): 在混合搜索中用于合并稠密与稀疏搜索结果的算法（例如 RRF，即 Reciprocal Rank Fusion） **queryMode** (`QueryMode`): 搜索模式：'DENSE' 表示仅稠密搜索，'SPARSE' 表示仅稀疏搜索，'HYBRID' 表示组合搜索 ### `listIndexes()` 以字符串数组形式返回索引名称（namespace）。 ### `describeIndex()` **indexName** (`string`): 要描述的索引名称 返回： ```typescript 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）结合起来，从而提高相关性与准确性。 ### 混合搜索基本用法 ```typescript 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, }) ``` ### 高级混合搜索选项 ```typescript 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 ```typescript // 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' }, }, }) ``` ## 响应类型 查询结果以以下格式返回： ```typescript interface QueryResult { id: string score: number metadata: Record vector?: number[] // Only included if includeVector is true } ``` ## 错误处理 该存储会抛出可捕获的类型化错误： ```typescript 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**: ```bash npm install @mastra/fastembed@latest ``` **pnpm**: ```bash pnpm add @mastra/fastembed@latest ``` **Yarn**: ```bash yarn add @mastra/fastembed@latest ``` **Bun**: ```bash bun add @mastra/fastembed@latest ``` 将以下内容添加到你的 Agent： ```typescript 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, }, }, }), }) ``` ## 相关内容 - [元数据过滤器](https://mastra.zisheng.pro/reference/rag/metadata-filters)