chroma-core/chroma：AI原生的轻量级嵌入式向量数据库

一、官方信息

二、项目背景

做 RAG 原型时，很多人根本不想为一个向量检索去拉起 Milvus、Qdrant 这种"全家桶"数据库——只要几行代码能存 embedding、能查相似文本就够了。Chroma 就是冲着这个场景来的：它把向量数据库做成了一个 pip 包，import 即用，像 SQLite 一样嵌入式运行，零配置、零依赖服务。

Chroma 由美国团队开发，是目前 LangChain、LlamaIndex 教程里出现频率最高的向量库，几乎所有入门 RAG 教程的第一个例子用的都是它。它内置了默认的 embedding 模型（all-MiniLM），你甚至不用自己接 embedding API，丢一段文本进去它自动帮你向量化。

当原型做大成了需要多进程 / 多机访问的服务时，Chroma 也提供了 Chroma Server 模式：一行命令起一个 HTTP 服务，客户端远程连接，还能配合 Docker 部署。从本地原型到团队协作，Chroma 都能平滑过渡。

三、核心特性

• 嵌入式零配置：pip install 后直接 import，无需起服务。
• 内置 Embedding：默认集成开源 embedding 模型，开箱即用。
• 纯 Python 体验：API 极简，几行代码完成增删改查。
• 持久化：自动落盘到本地目录，重启不丢。
• Server / Client 模式：支持 HTTP 远程访问与多客户端共享。
• 元数据过滤：可按 metadata 字段做 WHERE 过滤检索。
• 生态原生：LangChain / LlamaIndex / Chroma 官方深度集成。

四、环境要求

• Python 3.9 ~ 3.12。
• 操作系统：Linux / macOS / Windows。
• 嵌入式模式无需 Docker；Server 模式建议 Docker。
• 内存：建议 2GB 以上（内置 embedding 模型会占一定内存）。

五、详细部署步骤

方式一：嵌入式使用（最简单，3 行代码）

pip install chromadb

import chromadb

# 自动持久化到 ./chroma_data 目录
client = chromadb.PersistentClient(path="./chroma_data")

# 创建 collection
col = client.get_or_create_collection(name="my_docs")

# 插入文本（自动用内置模型向量化）
col.add(
    documents=["Chroma 是一个嵌入式向量数据库", "它非常适合做 RAG 原型"],
    ids=["doc1", "doc2"],
    metadatas=[{"source": "a"}, {"source": "b"}],
)

# 相似度搜索
results = col.query(query_texts=["什么是向量数据库"], n_results=2)
print(results["documents"])

方式二：Chroma Server（Docker 部署，团队共享）

docker run -d --name chroma \
  -p 8000:8000 \
  -v $(pwd)/chroma_data:/chroma/chroma \
  chromadb/chroma:latest

Python 客户端远程连接：

import chromadb
client = chromadb.HttpClient(host="服务器IP", port=8000)

方式三：Docker Compose（带持久化）

cat > docker-compose.yml <<'EOF'
services:
  chroma:
    image: chromadb/chroma:latest
    container_name: chroma
    restart: always
    ports:
      - "8000:8000"
    volumes:
      - ./chroma_data:/chroma/chroma
EOF
docker compose up -d

自定义 Embedding 模型（接入 OpenAI / 本地）

from chromadb.utils import embedding_functions

openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="sk-xxx",
    model_name="text-embedding-3-small",
)

col = client.get_or_create_collection(name="docs", embedding_function=openai_ef)
col.add(documents=["你好世界"], ids=["1"])

验证部署

curl http://localhost:8000/api/v1/heartbeat
# Server 模式下返回时间戳即正常

六、使用方法

1. 嵌入式：脚本里 chromadb.PersistentClient(path=...) 即用，无账号密码。
2. Server 模式：访问 http://服务器IP:8000，默认无鉴权，公网部署建议加反向代理 + 认证。
3. LangChain 集成：from langchain_community.vectorstores import Chroma，传入 persist_directory 或 client。
4. 常用 API：add / query / update / delete / get，参数直观。

七、常见问题 FAQ

Q1：嵌入式和 Server 模式怎么选？
A：个人脚本 / 单进程用嵌入式；需要多服务共享、远程访问时用 Server 模式。

Q2：内置 embedding 是什么模型？
A：默认是 all-MiniLM-L6-v2（384 维），适合英文；中文生产建议换 BGE / OpenAI 等中文 embedding。

Q3：数据存在哪？
A：嵌入式在 path 指定目录；Server 模式在容器内 /chroma/chroma（已映射到宿主机）。

Q4：切换 embedding 模型后查不到结果？
A：不同模型向量维度不同，旧数据需删除重建，否则维度不匹配。

Q5：能撑多大数据量？
A：Chroma 定位轻量，百万级以内文档很合适；千万级以上建议换 Milvus / Qdrant。

八、跳转链接

• GitHub 仓库：https://github.com/chroma-core/chroma
• 官方文档：https://docs.trychroma.com/
• Docker 镜像：https://hub.docker.com/r/chromadb/chroma
• PyPI：https://pypi.org/project/chromadb/