跳至主要內容

Couchbase 向量儲存

CouchbaseVector 類別使用 Couchbase Vector Search 提供向量搜尋。它可在 Couchbase 集合中進行高效率的相似度搜尋與中繼資料篩選。

需求
「需求」的直接連結

  • Couchbase Server 7.6.4 以上版本或相容的 Capella 叢集
  • Couchbase 部署已啟用 Search Service

安裝
「安裝」的直接連結

npm install @mastra/couchbase@latest

使用範例
「使用範例」的直接連結

import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})

建構函式選項
「建構函式選項」的直接連結

id:

string
此向量儲存執行個體的不重複識別碼

connectionString:

string
Couchbase 連線字串

username:

string
Couchbase 使用者名稱

password:

string
Couchbase 密碼

bucketName:

string
要使用的 Couchbase bucket 名稱

scopeName:

string
要使用的 Couchbase scope 名稱

collectionName:

string
要使用的 Couchbase 集合名稱

options?:

CouchbaseClientOptions
選用的 Couchbase 使用者端選項

方法
「方法」的直接連結

createIndex()
「createindex」的直接連結

在 Couchbase 中建立新的向量索引。

備註

索引建立是非同步操作。呼叫 createIndex 後，請先等待一段時間再查詢（小型資料集通常需要 1 到 5 秒，大型資料集則更久）。在正式環境中，請實作輪詢來檢查索引狀態，不要使用固定的延遲時間。

indexName:

string
要建立的索引名稱

dimension:

number
向量維度（必須與嵌入模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
相似度搜尋使用的距離度量

upsert()
「upsert」的直接連結

在集合中新增或更新向量及其中繼資料。

備註

你可以在建立索引前或建立後 upsert 資料。upsert 方法不要求索引必須存在。Couchbase 允許在同一個集合上建立多個 Search 索引。

indexName:

string
要插入資料的索引名稱

vectors:

number[][]
嵌入向量陣列

metadata?:

Record<string, any>[]
每個向量的中繼資料

ids?:

string[]
選用的向量 ID（未提供時會自動產生）

query()
「query」的直接連結

搜尋相似向量。

警告

目前不支援 filter 和 includeVector 參數。你必須在取得結果後於使用者端進行篩選，或直接使用 Couchbase SDK 的 Search 功能。若要取得向量嵌入，請使用 Couchbase SDK 依 ID 擷取完整文件。

indexName:

string
要搜尋的索引名稱

queryVector:

number[]
用於尋找相似向量的查詢向量

topK?:

number
= 10
要傳回的結果數量

filter?:

Record<string, any>
中繼資料篩選條件

includeVector?:

boolean
= false
結果是否包含向量資料

minScore?:

number
= 0
最低相似度分數門檻

describeIndex()
「describeindex」的直接連結

傳回索引的相關資訊。

indexName:

string
要描述的索引名稱

傳回：

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

deleteIndex()
「deleteindex」的直接連結

刪除索引及其中所有資料。

indexName:

string
要刪除的索引名稱

listIndexes()
「listindexes」的直接連結

列出 Couchbase bucket 中的所有向量索引。

傳回：Promise<string[]>

updateVector()
「updatevector」的直接連結

依 ID 使用新的向量資料及／或中繼資料更新指定的向量項目。Couchbase 尚未實作依篩選條件更新。

indexName:

string
包含該向量的索引名稱

id:

string
要更新的向量項目 ID

update:

{ vector?: number[]; metadata?: Record<string, any>; }
包含待更新向量及／或中繼資料的物件

deleteVector()
「deletevector」的直接連結

依 ID 從索引中刪除單一向量。

indexName:

string
包含該向量的索引名稱

id:

string
要刪除的向量 ID

deleteVectors()
「deletevectors」的直接連結

依 ID 刪除多個向量。Couchbase 尚未實作依篩選條件刪除。

indexName:

string
包含待刪除向量的索引名稱

ids:

string[]
要刪除的向量 ID 陣列

disconnect()
「disconnect」的直接連結

關閉 Couchbase 使用者端連線。向量儲存使用完畢後應呼叫此方法。

回應型別
「回應型別」的直接連結

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

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

錯誤處理
「錯誤處理」的直接連結

此儲存會擲回可攔截的具型別錯誤：

try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}

注意事項
「注意事項」的直接連結

  • **刪除索引的注意事項：**刪除 Search 索引不會刪除關聯 Couchbase 集合中的向量／文件。除非明確移除，否則資料會保留。
  • **必要權限：**Couchbase 使用者必須具備連線權限、在目標集合中讀寫文件的權限（kv 角色），以及管理 Search 索引的權限（相關 bucket/scope 的 search_admin 角色）。
  • 索引定義細節與文件結構：createIndex 方法會建立 Search 索引定義，以指定的 scopeName.collectionName 內文件為目標，並為 embedding 欄位（型別為 vector）和 content 欄位（型別為 text）建立索引。每份文件會將向量儲存在 embedding 欄位，並將中繼資料儲存在 metadata 欄位。如果 metadata 包含 text 屬性，其值也會複製到頂層的 content 欄位，供文字搜尋建立索引。
  • **複寫與耐久性：**建議使用 Couchbase 內建的複寫與持久性功能，確保資料耐久性。請定期監控索引統計資料，以確保搜尋效率。

限制
「限制」的直接連結

  • 建立索引的延遲可能會影響建立後立即進行的查詢。
  • 擷取資料時不會強制檢查向量維度（維度不符會在查詢時發生錯誤）。
  • 向量插入與索引更新採最終一致性。寫入後無法保證立即達到強一致性。
On this page