create_collection 创建集合

前面已经多次见过 create_collection 的身影，用来在当前连接的租户 + 数据库下新建向量集合。

完整签名如下：

client.create_collection(
    name,                       # 集合名，必填
    schema=None,                # 索引 schema（Cloud 用）
    configuration=None,         # 索引+嵌入函数配置
    metadata=None,              # 集合级元数据
    embedding_function=DefaultEmbeddingFunction(),   # 嵌入函数
    data_loader=None,           # 数据加载器（多模态用）
    get_or_create=False,        # 存在则直接返回而不是报错
)

示例：

import chromadb
from chromadb.api import DefaultEmbeddingFunction

client = chromadb.EphemeralClient()

client.create_collection(
    "name",               # 集合名，必填
    schema=None,                # 索引 schema（Cloud 用）
    configuration=None,         # 索引+嵌入函数配置
    metadata=None,              # 集合级元数据
    embedding_function=DefaultEmbeddingFunction(),   # 嵌入函数
    data_loader=None,           # 数据加载器（多模态用）
    get_or_create=False,        # 存在则直接返回而不是报错
)

print("当前集合列表：", [c.name for c in client.list_collections()])
# 输出：
# 当前集合列表： ['name']

最简形式：

col = client.create_collection("notes")

示例：

import chromadb
client = chromadb.EphemeralClient()

col = client.create_collection("notes")
print("当前集合列表：", [c.name for c in client.list_collections()])
# 输出：
# 当前集合列表： ['notes']

这样建出来的集合用的是默认嵌入函数（all-MiniLM-L6-v2，384 维）。

不要嵌入函数

如果你不想要让 Chroma 帮你计算向量，唯一的办法就是自己传 embeddings。如果不传递 embeddings，Chrome 会使用默认的嵌入函数帮你进行计算，即使创建集合时将 embedding_function 参数设置为 None，如下：

col = client.create_collection("notes", embedding_function=None)

示例：验证将 embedding_function 设置为 None，不传递 embeddings 参数，会使用默认向量进行计算，且不会抛出错误。

import chromadb

client = chromadb.EphemeralClient()
col = client.create_collection("news", embedding_function=None)
col.add(
    ids=["q1"],
    documents=["订单付款后多久发货？一般 48 小时内出库"],
    metadatas=[
        {"category": "物流"}
    ]
)
print("当前集合列表：", [c.name for c in client.list_collections()])
print(col.get(ids=["q1"], include=["metadatas", "documents","embeddings"]))

运行上面脚本，输出日志如下：

当前集合列表： ['news']
{'ids': ['q1'], 'embeddings': array([[ 1.59943867e-02,  8.88116360e-02,  8.09283629e-02,
         4.90221456e-02, -1.46053936e-02,  9.69636440e-02,...
         5.90087473e-02, -4.32127975e-02,  2.83376384e-03]]), 'documents': ['订单付款后多久发货？一般 48 小时内出库'], 'uris': None, 'included': ['metadatas', 'documents', 'embeddings'], 'data': None, 'metadatas': [{'category': '物流'}]}

注意，不使用默认嵌入函数，add 时必须自己传 embeddings，query 时必须自己传query_embeddings。我自己在生产里基本都是这么干的：嵌入模型单独部署成一个服务，Chroma 只当存储，职责清晰，也避免了客户端装一堆 torch 依赖。

指定索引配置

创建集合时，还可以通过 configuration 参数指定索引信息，如 space 距离度量，ef_construction 建立索引是的候选集大小，如下：

import chromadb

client = chromadb.EphemeralClient()
col = client.create_collection(
    name="notes",
    embedding_function=None,
    configuration={
        "hnsw": {
            "space": "cosine",       # 距离度量
            "ef_construction": 200,  # 建索引时的候选集大小
        }
    },
)
print("当前集合列表：", [c.name for c in client.list_collections()])
# 输出结果：
# 当前集合列表： ['notes']

完整的 hnsw 参数在第 9 章介绍。

集合元数据

使用 metadata 参数指定元数据，类型也是一个字典。

注意，元数据不参与过滤，纯粹是给人看的备注。但强烈建议至少记下 embed_model —— 等你三个月后忘了这个库用的是什么模型、多少维，会回来感谢自己。

例如：

import chromadb
from datetime import datetime

client = chromadb.EphemeralClient()
col = client.create_collection(
    name="notes",
    embedding_function=None,
    metadata={
        "description": "产品文档知识库",
        "created_at": datetime.now().isoformat(),
        "owner": "search-team",
        "embed_model": "bge-m3", # 备注嵌入模型
    },
)
print("当前集合列表：", [c.name for c in client.list_collections()])
# 输出结果：
# 当前集合列表： ['notes']

集合已存在会报错

当你使用 create_collection 方法在同一个租户+数据库下创建同名向量集合时，会报 DuplicateCollectionError 错，例如

import chromadb

client = chromadb.EphemeralClient()
try:
    client.create_collection("notes", embedding_function=None)
    client.create_collection("notes", embedding_function=None)
except Exception as e:
    print("集合已经存在，再建一次就是会报错：", type(e).__name__, e)

# 输出结果：
# 集合已经存在，再建一次就是会报错： InternalError Collection [notes] already exists

如果不想处理异常就用 get_or_create_collection 函数，如果集合不存在，则创建。如果集合存在，则直接返回，例如：

import chromadb

client = chromadb.EphemeralClient()
# 取不到就建，取到就返回（最常用）
col = client.get_or_create_collection("notes", embedding_function=None)
print([c.name for c in client.list_collections()])
# 输出结果：
# ['notes']

推荐使用 get_or_create_collection，避免 try-catch 异常处理。