介绍

LangChain + ChromaDB 是 轻量RAG开发的黄金组合，主打极简开发、本地优先、开箱即用，非常适合快速原型、中小规模私有知识库与教学场景。

1. 开发效率拉满（最突出）

一行建库：Chroma.from_documents() 自动完成文档加载→分块→嵌入→入库→建索引。
零配置本地持久化：指定 persist_directory 即可像 SQLite 一样本地存向量库。
无缝接入 LangChain 生态：as_retriever() 直接生成检索器，配合 RetrievalQA 快速搭问答链。
元数据过滤友好：支持类 MongoDB 语法（$and/$gt/$in），无需写 SQL。

2. 轻量无负担

纯 Python、零额外部署：无需 Docker/集群，直接嵌入项目。
内存友好：适合单机/本地开发，数据量百万级内表现稳定。
开源免费：无使用门槛，适合个人/小团队。

3. 灵活适配

支持本地/远程（Chroma Server）两种模式。
兼容 OpenAI、HuggingFace、BGE 等几乎所有主流嵌入模型。
可与 LangChain Agents、Tools 深度联动，做知识库工具。

缺点

大规模/高并发：单机性能上限低，不适合亿级向量、高QPS生产环境。
分布式/集群：原生分布式能力弱，生产级需额外架构设计。
复杂检索：缺少高级索引（如 HNSW 优化）、混合检索（向量+全文）深度支持。
GPU 加速：暂不支持 GPU 向量检索加速。

适用场景 vs 不适用场景

适合场景	不适合场景
快速原型/POC、教学演示	亿级向量、高并发生产服务
中小规模私有知识库（`<100万文档`）	分布式集群、多租户系统
本地/离线RAG、个人助手	对检索延迟/吞吐量要求极高
轻量级Agent知识库工具	复杂混合检索、多模态向量库

安装

pip 安装

pip install chromadb langchain-chroma

poetry 安装

pip install chromadb langchain-chroma

从文档直接建库

适合 首次建库场景，一步完成「文档→文本分块→嵌入向量→入库→持久化」，新手首选。

注意：

再次执行时，相同的ID会更新，没有的ID会增加
只适合首次建库，以后要 添加、修改、删除 时，不适合该方法

语法1

添加字符串，适合简单测试使用

Chroma.from_texts(
    documents: List[Document],  # 【必选】LangChain Document对象列表（含page_content+metadata）
    embedding: Embeddings,      # 【必选】嵌入模型（如OpenAIEmbeddings/BGEEmbeddings）
    persist_directory: Optional[str] = None,  # 【可选】本地持久化路径，None则仅内存（默认None）
    collection_name: str = "langchain",       # 【可选】集合名，区分不同数据集（默认"langchain"）
    client_settings: Optional[Settings] = None,  # 【可选】Chroma客户端配置（如远程连接）
    client: Optional[Chroma] = None,          # 【可选】自定义Chroma客户端（高级用法）
    ids: Optional[List[str]] = None,          # 【可选】自定义文档ID列表，不填则自动生成
    collection_metadata: Optional[Dict] = None,  # 【可选】集合级元数据（如{"description": "知识库v1"}）
    **kwargs,                                  # 【可选】透传Chroma底层参数
)

参数详解：

参数	核心用途	示例
`documents`	待入库的文档，必须是 LangChain `Document` 类型（包含`page_content`文本和`metadata`元数据）	`[Document(page_content="文本内容", metadata={"source": "文件1"})]`
`embedding`	将文本转换成向量的模型，需匹配 LangChain `Embeddings` 接口	`OpenAIEmbeddings()` / `BGEEmbeddings(model_name="bge-small-zh-v1.5")`
`persist_directory`	本地保存向量库的路径，填则持久化（重启不丢），不填则仅内存	`./chroma_local_db`
`collection_name`	向量库的「集合名」，一个路径下可创建多个集合（类似数据库的表）	`"product_manual"`
`ids`	不设置自动生成唯一ID，也可以自定义每个文档的唯一ID，方便后续精准删除/查询	`["doc_001", "doc_002"]`

语法2

添加 documents 对象，适合读取文件后，直接添加到数据库

