Couchbase 向量儲存

CouchbaseVector 類別使用 Couchbase Vector Search 提供向量搜尋功能，讓你可以在 Couchbase collection 內高效執行相似度搜尋及 metadata 篩選。

系統要求

• Couchbase Server 7.6.4+ 或兼容的 Capella cluster
• Couchbase 部署已啟用 Search Service

安裝

npm

npm install @mastra/couchbase@latest

pnpm

pnpm add @mastra/couchbase@latest

Yarn

yarn add @mastra/couchbase@latest

Bun

bun add @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

此向量儲存 instance 的唯一識別碼

connectionString:

string

Couchbase 連線字串

username:

string

Couchbase 使用者名稱

password:

string

Couchbase 密碼

bucketName:

string

要使用的 Couchbase bucket 名稱

scopeName:

string

要使用的 Couchbase scope 名稱

collectionName:

string

要使用的 Couchbase collection 名稱

options?:

CouchbaseClientOptions

可選的 Couchbase client 選項

方法

createIndex()

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

備註

索引建立程序以非同步方式進行。呼叫 createIndex 後，請先等候一段時間（小型資料集通常需時 1 至 5 秒，大型資料集則需要更長時間）才執行查詢。在正式環境中，應實作輪詢來檢查索引狀態，而非使用固定延遲。

indexName:

string

要建立的索引名稱

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜尋所用的距離度量

upsert()

在 collection 中新增或更新向量及其 metadata。

備註

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

indexName:

string

要插入資料的索引名稱

vectors:

number[][]

embedding 向量陣列

metadata?:

Record<string, any>[]

每個向量的 metadata

ids?:

string[]

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

query()

搜尋相似向量。

注意

目前尚未支援 filter 及 includeVector 參數。擷取結果後，必須在用戶端執行篩選，或直接使用 Couchbase SDK 的 Search 功能。要擷取向量 embedding，請使用 Couchbase SDK 按 ID 取得完整文件。

indexName:

string

要搜尋的索引名稱

queryVector:

number[]

用來尋找相似向量的查詢向量

topK?:

number

= 10

要傳回的結果數目

filter?:

Record<string, any>

Metadata 篩選條件

includeVector?:

boolean

= false

是否在結果中包括向量資料

minScore?:

number

= 0

最低相似度分數門檻

describeIndex()

傳回索引的相關資訊。

indexName:

string

要描述的索引名稱

傳回：

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

deleteIndex()

刪除索引及其所有資料。

indexName:

string

要刪除的索引名稱

listIndexes()

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

傳回：Promise<string[]>

updateVector()

按 ID 使用新的向量資料及／或 metadata 更新指定的向量項目。Couchbase 尚未實作按 filter 更新的功能。

indexName:

string

包含該向量的索引名稱

id:

string

要更新的向量項目 ID

update:

{ vector?: number[]; metadata?: Record<string, any>; }

包含要更新的向量及／或 metadata 的物件

deleteVector()

按 ID 從索引刪除單一向量。

indexName:

string

包含該向量的索引名稱

id:

string

要刪除的向量 ID

deleteVectors()

按 ID 刪除多個向量。Couchbase 尚未實作按 filter 刪除的功能。

indexName:

string

包含要刪除向量的索引名稱

ids:

string[]

要刪除的向量 ID 陣列

disconnect()

關閉 Couchbase client 連線。使用完此 store 後應呼叫此方法。

回應類型

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

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 collection 中的向量／文件。除非明確移除，否則資料會繼續保留。
• 所需權限： Couchbase 使用者必須擁有連線、讀取／寫入目標 collection 中文件（kv 角色），以及管理 Search 索引（相關 bucket／scope 上的 search_admin 角色）的權限。
• 索引定義詳情及文件結構： createIndex 方法會建立 Search 索引定義，為 embedding 欄位（類型為 vector）及 content 欄位（類型為 text）建立索引，並以指定 scopeName.collectionName 內的文件為目標。每份文件會將向量儲存在 embedding 欄位，並將 metadata 儲存在 metadata 欄位。如果 metadata 包含 text 屬性，其值亦會複製至頂層的 content 欄位，以供文字搜尋建立索引。
• 複寫及耐久性： 請考慮使用 Couchbase 內置的複寫及持久化功能來確保資料耐久性。請定期監察索引統計資料，以維持高效搜尋。

限制

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

相關內容

• Metadata 篩選器