Chroma 向量数据库手册

适用版本：chromadb 1.5.9（PyPI / GitHub 稳定 tag 1.5.9，Build 2026-05-05，核实于 2026-11） 许可与形态：Apache 2.0（本地 / 自托管）、Chroma Cloud 为商业 serverless；进程内嵌入式 / 单机 client-server 服务 / 全托管 Cloud 三种形态并存 一句话定位：以「集合 + embedding + metadata」为核心、原型上手极快的向量库，但本地与 Cloud 是两套客户端语义，不能照搬同一份代码 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Chroma 把「向量 + 文档 + 元数据」打包成集合（collection），以 Python / JS 客户端为主，屏蔽底层索引细节。进程与存储分层按形态拆成三类，这是读后续所有章节的前提：

底层经 Rust 重写（官方资料记为 foundation/、sharded collection rebuild），单节点用 HNSW。但最需记住的是客户端语义不统一：

版本差异：CloudClient 与 PersistentClient / HttpClient 语义不同；新 Search API（Search / Knn / Rrf / group_by / rank）仅 Chroma Cloud 提供，本地与自托管仍以 .query() / .get() 为主。把 Cloud 示例套到本地客户端会报方法不存在。

1.2 与同类产品的本质差别

服务端可有可无（嵌入式为主，区别于「先起服务再连」的 Milvus / Qdrant / Weaviate）；配置入口是 configuration={"hnsw": {...}}；过滤用 where / where_document dict 而非 SQL 字符串；云地不完全一致（新 Search API 仅 Cloud，跨形态迁移要改代码）。

1.3 适合 / 不适合

适合：① RAG 原型 / PoC / 离线脚本（pip install 后无需起服务即可落地）；② 文档问答类数据（documents+metadatas 与 embedding 同存，过滤开箱即用）；③ 中小规模、单进程或少量客户端共享；④ 已用 LangChain / LlamaIndex、求最小接入成本；⑤ 想免运维且能用 Cloud 新 Search API。

不适合：① 需明确分布式 / 多副本 / 水平分片承诺的核心在线服务；② 需云地一套查询代码且强依赖 Search / Rrf / rank 的场景；③ 超大规模、高 QPS、需细粒度资源隔离的强 SLA 场景；④ 需成熟 Prometheus 指标 / 官方 Helm chart 直接交付 K8s（见第 11 章未核实项）。

1.4 规模参考（经验值，非官方承诺）

单集合十万 ～ 百万级向量可胜任原型与中小规模（受内存、维度、HNSW 参数影响，须压测）；维度常见 768 / 1024 / 1536（示例用 3 维）；QPS 视内存、n_results、过滤复杂度而定，官方未给承诺数值，以实测为准。

1.5 在链路中的位置

文档切片 → Embedding 模型 → [Chroma: embeddings+documents+metadatas] → query(query_embeddings, where=...) → Top-K → 重排（可选）→ LLM 生成。推荐 / 以图搜图同理，把图片 embedding 与业务标签写入 metadatas，用 where 做品类、时间过滤。

2. 版本、许可与官方入口

2.1 版本状态表

版本差异：版本号分「PyPI 客户端 / GitHub 服务端 tag / Cloud」多条线，不可混用。写部署脚本固定 pip 版本，勿拿 GitHub tag 当 pip 版本。

2.2 许可证与商业版边界

2.3 官方 URL 表

2.4 版本识别命令

$ python3 -m pip show chromadb
$ python3 -c "import chromadb; print(chromadb.__version__)"

2.5 近两年重要变更与弃用提醒

1. 配置语法迁移：HNSW 参数由 metadata={"hnsw:space": ...} 迁到 configuration={"hnsw": {"space": ...}}（见第 5、9 章）。
2. Rust 重写：foundation/ 与 sharded collection rebuild 改变底层，旧数据须走导出 / 迁移，勿直接拷目录跨大版本。
3. API 分层：新 Search API（Search / Knn / Rrf / group_by / rank）仅 Cloud；本地 .query() 仍是主路径。
4. 客户端分化：CloudClient 与 PersistentClient / HttpClient 语义不同，选型先定形态。

3. 安装与启动

3.1 依赖与前置条件

Python >=3.9；嵌入式无需数据库 / Docker；client-server 需能监听端口的进程或容器运行时；持久化目录须可写并预留向量与 HNSW 图空间。

3.2 方式一：pip（嵌入式 / 客户端，推荐起步）