Chroma.from_documents(
    documents: List[Document],  # 【必选】LangChain Document对象列表（含page_content+metadata）
    embedding: Embeddings,      # 【必选】嵌入模型（如OpenAIEmbeddings/BGEEmbeddings）
    persist_directory: Optional[str] = None,  # 【可选】本地持久化路径，None则仅内存（默认None）
    collection_name: str = "langchain",       # 【可选】集合名，区分不同数据集（默认"langchain"）
    client_settings: Optional[Settings] = None,  # 【可选】Chroma客户端配置（如远程连接）
    client: Optional[Chroma] = None,          # 【可选】自定义Chroma客户端（高级用法）
    ids: Optional[List[str]] = None,          # 【可选】自定义文档ID列表，不填则自动生成
    collection_metadata: Optional[Dict] = None,  # 【可选】集合级元数据（如{"description": "知识库v1"}）
    **kwargs,                                  # 【可选】透传Chroma底层参数
)

参数

同上

例子1

批量添加字符串数据

from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from dotenv import load_dotenv

# 加载环境变量（需配置 OPENAI_API_KEY）
load_dotenv()

# 准备多条文本数据（核心）
texts = [
    "ChromaDB是轻量级开源向量数据库，支持本地持久化",
    "LangChain是LLM应用开发框架，可快速搭建RAG系统",
    "LangChain+ChromaDB组合适合中小规模私有知识库开发",
    "向量数据库的核心功能是相似性检索，支撑RAG的检索环节"
]

# 自定义每条记录的ID（可选，不填则自动生成）
ids = [
    "text_001",
    "text_002",
    "text_003",
    "text_004"
]

# 阿里嵌入模型
embeddings = DashScopeEmbeddings(model="text-embedding-v2")

# 建库并添加文档
db = Chroma.from_texts(
    texts=texts,
    ids=ids,  # 记录的id，不指定，会自动生成
    embedding=embeddings,
    persist_directory="./my_chroma_db",  # 数据库目录名
    collection_name="test_collection",  # 相当于mysql表名
)

查看数据

使用navcat打开下图的 chroma.sqlite3 文件：

向量数据保存在 embeddings_queue 表

原始数据保存在 embedding_metadata 表

例子2

读取 .docx 文件，并写入到向量数据库


from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.document_loaders import Docx2txtLoader
from dotenv import load_dotenv

# 加载环境变量（需配置 OPENAI_API_KEY）
load_dotenv()

embeddings = DashScopeEmbeddings(model="text-embedding-v2")

# 初始化加载器（指定文件路径+编码）
loader = Docx2txtLoader(
    file_path="../../企业报告（短）.docx",  # 必传：Word文件路径
)

# 加载文件（核心通用方法）
# 一次性加载（小文件）
docs = loader.load()

# 完整参数示例
db = Chroma.from_documents(
    documents=docs,
    embedding=embeddings,
    persist_directory="./my_chroma_db",
    collection_name="test_collection",
)

查看数据

加载已有库

加载已持久化到本地/远程的 Chroma 向量库，二次操作时使用。

创建对象

Chroma(
    embedding_function: Embeddings,  # 【必选】与建库时一致的嵌入模型（必须匹配！）
    persist_directory: Optional[str] = None,  # 【可选】本地持久化路径（建库时填了这里也要填）
    collection_name: str = "langchain",       # 【可选】集合名（需与建库时一致）
    client_settings: Optional[Settings] = None,  # 【可选】客户端配置（远程连接用）
    client: Optional[Chroma] = None,          # 【可选】自定义客户端
    collection_metadata: Optional[Dict] = None,  # 【可选】集合元数据
)

注意：embedding_function 必须和建库时完全一致（比如建库用 OpenAI Embedding，加载时不能换 BGE），否则向量维度不匹配会检索失败。

例子

from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from dotenv import load_dotenv

# 加载环境变量（需配置 OPENAI_API_KEY）
load_dotenv()

# 初始化大模型
embeddings = DashScopeEmbeddings(model="text-embedding-v2")

# 创建数据库对象
db = Chroma(
    embedding_function=embeddings,
    persist_directory="./my_chroma_db",
    collection_name="test_collection"
)

添加数据（字符串）

类似 db.add_documents()，但只能添加纯文本

语法

