chroma-core/chroma · 上手攻略

  • 仓库：chroma-core/chroma
  • 链接：https://github.com/chroma-core/chroma
  • 分类：ai
  • 作者：Jay
  • 更新：2026-07-09

是什么

Chroma（GitHub: chroma-core/chroma）是一个面向 AI 应用的开源向量数据库，用 Rust 编写，提供 Apache 2.0 许可证。它既是自托管可部署的开源版本，也有付费托管服务 Chroma Cloud。

Chroma 的核心理念是：让 AI 应用的向量存储和检索变得极简。官方口号是 "the open-source data infrastructure for AI"，主打"4 个核心函数走天下"——整个 SDK 的核心 API 只有 4 个函数：创建客户端、创建集合、添加文档、查询文档。上手门槛极低，是目前最流行的向量数据库之一，尤其在 LLM / RAG 生态中被广泛使用。

Chroma 2026 年 7 月最新数据：Stars 28,737，周增 +84，活跃度高。

解决什么问题

在 LLM 和 RAG 应用中，需要将文本、图片、音频等非结构化数据转换为向量（Embedding），然后在向量空间中进行相似性搜索。Chroma 解决的核心问题是：

  • 向量存储：将 Embedding 连同原始文档和元数据一起持久化存储
  • 向量检索：根据查询向量找到最相似的 Top-K 结果，支持元数据过滤
  • 多模态支持：不只支持文本，还支持图片、音频等多种模态的向量存储和检索
  • 部署灵活：可以嵌入式（in-memory）、本地持久化（Persistent）、客户端-服务器（Client-Server）多种模式运行
  • 混合搜索：支持密集向量检索 + 稀疏向量检索 + 全文关键词搜索

快速安装

Chroma 提供 Python 和 JavaScript/TypeScript 两种 SDK。

Python SDK（最常用）

pip install chromadb

JavaScript / TypeScript SDK

npm install chromadb   # Node.js
# 或
pnpm add chromadb

自托管服务器模式（可选）

# 安装chromadb服务器
pip install "chromadb[server]"

# 启动服务器（指定数据存储路径）
chroma run --path /path/to/chroma_db --host 0.0.0.0 --port 8000

⚠️ 注意：包名为 chromadb，但 GitHub 仓库名是 chroma-core/chroma。如果要用最新特性，建议同时关注 Chroma 官方文档。

核心用法

Chroma 的核心 API 只有 4 个函数，覆盖了最常见的向量检索流程。

1. 初始化客户端

import chromadb

# 方式一：内存模式（重启后数据丢失，适合快速原型）
client = chromadb.Client()

# 方式二：持久化模式（数据保存到磁盘）
client = chromadb.PersistentClient(path="./chroma_data")

# 方式三：连接远程服务器（需要先启动 chroma run）
client = chromadb.HttpClient(host="localhost", port=8000)

2. 创建或获取集合（Collection）

# 集合是 Chroma 中存储文档的容器，类似"表"
collection = client.create_collection(
    name="my-documents",
    metadata={"description": "我的文档集合"}  # 可选元数据
)

# 如果已存在则获取，不存在则创建
collection = client.get_or_create_collection(name="my-documents")

# 查看所有集合
print(client.list_collections())

3. 添加文档

collection.add(
    documents=[
        "这是关于机器学习的文档内容",
        "这是关于深度学习的文档内容",
        "这是关于自然语言处理的文档内容"
    ],
    metadatas=[
        {"source": "notion", "category": "ml"},
        {"source": "google-docs", "category": "dl"},
        {"source": "notion", "category": "nlp"}
    ],
    ids=["doc1", "doc2", "doc3"]  # 每个文档的唯一ID
)

说明：Chroma 会自动处理 Tokenization、Embedding 和 Indexing。如果你想自己提供 Embedding，可以使用 embeddings 参数传入。

4. 查询文档

results = collection.query(
    query_texts=["深度学习是什么？"],
    n_results=2,  # 返回最相似的2条
    where={"source": "notion"},  # 可选：元数据过滤条件
    where_document={"$contains": "机器"}  # 可选：文档内容过滤
)

# 返回结构
# results = {
#   'documents': [['...', '...']],
#   'metadatas': [[{...}, {...}]],
#   'distances': [[0.23, 0.45]],  # 距离越小越相似
#   'ids': [['doc1', 'doc2']]
# }

