> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Pinecone Vector 存储

PineconeVector 类提供 [Pinecone](https://www.pinecone.io/) Vector 数据库接口。 它提供实时 Vector 搜索，并支持混合搜索、元数据筛选和命名空间管理等功能。

## 构造函数选项

构造函数接受所有 [Pinecone 配置选项](https://docs.pinecone.io/reference/typescript-sdk)，以及 Mastra 专用字段。

**id** (`string`): 此 Vector 存储实例的唯一标识符

**apiKey** (`string`): Pinecone API 密钥

**controllerHostUrl** (`string`): 自定义 Pinecone 控制器主机 URL

**additionalHeaders** (`Record<string, string>`): 请求中包含的其他 HTTP header

**sourceTag** (`string`): 用于请求跟踪的来源标签

**cloud** (`'aws' | 'gcp' | 'azure'`): 创建新索引时使用的云 Provider (Default: `aws`)

**region** (`string`): 创建新索引时使用的区域 (Default: `us-east-1`)

## 方法

### `createIndex()`

**indexName** (`string`): 要创建的索引名称

**dimension** (`number`): Vector 维度（必须与嵌入模型匹配）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜索使用的距离度量。如果计划使用混合搜索，请使用 'dotproduct'。 (Default: `cosine`)

### `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`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 查询使用的元数据筛选条件

**includeVector** (`boolean`): 结果中是否包含 Vector (Default: `false`)

**namespace** (`string`): 用于查询 Vector 的可选命名空间。仅返回指定命名空间中的结果。

### `listIndexes()`

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

### `describeIndex()`

**indexName** (`string`): 要描述的索引名称

返回：

```typescript
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`): 删除操作使用的可选命名空间

## 响应类型

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

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  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
  }
}
```

### 环境变量

必需的环境变量：

- `PINECONE_API_KEY`：Pinecone API 密钥

## 混合搜索

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

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

## 相关内容

- [元数据筛选器](https://mastra.zisheng.pro/reference/rag/metadata-filters)