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

# Chroma 向量儲存

ChromaVector 類別使用開放原始碼的嵌入資料庫 [Chroma](https://docs.trychroma.com/docs/overview/getting-started) 提供向量搜尋。 它提供高效率的向量搜尋、中繼資料篩選與混合搜尋功能。

> **資訊:**
>
> **Chroma Cloud**
>
> Chroma Cloud 支援無伺服器向量搜尋與全文搜尋，具備極高速度、成本效益與大容量，且使用簡便。只需不到 30 秒即可建立資料庫，並使用 5 美元的免費額度試用。
>
> [開始使用 Chroma Cloud](https://trychroma.com/signup)

## 建構函式選項

**host** (`string`): Chroma 伺服器的主機位址。預設為 'localhost'

**port** (`number`): Chroma 伺服器的連接埠號碼。預設為 8000

**ssl** (`boolean`): 連線是否使用 SSL/HTTPS。預設為 false

**apiKey** (`string`): Chroma Cloud API 金鑰

**tenant** (`string`): 要連線的 Chroma 伺服器租戶名稱。單節點 Chroma 預設為 'default\_tenant'。Chroma Cloud 使用者會依提供的 API 金鑰自動解析

**database** (`string`): 要連線的資料庫名稱。單節點 Chroma 預設為 'default\_database'。Chroma Cloud 使用者會依提供的 API 金鑰自動解析

**headers** (`Record<string, any>`): 隨要求一併傳送的其他 HTTP 標頭

**fetchOptions** (`RequestInit`): HTTP 要求的其他 fetch 選項

## 執行 Chroma 伺服器

如果你是 Chroma Cloud 使用者，請將 API 金鑰、租戶和資料庫名稱提供給 `ChromaVector` 建構函式。

安裝 `@mastra/chroma` 套件後，你便可使用 [Chroma CLI](https://docs.trychroma.com/docs/cli/db)，並透過 `chroma db connect [DB-NAME] --env-file` 將這些值設為環境變數。

否則，你可以透過下列方式設定單節點 Chroma 伺服器：

- 使用 Chroma CLI 在本機執行：`chroma run`。更多設定選項請參閱 [Chroma 文件](https://docs.trychroma.com/docs/cli/run)。
- 使用 Chroma 官方映像檔在 [Docker](https://docs.trychroma.com/guides/deploy/docker) 上執行。
- 在你選擇的 Provider 上部署自己的 Chroma 伺服器。Chroma 提供 [AWS](https://docs.trychroma.com/guides/deploy/aws)、[Azure](https://docs.trychroma.com/guides/deploy/azure) 與 [GCP](https://docs.trychroma.com/guides/deploy/gcp) 的範例範本。

## 方法

### `createIndex()`

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

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

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

### `forkIndex()`

注意：只有 Chroma Cloud 或自行部署的開放原始碼**分散式** Chroma 支援分叉。

`forkIndex` 可讓你立即分叉現有的 Chroma 索引。對分叉索引執行的操作不會影響原始索引。詳情請參閱 [Chroma 文件](https://docs.trychroma.com/cloud/collection-forking)。

**indexName** (`string`): 要分叉的索引名稱

**newIndexName** (`string`): 分叉後的索引名稱

### `upsert()`

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

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

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

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

**documents** (`string[]`): Chroma 專用：與向量關聯的原始文字文件

### `query()`

使用 `queryVector` 查詢索引。此方法會依與 `queryVector` 的距離排序，傳回語意相似的記錄陣列。每筆記錄的結構如下：

```typescript
{
  id: string;
  score: number;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

你也可以在呼叫 `query` 時提供中繼資料的結構，以進行型別推斷：`query<T>()`。

**indexName** (`string`): 要查詢的索引名稱

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

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

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

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

**documentFilter** (`Record<string, any>`): Chroma 專用：要套用至文件內容的篩選條件

### `get()`

依 ID、中繼資料和文件篩選條件，從 Chroma 索引取得記錄。此方法會傳回具下列結構的記錄陣列：

```typescript
{
  id: string;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

你也可以在呼叫 `get` 時提供中繼資料的結構，以進行型別推斷：`get<T>()`。

**indexName** (`string`): 要查詢的索引名稱

**ids** (`string[]`): 要傳回的記錄 ID 清單。若未提供，則傳回所有記錄。

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

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

**documentFilter** (`Record<string, any>`): Chroma 專用：要套用至文件內容的篩選條件

**limit** (`number`): 要傳回的記錄數上限 (Default: `100`)

**offset** (`number`): 傳回記錄的位移量。請搭配 limit 使用，以分頁顯示結果。

### `listIndexes()`

以字串陣列傳回索引名稱。

### `describeIndex()`

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

傳回：

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

### `deleteIndex()`

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

### `updateVector()`

依 ID 或中繼資料篩選條件更新單一向量。必須提供 `id` 或 `filter` 其中一項，但不能同時提供兩者。

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

**id** (`string`): 要更新的向量 ID（不可與 filter 同時使用）

**filter** (`Record<string, any>`): 用於識別待更新向量的中繼資料篩選條件（不可與 id 同時使用）

**update** (`object`): 更新參數

`update` 物件可包含：

**vector** (`number[]`): 用來取代現有向量的新向量

**metadata** (`Record<string, any>`): 用來取代現有中繼資料的新中繼資料

範例：

```typescript
// Update by ID
await vectorStore.updateVector({
  indexName: 'docs',
  id: 'vec_123',
  update: { metadata: { status: 'reviewed' } },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
  update: { metadata: { version: 2 } },
})
```

### `deleteVector()`

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

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

### `deleteVectors()`

依 ID 或中繼資料篩選條件刪除多個向量。此方法支援大量刪除與依來源管理向量。必須提供 `ids` 或 `filter` 其中一項，但不能同時提供兩者。

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

**ids** (`string[]`): 要刪除的向量 ID 陣列（不可與 filter 同時使用）

**filter** (`Record<string, any>`): 用於識別待刪除向量的中繼資料篩選條件（不可與 ids 同時使用）

範例：

```typescript
// Delete all chunks from a document
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
})

// Delete multiple vectors by ID
await vectorStore.deleteVectors({
  indexName: 'docs',
  ids: ['vec_1', 'vec_2', 'vec_3'],
})

// Delete old temporary documents
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: {
    $and: [{ bucket: 'temp' }, { indexed_at: { $lt: '2025-01-01' } }],
  },
})
```

## 回應型別

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

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  document?: string // Chroma-specific: Original document if it was stored
  vector?: number[] // Only included if includeVector is true
}
```

## 錯誤處理

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

```typescript
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
  }
}
```

## 相關內容

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