5. 完整 RAG 示例（配合 LangChain）

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.document_loaders import TextLoader

# 加载文档
loader = TextLoader("article.txt")
documents = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs = splitter.split_documents(documents)

# 存入 Chroma
vectorstore = Chroma.from_documents(
    documents=docs,
    embedding=OpenAIEmbeddings(),
    persist_directory="./chroma_index"
)

# 检索
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
results = retriever.get_relevant_documents("查询内容")

6. 元数据过滤（Where 子句）

Chroma 支持丰富的元数据过滤语法：

# 精确匹配
collection.query(
    query_texts=["query"],
    where={"source": "notion"}
)

# 数值比较
collection.query(
    query_texts=["query"],
    where={"rating": {"$gte": 4}}
)

# 复合条件（AND）
collection.query(
    query_texts=["query"],
    where={"$and": [{"source": "notion"}, {"rating": {"$gte": 3}}]}
)

7. 全文搜索（Full-Text Search）

# 启用全文搜索需要在集合创建时指定
collection = client.create_collection(
    name="my-documents",
    metadata={"hnsw:space": "cosine", "hnsw:search_type": "mmr"},
    get_or_create=True
)

# 在查询时使用全文搜索
results = collection.query(
    query_texts=["machine learning"],
    n_results=5,
    where_document={"$contains": "neural"}  # 过滤包含"neural"的文档
)

典型适用场景

场景 说明
RAG 应用快速原型 用 Chroma + LangChain/LlamaIndex 快速搭建检索管道
AI 应用的语义搜索 企业知识库、客服机器人的文档检索
多模态应用 存储图片/音频的向量表示（需配合多模态 Embedding 模型）
代码搜索 用 AST-aware chunking 策略索引代码库
Agent 记忆存储 用作 Agent 的历史记忆向量数据库
推荐系统 基于向量相似度的内容推荐

坑与注意

  1. 内存模式数据易失：chromadb.Client()（内存模式）在进程结束后数据丢失。开发测试用，生产环境务必用 PersistentClient 或服务器模式。

  2. Embedding 模型兼容性：Chroma 默认使用 all-MiniLM-L6-v2（Sentence Transformers）作为 Embedding 模型。如果使用 OpenAI 或其他商业 Embedding API，需显式传入对应的 Embedding Function。

  3. 数据量级：Chroma 适合中小规模数据（百万级向量以内）。对于超大规模（千万级以上），建议考虑 Milvus、Pinecone 或 Qdrant 的分布式方案。

  4. 更新和删除的局限性：Chroma 的 Add 操作是追加式的，不支持直接"更新"已有文档（Row-based API 即将推出）。要更新一条记录，需要先 Delete 再重新 Add。

  5. HNSW 参数调优：HNSW 是 Chroma 默认的向量索引算法，ef（搜索时探索因子）和 efConstruction（构建时）参数会影响检索精度和性能，文档中有详细说明但默认参数对大多数场景已足够。

  6. JavaScript SDK 成熟度：Python SDK 生态最完善，JavaScript/TS SDK 功能相对较少，部分高级特性（如某些过滤语法）可能暂不支持。

与同类对比

数据库 语言 特点 适用规模
Chroma Rust + Python 最轻量、上手最快、Colab 原生友好 中小规模
Milvus Go 功能最全、支持分布式、HNSW/ANNS 算法丰富 超大规模
Qdrant Rust 过滤能力强、分布式成熟、亚秒级检索 中大规模
Pinecone 云服务 完全托管、免运维、价格较高 任意规模
Weaviate Go 原生支持混合搜索（向量+关键词） 中大规模

Chroma 的核心优势：上手成本最低，与 LangChain/LlamaIndex 集成最顺滑，非常适合 RAG 原型阶段。生产环境如果数据量不大（百万级以下），Chroma 配合合适的部署方式也完全够用。

一句话推荐结论

Chroma 是 AI 应用向量检索的"Hello World"——用 4 个函数就能跑起来一个完整的向量数据库，RAG 原型和 AI 应用首选。

推荐星级：⭐⭐⭐⭐⭐（强烈推荐） 适合人群：所有正在构建 LLM 应用、RAG 系统或向量检索功能的开发者 学习建议：官方 Colab 教程（4 个函数）先跑一遍，然后结合 LangChain 搭一个自己的 RAG pipeline