Chroma Vector 存储

ChromaVector 类使用开源 embedding 数据库 Chroma 提供 Vector 搜索。 它提供高效的 Vector 搜索，并支持元数据过滤和混合搜索。

信息

Chroma Cloud

Chroma Cloud 提供无服务器 Vector 搜索和全文搜索。它速度极快、经济高效、容量大且易于使用。创建一个数据库，即可在 30 秒内使用 5 美元的免费额度开始试用。

开始使用 Chroma Cloud

构造函数选项

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，它可以通过 chroma db connect [DB-NAME] --env-file 为你设置这些环境变量。

否则，你可以通过以下几种方式设置单节点 Chroma 服务器：

• 使用 Chroma CLI 在本地运行：chroma run。更多配置选项请参阅 Chroma 文档。
• 使用官方 Chroma 镜像在 Docker 上运行。
• 在你选择的 Provider 上部署自己的 Chroma 服务器。Chroma 为 AWS、Azure 和 GCP 提供了示例模板。

方法

createIndex()

indexName:

string

要创建的索引名称

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜索的距离度量

forkIndex()

注意：分叉功能仅在 Chroma Cloud 上受支持，或者你自行部署了开源的分布式 Chroma。

forkIndex 可让你立即分叉现有的 Chroma 索引。对分叉索引的操作不会影响原索引。有关更多信息，请参阅 Chroma 文档。

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 语义相似的记录，并按距离排序。每条记录的结构如下：

{
  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

= 10

要返回的结果数量

filter?:

Record<string, any>

查询的元数据过滤条件

includeVector?:

boolean

= false

是否在结果中包含 Vector

documentFilter?:

Record<string, any>

Chroma 特有：应用于文档内容的过滤条件

get()

通过 ID、元数据过滤条件和文档过滤条件，从 Chroma 索引获取记录。它返回一个记录数组，结构如下：

{
  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

= false

是否在结果中包含 Vector

documentFilter?:

Record<string, any>

Chroma 特有：应用于文档内容的过滤条件

limit?:

number

= 100

要返回的最大记录数

offset?:

number

0

返回记录时使用的偏移量。与 limit 配合使用以对结果分页。

listIndexes()

返回由索引名称字符串组成的数组。

describeIndex()

indexName:

string

要描述的索引名称

返回：

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>

用于替换现有元数据的新元数据

示例：

// 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 互斥）

示例：

// 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' } }],
  },
})

响应类型

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

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
}

错误处理

该存储会抛出可捕获的类型化错误：

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

相关内容

• 元数据过滤器