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