大模型应用：LlamaIndex 与 LangChain 深度集成构建本地化RAG系统.25

原创

未闻花名

发布于 2026-02-22 10:09:21

4300

一、引言

大模型在生成信息时可能出现幻觉问题，生成看似合理但实际错误或不存在的内容，同时，模型存在知识边界限制，其知识受限于训练数据的时间截点和覆盖范围，无法获取实时信息或特定领域深度知识。为解决这些问题，通常采用检索增强生成（RAG）技术，结合外部知识库实时检索来修正和补充模型知识；通过提示工程明确约束生成范围；建立事实核查和置信度评估机制。

这些方法显著提升了生成内容的准确性和可靠性，扩展了模型的实际应用边界，而 LlamaIndex 与 LangChain 作为 RAG 生态的两大核心工具，前者擅长文档索引与语义检索，后者强于 LLM 工作流编排与提示工程。传统 RAG 实践多依赖 OpenAI 等云端模型，存在数据安全风险与 API 成本问题；今天我们还是以本地化 Qwen1.5-1.8B-Chat 模型为基座，通过两个递进式示例，深度解析 LlamaIndex 与 LangChain 的集成逻辑，从极简版 “功能验证” 到生产级 “工程化落地”，揭示这两个框架如何各司其职、协同增效，构建全本地化、高可控的智能文档问答系统。

二、核心要点

1. 基础介绍

LlamaIndex：

核心能力：文档处理、分块、向量索引、语义检索
核心优势：文档理解与检索一体化，索引管理轻量化
实际应用：文档加载、分块配置、向量索引构建 / 加载、上下文检索

LangChain：

核心能力：LLM 封装、提示工程、工作流编排
核心优势：模块化链设计，适配多类 LLM，输出解析灵活
实际应用：本地 Qwen 模型封装、提示模板定义、RAG 链编排、交互式问答

2. 集成分工

LlamaIndex 与 LangChain 的集成遵循 “分工协作” 原则：

LlamaIndex负责“数据层”：文档→分块→向量化→索引→上下文检索
LangChain负责“推理层”：上下文+问题→提示模板→LLM生成→回答解析

两者通过 “检索结果（上下文文本）” 完成数据流转，形成 RAG 闭环。

3. 关键概念

向量索引：将文档片段转为 Embedding 向量并存储，通过VectorStoreIndex构建，新增持久化逻辑
检索器（Retriever）：基于问题语义匹配向量索引，使用index.as_retriever，并封装为VectorIndexRetriever
LLM Pipeline 封装：将本地 Qwen 模型转为 LangChain 兼容接口，通过HuggingFacePipeline实现
Runnable 链：LangChain 的声明式工作流，通过RunnablePassthrough实现 “问题→检索→提示→生成” 的自动化流转
索引持久化：新增StorageContext处理，将索引保存到./storage，避免重复加载文档/向量化

三、示例分析

我们结合两个示例，由浅入深、循序渐进的差异化讲解设计逻辑和价值体现

1. 轻量化 RAG

1.1 基础定位

本地化 RAG 实现，聚焦 “快速验证核心流程”，剥离所有工程化冗余，仅保留 RAG 的核心闭环：文档加载→索引构建→上下文检索→LLM 生成回答。

1.2 核心功能

完成本地 Qwen1.5-1.8B-Chat 模型的下载与基础封装；
通过 LlamaIndex 实现文档加载、向量索引构建（内存级）和语义检索；
借助 LangChain 完成提示模板定义与本地 LLM 调用；
以固定问题 “文档中提到的 RAG 核心步骤有哪些？” 完成单次问答验证。

1.3 示例特点

代码量少，逻辑线性，无函数封装（仅检索 / 问答简单封装）；
索引仅存于内存，程序重启后需重新加载文档、构建索引；
无异常处理、无交互式问答，仅满足 “能跑通、能回答” 的基础需求。

2. 工程化 RAG

2.1 基础定位

可落地的工程化版本，在示例 1 的基础上补充工程化能力，聚焦 “实用性、可复用性、稳定性”，适配真实场景下的 RAG 系统需求。

2.2 核心功能

