chroma

说明

编写任何代码之前，请先收集以下信息：

1. 部署目标：本地 Chroma 还是 Chroma Cloud？

   • 如果是 Cloud：需要配置 API key、租户和数据库
   • 如果是本地：确定是否需要持久化存储或临时存储

2. 搜索类型（仅限 Cloud）：仅密集搜索，还是混合搜索？

   • 仅密集搜索：设置更简单，适用于大多数语义搜索
   • 混合搜索（密集 + 稀疏）：更适合关键词较多的查询，使用 SPLADE

3. 嵌入模型：使用哪个提供商/模型？

   • 默认：@chroma-core/default-embed（TypeScript）或内置模型（Python）
   • OpenAI：text-embedding-3-large 最受欢迎，需要 @chroma-core/openai
   • 询问用户是否有偏好的模型或现有的提供商

4. 数据结构：他们要为哪些数据建立索引？

   • 用于确定分块策略
   • 用于设计筛选所需的元数据架构

决策工作流

• 用户希望添加搜索功能
• 询问使用本地 Chroma 还是 Chroma Cloud
  • 本地 Chroma
    • 使用 collection.query() 和密集嵌入模型
  • Chroma Cloud
    • 询问是否需要混合搜索
      • 是
        • 使用 Schema() + Search() API 和 SPLADE 稀疏索引
      • 否
        • 使用 collection.query() 和密集嵌入模型
• 询问使用哪种嵌入模型
• 设计元数据架构
• 实现数据同步策略

何时提问，何时继续

先询问：

• 嵌入模型选择（涉及成本和质量）
• 使用 Cloud 还是本地部署
• 使用混合搜索还是仅密集搜索
• 多租户数据隔离策略

采用合理的默认设置继续：

• 使用 getOrCreateCollection() / get_or_create_collection()
• 使用余弦相似度（最常见）
• 分块大小小于 8KB
• 在元数据中存储源 ID，以便更新/删除

验证事项

• Cloud 部署已设置环境变量
• 客户端导入正确（CloudClient 与 Client）
• 已安装嵌入函数包（TypeScript）
• Schema 和 Search API 仅用于 Cloud
• 重要：get_or_create_collection() 接受 embedding_function 或 schema，但不能同时接受两者。需要多个索引（混合搜索）或稀疏嵌入时使用 Schema；仅进行简单的密集搜索时使用 embedding_function。

快速开始

Chroma Cloud 设置（CLI）

要开始使用 Chroma Cloud，请使用 CLI 登录、创建数据库，并将凭据写入 .env 文件：

chroma login
chroma db create <my_database_name>
chroma db connect <my_database_name> --env-file

这会在当前目录中写入一个 .env 文件，其中包含 CHROMA_API_KEY、CHROMA_TENANT 和 CHROMA_DATABASE。下面的代码示例会从这些环境变量中读取值。

TypeScript（Chroma Cloud）：

import { CloudClient } from 'chromadb';
import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';

const client = new CloudClient({
  apiKey: process.env.CHROMA_API_KEY,
  tenant: process.env.CHROMA_TENANT,
  database: process.env.CHROMA_DATABASE,
});

const embeddingFunction = new DefaultEmbeddingFunction();
const collection = await client.getOrCreateCollection({
  name: 'my_collection',
  embeddingFunction,
});

// Add documents
await collection.add({
  ids: ['doc1', 'doc2'],
  documents: ['First document text', 'Second document text'],
});

// Query
const results = await collection.query({
  queryTexts: ['search query'],
  nResults: 5,
});

Python（Chroma Cloud）：

import os
import chromadb

client = chromadb.CloudClient(
    api_key=os.environ["CHROMA_API_KEY"],
    tenant=os.environ["CHROMA_TENANT"],
    database=os.environ["CHROMA_DATABASE"],
)

collection = client.get_or_create_collection(name="my_collection")

# Add documents
collection.add(
    ids=["doc1", "doc2"],
    documents=["First document text", "Second document text"],
)

# Query
results = collection.query(
    query_texts=["search query"],
    n_results=5,
)

了解 Chroma

Chroma 是一个数据库。 Chroma 数据库包含多个集合。 一个集合包含多个文档。

与关系型数据库中的表不同，集合是在应用层创建和销毁的。每个 Chroma 数据库可以包含数百万个集合。可以为每位用户、团队或组织创建一个集合。Chroma 的分区是集合，而不是像表那样按某个键进行分区。