db.add_texts(
    texts: List[str],               # 【必选】纯文本列表
    metadatas: Optional[List[Dict]] = None,  # 【可选】文本对应的元数据列表
    ids: Optional[List[str]] = None,         # 【可选】自定义ID
    **kwargs,
) -> List[str]  # 返回新增文档ID

例子


from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from dotenv import load_dotenv

# 加载环境变量（需配置 OPENAI_API_KEY）
load_dotenv()

# 初始化大模型
embeddings = DashScopeEmbeddings(model="text-embedding-v2")

# 创建数据库对象
db = Chroma(
    embedding_function=embeddings,
    persist_directory="./my_chroma_db",
    collection_name="test_collection"
)

# 准备多条文本数据
texts = [
    "ChromaDB是轻量级开源向量数据库，支持本地持久化",
    "LangChain是LLM应用开发框架，可快速搭建RAG系统",
    "LangChain+ChromaDB组合适合中小规模私有知识库开发",
    "向量数据库的核心功能是相似性检索，支撑RAG的检索环节"
]

# 自定义每条记录的ID（可选，不填则自动生成）
ids = [
    "text_101",
    "text_102",
    "text_103",
    "text_104"
]

# 添加记录，不指定id，则自动生成id
db.add_texts(texts, ids=ids)

添加数据（documents对象）

向已有向量库中追加文档，必须是 documents 对象

注意：数据库必须已经存在

db.add_documents(
    documents: List[Document],  # 【必选】待追加的Document列表
    ids: Optional[List[str]] = None,  # 【可选】自定义文档ID
    **kwargs,
) -> List[str]  # 返回新增文档的ID列表

例子

from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.document_loaders import Docx2txtLoader
from dotenv import load_dotenv

# 加载环境变量（需配置 OPENAI_API_KEY）
load_dotenv()

# 初始化大模型
embeddings = DashScopeEmbeddings(model="text-embedding-v2")

# 创建数据库对象
db = Chroma(
    embedding_function=embeddings,
    persist_directory="./my_chroma_db",
    collection_name="test_collection"
)

# 初始化加载器（指定文件路径+编码）
loader = Docx2txtLoader(
    file_path="../../企业报告（短）.docx",  # 必传：Word文件路径
)
ids = ["text_100"]
# 加载文件（核心通用方法）
# 一次性加载（小文件）
docs = loader.load()

# 添加记录，不指定id，则自动生成id
db.add_documents(docs, ids=ids)

删除数据

删除指定ID的文档（需先获取文档ID）

db.delete(
    ids: List[str],  # 【必选】要删除的文档ID列表
    **kwargs,
) -> None

例子

from langchain_chroma import Chroma

# 创建数据库对象
db = Chroma(
    persist_directory="./my_chroma_db",
    collection_name="test_collection"
)

ids = ["text_001", "text_002"]

db.delete(ids)

docs = db.get()
print("总共记录数：", len(docs["ids"]))
for item in docs["ids"]:
    print(item)

获取数据

作用：查询库中所有/指定ID的文档、元数据、向量（调试/校验必备）

db.get(
    ids: Optional[List[str]] = None,  # 【可选】指定ID列表，None则返回所有
    where: Optional[Dict] = None,     # 【可选】元数据过滤条件
    limit: Optional[int] = None,      # 【可选】返回数量限制
    offset: Optional[int] = None,     # 【可选】偏移量（分页用）
    **kwargs,
) -> Dict[str, Any]  # 返回：ids/texts/metadatas/embeddings

返回值

返回 dict 类型

key是 ids，表示主键
key是 documents，表示内容

例子

from langchain_chroma import Chroma

# 创建数据库对象
db = Chroma(
    persist_directory="./my_chroma_db",
    collection_name="test_collection"
)


# 获取记录
docs = db.get()

# dict类型
print("docs类型：", type(docs))

print("总共记录数：", len(docs["ids"]))

print("打印所有id----------")
for item in docs["ids"]:
    print(item)

print("\n\n打印所有内容----------")
for item in docs["documents"]:
    print(item)

总结

创建对象核心：from_documents()（新手首选）需指定 documents 和 embedding，persist_directory 决定是否本地持久化；加载已有库用 Chroma()，需匹配嵌入模型和集合名；
增删查方法：add_documents()（追加文档）、delete()（按ID删）、get()（查数据），操作前建议用 get() 校验数据；

原文出处：/show_1GW2rqWrlY0W.html