继承示例 1 的本地模型 / Embedding 本地化核心；
新增 LlamaIndex 全局配置（分块大小、重叠度），优化文档处理效果；
实现索引持久化（保存到./storage），避免重复构建索引；
封装检索器、索引管理、RAG 链等核心逻辑为可复用函数；
基于 LangChain 声明式 RAG 链实现 “检索→提示→生成→解析” 自动化流转；
新增交互式问答循环、异常捕获，提升用户体验与系统稳定性。

2.3 示例特点

代码模块化（索引管理、检索器、RAG 链、主流程分离），便于维护与扩展；
支持增量使用（索引持久化），大幅降低重复运行的时间 / 资源消耗；
具备直接部署使用得能力（交互性、异常处理、配置可定制）。

3. 差异对比

核心目标：

基础版验证本地化 RAG 核心流程是否可行
升级版实现可落地、可复用的本地化 RAG 系统

索引管理：

基础版内存临时索引，程序重启后丢失
升级版索引持久化到本地，首次构建后复用

代码结构：

基础版线性代码为主，仅简单函数封装
升级版模块化函数封装（索引管理、检索器、RAG 链），职责分离

LlamaIndex 配置：

基础版仅配置 Embedding，分块 / LLM 使用默认值
升级版全局配置分块参数，LlamaIndex 直接集成本地 LLM

LangChain 能力：

基础版手动拼接提示、调用 LLM，无输出解析
升级版声明式 RAG 链，自动流转，StrOutputParser 解析输出

交互方式：

基础版单次固定问题测试
升级版交互式循环问答，支持 exit 退出，异常捕获

扩展能力：

基础版几乎无扩展空间，仅能修改问题/文档
升级版支持元数据过滤、混合检索、模型量化等扩展，适配真实场景

四、代码分解

1. 本地 Qwen 模型加载

# 核心代码段
local_model_path = snapshot_download(MODEL_NAME, cache_dir=CACHE_DIR)
tokenizer = AutoTokenizer.from_pretrained(local_model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    local_model_path, trust_remote_code=True, device_map="auto"
)

关键分析：

trust_remote_code=True：Qwen 模型依赖自定义代码，必须开启；
device_map="auto"：自动适配 GPU/CPU，示例未指定 CUDA 时自动降级到 CPU 运行；
模型下载逻辑：首次运行从 ModelScope 下载（约 3.6GB），后续读取本地缓存，无需重复下载。

2. 本地化的 Embedding 模型

# 配置本地Embedding（中文优化）
Settings.embed_model = HuggingFaceEmbedding(
    model_name="D:/modelscope/hub/models/sentence-transformers/paraphrase-MiniLM-L6-v2",
    model_kwargs={"device": "cpu"},
    embed_batch_size=16
)

model_name：指定本地已下载的 Embedding 模型路径（这里是paraphrase-MiniLM-L6-v2，轻量且适配中文语义，存储在 ModelScope 本地缓存目录）；
model_kwargs={"device": "cpu"}：指定模型运行在 CPU 上（无 GPU 也可使用，若有 GPU 可改为"cuda"加速）；
embed_batch_size=16：批量处理文本向量化的批次大小，平衡处理速度与内存占用。
为 LlamaIndex 的向量索引构建、语义检索提供基础（文档 / 问题需转为向量才能做相似度匹配）；
实现完全本地化向量化，无需调用外部 API，paraphrase-MiniLM-L6-v2轻量化且语义表征效果好，适合中小规模 RAG 系统。

3. LlamaIndex 索引构建与检索

3.1 简单版

# 索引构建（无持久化）
documents = SimpleDirectoryReader(input_dir="./docs").load_data()
index = VectorStoreIndex.from_documents(documents)

# 检索函数
def get_context(query):
    retriever = index.as_retriever(similarity_top_k=3)
    nodes = retriever.retrieve(query)
    return "\n\n".join([node.text for node in nodes])

特点：

极简流程，适合快速验证 RAG 核心逻辑；
索引仅存在于内存，程序退出后丢失；
检索器直接由索引转换，无扩展配置（如元数据过滤）。

3.2 升级版

# 索引管理函数（核心升级）
def build_or_load_index(doc_dir: str = "./docs", index_dir: str = "./storage"):
    if not os.path.exists(index_dir):
        documents = SimpleDirectoryReader(input_dir=doc_dir, recursive=True).load_data()
        index = VectorStoreIndex.from_documents(documents)
        index.storage_context.persist(persist_dir=index_dir)  # 持久化
    else:
        storage_context = StorageContext.from_defaults(persist_dir=index_dir)
        index = load_index_from_storage(storage_context)  # 加载本地索引
    return index

