Pinecone Vector 存储

PineconeVector 类提供 Pinecone Vector 数据库接口。 它提供实时 Vector 搜索，并支持混合搜索、元数据筛选和命名空间管理等功能。

构造函数选项

构造函数接受所有 Pinecone 配置选项，以及 Mastra 专用字段。

id:

string

此 Vector 存储实例的唯一标识符

apiKey:

string

Pinecone API 密钥

controllerHostUrl?:

string

自定义 Pinecone 控制器主机 URL

additionalHeaders?:

Record<string, string>

请求中包含的其他 HTTP header

sourceTag?:

string

用于请求跟踪的来源标签

cloud?:

'aws' | 'gcp' | 'azure'

= aws

创建新索引时使用的云 Provider

region?:

string

= us-east-1

创建新索引时使用的区域

方法

createIndex()

indexName:

string

要创建的索引名称

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜索使用的距离度量。如果计划使用混合搜索，请使用 'dotproduct'。

upsert()

indexName:

string

Pinecone 索引的名称

vectors:

number[][]

密集嵌入 Vector 数组

sparseVectors?:

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

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

metadata?:

Record<string, any>[]

每个 Vector 的元数据

ids?:

string[]

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

namespace?:

string

用于存储 Vector 的可选命名空间。不同命名空间中的 Vector 相互隔离。

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

namespace?:

string

用于查询 Vector 的可选命名空间。仅返回指定命名空间中的结果。

listIndexes()

返回由索引名称字符串组成的数组。

describeIndex()

indexName:

string

要描述的索引名称

返回：

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

deleteIndex()

indexName:

string

要删除的索引名称

updateVector()

按 ID 或元数据筛选条件更新单个 Vector。必须提供 id 或 filter，但不能同时提供两者。

indexName:

string

包含待更新 Vector 的索引名称

id?:

string

要更新的 Vector ID（不能与 filter 同时使用）

filter?:

Record<string, any>

用于标识待更新 Vector 的元数据筛选条件（不能与 id 同时使用）

namespace?:

string

更新操作使用的可选命名空间

update:

object

更新参数

update.vector?:

number[]

要更新的新 Vector 值

update.metadata?:

Record<string, any>

要更新的新元数据

deleteVector()

indexName:

string

包含待删除 Vector 的索引名称

id:

string

要删除的 Vector ID

deleteVectors()

按 ID 或元数据筛选条件删除多个 Vector。必须提供 ids 或 filter，但不能同时提供两者。

indexName:

string

包含待删除 Vector 的索引名称

ids?:

string[]

要删除的 Vector ID 数组（不能与 filter 同时使用）

filter?:

Record<string, any>

用于标识待删除 Vector 的元数据筛选条件（不能与 ids 同时使用）

namespace?:

string

删除操作使用的可选命名空间

响应类型

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

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

环境变量

必需的环境变量：

• PINECONE_API_KEY：Pinecone API 密钥

混合搜索

Pinecone 通过组合密集和稀疏 Vector 支持混合搜索。使用混合搜索的方法如下：

1. 使用 metric: 'dotproduct' 创建索引
2. 在 upsert 期间，使用 sparseVectors 参数提供稀疏 Vector
3. 在查询期间，使用 sparseVector 参数提供稀疏 Vector

相关内容

• 元数据筛选器