langchain_chroma.Chroma 是 LangChain 提供的向量存储类，与 Chroma 数据库交互，用于存储嵌入向量并进行高效相似性搜索，广泛应用于检索增强生成（RAG）系统。

本文基于 LangChain 0.3.x，详细介绍 langchain_chroma.Chroma 的核心方法、功能及其在 RAG 系统中的典型应用，并提供一个独立示例，展示如何使用这些方法构建 RAG 系统。示例包含 PDF 加载（langchain_community.document_loaders.PyPDFLoader）、分割、嵌入生成和查询。

---

langchain_chroma.Chroma 简介

langchain_chroma.Chroma 是 LangChain 的 Chroma 向量存储包装器，连接 Chroma 数据库（一个开源的轻量级向量数据库），支持存储嵌入向量和元数据，执行高效的向量搜索（如余弦相似度）。它继承自 LangChain 的 VectorStore 基类，提供标准化的向量存储接口，适合本地开发和中小规模 RAG 系统。

核心功能：

• 存储文档的嵌入向量（由嵌入模型如 OpenAIEmbeddings 生成）。
• 支持快速相似性搜索，返回与查询最相关的文档。
• 提供 LangChain 检索器接口，集成 RAG 管道。
• 支持持久化存储（保存到磁盘）或内存模式。

初始化参数：

• embedding_function（必填）：嵌入模型（如 OpenAIEmbeddings）。
• collection_name（默认 "langchain"）：集合名称。
• persist_directory（可选）：持久化存储路径。
• client（可选）：自定义 Chroma 客户端。
• collection_metadata（可选）：集合元数据（如 {"hnsw:space": "cosine"}）。

适用场景：

• 本地 RAG 系统，处理文档、PDF 等。
• 快速原型设计或测试。
• 需要轻量级向量存储的应用。

---

Chroma 常用方法

以下是 langchain_chroma.Chroma 类的常用方法，基于源码（langchain_chroma/vectorstores.py）和官方文档（Chroma Vector Store）。我将列出方法签名、参数、返回值、功能描述及使用场景。

1. add_documents(documents: List[Document], **kwargs) -> List[str]

• 功能：将文档列表添加到 Chroma 集合，生成嵌入向量并存储。
• 参数：
  • documents：List[Document]，包含 page_content 和 metadata 的文档列表。
  • **kwargs：附加参数，如 ids（自定义文档 ID）。
• 返回值：List[str]，插入文档的 ID 列表。
• 使用场景：
  • 初始化向量存储，批量导入文档。
  • 更新集合，添加新文档。
• 示例：

  from langchain_core.documents import Document
  documents = [Document(page_content="示例文本", metadata={"source": "test"})]
  vectorstore.add_documents(documents)
  

2. add_texts(texts: Iterable[str], metadatas: Optional[List[dict]] = None, **kwargs) -> List[str]

• 功能：将文本列表添加到 Chroma 集合，生成嵌入并存储。
• 参数：
  • texts：文本字符串迭代器。
  • metadatas：可选的元数据列表，与文本对应。
  • **kwargs：附加参数，如 ids。
• 返回值：List[str]，插入文本的 ID 列表。
• 使用场景：
  • 直接添加原始文本（无 Document 对象）。
  • 适合轻量级数据导入。
• 示例：

  texts = ["物联网是连接物理设备的技术"]
  metadatas = [{"source": "iot"}]
  vectorstore.add_texts(texts, metadatas)
  

3. as_retriever(**kwargs) -> VectorStoreRetriever

• 功能：将 Chroma 向量存储转换为 LangChain 检索器，用于 RAG 管道。
• 参数：
  • search_type（默认 "similarity"）：搜索类型（"similarity", "mmr", "similarity_score_threshold"）。
  • search_kwargs：搜索参数，如 k（返回文档数）、filter（元数据过滤）、score_threshold（得分阈值）。
• 返回值：VectorStoreRetriever，可用于检索相关文档。
• 使用场景：
  • 在 RAG 系统中检索与查询最相关的文档。
  • 支持元数据过滤（如 filter={"source": "iot"}）。
• 示例：

  retriever = vectorstore.as_retriever(search_kwargs={"k": 2, "filter": {"source": "iot"}})
  docs = retriever.invoke("什么是物联网？")
  

4. similarity_search(query: str, k: int = 4, **kwargs) -> List[Document]

• 功能：根据查询文本执行相似性搜索，返回最相关的文档。
• 参数：
  • query：查询字符串。
  • k：返回文档数量。
  • **kwargs：附加参数，如 filter（元数据过滤）。
• 返回值：List[Document]，包含匹配的文档。
• 使用场景：
  • 手动测试向量搜索效果。
  • 调试或小规模检索。