# 检索器优化
def get_optimized_retriever(index, top_k: int = 3):
    retriever = VectorIndexRetriever(
        index=index, similarity_top_k=top_k
        # 可扩展：元数据过滤、相似度阈值等
    )
    return retriever

特点：

索引持久化：通过storage_context.persist将索引保存到./storage，解决 “重复构建索引” 的效率问题；
文档加载增强：recursive=True支持递归读取子目录文档，required_exts过滤文件格式；
检索器封装：VectorIndexRetriever支持更多扩展配置（如示例中注释的元数据过滤），为生产场景预留扩展空间；
全局分块配置：Settings.chunk_size=512/chunk_overlap=50，优化分块粒度，避免语义断裂。

4. LangChain RAG 链设计

4.1 简单版-手动拼接

# 提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "仅根据上下文回答问题...上下文：{context}"),
    ("human", "{question}")
])

# 问答逻辑（手动调用）
def answer_question(question):
    context = get_context(question)
    final_prompt = prompt.format(context=context, question=question)
    response = llm.invoke(final_prompt)
    return response

特点：

手动完成 “检索→提示拼接→LLM 调用”，流程直观但耦合度高；
无输出解析，直接返回 LLM 原始生成结果；
仅支持单次固定问题测试，无交互性。

4.2 升级版-声明式链

# RAG链构建（核心升级）
def build_rag_chain(retriever):
    def retrieve_context(query: str) -> str:
        nodes = retriever.retrieve(query)
        return "\n\n".join([node.text for node in nodes])

    prompt = ChatPromptTemplate.from_messages([...])  # 增强指令约束
    rag_chain = (
        {"context": RunnablePassthrough() | retrieve_context, "question": RunnablePassthrough()}
        | prompt
        | langchain_llm
        | StrOutputParser()  # 输出解析为纯文本
    )
    return rag_chain

特点：

声明式链编排：通过RunnablePassthrough实现 “用户问题” 同时传递给 “检索函数” 和 “提示模板”，无需手动拼接；
输出解析：StrOutputParser将 LLM 生成的复杂结果转为纯文本，提升回答可读性；
提示模板增强：新增多规则约束（如 “无信息时明确说明”），减少 LLM 幻觉；
交互式问答：主函数新增循环逻辑，支持持续提问，异常捕获避免程序崩溃。

5. 升级价值体现

升级版新增Settings.llm = HuggingFaceLLM(...)，实现 LlamaIndex 直接调用本地 Qwen 模型，而非仅依赖 LangChain 的 LLM 封装，核心价值：

LlamaIndex 的检索优化（如混合检索、路由检索）可直接使用本地模型；
统一 LLM 配置，避免 LlamaIndex 与 LangChain 分别配置模型的冗余问题；
为后续扩展（如 LlamaIndex 的 QueryEngine）奠定基础。

6. 示例运行

6.1 轻量化RAG系统

import os
from modelscope.hub.snapshot_download import snapshot_download
# LlamaIndex核心模块
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
# LangChain核心模块
from langchain_community.llms.huggingface_pipeline import HuggingFacePipeline
from langchain_core.prompts import ChatPromptTemplate
# HuggingFace模型加载
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline

# ===================== 1. 本地Qwen模型配置（核心改造） =====================
# 模型信息
MODEL_NAME = "qwen/Qwen1.5-1.8B-Chat"
CACHE_DIR = "D:\\modelscope\\hub"  # 模型下载/缓存目录

# 下载模型（首次运行自动下载，后续跳过）
print("正在加载/下载Qwen模型...")
local_model_path = snapshot_download(MODEL_NAME, cache_dir=CACHE_DIR)

# 加载Tokenizer和Model（适配Qwen1.5）
tokenizer = AutoTokenizer.from_pretrained(
    local_model_path,
    trust_remote_code=True,
    cache_dir=CACHE_DIR
)
model = AutoModelForCausalLM.from_pretrained(
    local_model_path,
    trust_remote_code=True,
    cache_dir=CACHE_DIR,
    device_map="auto",  # 自动分配GPU/CPU
    torch_dtype="auto"
)

