Chroma：给 RAG 应用最轻量友好的向量数据库

开篇：你要完成什么

这篇教程带你从零装好 Chroma，跑通第一个"简历问答"Demo：把一段文档写入向量库，然后对它做自然语言检索，最终你在本地就能拿到一个可运行的 RAG 最小闭环。

前置条件

• Python 3.8+：Chroma 基于 Python 开发，3.8 以下不支持
• pip：安装包用，建议 21 以上
• 无需 GPU：纯 CPU 就能跑通 Demo，内存 2GB 以上足够
• 终端工具：macOS/Linux 用 bash，Windows 用 PowerShell 或 CMD
• 建议虚拟环境：避免和全局 Python 依赖冲突

安装部署

1. 创建虚拟环境

python -m venv chroma-demo
source chroma-demo/bin/activate   # Windows 用 chroma-demoScriptsactivate

2. 安装 Chroma

pip install chromadb

会自动装上最新稳定版，以及依赖的 numpy、sqlite3 等库。

3. 验证安装

python -c "import chromadb; print(chromadb.__version__)"

能看到类似 0.4.24 的版本号，就说明装好了。

第一个 Demo：做一个小型文档问答

第一步：初始化客户端

这一步要创建 Chroma 客户端，并指定数据持久化的本地目录。

import chromadb

client = chromadb.PersistentClient(path="./chroma_data")

第二步：创建 Collection

Collection 相当于传统数据库的"表"，用来存向量和元数据。这里指定余弦距离便于做语义检索。

collection = client.get_or_create_collection(
    name="demo_docs",
    metadata={"hnsw:space": "cosine"}
)

第三步：写入文档

Chroma 会自动帮你做文本向量化（默认用内置的 embedding 模型），你只需要提供文档内容、元数据和唯一 ID。

collection.add(
    documents=[
        "Chroma 是一个面向 AI 应用的轻量级向量数据库。",
        "RAG 应用通常先检索相关信息，再交给大语言模型生成答案。",
        "Chroma 支持持久化存储，适合快速搭建原型。"
    ],
    metadatas=[
        {"source": "intro"},
        {"source": "rag"},
        {"source": "feature"}
    ],
    ids=["doc_01", "doc_02", "doc_03"]
)

第四步：查询文档

输入一个自然语言问题，Chroma 会返回与它语义最相近的前两条记录。

results = collection.query(
    query_texts=["什么是 RAG？"],
    n_results=2
)

print(results)

预期输出

{
  "ids": [["doc_02", "doc_01"]],
  "documents": [["RAG 应用通常先检索相关信息，再交给大语言模型生成答案。", "Chroma 是一个面向 AI 应用的轻量级向量数据库。"]],
  "distances": [[0.12, 0.25]]
}

你会第一条就拿到解释 RAG 的那条记录——这就是向量检索的"语义匹配"效果。

配置与调优

1. 选择合适的距离函数

创建 Collection 时通过 {"hnsw:space": "cosine"} 指定距离算法。文本语义检索推荐 cosine，数值特征用 euclidean，Embedding 维度高且追求速度可以试 ip（内积）。

2. 设置批量写入大小

大量写入时不要一条条 add，建议每 128～256 条作为一个 batch。这样能显著减少网络和索引开销。

for i in range(0, len(docs), 128):
    batch = docs[i:i+128]
    collection.add(documents=batch)

3. 关闭隐性 Embedding 调用

如果外部已经生成好向量，直接传 embeddings 参数，并跳过 documents。否则 Chroma 每次都会调用内置 embedding 模型，白白浪费时间。

collection.add(
    embeddings=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["v1", "v2"]
)

常见坑与排错

下一步

1. 接入真实 LLM 构建完整 RAG

把查询结果交给 OpenAI 或本地模型（如 Ollama），让 AI 根据检索到的文档片段生成回答，形成一个真正的问答机器人。

2. 使用 Metadata 过滤与复杂查询

探索 Chroma 的 where 参数，按来源、日期或标签过滤检索范围，提升结果精准度。

3. 服务化部署与多客户端接入

用 chroma run --path ./chroma_data 启动服务端，从 Web 或另一个 Python 进程通过 HTTP API 来读写数据，为前后端分离做铺垫。

你现在已经能跑通最小 Demo 了，剩下的就是在真实场景里不断打磨数据清洗和提示词策略。遇到问题欢迎回到文档或者社区看看，Chroma 的生态还在快速增长，坑也填得很快。