• 示例：

  docs = vectorstore.similarity_search("什么是物联网？", k=2, filter={"source": "iot"})
  for doc in docs:
      print(doc.page_content)
  

5. similarity_search_with_score(query: str, k: int = 4, **kwargs) -> List[Tuple[Document, float]]

• 功能：执行相似性搜索，返回文档及其相似度得分。
• 参数：
  • query：查询字符串。
  • k：返回文档数量。
  • **kwargs：如 filter。
• 返回值：List[Tuple[Document, float]]，文档和得分（取决于距离 metric，如余弦距离）。
• 使用场景：
  • 评估搜索结果的置信度。
  • 调试或优化检索阈值。
• 示例：

  results = vectorstore.similarity_search_with_score("什么是物联网？", k=2)
  for doc, score in results:
      print(f"Content: {doc.page_content}, Score: {score}")
  

6. delete_collection() -> None

• 功能：删除当前 Chroma 集合。
• 参数：无。
• 返回值：无。
• 使用场景：
  • 清理旧数据或重置集合。
  • 测试时删除临时集合。
• 示例：

  vectorstore.delete_collection()
  

7. persist() -> None

• 功能：将 Chroma 集合持久化到磁盘（需指定 persist_directory）。
• 参数：无。
• 返回值：无。
• 使用场景：
  • 保存向量存储以供后续加载。
  • 确保数据在程序重启后保留。
• 示例：

  vectorstore = Chroma(..., persist_directory="./chroma_db")
  vectorstore.persist()  # 最新版已不再支持，会自动进行持久化
  

8. from_documents(cls, documents: List[Document], embedding: Embeddings, **kwargs) -> Chroma

• 功能：类方法，从文档列表创建 Chroma 向量存储实例并添加文档。
• 参数：
  • documents：List[Document]，文档列表。
  • embedding：嵌入模型。
  • **kwargs：如 collection_name、persist_directory。
• 返回值：Chroma 实例。
• 使用场景：
  • 一次性创建并填充向量存储。
  • 简化初始化流程。
• 示例：

  from langchain_openai import OpenAIEmbeddings
  vectorstore = Chroma.from_documents(documents, OpenAIEmbeddings(), collection_name="test")
  

9. from_texts(cls, texts: List[str], embedding: Embeddings, metadatas: Optional[List[dict]] = None, **kwargs) -> Chroma

• 功能：类方法，从文本列表创建 Chroma 向量存储并添加文本。
• 参数：
  • texts：文本列表。
  • embedding：嵌入模型。
  • metadatas：可选的元数据列表。
  • **kwargs：如 collection_name。
• 返回值：Chroma 实例。
• 使用场景：
  • 快速导入原始文本。
  • 测试或小规模数据处理。
• 示例：

  vectorstore = Chroma.from_texts(["测试文本"], OpenAIEmbeddings(), collection_name="test")
  

其他辅助方法

• max_marginal_relevance_search(query: str, k: int = 4, fetch_k: int = 20, **kwargs) -> List[Document]：
  • 使用最大边际相关性（MMR）搜索，优化结果多样性。
  • 场景：避免检索过于相似的文档。
• similarity_search_by_vector(embedding: List[float], k: int = 4, **kwargs) -> List[Document]：
  • 直接使用嵌入向量搜索（不需查询文本）。
  • 场景：已有嵌入向量时直接检索。

---

方法使用场景总结

方法	主要用途	典型场景
add_documents	批量添加文档	初始化 RAG 知识库
add_texts	添加原始文本	轻量级数据导入
as_retriever	转换为 RAG 检索器	构建 RAG 管道
similarity_search	手动相似性搜索	测试检索效果
similarity_search_with_score	带得分搜索	评估检索质量
delete_collection	删除集合	清理或重置数据
persist	持久化存储	保存数据库
from_documents	创建并填充存储	快速初始化
from_texts	从文本创建存储	小规模测试

推荐方法：

• as_retriever：RAG 系统中用于检索。
• add_documents / from_documents：初始化或更新知识库。
• similarity_search：调试和验证。

---

使用 Chroma 常用方法的 RAG 示例

以下示例展示如何使用 langchain_chroma.Chroma 的常用方法（from_documents, as_retriever, similarity_search, persist），构建一个 RAG 系统，加载 PDF 文档（关于大数据分析主题），回答查询。

准备文件：
创建一个 PDF 文件 data_analytics_knowledge.pdf，内容如下（可使用 Word 保存为 PDF）：

大数据分析是从大规模数据集中提取有价值信息的过程。
数据挖掘是大数据分析的核心技术，用于发现模式和关联。
预测分析利用历史数据预测未来趋势。

