Couchbase Vector 存储

CouchbaseVector 类使用 Couchbase Vector Search 提供 Vector 搜索。它可以在 Couchbase collection 中执行高效的相似度搜索和元数据过滤。

要求

• 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

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

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 中创建新的 Vector 索引。

备注

索引创建是异步的。调用 createIndex 后，请等待一段时间再查询（小型数据集通常需要 1 到 5 秒，大型数据集需要更长时间）。在生产环境中，应通过轮询检查索引状态，而不是使用固定延迟。

indexName:

string

要创建的索引名称

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜索的距离度量

upsert()

在 collection 中添加或更新 Vector 及其元数据。

备注

你可以在创建索引之前或之后执行数据 upsert。upsert 方法不要求索引已经存在。Couchbase 允许对同一个 collection 创建多个 Search 索引。

indexName:

string

要插入数据的索引名称

vectors:

number[][]

embedding Vector 数组

metadata?:

Record<string, any>[]

每个 Vector 的元数据

ids?:

string[]

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

query()

搜索相似 Vector。

注意

目前不支持 filter 和 includeVector 参数。必须在检索结果后进行客户端过滤，或者直接使用 Couchbase SDK 的 Search 功能。要检索 Vector embedding，请使用 Couchbase SDK 按 ID 获取完整文档。

indexName:

string

要在其中搜索的索引名称

queryVector:

number[]

用于查找相似 Vector 的查询 Vector

topK?:

number

= 10

要返回的结果数量

filter?:

Record<string, any>

元数据过滤条件

includeVector?:

boolean

= false

是否在结果中包含 Vector 数据

minScore?:

number

= 0

最低相似度分数阈值

describeIndex()

返回索引相关信息。

indexName:

string

要描述的索引名称

返回：

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

deleteIndex()

删除索引及其所有数据。

indexName:

string

要删除的索引名称

listIndexes()

列出 Couchbase bucket 中的所有 Vector 索引。

返回：Promise<string[]>

updateVector()

根据 ID 使用新的 Vector 数据和/或元数据更新特定 Vector 条目。Couchbase 尚未实现基于过滤条件的更新。

indexName:

string

包含该 Vector 的索引名称

id:

string

要更新的 Vector 条目 ID

update:

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

包含要更新的 Vector 和/或元数据的对象

deleteVector()

根据 ID 从索引中删除单个 Vector。

indexName:

string

包含该 Vector 的索引名称

id:

string

要删除的 Vector ID

deleteVectors()

根据 ID 删除多个 Vector。Couchbase 尚未实现基于过滤条件的删除。

indexName:

string

包含要删除 Vector 的索引名称

ids:

string[]

要删除的 Vector ID 数组

disconnect()

关闭 Couchbase client 连接。使用完该存储后应调用此方法。

响应类型

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

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 中的 Vector/文档。除非明确删除，否则数据仍会保留。
• 所需权限： Couchbase 用户必须具有连接权限、对目标 collection 中的文档进行读写的权限（kv role），以及管理 Search 索引的权限（相关 bucket/scope 上的 search_admin role）。
• 索引定义详情和文档结构： createIndex 方法会构建一个 Search 索引定义，以索引 embedding 字段（类型为 vector）和 content 字段（类型为 text），目标是指定 scopeName.collectionName 中的文档。每个文档都将 Vector 存储在 embedding 字段中，并将元数据存储在 metadata 字段中。如果 metadata 包含 text 属性，其值还会复制到顶层 content 字段，并为文本搜索建立索引。
• 复制和持久性： 考虑使用 Couchbase 内置的复制和持久化功能来确保持久存储数据。定期监控索引统计信息，以确保搜索高效运行。

限制

• 索引创建延迟可能会影响创建后立即执行的查询。
• 写入时不会强制检查 Vector 维度（维度不匹配会在查询时引发错误）。
• Vector 插入和索引更新采用最终一致性。写入后不会立即保证强一致性。

相关内容

• 元数据过滤器