Chroma 教程 收藏

跟 LangChain / LlamaIndex 集成

🎉摘要:了解如何将Chroma作为向量存储集成到LangChain和LlamaIndex框架中,包含安装步骤、代码示例、CrossEncoder重排及完整RAG检索流程。

如果你已经在用这些框架,Chroma 可以作为它们的 vectorstore(向量存储)。

LangChain

LangChain 是一套面向大模型应用的开发框架,不是大模型本身,它不提供 LLM 能力,只是帮你把大模型、向量库、工具、检索、提示词串起来。

核心定位:简化基于 LLM 的应用开发,把 RAG、Agent、工具调用、记忆管理这些通用能力封装成组件,不用自己从零写大量胶水代码。

安装 LangChain

执行下面命令:

pip install langchain-chroma langchain-openai langchain_ollama langchain_text_splitters

安装完成后,执行下面命令验证安装是否成功:

python -c "import langchain_core; print('langchain_core ok')"

执行命令,如果输出“langchain_core ok”,则表示安装成功。

简单示例

下面通过简单示例介绍如何在 LangChain 中使用 Chroma 向量数据库:

import os
import tempfile
from langchain_chroma import Chroma
from langchain_ollama import OllamaEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 持久化示例写到临时目录,工作目录保持干净
os.chdir(tempfile.mkdtemp(prefix="chroma_demo_"))

# 上文用到的定义,直接搬过来,保证这段能独立跑
doc = """
# 退款政策

## 一、申请条件
订单在签收后 7 天内,且商品未影响二次销售的,可以申请无理由退货。
定制类商品、已拆封的音像制品、虚拟商品不在无理由退货范围内。

## 二、申请流程
在"我的订单"页面找到对应订单,点击"申请退款",填写原因并提交。
客服会在 24 小时内审核,审核通过后退款将在 3-5 个工作日退回原支付账户。

## 三、特殊情况
如果商品存在质量问题,不受 7 天限制,可以随时申请,且运费由我们承担。

## 四、发票
电子发票可以在"个人中心-发票管理"里自助开具,开票后 24 小时内发送到预留邮箱。
"""

vectorstore = Chroma(
    collection_name="kb_docs",
    embedding_function=OllamaEmbeddings(model="bge-m3", base_url="http://localhost:11434"),
    persist_directory="./chroma_langchain",
)

# 递归切分文档
# 原文切分成 150 字的文档片段,重叠 30 字
splitter = RecursiveCharacterTextSplitter(chunk_size=150, chunk_overlap=30)

# 创建文档片段
# 每个文档片段的元信息里,都带有 doc_id 字段,用于标记文档片段所属的文档
docs = splitter.create_documents([doc], metadatas=[{"doc_id": "refund_policy"}])

# 文档添加到向量存储
# 向量存储会自动将文档片段切分后的向量存储起来
vectorstore.add_documents(docs)

# 做相似度检索
# 挑选相似度最高的前 3 条文档片段(Document)返回
results = vectorstore.similarity_search("怎么退款", k=3)
for idx,r in enumerate(results, 1):
    print(f"{"="*20} {idx} {"="*20}")
    print(f"{r}\n")

运行输出如下:

==================== 1 ====================
page_content='## 二、申请流程
在"我的订单"页面找到对应订单,点击"申请退款",填写原因并提交。
客服会在 24 小时内审核,审核通过后退款将在 3-5 个工作日退回原支付账户。

## 三、特殊情况
如果商品存在质量问题,不受 7 天限制,可以随时申请,且运费由我们承担。' metadata={'doc_id': 'refund_policy'}

==================== 2 ====================
page_content='# 退款政策

## 一、申请条件
订单在签收后 7 天内,且商品未影响二次销售的,可以申请无理由退货。
定制类商品、已拆封的音像制品、虚拟商品不在无理由退货范围内。' metadata={'doc_id': 'refund_policy'}

