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

# Couchbase 向量儲存

`CouchbaseVector` 類別使用 [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html) 提供向量搜尋。它可在 Couchbase 集合中進行高效率的相似度搜尋與中繼資料篩選。

## 需求

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

## 安裝

**npm**:

```bash
npm install @mastra/couchbase@latest
```

**pnpm**:

```bash
pnpm add @mastra/couchbase@latest
```

**Yarn**:

```bash
yarn add @mastra/couchbase@latest
```

**Bun**:

```bash
bun add @mastra/couchbase@latest
```

## 使用範例

```typescript
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()`

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

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

**indexName** (`string`): 要建立的索引名稱

**dimension** (`number`): 向量維度（必須與嵌入模型相符）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋使用的距離度量 (Default: `cosine`)

### `upsert()`

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

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

**indexName** (`string`): 要插入資料的索引名稱

**vectors** (`number[][]`): 嵌入向量陣列

**metadata** (`Record<string, any>[]`): 每個向量的中繼資料

**ids** (`string[]`): 選用的向量 ID（未提供時會自動產生）

### `query()`

搜尋相似向量。

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

**indexName** (`string`): 要搜尋的索引名稱

**queryVector** (`number[]`): 用於尋找相似向量的查詢向量

**topK** (`number`): 要傳回的結果數量 (Default: `10`)

**filter** (`Record<string, any>`): 中繼資料篩選條件

**includeVector** (`boolean`): 結果是否包含向量資料 (Default: `false`)

**minScore** (`number`): 最低相似度分數門檻 (Default: `0`)

### `describeIndex()`

傳回索引的相關資訊。

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

傳回：

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

### `deleteIndex()`

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

**indexName** (`string`): 要刪除的索引名稱

### `listIndexes()`

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

傳回：`Promise<string[]>`

### `updateVector()`

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

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要更新的向量項目 ID

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

### `deleteVector()`

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

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要刪除的向量 ID

### `deleteVectors()`

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

**indexName** (`string`): 包含待刪除向量的索引名稱

**ids** (`string[]`): 要刪除的向量 ID 陣列

### `disconnect()`

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

## 回應型別

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

```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: '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 內建的複寫與持久性功能，確保資料耐久性。請定期監控索引統計資料，以確保搜尋效率。

## 限制

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

## 相關內容

- [中繼資料篩選條件](https://mastra.zisheng.pro/zh-TW/reference/rag/metadata-filters)