Chroma向量数据库介绍

一、Chroma 核心定位 & 为什么 Agent 开发必用它

1. 核心定义

Chroma 是一款轻量级、开源、专为 LLM/RAG 场景设计的嵌入式向量数据库（Vector Database），用 Python/TypeScript 开发，主打「开箱即用」和「低运维成本」。

简单说：你把文本转成 Embedding 向量后，Chroma 帮你存、查、管理这些向量，并且能快速找到和查询向量最相似的结果 —— 这是 Agent 中 RAG 模块的核心组件。

2. 对比其他向量库（为什么选它？）

表格

特性	Chroma	FAISS（Facebook）	Pinecone（云服务）	Milvus（开源）
上手难度	极低（1 行代码启动）	中（需编译）	低（云服务）	高（需部署集群）
本地开发友好度	🌟🌟🌟🌟🌟	🌟🌟🌟	❌（需联网）	🌟
Python 集成	原生支持	需封装	API 调用	SDK 调用
元数据过滤	支持	不支持	支持	支持
生产部署复杂度	中（单节点 / 集群）	高（需自己运维）	低（托管）	高（集群配置）
成本	免费（开源）	免费	按用量收费	免费（开源）

👉 Agent 开发场景首选 Chroma 的原因：

• 本地开发无需部署集群，快速验证 RAG 逻辑；
• 原生支持「向量 + 元数据」存储（比如存文档 ID、类型、时间），Agent 检索时可精准过滤；
• 和 LangChain/LangGraph 无缝集成，是 RAG 落地的「最小成本方案」。

二、Chroma 核心概念（工程师视角）

不用记学术术语，记住这 5 个核心概念即可：

1. Collection（集合） ：

   • 类比关系型数据库的「表」，用于隔离不同类型的向量数据（比如 Agent 的知识库分「产品文档」「用户手册」两个 Collection）；
   • 每个 Collection 有独立的向量空间和元数据索引。

2. Embedding（嵌入向量） ：

   • 文本 / 图片转成的数值数组（比如 768 维），Chroma 不负责生成向量，只负责存储和检索；
   • 常用生成工具：OpenAI Embedding、BGE、m3e（国内开源）。

3. Document（文档） ：

   • Chroma 中存储的基本单元，包含 3 部分：

     • id：唯一标识（自定义 / 自动生成）；
     • embeddings：向量数组；
     • metadata：元数据（字典格式，比如{"doc_type":"pdf", "create_time":"2026-03-08"}）；
     • documents：原始文本（可选，方便回溯）。

4. Query（查询） ：

   • 输入查询文本的向量，Chroma 返回「相似度 Top N」的文档；
   • 支持「向量检索 + 元数据过滤」（比如只查 2026 年的 pdf 文档）。

5. Distance Function（距离函数） ：

   • 衡量向量相似度的算法，Chroma 默认用cosine（余弦相似度），也支持l2（欧氏距离）、ip（内积）；
   • Agent 场景优先用cosine（文本相似度最常用）。

三、Chroma 实战（Agent 开发核心代码）

1. 环境准备

bash

运行

# 安装核心包
pip install chromadb  # 基础版
pip install chromadb[all]  # 完整版（含依赖）
# 配合LangChain使用
pip install langchain langchain-chroma

2. 核心操作（完整可运行代码）

python

运行

import chromadb
from chromadb.utils import embedding_functions

# ====================== 1. 初始化Chroma客户端 ======================
# 方式1：内存模式（开发/测试用，重启数据丢失）
client = chromadb.Client()

# 方式2：持久化模式（生产用，数据存本地）
# client = chromadb.PersistentClient(path="./chroma_data")

# ====================== 2. 创建/获取Collection ======================
# 创建集合（指定距离函数）
collection = client.create_collection(
    name="agent_knowledge_base",
    metadata={"hnsw:space": "cosine"},  # 余弦相似度
    get_or_create=True  # 存在则获取，不存在则创建
)

# ====================== 3. 嵌入函数（生成向量） ======================
# 示例：用开源的BGE嵌入模型（国内推荐）
# 也可以用OpenAI Embedding（需API Key）
embedding_func = embedding_functions.HuggingFaceEmbeddingFunction(
    model_name="BAAI/bge-small-zh-v1.5"
)

# ====================== 4. 插入数据（Agent知识库入库） ======================
# 模拟文档数据
documents = [
    "AI Agent核心组件：规划、记忆、工具调用、反思",
    "Function Calling是让LLM调用外部工具的能力",
    "RAG通过检索知识库降低LLM幻觉，提升准确性"
]
metadatas = [
    {"doc_type": "agent_base", "source": "internal"},
    {"doc_type": "function_call", "source": "internal"},
    {"doc_type": "rag", "source": "internal"}
]
ids = ["doc_1", "doc_2", "doc_3"]  # 自定义ID