==================== 3 ====================
page_content='## 四、发票
电子发票可以在"个人中心-发票管理"里自助开具,开票后 24 小时内发送到预留邮箱。' metadata={'doc_id': 'refund_policy'}

我们还可以使用 CrossEncoder 实现粗召回 + 重排,代码如下:

import os
from typing import List

from langchain_core.callbacks import CallbackManagerForRetrieverRun
from langchain_core.documents import Document
from langchain_core.retrievers import BaseRetriever

# 国内直接连 hf 下载容易超时,用国内镜像
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

import tempfile
from langchain_chroma import Chroma
from langchain_ollama import OllamaEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter
from sentence_transformers import CrossEncoder

# 持久化示例写到临时目录,工作目录保持干净
os.chdir(tempfile.mkdtemp(prefix="chroma_demo_"))

# 上文用到的定义,直接搬过来,保证这段能独立跑
doc = """
# 退款政策

## 一、申请条件
订单在签收后 7 天内,且商品未影响二次销售的,可以申请无理由退货。
定制类商品、已拆封的音像制品、虚拟商品不在无理由退货范围内。

## 二、申请流程
在"我的订单"页面找到对应订单,点击"申请退款",填写原因并提交。
客服会在 24 小时内审核,审核通过后退款将在 3-5 个工作日退回原支付账户。

## 三、特殊情况
如果商品存在质量问题,不受 7 天限制,可以随时申请,且运费由我们承担。

## 四、发票
电子发票可以在"个人中心-发票管理"里自助开具,开票后 24 小时内发送到预留邮箱。
"""

# 向量存储
# 向量存储会自动将文档片段切分后的向量存储起来
vectorstore = Chroma(
    collection_name="kb_docs",
    embedding_function=OllamaEmbeddings(model="bge-m3", base_url="http://localhost:11434"),
    persist_directory="./chroma_langchain",
)
# 递归切分文档
# 原文切分成 150 字的文档片段,重叠 30 字
splitter = RecursiveCharacterTextSplitter(chunk_size=150, chunk_overlap=30)
docs = splitter.create_documents([doc], metadatas=[{"doc_id": "refund_policy"}])
vectorstore.add_documents(docs)


class BGERerankRetriever(BaseRetriever):
    """包装原始retriever,实现:粗召回 -> cross-encoder重排 -> 返回top_n"""
    # 原始retriever
    base_retriever: BaseRetriever
    # 重排模型
    # 重排模型输入:query-doc对,输出:分数,分数越高越相关
    reranker_model: CrossEncoder
    # 重排之后最终保留多少条
    rerank_top_n: int = 5

    def _get_relevant_documents(
        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
    ) -> List[Document]:
        # 第一步:粗召回
        docs = self.base_retriever.invoke(query)
        if not docs:
            return []

        # 构造 query-doc 配对给cross-encoder
        pairs = [[query, doc.page_content] for doc in docs]
        scores = self.reranker_model.predict(pairs)

        # 把文档和分数绑定、按分数降序
        scored_docs = list(zip(docs, scores))
        scored_docs.sort(key=lambda x: x[1], reverse=True)

        # 取重排后topN
        final_docs = [item[0] for item in scored_docs[:self.rerank_top_n]]
        return final_docs


# 测试调用
if __name__ == "__main__":
    # 当 retriever 用,粗召回5条
    retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
    # 组装成【粗召回+重排】的检索器
    retriever = BGERerankRetriever(
        base_retriever=retriever,
        # 加载BGE重排模型
        reranker_model=CrossEncoder("BAAI/bge-reranker-base"),
        rerank_top_n=5
    )

    query = "发票怎么开"
    result_docs = retriever.invoke(query)
    print(f"重排后返回 {len(result_docs)} 条:")
    for d in result_docs:
        print("-"*40)
        print(d.page_content)

更多关于 LangChain 库的用法,后续将单独提供教程。

LlamaIndex

