LangChain + RAG 实战：从零构建本地知识库问答系统

简介这份资源是面向AI应用开发者与NLP学习者的LangChainRAG实战项目包聚焦检索增强生成技术的落地实践适合具备一定Python基础、希望深入理解大模型问答系统构建流程的中级开发者。压缩包共6个文件以3个Python脚本、2个Markdown文档和1个依赖清单为主脚本分别承担向量嵌入对比、数据库创建与查询等核心环节文档则提供项目说明与流程指引整体约65KB结构紧凑便于快速上手。目前已有1397人学习下载热度可观。项目通过完整源码与流程教程展示如何搭建开发环境、编写检索与生成代码并进行调试优化读者可据此理解LangChain框架的组件协作方式掌握RAG从文本检索到答案生成的关键链路并迁移至问答系统、对话机器人或智能搜索等场景是学习现代语言处理技术的一份实用范例。1. 从一份 zip 说起LangChain RAG 到底能跑出什么很多人第一次接触 RAG是被“本地知识库”这四个字吸引的把公司文档、产品手册、个人笔记丢进去然后用自然语言提问模型基于这些资料回答而不是凭空编。这个方向最经典的入门组合就是 LangChain RAG。你拿到的是一份名为“Langchain-一个简单的基于LangchainRAG的应用示例-附项目源码流程教程”的 zip它本质上是一个最小可运行的知识库问答原型文档加载、切块、向量化、检索、拼提示词、调用大模型生成答案整条链路都串起来了。这篇文章不假设你已经看过那份源码而是把这类项目最常见的实现方式拆开讲清楚它由哪些模块组成、每个模块的参数怎么定、本地怎么跑通、换数据换模型时改哪里、以及新手最容易翻车的几个点。适合两类人一类是刚学完 Python、想找一个完整 RAG 项目练手的另一类是已经会用大模型 API但想把私有资料接进问答流程的工程师。读完你应该能自己复现一个同结构的 LangChain RAG 应用并知道哪些地方值得继续投入。2. LangChain RAG 的最小链路六个模块与选型理由2.1 为什么是“加载 → 切块 → 向量化 → 检索 → 拼装 → 生成”RAG 的核心思想不复杂大模型的参数里没有你的私有数据那就别指望它记住而是在提问时把相关资料“临时塞进”上下文。LangChain 把这个过程抽象成一条链常见做法是六个环节。第一Document Loader 负责把不同格式的文件读成统一结构。txt、md、pdf、docx、csv 各有各的 loader输出都是带 page_content 和 metadata 的 Document 对象。第二Text Splitter 把长文档切成小块因为嵌入模型和上下文窗口都有长度限制整篇塞进去既贵又不准。第三Embedding 模型把每个文本块转成向量。第四Vector Store 存向量并支持相似度检索。第五Retriever 根据用户问题召回 top-k 个相关块。第六Prompt 拼装 LLM 生成把召回内容和问题一起交给模型。选 LangChain 而不是自己手写主要理由是这些环节都有现成抽象换模型、换向量库、换切块策略时改动量小。但要注意LangChain 版本迭代快不同版本的 API 差异不小网上很多教程代码跑不通往往就是版本对不上。我一般会先锁定版本再动手而不是装最新版。2.2 环境准备conda 建环境与依赖锁定这类项目第一步不是写代码是把环境弄干净。LangChain 生态依赖多直接装在系统 Python 里后面出问题很难排查。用 conda 建独立环境是常见做法。# 创建独立环境python 版本建议 3.10 或 3.11 conda create -n langchain-rag python3.11 -y conda activate langchain-rag # 安装核心依赖版本按项目实际锁定不要盲目 latest pip install langchain0.2.16 pip install langchain-community0.2.16 pip install langchain-openai0.1.23 pip install chromadb0.5.5 pip install pypdf4.3.1 pip install sentence-transformers3.0.1这里几个包的分工要说清楚。langchain 是核心抽象层langchain-community 放各种 loader 和第三方集成langchain-openai 是 OpenAI 兼容接口的封装chromadb 是本地向量库pypdf 用来读 PDFsentence-transformers 用于本地嵌入模型。版本号不是随便写的LangChain 0.2.x 和 0.1.x 的导入路径差别很大比如 RetrievalQA 在旧版和新版里的位置就不一样。如果你拿到的源码报 ImportError先查版本别急着改逻辑。提示如果项目用的是 OpenAI 接口需要配置 API Key 环境变量如果完全本地跑嵌入和生成都可以换成 Ollama 或本地模型后面会讲。2.3 文档加载与切块chunk_size 和 overlap 怎么定加载和切块是 RAG 质量的地基很多人只调模型不调这里结果检索永远不准。先看加载。from langchain_community.document_loaders import TextLoader, PyPDFLoader, DirectoryLoader # 加载单个 txt loader TextLoader(./docs/manual.txt, encodingutf-8) docs loader.load() # 加载整个目录下的 pdf pdf_loader DirectoryLoader( ./docs, glob**/*.pdf, loader_clsPyPDFLoader ) pdf_docs pdf_loader.load() print(ftxt 文档数: {len(docs)}, pdf 文档数: {len(pdf_docs)}) print(pdf_docs[0].page_content[:200])DirectoryLoader 的 glob 参数决定扫哪些文件loader_cls 决定用哪个解析器。PDF 解析经常出问题扫描版 PDF 没有文字层pypdf 读出来是空的这种情况需要 OCR不在这个最小示例范围内。加载完先打印前 200 字确认内容真的读进来了这一步能省掉后面大量排查时间。切块用 RecursiveCharacterTextSplitter它会按段落、句子、字符逐级尝试分割尽量保持语义完整。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, # 每块目标字符数 chunk_overlap80, # 相邻块重叠字符数 separators[\n\n, \n, 。, , , , ] ) chunks splitter.split_documents(pdf_docs) print(f切块总数: {len(chunks)}) print(chunks[0].page_content)chunk_size 和 chunk_overlap 是最需要按数据调的两个参数。中文技术文档我一般从 500 起步overlap 取 chunk_size 的 15% 左右。块太小单块信息不完整检索到了也答不好块太大一个块里混了好几个主题向量被平均掉相似度反而不准。separators 里加上中文标点很重要默认分隔符对中文不友好容易把句子从中间切断。切完打印几块看看如果发现块首尾都是半句话就调 overlap 或换分隔符。3. 向量化与检索把知识库真正建起来3.1 嵌入模型选择本地 sentence-transformers 还是 API嵌入模型决定“语义相似”这件事准不准。两条路用 API 嵌入质量稳定但按量计费、数据出本地用本地 sentence-transformers免费、数据不出门但首次下载模型慢效果取决于模型。from langchain_community.embeddings import HuggingFaceEmbeddings # 本地中文嵌入模型首次运行会自动下载 embedding HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, model_kwargs{device: cpu}, encode_kwargs{normalize_embeddings: True} ) # 测试一条 vec embedding.embed_query(什么是向量检索) print(f向量维度: {len(vec)})model_name 选中文场景的模型bge 系列在中文检索上表现稳定。device 设 cpu 还是 cuda 看机器有显卡就设 cuda 快很多。normalize_embeddings 设为 True 让向量归一化配合余弦相似度使用。如果项目里用的是 OpenAIEmbeddings接口类似但要把 API Key 配好且注意每次调用都有成本建库时文档多的话费用要心里有数。注意嵌入模型一旦选定建库和查询必须用同一个模型。中途换模型旧向量全部作废必须重建库这是新手常踩的坑。3.2 用 Chroma 建库并持久化Chroma 是最省事的本地向量库适合个人和小团队。建库就是把切好的块嵌入后存进去。from langchain_community.vectorstores import Chroma # 建库并持久化到磁盘 vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db, collection_namemy_rag ) vectorstore.persist() print(向量库已建立并保存到 ./chroma_db)from_documents 会逐块调用嵌入模型文档多时这一步耗时最长。persist_directory 指定落盘目录下次不用重新嵌入直接加载即可。collection_name 是集合名一个库里可以有多个集合换数据集时用不同名字避免混在一起。加载已有库的写法vectorstore Chroma( persist_directory./chroma_db, embedding_functionembedding, collection_namemy_rag ) retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 4} )search_kwargs 里的 k 是召回块数一般 3 到 5。k 太小可能漏掉关键信息太大则上下文变长、噪声变多、生成变慢。search_type 除了 similarity还有 mmr适合结果重复度高的情况它会在相关性和多样性之间做平衡。3.3 检索质量自检先看召回再看生成很多人一上来就调生成模型其实问题多半出在检索。一个简单的自检方法是直接打印召回结果。query 这个产品的安装步骤是什么 hits retriever.invoke(query) for i, doc in enumerate(hits): print(f--- 召回块 {i1} ---) print(doc.page_content[:300]) print()如果召回的内容和问题明显不相关别去改 prompt先回头查切块和嵌入。常见原因是块太大导致主题混杂或者嵌入模型不适合你的语言。如果召回相关但答案还是不对那才是生成环节的问题。这个“先看召回”的习惯能帮你把排查范围缩小一半。4. 拼装与生成让模型基于资料回答4.1 Prompt 模板怎么写才不容易跑偏RAG 的 prompt 要解决一件事让模型只用给定资料回答资料里没有就说不知道别自己编。模板通常包含三部分角色和规则、检索到的上下文、用户问题。from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_template( 你是一个严谨的知识库助手。请只根据下面提供的资料回答问题。 如果资料中没有相关信息直接回答“资料中未提及”不要编造。 资料 {context} 问题{question} 回答 )规则写得越明确模型越不容易自由发挥。“资料中未提及”这句兜底很重要否则模型倾向于硬答。context 是检索结果拼成的字符串question 是用户输入这两个占位符名字要和后面链里传的键一致不一致会报 KeyError。4.2 用 LCEL 串起检索与生成LangChain 表达式语言LCEL是现在推荐的写法用管道符把各环节连起来比旧的 RetrievalQA 更灵活。from langchain_openai import ChatOpenAI from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough llm ChatOpenAI( modelgpt-4o-mini, temperature0, api_key你的key # 生产环境用环境变量 ) def format_docs(docs): return \n\n.join(doc.page_content for doc in docs) rag_chain ( {context: retriever | format_docs, question: RunnablePassthrough()} | prompt | llm | StrOutputParser() ) answer rag_chain.invoke(这个产品的安装步骤是什么) print(answer)这段链的逻辑输入问题后一路进 retriever 召回并格式化成 context另一路原样传给 question两路汇合进 prompt再交给 llm最后用 StrOutputParser 把输出转成纯字符串。temperature 设 0 是为了让回答稳定RAG 场景不需要创意。format_docs 把多个块用空行拼起来块之间留分隔模型更容易区分。如果要用本地模型把 ChatOpenAI 换成 Ollama 的封装即可接口结构一致只是模型名和 base_url 不同。这也是 LangChain 的价值换模型基本只改一行。4.3 多轮对话怎么接把历史带进链里单轮问答跑通后下一步通常是多轮。多轮的关键是把对话历史也拼进 prompt并且让检索能理解指代。简单做法是用一个带历史的 prompt。from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder history_prompt ChatPromptTemplate.from_messages([ (system, 你是一个知识库助手只根据资料回答资料没有就说未提及。), MessagesPlaceholder(variable_namehistory), (human, 资料\n{context}\n\n问题{question}) ])MessagesPlaceholder 是历史消息的占位符调用时传入一个消息列表。要注意的是多轮里用户说“那第二步呢”检索器拿到的是这句话本身可能召回不准。常见做法是先用模型把带指代的问题改写成独立问题再拿去检索这一步叫问题改写是提升多轮体验的关键但会增加一次模型调用。5. 避坑与排查这类项目最容易翻车的五个点5.1 现象代码报 ImportError找不到 RetrievalQA原因LangChain 0.2 之后很多类挪了位置网上老教程用的是 0.0.x 的导入路径。解决先确认版本pip show langchain 看实际装的版本再按对应版本文档改导入。更稳的做法是直接用 LCEL 写链不依赖那些被移动的高层封装。5.2 现象检索结果全是无关内容原因多半是切块太大或嵌入模型不匹配。块太大时一个向量代表太多主题相似度被稀释。解决把 chunk_size 调小到 300 到 500 之间试overlap 保持 15% 左右并确认嵌入模型是中文模型。改完必须重建向量库旧库不会自动更新。5.3 现象PDF 读出来是空的原因扫描版 PDF 没有文字层pypdf 只能读文字层。解决先用 pdf 阅读器确认能不能选中文字不能选中的就是扫描件需要先做 OCR 转成带文字层的 PDF 或 txt再进流程。这个坑在真实文档里非常常见。5.4 现象回答里出现资料中没有的内容原因prompt 约束不够或者 temperature 太高。解决prompt 里明确写“只根据资料回答”和兜底话术temperature 设 0。如果还编可以在生成后加一步校验但最简单有效的还是把 prompt 规则写死。5.5 现象换了嵌入模型后检索全乱原因向量库里的向量是旧模型生成的查询用的是新模型两个向量不在同一空间相似度没有意义。解决换嵌入模型必须删掉旧库重建。persist_directory 直接删目录或者换个 collection_name 重新建。这是血泪经验别想着省那点重建时间。6. 进阶技巧把召回质量再抬一档最小示例跑通只是起点真正决定 RAG 好不好用的是召回质量。这里给几个我实际用过、改动不大但效果明显的技巧。第一个是混合检索。纯向量检索对语义相似敏感但对关键词精确匹配弱。比如用户问一个具体型号向量可能召回一堆语义相近但型号不同的块。做法是同时做关键词检索BM25和向量检索再把两路结果融合。LangChain 里有 EnsembleRetriever 可以直接组合两个 retriever权重按数据调一般各占一半起步。第二个是重排序。先召回较多候选比如 k20再用一个重排序模型对候选打分取前 4 个进 prompt。重排序模型比嵌入模型更精细能显著提升 top 结果的相关性。代价是多一次模型调用延迟增加但对质量要求高的场景值得。第三个是元数据过滤。加载文档时把来源、章节、日期存进 metadata检索时按条件过滤。比如只查某个产品的文档或者只查最近一年的资料。这能避免跨主题串味在文档多的库里效果立竿见影。第四个是查询改写。前面提过多轮场景其实单轮也适用。用户的问题往往口语化、有指代先让模型改写成更规范的检索查询再拿去召回命中率会高不少。这一步和生成是两次独立调用别混在一起。验证这些改动有没有用别凭感觉。准备一组问题每个问题标注正确答案所在的文档块然后看改动前后召回率有没有提升。没有评测集优化就是玄学。我一般会先攒 20 到 30 个真实问题做小评测集再动参数。最后说个习惯每次改完切块、嵌入或检索参数都重建库并跑一遍评测集把结果记下来。RAG 调参很容易改了这个坏了那个有记录才知道哪次是真进步。这套流程不复杂但坚持下来的人不多而效果差距往往就出在这里。希望帮到你。本文还有配套的精品资源点击获取