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

# Chroma Vector 存储

ChromaVector 类使用开源 embedding 数据库 [Chroma](https://docs.trychroma.com/docs/overview/getting-started) 提供 Vector 搜索。 它提供高效的 Vector 搜索，并支持元数据过滤和混合搜索。

> **信息:**
>
> **Chroma Cloud**
>
> Chroma Cloud 提供无服务器 Vector 搜索和全文搜索。它速度极快、经济高效、容量大且易于使用。创建一个数据库，即可在 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 key

**tenant** (`string`): 要连接的 Chroma 服务器中的 tenant 名称。单节点 Chroma 默认为 'default\_tenant'。Chroma Cloud 用户会根据提供的 API key 自动解析

**database** (`string`): 要连接的数据库名称。单节点 Chroma 默认为 'default\_database'。Chroma Cloud 用户会根据提供的 API key 自动解析

**headers** (`Record<string, any>`): 随请求发送的额外 HTTP header

**fetchOptions** (`RequestInit`): HTTP 请求的额外 fetch 选项

## 运行 Chroma 服务器

如果你是 Chroma Cloud 用户，请向 `ChromaVector` 构造函数提供 API key、tenant 和数据库名称。

安装 `@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`): Vector 维度（必须与 embedding 模型匹配）

**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[][]`): embedding Vector 数组

**metadata** (`Record<string, any>[]`): 每个 Vector 的元数据

**ids** (`string[]`): 可选的 Vector ID（未提供时自动生成）

**documents** (`string[]`): Chroma 特有：与 Vector 关联的原始文本文档

### `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[]`): 用于查找相似 Vector 的查询 Vector

**topK** (`number`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 查询的元数据过滤条件

**includeVector** (`boolean`): 是否在结果中包含 Vector (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`): 是否在结果中包含 Vector (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 或元数据过滤条件更新单个 Vector。必须提供 `id` 或 `filter`，但不能同时提供二者。

**indexName** (`string`): 包含要更新 Vector 的索引名称

**id** (`string`): 要更新的 Vector ID（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别要更新 Vector 的元数据过滤条件（与 id 互斥）

**update** (`object`): 更新参数

`update` 对象可以包含：

**vector** (`number[]`): 用于替换现有 Vector 的新 Vector

**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`): 包含要删除 Vector 的索引名称

**id** (`string`): 要删除的 Vector ID

### `deleteVectors()`

通过 ID 或元数据过滤条件删除多个 Vector。该方法支持批量删除和基于来源的 Vector 管理。必须提供 `ids` 或 `filter`，但不能同时提供二者。

**indexName** (`string`): 包含要删除 Vector 的索引名称

**ids** (`string[]`): 要删除的 Vector ID 数组（与 filter 互斥）

**filter** (`Record<string, any>`): 用于识别要删除 Vector 的元数据过滤条件（与 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/reference/rag/metadata-filters)