$ python3 -m pip install chromadb             # 完整客户端，含本地持久化
$ python3 -m pip install chromadb-client      # client-server 瘦 HTTP 客户端

chromadb 自带本地持久化，chromadb-client 是连服务端的瘦客户端，勿混装后误判行为。

3.3 方式二：CLI 服务端 + Docker 服务端

# 单机 CLI 服务端（client-server 形态）
$ chroma run --path /chroma_db_path
# 或 Docker 服务端，默认端口 8000
$ docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma

import chromadb
client = chromadb.HttpClient(host="localhost", port=8000)

版本差异：官方 Helm chart、管理界面均未核实；K8s 交付前以官方文档复核，勿假定存在现成 chart 或管理面板。

3.4 目录与端口表

3.5 启动后健康检查与连通性验证

$ curl -s http://localhost:8000/api/v2/heartbeat

import chromadb
client = chromadb.HttpClient(host="localhost", port=8000)
print(client.heartbeat())

避坑：只允许用已确认的 client.heartbeat() / /api/v2/heartbeat 做连通性检查；管理界面与 Prometheus 监控端点官方未明确（见第 11 章），勿照抄第三方 /metrics 路径。

3.6 生产最小配置建议

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级

Client（PersistentClient / HttpClient / CloudClient）→ Collection（name + configuration）→ Record: id + embedding + document + metadata。记录四元组 ids / embeddings / documents / metadatas 按位置一一对应，长度必须一致。

4.3 字段与向量类型

4.4 距离度量与方向

configuration={"hnsw": {"space": "cosine"}} 为余弦距离，值越小越相似。

未核实：hnsw.space 的完整取值列表未在官方确认，正文只写出现过的 cosine；执行前以官方配置文档为准。

4.5 索引类型与关键参数

4.6 写入 → 建索引 → 可检索的生命周期

1. create_collection(..., configuration=...) 确定索引与度量；2. add(...) 写入后向量即可检索，无需显式 load / build（与需 load_collection 的产品不同）；3. query / get 立即生效；4. 嵌入式与单节点为本地一致性，Cloud / 分布式一致性承诺官方资料未给出，以官方文档为准。

5. 快速上手：完整 CRUD 示例

以本地嵌入式 PersistentClient 为主，基于官方 Quickstart 当前写法；import 齐全、变量均有定义、可整体复制运行。示例用 3 维向量（实际常见 768 / 1024 / 1536）。

import chromadb

# 1) 连接：本地持久化客户端，path 即数据目录
client = chromadb.PersistentClient(path="./chroma-data")

# 2) 创建集合：新配置语法 configuration，显式指定 hnsw.space
col = client.create_collection(
    name="my_collection",
    configuration={"hnsw": {"space": "cosine"}},
)

# 示例用 3 维；实际常见 768 / 1024 / 1536 维
embeddings = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]

# 3) 插入：四个列表按位置一一对应，长度必须一致
col.add(
    ids=["id1", "id2", "id3"],
    documents=["第一章 向量检索导论", "第二章 索引结构", "第三章 生产运维"],
    metadatas=[{"chapter": 1, "page": 3}, {"chapter": 2, "page": 18}, {"chapter": 3, "page": 42}],
    embeddings=embeddings,
)
query_vec = [1.0, 0.0, 0.0]

# 4) 相似度检索
print("== 纯向量检索 ==")
print(col.query(query_embeddings=[query_vec], n_results=2))

# 5) 带标量过滤检索：where 走 metadata，where_document 走全文
print("== 带过滤检索 ==")
print(col.query(
    query_embeddings=[query_vec], n_results=2,
    where={"page": {"$gt": 10}}, where_document={"$contains": "索引"},
))

# 6) 更新：按 id 改 metadata（也可改 documents / embeddings）
col.update(ids=["id1"], metadatas=[{"chapter": 1, "page": 5}])
# 7) 删除：按 id 删除记录
col.delete(ids=["id3"])
# 8) 读回校验：get 不做向量检索
print("== 读回校验 ==")
print(col.get(ids=["id1", "id2"]))
# 9) 清理：删除整个集合
client.delete_collection(name="my_collection")

旧教程会写成什么：① create_collection(name=..., metadata={"hnsw:space": "cosine"})——已过时，当前写法是 configuration={"hnsw": {"space": "cosine"}}；② 旧文常省略配置导致度量走默认、与业务预期不符；③ 云端的 Search / Knn / Rrf / group_by / rank 在本地 PersistentClient 上并不存在，照抄会 AttributeError。

