Chroma

Chroma 快速入门

AI 应用的”记忆系统”——存储和检索向量嵌入，让 LLM 记住你的数据。

这是什么？适合谁？

Chroma 是专为 LLM 应用设计的开源向量数据库。它把文档、图片、代码转换成向量嵌入，存储在数据库中，然后通过语义搜索快速找到相关内容。GitHub 28K+ stars，15M+ 月下载量，Apache 2.0 开源。目前提供 Chroma Cloud（付费托管）和 OSS（自托管）两种形态。

适合谁？一是构建 RAG 应用的开发者，需要向量存储和语义搜索；二是 AI 创业者，需要快速搭建原型（Chroma 的 API 极其简单）；三是需要本地运行的团队（无需外部数据库）。不适合：需要大规模分布式向量搜索的场景（用 Pinecone 或 Weaviate），以及需要复杂过滤和混合搜索的生产环境。

准备工作

• 安装：pip install chromadb
• Python：3.8+

3 步快速上手

第 1 步：安装

pip install chromadb

第 2 步：创建集合并添加文档

import chromadb
client = chromadb.Client()
collection = client.create_collection("my_docs")
collection.add(
    documents=["这是第一份文档", "这是第二份文档"],
    ids=["doc1", "doc2"]
)

第 3 步：语义搜索

results = collection.query(query_texts=["搜索关键词"], n_results=2)
print(results["documents"])

常见踩坑

踩坑 1：持久化数据丢失

• 症状：重启后数据消失
• 原因：默认使用内存模式
• 解决：使用 chromadb.PersistentClient(path="./chroma_db")

踩坑 2：嵌入函数不匹配

• 症状：查询结果不相关
• 原因：添加文档和查询时使用了不同的嵌入模型
• 解决：创建集合时指定嵌入函数：collection = client.create_collection("name", embedding_function=my_ef)

踩坑 3：Docker 模式下连接拒绝

• 症状：连接 Chroma Server 时显示 Connection Refused
• 原因：Docker 容器未暴露正确端口，或 bind IP 不是 0.0.0.0
• 解决：docker run -p 8000:8000 chromadb/chroma，并确保服务监听 0.0.0.0:8000

踩坑 4：大量数据导入极慢

• 症状：插入 10 万条数据耗时数小时
• 原因：逐个插入且每次触发索引重建
• 解决：使用 collection.add 批量接口（一次传入全部文档），或在客户端设置 chromadb.config.Settings(anonymized_telemetry=False) 减少上报延迟

踩坑 5：嵌入式函数报错 “DefaultEmbeddingFunction not found”

• 症状：未指定 embedding_function 时报错
• 原因：Chroma 默认使用 all-MiniLM-L6-v2（通过 sentence-transformers），后者未安装
• 解决：pip install sentence-transformers，或指定 OpenAI/其他嵌入：from chromadb.utils import embedding_functions; ef = embedding_functions.OpenAIEmbeddingFunction(api_key="...", model_name="text-embedding-3-small")

踩坑 6：查询结果为空

• 症状：query() 返回空列表
• 原因：文档之间嵌入相似度太低，或 n_results 设置太小
• 解决：增大 n_results，或检查 where 过滤条件是否正确

踩坑 7：collection.delete 后空间未释放

• 症状：删除文档后磁盘占用不变
• 原因：Chroma 的删除是逻辑删除，索引文件未压缩
• 解决：定期调用 collection.compact() 压缩数据（v0.6+），或重建集合

FAQ 常见问题

Q1：Chroma 是免费的吗？怎么收费？

A：Chroma OSS 完全免费（Apache 2.0）。Chroma Cloud 按用量付费：写入 $2.50/GiB、存储 $0.33/GiB/月、查询 $0.0075/TiB、网络 $0.09/GiB 传出。Starter 计划 $0/月 + $5 免费额度。对比 Pinecone（写入约 $5.00/GiB + 存储 $0.40/GiB/月），Chroma Cloud 价格约为 Pinecone 的 60-70%。来源

Q2：Chroma 和 Pinecone、Weaviate、Qdrant 有什么区别？