LlamaIndex,原来叫 GPT Index,是一个主打数据检索的 RAG 框架,核心定位就是帮大模型对接私有文档、知识库。和 LangChain 不一样,LangChain 是通用大模型应用框架,能做链、Agent、各种复杂流程;LlamaIndex 重心全部放在“文档怎么解析、怎么切分、怎么建索引、怎么精准检索”这件事上。

它里面把文档拆成 Document 和 Node,Node 就相当于我们手写 RAG 里的 chunk。内置了很多索引类型,不只是向量索引,还有摘要索引、树索引、图索引、关键词索引,自带很多高级检索策略:父文档检索、自动合并检索、混合检索、查询拆解,做 RAG 的高级玩法会方便很多。

它的组件链路很清晰:文档加载 → 解析分块(NodeParser) → 建索引入库 → 检索(Retriever) → 后处理(Postprocessor,这里就可以接入我们刚才写的 BGE 重排器) → QueryEngine/ChatEngine 生成回答腾讯云。 它的后处理层就是专门放 rerank、过滤、压缩这些逻辑的,原生就支持接入 cross-encoder 重排。

安装 LlamaIndex

执行下面命令:

pip install llama-index llama-index-vector-stores-chroma llama-index-embeddings-ollama llama-index-llms-ollama chromadb sentence-transformers

安装完成后,执行下面命令验证安装是否成功:

python -c "import llama_index.vector_stores.chroma; print('导入成功!')"

执行命令,如果输出“导入成功!”,则表示安装成功。

简单示例

下面通过一个简单的示例介绍 LlamaIndex 和 Chroma 配合使用:

import os

# 设置HuggingFace国内镜像地址,避免直接访问hf国外站点下载模型超时
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

import tempfile
import chromadb
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core import StorageContext, VectorStoreIndex, Document, Settings
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.embeddings.ollama import OllamaEmbedding
from llama_index.llms.ollama import Ollama
from llama_index.core.postprocessor import SentenceTransformerRerank

# 关闭HuggingFace Hub的软链接警告,减少控制台冗余输出
os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"

# 创建临时目录作为持久化存储目录,避免污染本地工作目录
tmp_dir = tempfile.mkdtemp(prefix="chroma_demo_")
os.chdir(tmp_dir)
print(f"临时工作目录:{tmp_dir}")

# 测试文档:退款政策文本
doc_text = """
# 退款政策

## 一、申请条件
订单在签收后 7 天内,且商品未影响二次销售的,可以申请无理由退货。
定制类商品、已拆封的音像制品、虚拟商品不在无理由退货范围内。

## 二、申请流程
在"我的订单"页面找到对应订单,点击"申请退款",填写原因并提交。
客服会在 24 小时内审核,审核通过后退款将在 3-5 个工作日退回原支付账户。

## 三、特殊情况
如果商品存在质量问题,不受 7 天限制,可以随时申请,且运费由我们承担。

## 四、发票
电子发票可以在"个人中心-发票管理"里自助开具,开票后 24 小时内发送到预留邮箱。
"""

# 初始化Ollama Embedding模型,使用bge-m3做向量化
embed_model = OllamaEmbedding(
    model_name="bge-m3",
    base_url="http://localhost:11434",
    timeout=60,
)
# 初始化Ollama大模型,用于最终回答生成
llm = Ollama(model="qwen2:0.5b", base_url="http://localhost:11434", timeout=120)

# 全局配置:指定默认Embedding模型与LLM模型
Settings.embed_model = embed_model
Settings.llm = llm

# 初始化Chroma持久化客户端,向量数据保存在本地 ./chroma_llama
# 由于上面将工作目录指定到了临时目录,所以向量数据也保存在临时目录,进程退出时会自动删除
client = chromadb.PersistentClient(path="./chroma_llama")
# 获取或新建向量集合collection
collection = client.get_or_create_collection("kb_docs")
# 包装成LlamaIndex可用的向量存储对象
vector_store = ChromaVectorStore(chroma_collection=collection)
# 构造存储上下文,绑定向量库
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 构造LlamaIndex文档对象,挂载元数据doc_id用于区分文档
llama_doc = Document(text=doc_text, metadata={"doc_id": "refund_policy"})

