一、引言

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

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

25.2-LlamaIndex 与 LangChain2.jpg

二、核心要点

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 基础定位

25.3-基础版流程 deepseek_mermaid_20251215_5757d4.png

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

1.2 核心功能

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

1.3 示例特点

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

2. 工程化 RAG

2.1 基础定位

25.4-升级版流程 deepseek_mermaid_20251215_c2843f.png

可落地的工程化版本，在示例 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 系统的落地提供了构建的思路，也可进行针对性的自定义优化以达到更精确的效果。

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

一、引言

二、核心要点

1. 基础介绍

2. 集成分工

3. 关键概念

三、示例分析

1. 轻量化 RAG

2. 工程化 RAG

3. 差异对比

四、代码分解

1. 本地 Qwen 模型加载

2. 本地化的 Embedding 模型

3. LlamaIndex 索引构建与检索

4. LangChain RAG 链设计

5. 升级价值体现

6. 示例运行

6.1 轻量化RAG系统

6.2 工程化的RAG系统

五、总结

通义大模型

热门文章

最新文章

相关电子书