# 插入数据（Chroma自动调用嵌入函数生成向量）
collection.add(
    documents=documents,
    metadatas=metadatas,
    ids=ids,
    embedding_function=embedding_func  # 也可以提前生成向量传入
)

# ====================== 5. 检索（Agent RAG核心步骤） ======================
# 模拟用户查询
query_text = "AI Agent怎么解决幻觉问题？"
# 检索相似文档（Top 2）
results = collection.query(
    query_texts=[query_text],  # 支持批量查询
    n_results=2,
    where={"doc_type": {"$in": ["agent_base", "rag"]}},  # 元数据过滤
    embedding_function=embedding_func
)

# 打印结果
print("检索到的文档：")
for i, doc in enumerate(results["documents"][0]):
    print(f"Top {i+1}: {doc} | 相似度分数: {results['distances'][0][i]}")

# ====================== 6. 其他常用操作（Agent运维） ======================
# 更新文档
collection.update(
    ids=["doc_1"],
    documents=["AI Agent核心组件：规划、短期/长期记忆、工具调用、反思、自我修正"],
    metadatas=[{"doc_type": "agent_base", "source": "internal", "update_time": "2026-03-08"}]
)

# 删除文档
collection.delete(ids=["doc_2"])

# 查看集合信息
print("集合文档数量：", collection.count())

3. 关键代码解释

• 持久化模式：PersistentClient是生产环境必用，数据存在本地文件，重启不丢失；
• 元数据过滤：where参数是 Agent 检索的核心 —— 比如用户问「产品 A 的问题」，可以只检索「产品 A」的文档，提升精准度；
• 相似度分数：Chroma 返回的distances越小，相似度越高（cosine 距离范围 0~2，0 是完全相似）；
• 批量操作：支持批量插入 / 查询，适配 Agent 处理海量文档的场景。

四、Chroma 生产级部署（Agent 上线必看）

1. 部署方式

方式 1：单节点部署（中小规模 Agent）

bash

运行

# 启动Chroma服务（REST API）
chroma run --path ./chroma_data --host 0.0.0.0 --port 8000

Python 客户端连接：

python

运行

import chromadb
client = chromadb.HttpClient(host="localhost", port=8000)

方式 2：Docker 部署（推荐）

bash

运行

# 拉取镜像
docker pull chromadb/chroma:latest
# 启动容器（持久化+端口映射）
docker run -d -p 8000:8000 -v ./chroma_data:/chroma/chroma_data chromadb/chroma:latest

2. 生产注意事项（5 年 Python 后端重点关注）

1. 数据备份：定期备份chroma_data目录（嵌入式存储，无内置容灾）；

2. 性能优化：

   • 大规模数据（10 万 + 文档）：调整hnsw:ef_construction（索引构建参数）、hnsw:M（邻居数量）；
   • 批量插入：单次插入 1000~5000 条，避免频繁小批量操作；

3. 并发控制：Chroma 单节点并发能力有限（约 100 QPS），高并发 Agent 需加缓存（Redis）；

4. 监控：通过collection.count()、接口响应时间监控状态，接入 Prometheus（需自定义埋点）；

5. 升级：Chroma 版本迭代快，升级前先备份数据，避免兼容性问题。

五、Chroma 在 AI Agent 中的典型应用流程

预览

查看代码

Agent接收用户问题

将问题转成Embedding向量

Chroma检索相似文档（向量+元数据过滤）

将检索结果+问题拼接成Prompt

LLM生成回答

Agent返回回答给用户

flowchart TD
    A[Agent接收用户问题] --> B[将问题转成Embedding向量]
    B --> C[Chroma检索相似文档（向量+元数据过滤）]
    C --> D[将检索结果+问题拼接成Prompt]
    D --> E[LLM生成回答]
    E --> F[Agent返回回答给用户]

Agent接收用户问题

将问题转成Embedding向量

Chroma检索相似文档（向量+元数据过滤）

将检索结果+问题拼接成Prompt

LLM生成回答

Agent返回回答给用户

豆包

你的 AI 助手，助力每日工作学习

👉 核心价值：Chroma 让 Agent 拥有「外挂知识库」，不再只依赖 LLM 的内置知识，解决幻觉和知识时效性问题。

---

总结

1. 核心定位：Chroma 是轻量级、开箱即用的向量数据库，是 AI Agent 中 RAG 模块的首选工具（适配 Python 后端开发）；
2. 核心操作：重点掌握「集合管理、数据插入、带元数据过滤的检索」，这是 Agent 开发中 90% 会用到的功能；
3. 生产落地：开发用内存模式，上线用 Docker 部署的持久化模式，关注备份、性能优化和监控。