补充说明：create_collection / add / query / get 的签名以官方 Quickstart 为准；update / delete / delete_collection update / delete 等方法请以官方 API 参考为准，参数细节以官方文档为准。

输出怎么读：query / get 返回按 key 组织的 dict。

第 4 步 n_results=2 表示每个查询向量返回 2 条；第 5 步叠加 where={"page":{"$gt":10}} 后再叠加 where_document，结果可能少于 2 条——这是过滤收敛，不是召回故障。

REST / cURL 等价示例（client-server 形态）：官方资料仅确认心跳与 v2 前缀，集合级 REST 路径官方未明确，故只给确认可用的连通性检查。

$ chroma run --path /chroma_db_path
$ curl -s http://localhost:8000/api/v2/heartbeat
# 集合级 REST 操作（/api/v2/... 具体路径与参数以官方文档为准，不臆造）

6. 索引与检索进阶

6.1 索引参数调优表

除 cosine 外的 hnsw.space 取值、HNSW 构建参数在官方资料官方未明确，本表不列默认值；以官方配置文档为准。

6.2 召回率 recall 与延迟的取舍

近似 HNSW 以少量召回损失换低延迟；提高探索强度通常提升 recall、增加延迟。经验做法：用标注查询集对比 query 与全量精确（flat）结果的交集测 recall；先固定 n_results、再调过滤、最后才动索引参数，参数调整须 A/B 压测，官方未给承诺曲线。

6.3 标量过滤的 pre / post-filter 行为

官方资料未明确 where 的 pre/post-filter 实现。经验性表述：过滤越严格候选越少、结果可能少于 n_results；若「过滤后召回明显偏低」，先用 get(where=...) 核对满足条件的基数，再判断是数据问题还是检索行为，勿假定索引损坏。

6.4 混合检索、多向量 / 稀疏向量 / 重排

官方资料确认 Cloud 新 Search API 含 Rrf（倒数排名融合）、rank、group_by，即混合 / 重排能力集中 Cloud；本地 .query() 不提供。本地如需「BM25 + 稠密」通常在上层框架两路召回再融合（经验做法）；多向量 / 稀疏向量字段支持、量化与压缩开关官方资料均未给出，本篇不列具体参数，以官方文档为准。

6.5 内存与磁盘容量估算（经验公式）

公式：向量大小 ≈ N × D × 4B（float32）；总内存 ≈ 向量大小 + HNSW 图开销 + 文本 + 运行时缓冲。

示例：N=100 万、D=768 → 向量约 1e6 × 768 × 4B ≈ 2.86 GiB；叠加图与文本后按 2～4 倍预留内存并以实测为准。此为经验估算，非官方承诺。

7. 生产部署与运维

7.1 形态选择决定运维模型（重点）

版本差异：再强调——CloudClient 与 PersistentClient / HttpClient 语义不同，新 Search API 仅 Cloud。排障先确认「连的是哪种客户端」，很多「方法不存在 / 参数不对」根因是形态错配而非版本 bug。

7.2 高可用 / 集群 / 分片 / 副本

嵌入式与单节点不提供分布式副本承诺；核心在线服务若需多副本应评估分布式产品或 Cloud。底层 Rust 重写涉及 sharded collection rebuild（内部有分片概念），但对外 HA / 副本配置方式官方资料未给出，以官方文档为准。

7.3 备份与恢复（含索引是否需重建）

⚠️ 危险：跨大版本（尤其 Rust 重写前后）勿直接拷数据目录当升级手段——官方资料提示 sharded collection rebuild，旧格式须走导出 / 迁移，直接覆盖可能导致集合不可读。

7.4 监控端点与关键指标、告警阈值建议

建议自建监控：进程存活（心跳失败告警）、数据目录磁盘使用率（>80% 预警）、查询 P99 延迟、写入错误率；阈值为经验建议，按自身 SLA 调整。

7.5 容量规划与扩缩容

按 6.5 公式估算内存；嵌入式扩缩容 = 扩应用进程 / 换更大机型。单节点瓶颈优先「减维度、减 n_results、加过滤收敛」，再考虑迁移形态。

7.6 升级与跨版本迁移

① 锁定当前版本（pip show chromadb）；② 用 get / 导出接口把集合导出为 id/embedding/document/metadata；③ 升级客户端，用新 configuration 语法重建集合再导入；④ 校验条数与抽样检索一致后切流。

