做 RAG 原型时,选向量库常常比选大模型还费劲:Milvus 要拉一堆容器,Qdrant 要先跑服务端,pgvector 得有现成的 PostgreSQL。Chroma 的思路是把这一切全部砍掉——pip install chromadb,几行代码就能存向量、做语义检索,让开发者把时间花在分块策略和提示词上。它是 LangChain、LlamaIndex 教程里出镜率最高的向量库之一,也是"先跑通再优化"路线的代表。本文按"定位 → 持久化 → 数据模型 → 查询 → 嵌入 → 服务器模式 → 适用边界 → 迷你 RAG 实战"的顺序展开,所有代码都可以在本地直接跑通。
1、定位:为原型而生
Chroma 是一个 Apache 2.0 协议的开源向量数据库,GitHub 仓库位于 chroma-core 组织下。它的核心卖点是为原型而生的零负担起步:不需要 Docker,不需要独立服务端,不需要任何 API Key,装完即用。概括成三句话:
- pip 装完即用:没有外部数据库、没有服务端、没有 Key
- 四个核心动词:建集合、add、query、get 覆盖九成操作
- 自带嵌入函数:文本进、相似块出,全程本地计算
活跃度方面,截至 2026 年 11 月,PyPI 的 chromadb 包最新版本为 1.5.9(2026 年 5 月构建),官方更新日志显示 2026 年持续有功能发布——2 月索引吞吐量提升约 70%,3 月加入元数据数组与 S3、GitHub 同步,迭代节奏稳定。
安装只要一条命令:
pip install chromadb
python -c "import chromadb; print(chromadb.__version__)"
首次安装会带上 ONNX 运行时等依赖,体积不小但都是纯本地组件。版本检查输出如下即环境就绪:
1.5.9
解读:版本号能正常打印,说明依赖完整可用。Chroma 同时提供 JavaScript 客户端(npm install chromadb),与 Python 端 API 风格基本一致,本文以 Python 为主线。
2、持久化:PersistentClient
Chroma 有三种客户端形态:Client() 纯内存、进程退出即失;PersistentClient 落地本地目录;HttpClient 连接远程服务。做原型九成场景用 PersistentClient——数据自动写进指定目录,重启不丢。示例如下:
import chromadb
client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_or_create_collection("notes")
collection.add(
documents=["Chroma 用 SQLite 存元数据"],
ids=["note-1"],
)
print(collection.count()) # 退出进程再执行,输出仍是 1
解读:path 指向的目录由 Chroma 自动创建,里面是一个 SQLite 文件(元数据与文档原文)加 HNSW 索引文件(向量)。get_or_create_collection 是幂等写法,首次创建、之后复用,比 create_collection 更适合脚本反复执行的场景。整库备份就是拷贝这个目录,没有额外的运维概念。
还有一个形态选择相关的实际问题:同一进程内多次创建指向同一目录的 PersistentClient 是安全的,Chroma 会复用底层连接;但两个独立进程同时写一个目录就可能撞上 SQLite 文件锁。单进程脚本随意用,多进程场景直接看第 6 节的服务器模式。
3、数据模型:collection 与 add
Chroma 的数据模型只有两层:collection(类似表)和记录(类似行)。一条记录由四个字段构成,通过 collection.add 一次写入。各参数说明如下:
| 参数 | 必填 | 说明 |
|---|---|---|
ids |
是 | 记录唯一标识,重复 id 会被跳过 |
documents |
否 | 原文,用于展示与自动嵌入 |
metadatas |
否 | 结构化属性,供 where 过滤 |
embeddings |
否 | 自算向量,不传则自动嵌入 |
写入示例如下:
collection.add(
ids=["doc-1", "doc-2"],
documents=["持久化目录由 path 参数指定",
"查询支持元数据精确过滤"],
metadatas=[{"source": "handbook", "page": 1},
{"source": "faq", "page": 3}],
)
解读:documents 与 metadatas 是按位置一一对应的列表。同 id 再次 add 不报错也不覆盖,而是静默跳过;要覆盖旧记录需改用 collection.upsert。配套方法还有按 id 取原文的 get、update 与 delete——增删改查各一个方法,没有更多概念,这是它上手极快的原因。
4、查询:query 与元数据过滤
检索用 collection.query,最常用的形态是文本进、相似块出:
res = collection.query(
query_texts=["怎么配置持久化"],
n_results=3,
where={"source": "handbook"}, # 元数据精确匹配
)
for doc, dist in zip(res["documents"][0], res["distances"][0]):
print(round(dist, 3), doc)
解读:query_texts 中的查询文本会被自动嵌入成向量再比对,因此不需要自己算嵌入。返回值是字典,每个键的值按"查询条目"分组嵌套——只传一条查询时取 [0]。distances 是距离,数值越小越相似,具体含义随第 5 节的距离度量变化。
结果里除了 documents 与 distances,默认还带 ids 与 metadatas;想省流量可用 include=["documents"] 只取需要的字段。另一个细节是 n_results 不能超过集合现有记录数,超了会直接报错,检索前先 count() 做个防御是便宜的好习惯。
where 支持比较与组合操作符,例如 {"$and": [{"page": {"$gt": 2}}, {"source": "faq"}]};where_document={"$contains": "持久化"} 则做原文包含匹配。若只是按 id 或条件取回数据、不需要相似度,用 collection.get(ids=["doc-1"]) 即可,返回结构与 query 同构。
5、内置嵌入与距离度量
前面所有代码都没出现"嵌入模型"四个字,却都能做语义检索——因为 Chroma 默认自带嵌入函数:不传 embeddings 时自动调用本地运行的 all-MiniLM-L6-v2(384 维小模型,首次使用时自动下载权重),全程不依赖外部 API。
这份便利有两个代价。其一,默认模型以英文语料为主,中文语义检索效果一般;其二,向量与嵌入模型是一对一锁定的——集合里的向量由哪个模型生成,查询就必须一直用哪个模型,中途换模型等于换了向量空间,旧数据必须全部重新嵌入。所以中文语料建议在建集合那一刻就换中文模型,并显式声明度量:
from chromadb.utils import embedding_functions
ef = embedding_functions.SentenceTransformerEmbeddingFunction(
model_name="BAAI/bge-small-zh-v1.5", # 中文小模型,本地运行
)
col = client.get_or_create_collection(
name="notes_zh",
embedding_function=ef,
metadata={"hnsw:space": "cosine"}, # 默认 l2,可选 ip 与 cosine
)
解读:距离度量在建集合时通过 metadata 的 hnsw:space 键指定(新版本另有 configuration 参数的等价写法),之后不可更改。默认 l2 是欧氏距离平方,cosine 是余弦相似度,ip 是内积;对做过归一化的向量三者排序通常一致,选 cosine 语义最直观。官方还提供 OpenAI、Ollama、Jina 等十余种现成嵌入函数,见嵌入函数文档。
提醒:嵌入模型与距离度量都是集合的"出生属性",定了就别改;真要改,唯一正确的做法是新建集合并全量重写。
6、服务器模式:HttpClient
PersistentClient 是嵌进进程内的库形态,多个进程共享同一目录会有锁冲突。想让多个应用共用一份向量数据,就切到客户端/服务器模式。服务端一条命令启动:
chroma run --path ./chroma_data --port 8000
这条命令在 8000 端口起一个 HTTP 服务,数据落在 ./chroma_data 目录。客户端改用 HttpClient 连接:
import chromadb
client = chromadb.HttpClient(host="localhost", port=8000)
collection = client.get_or_create_collection("notes")
print(collection.count())
解读:连接之后 collection 一层的 API 与本地模式完全一致,业务代码几乎不用改。一个容易忽略的细节:Python 客户端在本地把文本算成向量再发给服务端,因此自定义嵌入函数只需配好客户端,服务端不必安装模型。生产环境需要认证时,用 HttpClient(host=..., headers=...) 携带令牌;JS 客户端连接的也是同一个服务。
什么时候该切服务器模式?三条信号:有第二个进程要读同一份数据、想把向量服务与业务进程分开部署(比如各自进容器)、或者需要 Python 与 JS 双语言客户端同时访问。只做本地开发时,PersistentClient 依旧是最简单的选择。
7、适用边界:原型与生产
Chroma 把云托管作为商业化路径,开源版的设计重心始终是单机体验。把它推到生产环境之前,先对照几个维度。对比如下:
| 维度 | 原型阶段表现 | 生产环境顾虑 |
|---|---|---|
| 部署 | pip 装完即用 | 单进程写入,横向扩容乏力 |
| 规模 | 百万级向量内流畅 | 无分片与副本机制 |
| 运维 | 备份即拷目录 | 监控与高可用需自建 |
| 安全 | 本地回环使用无虞 | 曾披露预认证 RCE 漏洞 |
安全问题值得展开一句:2026 年 5 月,安全厂商披露 Chroma 1.0.0 至 1.5.8 存在预认证远程代码执行漏洞(CVE-2026-45829),详见 Orca Security 的分析。
注意:
chroma run起的服务端绝不能直接暴露公网。最小做法是只监听内网并加认证头;数据量与并发上来后,再考虑 Qdrant、Milvus 或 pgvector。
经验边界大致是:个人知识库、Demo、测试替身、内部小工具,Chroma 是最省事的选择;十万级以下文档、单机可承载的读多写少场景也够用。再往上,缺的不是功能而是分布式架构,那时换库的成本低于硬撑。好在 Chroma 的数据模型(集合、id、metadata)几乎已是行业公约数,迁往 Qdrant 或 pgvector 时概念可以直接平移,重活只在重算嵌入与批量搬数据。
8、实战:百行迷你 RAG
把前面的能力串起来:拿一份 Markdown 手册,分块入库、检索、拼提示词、交给任意 OpenAI 兼容接口的大模型。整体流程如下:
图的上半部分是离线链路,只跑一次;下半部分是在线链路,每次提问执行;两条链路在"检索相似块"处汇合。入库脚本不到 20 行:
# ingest.py —— 分块入库
import chromadb
def chunk(text: str, size: int = 300, overlap: int = 50):
step = size - overlap
return [text[i:i + size] for i in range(0, len(text), step)]
raw = open("handbook.md", encoding="utf-8").read()
client = chromadb.PersistentClient(path="./rag_db")
col = client.get_or_create_collection("handbook")
for i, piece in enumerate(chunk(raw)):
col.add(ids=[f"chunk-{i}"], documents=[piece],
metadatas=[{"part": i // 20}])
print("入库块数:", col.count())
解读:滑窗切块带 50 字重叠,避免关键句被拦腰截断;块号写进 id、段落号写进 metadata,方便调试时定位原文。中文语料记得按第 5 节的做法把默认嵌入换成 bge 中文模型。检索与生成同样精简:
# ask.py —— 检索并生成
import chromadb
from openai import OpenAI
col = chromadb.PersistentClient(path="./rag_db").get_or_create_collection("handbook")
res = col.query(query_texts=["怎么配置持久化目录"], n_results=3)
context = "\n---\n".join(res["documents"][0])
prompt = f"仅依据以下资料回答,资料没有就说不知道:\n{context}\n\n问题:怎么配置持久化目录"
llm = OpenAI(base_url="https://your-llm-endpoint/v1", api_key="sk-xxx")
answer = llm.chat.completions.create(
model="your-model",
messages=[{"role": "user", "content": prompt}],
)
print(answer.choices[0].message.content)
解读:base_url 可换成任意 OpenAI 兼容端点——vLLM、Ollama 或各云厂商网关都行。两段脚本合计约 35 行,远低于一百行的预算,这就是 Chroma 路线的底色。剩下的功夫都在块大小、Top-K 数量与提示词模板上,这些与向量库无关的变量恰恰是 RAG 效果的主战场。
9、总结
Chroma 把向量检索的起步成本压到了最低:pip 安装、PersistentClient 持久化、add 与 query 两个动词、自带嵌入函数,一个下午就能从零跑通可用的 RAG。代价是单机架构决定了它的舒适区——原型、个人知识库、中小规模内部工具;并发、分片、高可用这些生产命题,要么交给 Chroma Cloud,要么换更重的引擎。选型也不是二选一:测试环境用 Chroma 内嵌模式跑、生产环境换 Qdrant,只要把检索层抽成接口,两边切换成本很低。三条动手练习:
- 用 PersistentClient 建集合写入 20 段笔记,验证重启后数据仍在。
- 给集合换上 bge-small-zh-v1.5 与 cosine 度量,对比默认嵌入的检索差异。
- 扩展第 8 节脚本:给 query 加 where 过滤,只检索某个章节的块。
对于"先验证想法、再谈架构"的开发节奏,建议从 Chroma 起步,把省下的时间花在分块与提示词上——这两个变量对效果的影响远大于向量库本身的选型。


