Chroma 是什么
Chroma 以轻量著称：几行代码就能跑起向量检索，支持内存模式与本地持久化（PersistentClient），自带默认 embedding 函数与集合 API，常用于原型验证、教学演示与小型知识库。它的定位是先把链路跑通再谈规模；数据量与并发上来之后，通常需要换成服务化向量库或自建方案。
基本信息
| 运行模式 | 内存模式与本地持久化（PersistentClient） |
|---|---|
| 默认能力 | 内置默认 embedding 函数，也可替换为自定义函数 |
| 距离空间 | 通过集合 metadata 里的 hnsw:space 配置 |
| 适用边界 | 原型与小型知识库，大规模高并发建议换库 |
典型使用场景
- 原型验证：验证检索与问答链路是否走得通，不必先搭集群
- 本地文档助手：个人资料库或团队小语料，单机即可运行
- 教学演示：几行代码展示向量检索原理，环境依赖少
- 离线实验：快速试不同切分与检索参数的效果差异
- 测试替身：单元测试里用内存模式模拟向量库，避免依赖外部服务
持久化客户端与集合
持久化客户端与集合
import chromadb
client = chromadb.PersistentClient(path="./chroma_db") # 本地持久化目录
col = client.get_or_create_collection(
name="kb",
metadata={"hnsw:space": "cosine"}, # 距离空间建库时确定
)
col.add(ids=["c1", "c2"], documents=["第 1 段文本", "第 2 段文本"],
metadatas=[{"source": "faq"}, {"source": "faq"}])
res = col.query(query_texts=["文本检索"], n_results=3)
print(res["ids"], res["distances"]) # 文本查询会走 embedding 函数
常用操作与注意
| 操作 | 方法 | 注意 |
|---|---|---|
| 创建集合 | get_or_create_collection | 距离空间建库时确定，事后改动要重建 |
| 写入 | add 或 upsert | 两者在重复 id 上的语义不同，需确认 |
| 查询 | query 支持文本或向量 | 文本查询依赖所配 embedding 函数 |
| 删除 | 按 id 或条件删除 | 删除后核对集合计数 |
默认 embedding 函数适合快速演示；中文场景建议显式接入自己的 embedding 函数并统一维度，否则换模型时向量全部失效。
持久化目录要纳入备份范围：只备份源文档而不备份向量库，恢复时需要重新解析与向量化，耗时可能远超备份本身的成本，且结果未必可复现。
升级或迁移前先导出校验：把集合计数与若干固定查询的结果存下来，迁移后逐条比对；没有这份对照，很难判断新环境里的检索是否与原来一致。