7.7 安全基线

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：度量不符预期。原因：用了旧 metadata={"hnsw:space":...}。怎么做：一律改 configuration={"hnsw":{"space":"cosine"}}，旧写法只留在对照里。
2. 现象：本地跑 Cloud 教程报 AttributeError。原因：Search / Knn / Rrf / group_by / rank 仅 Cloud。怎么做：本地用 .query() / .get()；需要 RRF 评估 Cloud 或上层自实现。
3. 现象：CloudClient 与 PersistentClient 对不上。原因：语义不同。怎么做：先定形态再写代码，连接对象不跨形态复用。
4. 现象：升级后集合打不开。原因：Rust 重写 / sharded rebuild 前后格式变化、直接拷目录。怎么做：导出再导入，走迁移路径。
5. 现象：add 抛长度错误。原因：四列表数量不等。怎么做：写入前 assert len(...) 校验一致。
6. 现象：过滤后少于 n_results。原因：where 与 where_document 叠加收敛。怎么做：get(where=...) 核对基数，属正常行为。
7. 现象：chromadb-client 下本地持久化不可用。原因：瘦 HTTP 客户端不含嵌入式持久化。怎么做：本地用 chromadb，client-server 才用 chromadb-client。
8. 现象：照第三方配 /metrics 或管理面板 404。原因：监控端点 / 管理界面官方未明确。怎么做：只用确认的 heartbeat 探活，其余以官方文档为准。
9. 现象：K8s 找不到官方 chart。原因：官方 Helm chart 未核实。怎么做：以官方文档确认交付方式，不臆造仓库地址。
10. 现象：写 hnsw.space 其它取值后行为异常。原因：space 全量取值未核实。怎么做：只用确认过的 cosine，其它先查官方配置文档。
11. 现象：选型文档写「支持 SPANN」。原因：SPANN 逐字条目未核实。怎么做：请勿当作确定事实，以官方文档为准。
12. 现象：8000 端口被扫到、数据暴露。原因：服务端直接暴露公网且未加认证。怎么做：仅内网监听 + TLS 反向代理 + 密钥管理。

⚠️ 危险：删除集合（delete_collection）与跨版本直接覆盖持久化目录都不可逆。执行前必须确认已备份、且连接的是测试/目标环境而非生产库。

⚠️ 危险：把 .dev 构建或未经锁定的最新版推生产，可能因 Rust 重写期数据结构变化导致集合不兼容；生产一律固定明确版本。

10. 速查表

10.1 命令 / API 速查

10.2 常用端口与路径

11. 参考与延伸

11.1 官方文档链接清单

11.2 与同册其他产品的关系

需分布式 / 多副本见 ../01-专用向量数据库/ 下 Milvus、Qdrant、Weaviate 分册；已有 PostgreSQL 见 ../02-融合型向量能力/pgvector.md（若已存在）；嵌入式、无服务端、直读对象存储的另一选择见同目录 LanceDB.md；schema-first + YQL + 滚动发布的重型引擎见同目录 Vespa.md。

11.3 进阶阅读方向

① 官方「Collections / Configure」的 configuration 全量字段与 hnsw.space 取值；② 官方 Cloud 文档 Search / Knn / Rrf / group_by / rank 新 API；③ llms.txt 按主题定位最新页（优先官方而非缓存教程）；④ 混合检索与 RRF 的 Cloud 侧能力与上层自实现取舍。

11.4 本篇「未核实 / 以官方为准」事项（官方资料明确标注）

以下条目官方资料标为「未核实」，正文未写作确定事实，执行前必须以官方文档复核：

1. hnsw.space 的全量取值列表（正文仅以确认过的 "cosine" 举例，未枚举其它值）。
2. SPANN 索引的逐字条目 / 是否支持——官方未明确，不得写成确定结论。
3. 官方 Helm chart 是否存在及仓库地址——官方未明确，K8s 交付方式以官方文档为准。
4. 监控端点 / 管理界面（Prometheus /metrics 一类）——官方未明确，探活仅用已确认的 heartbeat() 与 /api/v2/heartbeat。

补充：CloudClient 与 PersistentClient / HttpClient 语义不同、新 Search API 仅 Cloud、Rust 重写与 sharded collection rebuild 属已核实变更；但 Cloud 具体参数、内部 HA / 一致性承诺等细节仍以官方文档为准。