# 句子切分器:控制分块大小与重叠
# chunk_size:单块最大token数;chunk_overlap:块之间重叠token,用来保留上下文
splitter = SentenceSplitter(chunk_size=150, chunk_overlap=30)

# 构建向量索引
# transformations:文档预处理流水线,这里传入分块器
# show_progress:打印构建进度条
index = VectorStoreIndex.from_documents(
    documents=[llama_doc],
    storage_context=storage_context,
    transformations=[splitter],
    show_progress=True,
)

# 初始化BGE重排器:对粗召回的节点做二次排序,提升相关性
# top_n:重排之后保留多少条片段
rerank = SentenceTransformerRerank(
    model="BAAI/bge-reranker-base",
    top_n=3
)

# 构建查询引擎
# similarity_top_k:向量粗召回先取出5条
# node_postprocessors:后置处理器,这里加入重排组件
query_engine = index.as_query_engine(
    similarity_top_k=5,
    node_postprocessors=[rerank]
)

# 测试提问
question = "怎么退款"
resp = query_engine.query(question)
print(f"问题:{question}")
print(f"回答:{resp}")
print(f"一共检索到 {len(resp.source_nodes)} 个片段:")
# 遍历打印检索出来的原文片段、重排分数
for idx,node in enumerate(resp.source_nodes,1):
    print(f"片段{idx}, score: {node.score}")
    print(node.text)
    print("\n")

运行代码,效果如下:

临时工作目录:C:\Users\ADMINI~1\AppData\Local\Temp\chroma_demo_gn48dj39
Applying transformations: 100%|██████████| 1/1 [00:01<00:00,  1.30s/it]
Generating embeddings: 100%|██████████| 2/2 [00:03<00:00,  1.92s/it]
Loading weights: 100%|██████████| 201/201 [00:00<00:00, 787.04it/s]
问题:怎么退款
回答:在申请无理由退货时,你需要在"我的订单"页面找到订单并点击"申请退款",填写原因并提交。
一共检索到 2 个片段:
片段1, score: 0.9564008116722107
# 退款政策

## 一、申请条件
订单在签收后 7 天内,且商品未影响二次销售的,可以申请无理由退货。
定制类商品、已拆封的音像制品、虚拟商品不在无理由退货范围内。

## 二、申请流程
在"我的订单"页面找到对应订单,点击"申请退款",填写原因并提交。


片段2, score: 0.5883668661117554
客服会在 24 小时内审核,审核通过后退款将在 3-5 个工作日退回原支付账户。

## 三、特殊情况
如果商品存在质量问题,不受 7 天限制,可以随时申请,且运费由我们承担。

## 四、发票
电子发票可以在"个人中心-发票管理"里自助开具,开票后 24 小时内发送到预留邮箱。

输出效果和我们前面自己编写的效果类似。

我建议:中小项目直接用原生 Chroma API 就够了,框架会带来额外的抽象层和版本耦合。等你真的需要框架里的 chain / agent / 多模态解析那些能力时再引入。

关于更多 LlamaIndex 的知识后续将使用单独的教程进行介绍。

  

说说我的看法
全部评论()
没有评论
关于
本网站专注于 Java、数据库(MySQL、Oracle)、Linux、软件架构及大数据等多领域技术知识分享。涵盖丰富的原创与精选技术文章,助力技术传播与交流。无论是技术新手渴望入门,还是资深开发者寻求进阶,这里都能为您提供深度见解与实用经验,让复杂编码变得轻松易懂,携手共赴技术提升新高度。如有侵权,请来信告知:hxstrive@outlook.com
其他应用
公众号