Chroma 集合管理

原文：管理 Collections

一句话

Chroma 使用 collection 作为基本单位来管理 embeddings 集合，支持创建、获取、修改和删除操作。

什么时候翻这页

当你需要管理 Chroma 数据库中的 collections，包括创建新的 collection、获取现有 collection、修改其属性或删除不再需要的 collection 时。

核心概念

Collection: Chroma 中存储和查询 embeddings 的基本单位
Embedding Function: 用于将文档转换为 embeddings 的函数，Chroma 默认使用 sentence transformer
Metadata: 可选的键值对映射，用于存储 collection 的附加信息

怎么做

创建 Collections

Collection 名称必须满足以下要求：

长度在 3 到 512 个字符之间
必须以小写字母或数字开头和结尾，中间可以包含点、连字符和下划线
不能包含两个连续的点
不能是有效的 IP 地址

# Python
collection = client.create_collection(name="my_collection")

// TypeScript
const collection = await client.createCollection({
  name: "my_collection",
});

// Rust
let collection = client
    .create_collection("my_collection", None, None)
    .await?;

使用 Embedding Functions

当向 collection 添加文档时，Chroma 会使用 collection 的 embedding function 将它们转换为 embeddings。默认使用 sentence transformer embedding function。

# Python - 使用 OpenAI embedding function
import os
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

collection = client.create_collection(
    name="my_collection",
    embedding_function=OpenAIEmbeddingFunction(
        api_key=os.getenv("OPENAI_API_KEY"),
        model_name="text-embedding-3-small"
    )
)

设置 Collection Metadata

创建 collection 时，可以传递可选的 metadata 参数来添加键值对映射：

# Python
from datetime import datetime

collection = client.create_collection(
    name="my_collection",
    embedding_function=emb_fn,
    metadata={
        "description": "my first Chroma collection",
        "created": str(datetime.now())
    }
)

获取 Collections

# Python
collection = client.get_collection(name="my-collection")
collection = client.get_or_create_collection(
    name="my-collection",
    metadata={"description": "..."}
)
collections = client.list_collections()
first_collections_batch = client.list_collections(limit=100)

修改 Collections

# Python
collection.modify(
   name="new-name",
   metadata={"description": "new description"}
)

删除 Collections

# Python
client.delete_collection(name="my-collection")

便捷方法

# Python
collection.count()  # 返回 collection 中的记录数
collection.peek()  # 返回 collection 中的前 10 条记录

命令 / API 速查

方法	描述	示例
`create_collection`	创建新的 collection	`client.create_collection(name="my_collection")`
`get_collection`	获取已存在的 collection	`client.get_collection(name="my-collection")`
`get_or_create_collection`	获取 collection，如果不存在则创建	`client.get_or_create_collection(name="my-collection")`
`list_collections`	列出所有 collections	`client.list_collections(limit=100, offset=0)`
`modify`	修改 collection 的名称和元数据	`collection.modify(name="new-name", metadata={...})`
`delete_collection`	删除 collection	`client.delete_collection(name="my-collection")`
`count`	获取 collection 中的记录数	`collection.count()`
`peek`	查看 collection 中的前几条记录	`collection.peek()`

与 Hello-Agents / LangGraph / 本博客 handbook 索引的联系

在 Hello-Agents 的记忆与检索章节中，我们学习了如何使用 Chroma 作为 vector store 来存储和检索 embeddings。本页内容扩展了这一概念，详细介绍了如何管理 Chroma collections，包括创建、获取、修改和删除操作。这些操作是构建 RAG 系统的基础，特别是在使用 LangGraph 构建复杂工作流时，可能需要动态管理多个 collections 来存储不同类型的知识或对话历史。本博客 handbook 中已使用 Chroma 索引相关内容，这些集合管理操作可以帮助你更好地组织和维护你的向量数据库。

初学者易错点

Collection 名称必须在 Chroma 数据库中唯一，尝试创建同名 collection 会引发异常
删除 collection 是不可逆操作，会同时删除所有 embeddings、文档和元数据
使用旧版本 Chroma 客户端或服务器时，获取 collection 可能需要提供相同的 embedding function
Collection 名称有严格的格式要求，不符合要求的名称会导致创建失败
直接提供 embeddings 而不设置 embedding function 时，需要在添加数据和查询时直接提供 embeddings

语义检索