代码：

import os
os.environ["OPENAI_API_KEY"] = "Your OpenAI API Key"

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_chroma import Chroma
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import PyPDFLoader

# 加载 PDF 文档
loader = PyPDFLoader(file_path="data_analytics_knowledge.pdf")
documents = loader.load()

# 分割文档
splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=20,
    separators=["\n\n", "\n", " ", ""]
)
split_documents = splitter.split_documents(documents)

# 使用 from_documents 创建 Chroma 向量存储
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(
    documents=split_documents,
    embedding=embeddings,
    collection_name="analytics_collection",
    persist_directory="./chroma_db"
)

# 测试 similarity_search
print("测试 similarity_search:")
results = vectorstore.similarity_search("什么是大数据分析？", k=2)
for doc in results:
    print(f"Content: {doc.page_content}")

# 初始化 LLM
llm = ChatOpenAI(temperature=0, model="gpt-4")

# 提示模板
prompt = ChatPromptTemplate.from_template(
    """根据以下上下文回答问题：
上下文：{context}
问题：{question}
回答："""
)

# 格式化文档函数
def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

# 使用 as_retriever 创建 RAG 链
rag_chain = (
    {
        "context": vectorstore.as_retriever(search_kwargs={"k": 2}) | format_docs,
        "question": RunnablePassthrough()
    }
    | prompt
    | llm
    | StrOutputParser()
)

# 调用链
print("\nRAG 链输出：")
response = rag_chain.invoke("什么是大数据分析？")
print(response)
response = rag_chain.invoke("它包含哪些技术？")
print(response)

输出示例：

测试 similarity_search:
Content: 大数据分析是从大规模数据集中提取有价值信息的过程。
Content: 数据挖掘是大数据分析的核心技术，用于发现模式和关联。

RAG 链输出：
大数据分析是从大规模数据集中提取有价值信息的过程。
大数据分析包含技术，如数据挖掘和预测分析。

代码说明

1. 文档加载与分割：
   • PyPDFLoader 加载 data_analytics_knowledge.pdf。
   • RecursiveCharacterTextSplitter 分割为 100 字符块，chunk_overlap=20。
2. 向量存储：
   • Chroma.from_documents 创建并填充 analytics_collection，自动持久化到 ./chroma_db。
3. 方法使用：
   • similarity_search：手动测试检索效果。
   • as_retriever：集成到 RAG 链，检索相关文档。
   • persist：保存数据库到磁盘。
4. RAG 链：
   • retriever 返回 2 个最相关文档。
   • prompt 和 llm（gpt-4）生成答案。

运行要求：

• data_analytics_knowledge.pdf 存在且可读。
• OpenAI API 密钥有效。
• 磁盘有写权限（用于 persist_directory）。

---

注意事项

1. API 密钥：
   • 使用 .env 文件：

     from dotenv import load_dotenv
     load_dotenv()
     

   • 确保密钥支持 text-embedding-3-small 和 gpt-4。
2. 依赖：
   • 安装：

     pip install --upgrade langchain langchain-chroma langchain-openai chromadb pypdf
     

3. Chroma 配置：
   • 验证持久化：

     ls ./chroma_db  # 检查数据库文件
     

   • 清除旧集合：

     vectorstore.delete_collection()
     

4. 性能优化：
   • 调整 chunk_size（500-1000）、search_kwargs={"k": 3}。
   • 添加元数据过滤：

     vectorstore.as_retriever(search_kwargs={"k": 2, "filter": {"source": "data_analytics_knowledge.pdf"}})
     

5. 错误调试：
   • 检查 Chroma 数据库：print(vectorstore._collection.count()) 查看文档数量。
   • 设置 langchain.debug = True 查看 LCEL 链日志。

---

常见问题

Q1：as_retriever 和 similarity_search 的区别？
A：as_retriever 返回可集成到 RAG 链的检索器，适合管道；similarity_search 是手动查询方法，适合调试。

Q2：如何过滤元数据？
A：使用 filter 参数，如 vectorstore.as_retriever(search_kwargs={"filter": {"source": "iot"}})。

Q3：如何加载已有 Chroma 数据库？
A：指定相同的 persist_directory：

vectorstore = Chroma(..., persist_directory="./chroma_db")

Q4：支持哪些搜索类型？
A：支持 "similarity", "mmr", "similarity_score_threshold"，通过 as_retriever(search_type=...) 设置。

---

总结

langchain_chroma.Chroma 的常用方法包括：

• 添加数据：add_documents, add_texts, from_documents, from_texts。
• 检索：as_retriever, similarity_search, similarity_search_with_score。
• 管理：delete_collection, persist.