Chroma轻量入门

为什么很多原型先从 Chroma 开始

不是每个向量检索项目一开始都需要分布式数据库。很多时候，你只是想验证三件事：embedding 模型是否选得合适，切分策略能否召回正确片段，问答链路在你的数据上是否有价值。对这类任务来说，一个依赖轻、接口简单、可本地持久化的工具，比一套完整集群更实际。

ChromaChromaChromaChroma is a lightweight vector database oriented toward local development and rapid prototyping. It emphasizes a simple developer experience: create a collection, add documents and metadata, then run similarity search with minimal setup. 恰好落在这个位置。它不是为了把海量在线流量扛到极限而设计的，而是为了让你在笔记本电脑上迅速完成一个最小可用的向量检索闭环。对于单机知识库、实验型 RAG、课程演示和内部小工具，它非常顺手。

更重要的是，Chroma 的接口贴近应用开发者思维。你不必先理解很多复杂的节点角色、索引分层和集群拓扑，先把文档、元数据和 embedding 接上就能工作。因此它非常适合作为“把检索这件事先做明白”的第一站。

安装依赖与准备数据

本篇会先演示原生 chromadb 用法，再给出 LangChain 接入示例。为了在本地直接运行，我们采用 Hugging Face 的句向量模型。

pip install chromadb langchain langchain-chroma langchain-huggingface sentence-transformers

下面先准备一组非常小的文档：

documents = [
    "FAISS 适合做单机高性能向量检索。",
    "Chroma 适合本地原型和轻量知识库。",
    "Qdrant 对 payload 过滤支持较强。",
    "Milvus 更适合大规模分布式向量检索。",
]

metadatas = [
    {"topic": "faiss"},
    {"topic": "chroma"},
    {"topic": "qdrant"},
    {"topic": "milvus"},
]

ids = ["doc-1", "doc-2", "doc-3", "doc-4"]

用原生 Chroma API 建一个最小集合

Chroma 的基本对象是集合collectioncollectionA collection is the primary container in Chroma. It groups related vectors, documents, metadata, and IDs under one logical name, much like a table or namespace for a retrieval task. 。你可以把它理解成某个知识库或某类检索任务对应的一张逻辑表。

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

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

embedding_fn = SentenceTransformerEmbeddingFunction(
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)

collection = client.get_or_create_collection(
    name="vector_db_demo",
    embedding_function=embedding_fn,
)

collection.add(
    documents=[
        "FAISS 适合做单机高性能向量检索。",
        "Chroma 适合本地原型和轻量知识库。",
        "Qdrant 对 payload 过滤支持较强。",
        "Milvus 更适合大规模分布式向量检索。",
    ],
    metadatas=[
        {"topic": "faiss"},
        {"topic": "chroma"},
        {"topic": "qdrant"},
        {"topic": "milvus"},
    ],
    ids=["doc-1", "doc-2", "doc-3", "doc-4"],
)

result = collection.query(
    query_texts=["哪个方案适合先在本地做知识库原型？"],
    n_results=2,
)

print(result["documents"])
print(result["metadatas"])

这里做了三件事。第一，创建持久化客户端，使数据写入本地目录。第二，指定 embedding 函数，让 Chroma 自动把文档与查询都编码成向量。第三，往集合中加入文档、元数据和 ID，然后用自然语言直接查询。对于原型开发，这种体验已经足够顺滑。

过滤不是附属功能，而是实用性的分水岭

只做“纯向量近似搜索”的演示很容易，但真正让系统变得可用的，往往是元数据过滤元数据过滤元数据过滤指在相似度搜索之外，再叠加结构化条件，例如文档类型、租户、时间范围、标签、权限等。没有过滤，很多检索系统只能演示；有了过滤，系统才开始接近真实业务。 。如果你的知识库里混合了多个主题、多个租户或多个版本，不加过滤就很容易把看似相似、但业务上不该返回的内容一起召回。

Chroma 也支持基于 metadata 的简单过滤。例如只在 topic=chroma 范围内检索：

result = collection.query(
    query_texts=["哪个方案适合快速做本地实验？"],
    n_results=2,
    where={"topic": "chroma"},
)

print(result["documents"])

这类过滤能力虽然不如专门数据库那样复杂，但对于个人项目和中小型内部工具已足够有用。它把“玩具级 demo”和“可落地原型”分开了。

接入 LangChain 做更贴近 RAG 的流程

很多人接触 Chroma，是因为它在 LangChain 生态里用起来很方便。此时 Chroma 不只是一个独立客户端，而是整个检索链条里的向量存储后端。

from langchain_chroma import Chroma
from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)

vectorstore = Chroma(
    collection_name="langchain_demo",
    persist_directory="./chroma_langchain",
    embedding_function=embeddings,
)

vectorstore.add_texts(
    texts=[
        "FAISS 更偏底层索引库。",
        "Chroma 更偏本地原型与轻量知识库。",
        "Milvus 面向分布式向量检索。",
    ],
    metadatas=[
        {"source": "note-1"},
        {"source": "note-2"},
        {"source": "note-3"},
    ],
)

docs = vectorstore.similarity_search("我想在本地电脑上先做一个知识库原型", k=2)
for doc in docs:
    print(doc.page_content, doc.metadata)

如果再往前走一步，可以把 vectorstore.as_retriever() 接到问答链里，让检索结果进入大模型上下文。这时，一个最小的 RAG 系统就已经成形。

Chroma 最适合什么，不适合什么

Chroma 最大的优点，是把向量检索压缩成非常低的使用门槛。你不需要先搭服务进程，不需要准备复杂部署，不需要投入太多运维心智，就能快速验证检索效果。因此它很适合以下几类场景。

• 本地 notebook 实验或课程示例。
• 小型知识库与个人工具。
• 在真正上线前，快速比较 embedding、切分和 prompt 策略。

但也要看清它的边界。Chroma 不是为了高度复杂的在线多租户场景设计的。随着数据量、并发量和过滤复杂度上升，你会越来越需要更完整的服务化能力，例如更成熟的索引管理、集群扩展、备份恢复和权限模型。

轻量不等于随意

尽管 Chroma 的上手体验很轻，但数据建模仍然要认真做。你仍然需要给文档稳定的 ID，决定是否覆盖或增量写入；仍然要设计合适的 metadata 字段，用来支持过滤与追踪；仍然要明确持久化目录与版本管理策略，避免实验目录与生产数据混杂。工具轻量，不代表工程可以随意。

此外，本地原型阶段也建议保留几组固定测试问题。因为向量检索最容易出现的误判，并不是程序报错，而是“能返回结果，但结果其实不够相关”。如果没有固定测试集，你很难比较不同 embedding 模型或切分策略到底谁更好。

本篇要点

• Chroma 很适合作为本地原型与轻量知识库的向量存储方案，门槛低、集成快。
• 原生 chromadb API 可以快速完成集合创建、文档写入、向量查询与本地持久化。
• 元数据过滤决定了系统是否能从 demo 走向可用原型，不应被忽视。
• Chroma 与 LangChain 集成顺滑，适合快速搭建最小 RAG 链路。
• 轻量工具依然需要认真处理 ID、metadata、持久化目录和回归测试问题。

下一篇

当你从本地实验走向更接近生产的系统时，过滤表达能力、混合检索和服务化部署会变得更重要。下一篇将把目光转向两个常见产品：Qdrant 与 Weaviate，并比较它们在实际选型中的差异。

参考资料

• Chroma Docs
• LangChain Chroma Integration
• Sentence Transformers