A：Chroma 的核心差异是”极简 API”和”对象存储架构”。对比概览：Pinecone（托管，功能最全面但最贵，约 $70/月起步）；Weaviate（支持混合搜索，Kubernetes 部署复杂，GitHub 13K stars）；Qdrant（Rust 编写，高性能但需要自运维，GitHub 23K stars）；Chroma（上手最简单，API 最像标准库，但分布式能力有限）。数据量 <1M 条时 Chroma 足够；>10M 条时推荐 Qdrant 或 Pinecone。来源

Q3：Chroma 和 LangChain/LlamaIndex 集成吗？

A：原生集成。LangChain 中 from langchain_community.vectorstores import Chroma 即可使用，LlamaIndex 中 from llama_index.vector_stores.chroma import ChromaVectorStore。Chroma 可能是这两个框架中最广泛使用的默认向量存储方案。来源

Q4：Chroma 支持多模态（图片、音频）搜索吗？

A：Chroma 本身是向量存储和检索引擎，不关心向量的来源。只要提供图片/音频的嵌入向量，就可以检索。例如配合 CLIP 模型做图片搜索，配合 Whisper + text-embedding 做音频检索。Chroma 还支持 include=["metadatas", "documents", "distances"] 灵活控制返回内容。

Q5：Chroma v1 有什么新变化？

A：Chroma v1（2025-2026 年）引入了重大架构重写：新增稀疏向量搜索（BM25、SPLADE）、全文搜索（Trigram/Regex）、元数据数组支持、Schema 和 Search API、Collection Forking（写时复制）、基于对象存储的 WAL（Write-Ahead Log）、JavaScript Client V3（减少打包体积）。这是向”完整搜索基础设施”转型的重要版本。来源

初级用法

1. 获取集合条数：collection.count() - 快速了解数据量
2. 按 ID 查询：collection.get(ids=["doc1"]) - 按 ID 检索原始文档
3. 按元数据过滤：collection.query(query_texts=["关键词"], where={"category": "技术"}) - 带过滤条件的检索
4. 查看集合列表：client.list_collections() - 列出所有集合
5. 删除集合：client.delete_collection("my_docs") - 完整移除集合及其所有数据

高级玩法

1. 多向量搜索：同时对同一集合做密集向量搜索（语义）和稀疏向量搜索（BM25 关键词），然后融合结果
2. 集合 Forking：collection2 = collection1.fork("experiment-v2") 写时复制，安全做 A/B 测试
3. 自定义 Embedding 函数：实现自己的 EmbeddingFunction 类，支持任意嵌入模型（HuggingFace、vLLM、Ollama）
4. MCP Server：Chroma 提供 Package Search MCP 工具，查询数千个开源仓库的代码知识
5. 批量增量更新：collection.upsert(documents=[...], ids=[...], metadatas=[...]) 幂等更新，新文档插入、旧文档覆盖

小技巧

1. 在 query() 中查看嵌入向量：设置 include=["embeddings"] 返回原始向量，用于调试或二次处理
2. 使用 collection.update() 修改元数据：仅更新已有文档的 metadata 而不修改向量/文档内容
3. 添加自定义 metadata 提高过滤精度：collection.add(documents=[...], metadatas=[{"source": "wiki", "date": "2025-01-01"}])
4. 限制返回距离：n_results=5 + where_document={"$contains": "关键词"} 对文档内容做预过滤
5. 使用 peek() 快速预览：collection.peek() 返回前 10 条记录，无需编写查询

进阶学习建议

• 阅读 Chroma 官方文档：https://docs.trychroma.com 了解 Schema API 和 Search API（v1 核心）
• 尝试 Chroma Cloud：利用 $5 免费额度体验托管服务，对比自托管和云托管的生产差异
• 研究 Chroma 的研究论文：Context-1（自编辑搜索 Agent）、Context Rot（输入长度对 LLM 性能的影响）https://www.trychroma.com/research
• 学习稀疏向量搜索：理解 BM25 和 SPLADE 的原理，配合 Chroma v1 做混合搜索
• 实战 RAG 项目：用 Chroma + LangChain/LlamaIndex 构建完整的文档问答系统

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

• Chroma 官网
• Chroma GitHub
• Chroma 文档
• Chroma 定价