# 配置LlamaIndex本地Embedding（替代OpenAI Embedding）
Settings.embed_model = HuggingFaceEmbedding(
    model_name="D:/modelscope/hub/models/sentence-transformers/paraphrase-MiniLM-L6-v2",  # 中文轻量Embedding
    model_kwargs={"device": "cpu"}
)

# ===================== 2. LlamaIndex：加载文档+构建索引 =====================
# 加载单个PDF/TXT文档（放入./docs目录）
documents = SimpleDirectoryReader(input_dir="./docs").load_data()
# 构建向量索引（自动分块+本地向量化）
index = VectorStoreIndex.from_documents(documents)

# ===================== 3. LlamaIndex：检索相关上下文 =====================
def get_context(query):
    # 检索相似度前3的文档片段
    retriever = index.as_retriever(similarity_top_k=3)
    nodes = retriever.retrieve(query)
    # 拼接上下文
    return "\n\n".join([node.text for node in nodes])

# ===================== 4. LangChain：本地Qwen模型+提示模板 =====================
# 构建HF Pipeline（适配LangChain）
qwen_pipeline = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    max_new_tokens=512,  # 最大生成token数
    temperature=0.1,     # 生成随机性
    top_p=0.95,
    repetition_penalty=1.15,
    device_map="auto"
)
# 封装为LangChain兼容的LLM
llm = HuggingFacePipeline(pipeline=qwen_pipeline)

# 提示模板（适配Qwen的指令格式）
prompt = ChatPromptTemplate.from_messages([
    ("system", "仅根据上下文回答问题，无相关信息则说“无法回答”。上下文：{context}"),
    ("human", "{question}")
])

# ===================== 5. 问答逻辑 =====================
def answer_question(question):
    context = get_context(question)
    # 组装提示并调用本地Qwen模型
    final_prompt = prompt.format(context=context, question=question)
    response = llm.invoke(final_prompt)
    return response

# ===================== 6. 测试 =====================
if __name__ == "__main__":
    query = "文档中提到的RAG核心步骤有哪些？"
    print("问题：", query)
    print("回答：", answer_question(query))

6.2 工程化的RAG系统

import os
from dotenv import load_dotenv
from modelscope.hub.snapshot_download import snapshot_download
# LlamaIndex核心模块
from llama_index.core import (
    SimpleDirectoryReader, VectorStoreIndex, StorageContext,
    load_index_from_storage, Settings
)
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.llms.huggingface import HuggingFaceLLM  # LlamaIndex适配HF模型
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# LangChain核心模块
from langchain_community.llms.huggingface_pipeline import HuggingFacePipeline
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
# HuggingFace模型加载
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline

# ===================== 1. 本地模型配置（核心改造） =====================
# 模型信息
MODEL_NAME = "qwen/Qwen1.5-1.8B-Chat"
CACHE_DIR = "D:\\modelscope\\hub"  # 模型下载目录

# 下载模型（首次运行自动下载，后续跳过）
print("开始下载/加载模型...")
local_model_path = snapshot_download(MODEL_NAME, cache_dir=CACHE_DIR)
print(f"模型本地路径：{local_model_path}")

# 加载Tokenizer和Model（适配Qwen1.5）
tokenizer = AutoTokenizer.from_pretrained(
    local_model_path,
    trust_remote_code=True,
    cache_dir=CACHE_DIR
)
model = AutoModelForCausalLM.from_pretrained(
    local_model_path,
    trust_remote_code=True,
    cache_dir=CACHE_DIR,
    device_map="auto",  # 自动分配GPU/CPU
    torch_dtype="auto"
)

# ===================== 2. 全局配置 =====================
# LlamaIndex全局配置
Settings.chunk_size = 512          # 文档分块大小
Settings.chunk_overlap = 50        # 分块重叠
# 配置LlamaIndex的LLM为本地Qwen
Settings.llm = HuggingFaceLLM(
    model=model,
    tokenizer=tokenizer,
    context_window=4096,           # Qwen1.5-1.8B上下文窗口
    max_new_tokens=512,            # 最大生成token数
    generate_kwargs={"temperature": 0.1},  # 生成参数
    model_kwargs={"device_map": "auto"}
)
# 配置本地Embedding（中文优化）
Settings.embed_model = HuggingFaceEmbedding(
    model_name="D:/modelscope/hub/models/sentence-transformers/paraphrase-MiniLM-L6-v2",
    model_kwargs={"device": "cpu"},
    embed_batch_size=16
)