集合没有行，而是包含文档；文档是要搜索的文本数据。创建或更新数据时，客户端会为数据创建嵌入向量。这是在客户端完成的，依据的是提供给客户端的嵌入函数。为了创建嵌入向量，客户端会使用其配置，通过嵌入函数调用指定的嵌入模型提供商。这可以在进程内完成，但绝大多数情况下会通过 HTTP 调用第三方服务。

还可以使用文档元数据进一步分区或筛选数据。每个文档都有一个键值元数据对象。键是字符串，值可以是字符串、整数或布尔值。元数据支持多种运算符。

查询时，查询文本会使用集合定义的嵌入函数转换为嵌入向量，然后连同其余查询参数一起发送给 Chroma。随后，Chroma 会考虑元数据筛选器等查询参数，以缩小潜在结果集的范围，再使用距离算法，根据查询向量与被查询集合中的向量索引，搜索最近邻。

使用 Chroma 客户端的 get_or_create_collection()（TypeScript 中为 getOrCreateCollection()）即可轻松处理集合，避免编写繁琐的样板代码。

本地与云端

Chroma 可以作为本地进程运行，也可以通过 Chroma Cloud 在云端使用。

本地能做的事在云端都能做，但云端能做的事不一定都能在本地完成。

对开发者体验影响最大的区别是 Schema() 和 Search() API，这些 API 仅在 Chroma Cloud 中提供。

除此之外，唯一需要更改的是从 Chroma 包导入的客户端，接口保持不变。

如果你使用云端，可能会想使用 Schema() 和 Search() API。

此外，如果用户想使用云端，请询问他们想采用哪种搜索方式：仅使用稠密嵌入，还是混合搜索。如果选择混合搜索，通常最好使用 SPLADE 作为稀疏嵌入策略。

嵌入

使用嵌入函数时，可以使用默认嵌入函数，但它往往不是最佳选择。建议使用 Chroma Cloud Qwen。TypeScript：npm install @chroma-core/chroma-cloud-qwen；Python 中已包含，但需要运行 pip install httpx。

在 TypeScript 中，每种嵌入函数都需要安装对应的包；请根据用户的说明安装正确的包。

请注意，Chroma 支持在服务端使用 SPLADE 和 Qwen 生成嵌入（TypeScript 中通过 @chroma-core/chroma-cloud-qwen 实现），其他所有嵌入函数都需要在外部使用。

了解更多

如果你需要本技能未涵盖的 Chroma 详细信息，请获取 Chroma 的 llms.txt，以查阅完整文档：https://docs.trychroma.com/llms.txt

可用主题

Typescript

• Chroma 正则筛选 - 了解如何在 Chroma 查询中使用正则筛选器
• 查询与获取 - 查询并获取 Chroma 集合中的数据
• Schema - Schema() 可通过多个索引配置集合
• 元数据数组 - 在元数据字段中存储和查询字符串、数字和布尔值数组
• 更新与删除 - 更新现有文档并从集合中删除数据
• 错误处理 - 使用 Chroma 时处理错误和故障
• 本地 Chroma - 如何运行和使用本地 chroma
• 集合分叉 - 使用 Chroma Cloud 中的写时复制分叉，立即复制集合
• Search() API - 一个表达力强且灵活的 API，可对集合执行稠密和稀疏向量搜索以及混合搜索

Python

• Chroma 正则筛选 - 了解如何在 Chroma 查询中使用正则筛选器
• 查询与获取 - 查询并获取 Chroma 集合中的数据
• Schema - Schema() 可通过多个索引配置集合
• 元数据数组 - 在元数据字段中存储和查询字符串、数字和布尔值数组
• 更新与删除 - 更新现有文档并从集合中删除数据
• 错误处理 - 使用 Chroma 时处理错误和故障
• 本地 Chroma - 如何运行和使用本地 chroma
• 集合分叉 - 使用 Chroma Cloud 中的写时复制分叉，立即复制集合
• Search() API - 一个表达力强且灵活的 API，可对集合执行稠密和稀疏向量搜索以及混合搜索

通用

• Chroma CLI - 开始使用 Chroma CLI 管理云数据库
• 数据模型 - 概述 Chroma 如何存储数据
• 将 Chroma 集成到现有系统中 - 将 Chroma 搜索添加到现有应用程序的指南