LangChain教程：ChromaDB向量数据库 作者：马育民 • 2026-03-01 15:12 • 阅读：10014 # 介绍 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 ``` # 从文档直接建库 适合 **首次建库场景**，一步完成「文档→文本分块→嵌入向量→入库→持久化」，新手首选。 **注意：** 1. 再次执行时，**相同的ID会更新**，**没有的ID会增加** 2. **只适合首次建库**，以后要 **添加、修改、删除** 时，**不适合该方法** ### 语法1 添加 字符串，适合简单测试使用 ```python 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` 对象，适合读取文件后，直接添加到数据库 ```python 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` 文件： [](https://www.malaoshi.top/upload/0/0/1GW2rnMpCNSi.png) 向量数据保存在 `embeddings_queue` 表 [](https://www.malaoshi.top/upload/0/0/1GW2rnLY7usS.png) 原始数据保存在 `embedding_metadata` 表 [](https://www.malaoshi.top/upload/0/0/1GW2rnLqtXMX.png) ### 例子2 读取 `.docx` 文件，并写入到向量数据库 ```python 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", ) ``` ##### 查看数据 [](https://www.malaoshi.top/upload/0/0/1GW2rnSM5TIv.png) # 加载已有库 加载已持久化到本地/远程的 Chroma 向量库，二次操作时使用。 ### 创建对象 ```python 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），否则向量维度不匹配会检索失败。 ### 例子 ```python 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()`，但只能添加纯文本 ### 语法 ```python 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` 对象 **注意：**数据库必须已经存在 ```python db.add_documents( documents: List[Document], # 【必选】待追加的Document列表 ids: Optional[List[str]] = None, # 【可选】自定义文档ID **kwargs, ) -> List[str] # 返回新增文档的ID列表 ``` ### 例子 ```python 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） ```python db.delete( ids: List[str], # 【必选】要删除的文档ID列表 **kwargs, ) -> None ``` ### 例子 ```python 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的文档、元数据、向量（调试/校验必备） ```python 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`，表示内容 ### 例子 ```python 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) ``` # 总结 1. **创建对象核心**：`from_documents()`（新手首选）需指定 `documents` 和 `embedding`，`persist_directory` 决定是否本地持久化；加载已有库用 `Chroma()`，需匹配嵌入模型和集合名； 2. **增删查方法**：`add_documents()`（追加文档）、`delete()`（按ID删）、`get()`（查数据），操作前建议用 `get()` 校验数据； 原文出处：http://malaoshi.top/show_1GW2rqWrlY0W.html