Pinecone 向量儲存

PineconeVector class 提供連接 Pinecone 向量資料庫的介面。 它提供即時向量搜尋，並具備混合搜尋、metadata 篩選及 namespace 管理等功能。

Constructor 選項

Constructor 接受所有 Pinecone 設定選項，以及 Mastra 特有的欄位。

id:

string

此向量 store instance 的唯一識別碼

apiKey:

string

Pinecone API 金鑰

controllerHostUrl?:

string

自訂 Pinecone controller host URL

additionalHeaders?:

Record<string, string>

請求中包含的額外 HTTP header

sourceTag?:

string

用於追蹤請求的來源標籤

cloud?:

'aws' | 'gcp' | 'azure'

= aws

建立新 index 時使用的雲端 Provider

region?:

string

= us-east-1

建立新 index 時使用的區域

方法

createIndex()

indexName:

string

要建立的 index 名稱

dimension:

number

向量維度（必須與你的 embedding model 相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜尋的距離度量。如計劃使用混合搜尋，請使用 'dotproduct'。

upsert()

indexName:

string

你的 Pinecone index 名稱

vectors:

number[][]

密集 embedding 向量陣列

sparseVectors?:

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

用於混合搜尋的稀疏向量陣列。每個向量的 indices 與 values 陣列必須互相對應。

metadata?:

Record<string, any>[]

每個向量的 metadata

ids?:

string[]

選填的向量 ID（如未提供則自動產生）

namespace?:

string

用於儲存向量的選填 namespace。不同 namespace 中的向量會互相隔離。

query()

indexName:

string

要查詢的 index 名稱

queryVector:

number[]

用於尋找相似向量的密集查詢向量

sparseVector?:

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

用於混合搜尋的選填稀疏向量。indices 與 values 陣列必須互相對應。

topK?:

number

= 10

要傳回的結果數目

filter?:

Record<string, any>

查詢的 metadata 篩選條件

includeVector?:

boolean

= false

是否在結果中包含向量

namespace?:

string

用於查詢向量的選填 namespace。只傳回指定 namespace 中的結果。

listIndexes()

以字串陣列傳回 index 名稱。

describeIndex()

indexName:

string

要描述的 index 名稱

傳回：

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

deleteIndex()

indexName:

string

要刪除的 index 名稱

updateVector()

按 ID 或 metadata 篩選條件更新單一向量。必須提供 id 或 filter，但不可同時提供兩者。

indexName:

string

包含該向量的 index 名稱

id?:

string

要更新的向量 ID（與 filter 互斥）

filter?:

Record<string, any>

用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

namespace?:

string

更新操作所用的選填 namespace

update:

object

更新參數

update.vector?:

number[]

要更新的新向量值

update.metadata?:

Record<string, any>

要更新的新 metadata

deleteVector()

indexName:

string

包含該向量的 index 名稱

id:

string

要刪除的向量 ID

deleteVectors()

按 ID 或 metadata 篩選條件刪除多個向量。必須提供 ids 或 filter，但不可同時提供兩者。

indexName:

string

包含要刪除向量的 index 名稱

ids?:

string[]

要刪除的向量 ID 陣列（與 filter 互斥）

filter?:

Record<string, any>

用於識別要刪除向量的 metadata 篩選條件（與 ids 互斥）

namespace?:

string

刪除操作所用的選填 namespace

回應類型

查詢結果會以下列格式傳回：

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

錯誤處理

此 store 會拋出可供捕捉的型別化錯誤：

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 透過結合密集向量與稀疏向量支援混合搜尋。使用混合搜尋的方法如下：

1. 使用 metric: 'dotproduct' 建立 index
2. upsert 時，透過 sparseVectors 參數提供稀疏向量
3. 查詢時，透過 sparseVector 參數提供稀疏向量

相關內容

• Metadata 篩選條件