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

一、引言

大模型在生成信息时可能出现幻觉问题，生成看似合理但实际错误或不存在的内容，同时，模型存在知识边界限制，其知识受限于训练数据的时间截点和覆盖范围，无法获取实时信息或特定领域深度知识。为解决这些问题，通常采用检索增强生成（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 系统的落地提供了构建的思路，也可进行针对性的自定义优化以达到更精确的效果。