# LangChain配置：将本地Qwen封装为LangChain LLM
# 构建HF Pipeline
qwen_pipeline = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    max_new_tokens=512,
    temperature=0.1,
    top_p=0.95,
    repetition_penalty=1.15,
    device_map="auto"
)
# 封装为LangChain LLM
langchain_llm = HuggingFacePipeline(pipeline=qwen_pipeline)

# ===================== 3. 索引管理 =====================
def build_or_load_index(doc_dir: str = "./docs", index_dir: str = "./storage"):
    """构建或加载向量索引（避免重复构建）"""
    if not os.path.exists(index_dir):
        # 加载文档（支持PDF/TXT，递归读取）
        reader = SimpleDirectoryReader(
            input_dir=doc_dir,
            required_exts=[".pdf", ".txt"],
            recursive=True
        )
        documents = reader.load_data()
        print(f"加载文档数量：{len(documents)}")

        # 构建向量索引
        index = VectorStoreIndex.from_documents(documents)
        # 持久化索引到本地
        index.storage_context.persist(persist_dir=index_dir)
        print("索引构建并保存完成")
    else:
        # 加载本地索引
        storage_context = StorageContext.from_defaults(persist_dir=index_dir)
        index = load_index_from_storage(storage_context)
        print("加载本地索引完成")
    return index

# ===================== 4. 检索器配置 =====================
def get_optimized_retriever(index, top_k: int = 3):
    """获取优化的向量检索器"""
    retriever = VectorIndexRetriever(
        index=index,
        similarity_top_k=top_k,
        # 可选：元数据过滤（如只检索指定文档）
        # filters=[MetadataFilter(key="source", value="example.pdf")]
    )
    return retriever

# ===================== 5. LangChain RAG链构建 =====================
def build_rag_chain(retriever):
    """构建本地化RAG链"""
    # 检索上下文函数
    def retrieve_context(query: str) -> str:
        nodes = retriever.retrieve(query)
        return "\n\n".join([node.text for node in nodes])

    # 提示模板（适配Qwen的指令格式）
    prompt = ChatPromptTemplate.from_messages([
        ("system", """
        你是智能文档问答助手，严格遵循以下规则：
        1. 仅使用提供的上下文回答用户问题；
        2. 如果上下文没有相关信息，明确说明“无法从文档中找到相关答案”；
        3. 回答简洁、准确，使用中文表述。
        上下文：{context}
        """),
        ("human", "{question}")
    ])

    # 构建RAG链
    rag_chain = (
        {"context": RunnablePassthrough() | retrieve_context, "question": RunnablePassthrough()}
        | prompt
        | langchain_llm
        | StrOutputParser()
    )
    return rag_chain

# ===================== 6. 主函数（交互式问答） =====================
def main():
    # 步骤1：构建/加载索引
    index = build_or_load_index(doc_dir="./docs", index_dir="./storage")

    # 步骤2：初始化检索器
    retriever = get_optimized_retriever(index, top_k=3)

    # 步骤3：构建RAG链
    rag_chain = build_rag_chain(retriever)

    # 步骤4：交互式问答
    print("\n===== 本地化RAG问答系统（Qwen1.5-1.8B-Chat） =====")
    print("输入 'exit' 退出问答")
    while True:
        query = input("\n请输入问题：")
        if query.lower() == "exit":
            print("退出系统...")
            break
        
        # 调用RAG链生成回答
        try:
            response = rag_chain.invoke(query)
            print(f"\n回答：\n{response}")
        except Exception as e:
            print(f"回答生成失败：{str(e)}")

if __name__ == "__main__":
    main()

五、总结

LlamaIndex 与 LangChain的深度集成，本质是专业工具做专业事的应用化实践：LlamaIndex 解决了 RAG 的数据处理与检索的痛点，LangChain 解决了LLM 调用与流程编排的痛点。今天我们通过两个递进式示例，从极简验证到生产级落地，完整展现了双工具集成的核心逻辑与本地化改造路径，既保留了 RAG 的核心价值解决 LLM 幻觉，又实现了全流程的本地化可控，为RAG 系统的落地提供了构建的思路，也可进行针对性的自定义优化以达到更精确的效果。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

第四期热点征文-大模型技术

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

第四期热点征文-大模型技术

#LlamaIndex

#LangChain

登录后参与评论

0 条评论

热度