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

# Chroma 向量儲存

ChromaVector 類別使用開源 embedding 資料庫 [Chroma](https://docs.trychroma.com/docs/overview/getting-started) 提供向量搜尋。 它提供高效的向量搜尋，並支援 metadata 篩選及混合搜尋。

> **資訊:**
>
> **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 header

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

## 執行 Chroma 伺服器

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

安裝 `@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`): 向量維度（必須與你的 embedding 模型相符）

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

### `forkIndex()`

注意：只有 Chroma Cloud，或自行部署的 OSS **分散式** Chroma 支援 fork。

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

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

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

### `upsert()`

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

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

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

**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` 呼叫提供 metadata 的結構，以進行類型推斷：`query<T>()`。

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

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

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

**filter** (`Record<string, any>`): 查詢所用的 metadata 篩選條件

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

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

### `get()`

按 ID、metadata 及文件篩選條件，從 Chroma 索引取得記錄。它會傳回結構如下的記錄陣列：

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

你亦可向 `get` 呼叫提供 metadata 的結構，以進行類型推斷：`get<T>()`。

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

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

**filter** (`Record<string, any>`): Metadata 篩選條件.

**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 或 metadata 篩選條件更新單一向量。必須提供 `id` 或 `filter`，但不可同時提供兩者。

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

**id** (`string`): 要更新的向量 ID（與 filter 互斥）

**filter** (`Record<string, any>`): 用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

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

`update` 物件可包含：

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

**metadata** (`Record<string, any>`): 用於取代現有 metadata 的新 metadata

範例：

```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`): 包含該向量的索引名稱 to delete

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

### `deleteVectors()`

按 ID 或 metadata 篩選條件刪除多個向量。此方法支援批量刪除及按來源管理向量。必須提供 `ids` 或 `filter`，但不可同時提供兩者。

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

**ids** (`string[]`): 要刪除的向量 ID 陣列（與 filter 互斥）

**filter** (`Record<string, any>`): 用於識別要刪除向量的 metadata 篩選條件（與 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
  }
}
```

## 相關內容

- [Metadata 篩選條件](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)