1. 项目全貌为什么我选择“本地ollama LangChain”做知识库助手最近在给团队搭一个内部知识库问答助手要求很简单不能把文档数据传到外部API还要能支持支付行业那一堆合规文档、产品说明书的语义检索。我第一反应就是RAG检索增强生成用本地ollama部署大模型用LangChain做编排。这套组合在今天几乎成了本地知识库方案的事实标准原因很直白ollama解决了“模型怎么跑”的问题LangChain解决了“流程怎么串”的问题RAG解决了“模型怎么知道你的私有知识”的问题。三者拼起来就是一个完整的私有化问答系统。这个项目适合谁参考三类人一是正在入门LangChain但不知道从哪下手的学习者二是被云端大模型API费用和隐私问题卡住的技术负责人三是有大量文档需要快速变成可检索问答能力的业务团队。我会把从环境搭建、模型下载、知识库切分入库到检索问答的完整链路都走一遍用的代码都是可以直接复制改用的。最后如果你需要适配支付行业或其他垂直领域文档我给了通用做法不会只停留在demo层面。先看整体架构。整个系统的核心链路是文档加载 → 文本切分 → 向量化 → 向量存储 → 检索召回 → 组装Prompt → 大模型生成。这里的每个环节都有坑尤其是文档切分参数和检索质量直接决定最终回答好不好用。很多新手把模型拉下来、代码能跑通就以为完事了结果问两个问题就露馅。本文的重点会在这些“看不见的细节”上多花笔墨让你少走弯路。1.1 核心需求解析从“能跑通”到“好用”差在哪我先说说这个项目的真实痛点。假设你有一批PDF格式的支付行业合规文档总数大概几十份每份几十页。如果直接把PDF全部塞给大模型有几个致命问题第一上下文窗口有限塞不进去第二就算强行塞进去模型回答也会“淹没”在大量无关文本里第三文档更新后整个系统要重新处理。RAG的解决思路是“先检索再生成”。先把文档切块并转成向量用户提问时先在向量库里找到最相关的几个片段再把这些片段连同问题一起交给大模型。这个方案的好处是不训练模型、不改模型权重知识库更新只要重新跑一遍切分入库就行回答还能附带引用来源方便人工核查。我在实际搭建时对方案做了三个关键取舍。第一模型选型上选了qwen2.5:7b作为主模型兼顾中文效果和本地运行的硬件成本第二向量库选了FAISS单机场景用它够用、够快不需要上Milvus或Elasticsearch这种重组件第三用LangChain做链路编排而不是LangGraph因为这里还是标准RAG流程。LangGraph更适合需要复杂状态流转、多智能体协作的场景我会在文章最后一章展开说这俩的差别。1.2 工具选型解析ollama、嵌入模型、向量库如何搭配很多人纠结“该用哪个嵌入模型”“该用哪个向量库”我直接给结论本地小规模知识库嵌入模型用bge-m3向量库用FAISS大模型用qwen2.5系列这是目前性价比最高的组合之一。先说为什么选bge-m3。嵌入模型负责把文本变成向量它的效果直接影响检索召回率。bge-m3是智源开源的支持中文效果极好而且能同时处理短文本和长文本最大支持8192个token这对文档切块比较友好。如果追求更轻量bge-small-zh-v1.5也可以速度快但精度略低。不要用OpenAI的文本嵌入模型因为你的目的是私有化数据不出本地而且本地模型已经够用。再说为什么是FAISS。FAISS是Meta开源的向量检索库单机、安装简单、性能足够几万条文本片段毫无压力。如果你的知识库将来会到百万级向量再考虑Milvus或Qdrant。对这篇文章的目标场景FAISS是完全正确的选择。ollama的选择没什么悬念它是目前本地跑大模型最省事的工具。内置了模型管理、API服务一条命令就能启动一个OpenAI兼容接口。后面你会看到LangChain甚至可以直接用langchain_ollama这个包来调用连HTTP接口都不用自己封装。2. 环境搭建与模型下载那些让你血压升高的坑一次排完我先梳理一下完整环境清单省得你装到一半发现缺东西。操作系统以Windows 11为例如果你用macOS或Linux命令基本一致只是安装包不同。Python版本要求3.9以上建议3.10或3.11太新或太旧都可能遇到依赖冲突。需要安装的组件就四样ollama、Python、LangChain相关库、向量数据库层这里直接用FAISS。用表格列一下最核心的依赖及其用途组件用途安装方式ollama运行大模型提供本地推理服务官网下载安装包langchain文档加载、切分、检索、编排pip install langchainlangchain-community社区集成如PDF加载器pip install langchain-communitylangchain-ollamaollama的LangChain封装pip install langchain-ollamalangchain-huggingfaceHuggingFace嵌入模型封装pip install langchain-huggingfacesentence-transformers本地嵌入模型运行库pip install sentence-transformersfaiss-cpu本地向量检索pip install faiss-cpupypdfPDF文档解析pip install pypdf说句实在话环境安装这一步劝退了不少初学者但如果你按下面这个顺序操作基本不会出问题。2.1 ollama安装与模型拉取的详细过程第一步是安装ollama。直接去ollama官网下载对应系统的安装包Windows版是个exe双击安装就行。macOS是dmgLinux用官方安装脚本。安装完成后打开终端验证一下ollama --version能输出版本号说明安装成功。接着拉取模型。这里有个很多人都会问的问题为什么不直接在ollama里把模型拉下来因为国内网络环境下载速度太慢很多人卡在这一步。我自己实测下来默认官方源下载qwen2.5:7b可能需要几个小时这不是你的网络问题是源的问题。解决办法是配置国内镜像源在系统环境变量里添加一个OLLAMA_HOST不一定能解决下载慢真正关键的是设置模型仓库镜像。目前社区里常用的做法是设置OLLAMA_MODELS指向自定义目录以及在终端里用镜像加速脚本具体可以搜索“ollama国内镜像源”看最新方案。我个人的经验是如果你不想折腾镜像可以用一个更稳妥的办法找一台网络条件好的机器把模型文件下载好之后拷贝到本地ollama的models目录。ollama的模型是分层的拷贝的时候注意保持目录结构。但说实话设置国内镜像源是最高效的方式一次配置之后拉取任何模型都很快。配置好之后执行ollama pull qwen2.5:7b这里我解释一下为什么用7B这个尺寸。7B是“70亿参数”的意思量化之后模型文件大约4.7GB对硬件的要求是内存或显存至少8GB。如果你只有CPU没有独立显卡运行7B模型会比较慢生成速度大概每秒几个token做验证和demo够用但生产级体验还是建议用GPU。如果硬件不足可以换qwen2.5:3b速度更快中文效果也不差。2.2 嵌入模型的下载与配置细节嵌入模型我们不用ollama来跑直接用sentence-transformers库加载HuggingFace模型。原因是sentence-transformers在文本向量化上性能更好也更容易和LangChain集成。我常用的命令是pip install sentence-transformers然后Python里这样加载from langchain_huggingface import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-m3, encode_kwargs{normalize_embeddings: True} )这里有个重点normalize_embeddings参数必须设为True。因为FAISS在做相似度检索时默认用向量内积或欧氏距离归一化之后向量长度为1内积和余弦相似度等价检索结果更稳定。这个小细节很多人忽略会造成检索排序不稳定。模型第一次加载时会从HuggingFace下载权重国内同样可能遇到下载慢问题。解决方案和ollama类似配置HuggingFace的国内镜像源export HF_ENDPOINThttps://hf-mirror.comWindows用户在系统环境变量里新建变量名HF_ENDPOINT值https://hf-mirror.com。2.3 LangChain及相关Python库的安装LangChain的库建议直接安装最新版本但要注意“LangChain 0.3”之后的变化很多以前内置的工具被拆到了langchain-community里文档加载器、向量存储这些都需要单独引入。执行pip install langchain langchain-community langchain-core langchain-text-splitters langchain-ollama langchain-huggingface pypdf faiss-cpu如果你是离线环境可以在联网机器上把wheel包下载好再拷贝安装pip download -r requirements.txt -d ./packages到目标机器上pip install --no-index --find-links./packages -r requirements.txt。全部装完后我建议立刻在Python里验证一次避免后面报错影响判断from langchain_ollama import ChatOllama ollama_llm ChatOllama(modelqwen2.5:7b, temperature0.3) response ollama_llm.invoke(你好请介绍一下自己) print(response.content)如果这里能正常返回内容说明你的环境已经通了。如果报错连接不上先确认ollama服务是否在后台运行Windows上ollama装了之后默认开机自启但可能需要手动启动一下。3. 知识库构建的核心细节从文档到向量每一步都有讲究环境通了之后就进入真正的核心知识库构建。这一步做得好不好直接决定后续问答质量。很多人的RAG效果差90%的问题出在这一环节——文档没清洗、切分不合理、嵌入模型没选对。3.1 文档加载PDF、Word、TXT的多种方式先看文档加载。不同格式需要不同加载器LangChain里最常用的是PyPDFLoader它能读取PDF的每一页文本。如果你还有Word文档用Docx2txtLoader纯文本就简单了TextLoader直接搞定。from langchain_community.document_loaders import PyPDFLoader, Docx2txtLoader, TextLoader def load_documents(file_path): if file_path.endswith(.pdf): loader PyPDFLoader(file_path) elif file_path.endswith(.docx): loader Docx2txtLoader(file_path) else: loader TextLoader(file_path, encodingutf-8) docs loader.load() return docs这里有个容易踩的坑PDF如果是扫描件没有文字层PyPDFLoader读出来是空内容。要处理这种就得先走OCR常见方案是paddleocr或tesseract但中文OCR的精度差异很大支付行业那些扫描合同最好先用Adobe或WPS做一遍OCR再入库。加载出来的docs是一个个Document对象每个对象有page_content和metadata。这一步不要急着切分先批量检查一下有没有乱码、空白页、重复页。我习惯写一个简单的遍历脚本统计每个文档的字符数和页数如果某页小于50个字符大概率是空白页或页眉页脚建议提前过滤。3.2 文本切分策略固定长度还是递归切分这是整个知识库构建中最有技术含量的一步。切分太粗一个块里包含多个主题检索时会带入无关信息切分太细语义被割裂单个块无法完整表达一个知识点。我推荐用LangChain的RecursiveCharacterTextSplitter它比固定长度切分聪明它会尽量按段落、句子、标点来切而不是粗暴地按字符数截断。from langchain_text_splitters import RecursiveCharacterTextSplitter text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , ., !, ?, , ;, , ,] )这里几个参数的考虑说一下。chunk_size500字符是因为bge-m3嵌入模型对512 token左右的文本效果最稳定500个中文字符大约等于500个token中文一个字约等于一个token正好在最佳区间。chunk_overlap100的意思是相邻两个块之间重叠100个字符避免一个完整知识点刚好被切成两半、检索时两边都“差半句话”。separators的排序很重要它决定优先按什么层级切分我建议段落优先其次是换行、句号、逗号最后才是逗号兜底。如果你处理的是问答格式的文档比如“问题xxx 答xxx”用递归切分就可能把问题和答案拆到两个块里检索时只看到问题而没看到答案。这种情况我会建议用MarkdownHeaderTextSplitter按标题层级来切或者自定义分隔符。支付行业的规则文档经常是这种问答体需要特殊处理。3.3 构建向量索引FAISS入库与本地持久化切分完成后把每个块交给嵌入模型向量化再存入FAISS索引。直接看代码from langchain_community.vectorstores import FAISS # chunks是切分后的Document列表 vectorstore FAISS.from_documents( documentschunks, embeddingembeddings ) # 保存到本地 vectorstore.save_local(faiss_index)保存到本地的是两个文件index.faiss存向量索引index.pkl存文档原文和元数据。下次直接加载vectorstore FAISS.load_local( faiss_index, embeddings, allow_dangerous_deserializationTrue )注意allow_dangerous_deserialization参数新版LangChain出于安全考虑默认禁止加载pickle文件必须显式设为True。这个警告不是吓唬人如果你加载的faiss_index不是你自己生成的可能有安全风险。建完索引之后可以先验证一下检索效果query 交易手续费如何计算 docs vectorstore.similarity_search_with_score(query, k5) for doc, score in docs: print(fscore: {score:.4f} | content: {doc.page_content[:80]}...)这里的score是向量距离值越小表示越相似。如果你发现检索结果不理想排在前面的文档和问题明显不相关就要回头调整切分参数或换嵌入模型而不是急着往下走。检索质量是RAG的地基地基歪了上面什么都白搭。3.4 项目实战扩展加载本地文件并构建支持支付行业文档的知识库为了让你看得更具体我给一个完整的建库脚本这个脚本能遍历指定目录下的所有PDF/Word/TXT清洗后切分、向量化、入库最终生成一个可以直接使用的faiss_index目录import os from langchain_community.document_loaders import PyPDFLoader, Docx2txtLoader, TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_huggingface import HuggingFaceEmbeddings from langchain_community.vectorstores import FAISS def load_documents_from_dir(dir_path): docs [] for root, _, files in os.walk(dir_path): for file in files: file_path os.path.join(root, file) if file.endswith(.pdf): loader PyPDFLoader(file_path) elif file.endswith(.docx): loader Docx2txtLoader(file_path) elif file.endswith(.txt): loader TextLoader(file_path, encodingutf-8) else: continue try: docs.extend(loader.load()) print(f成功加载: {file_path}) except Exception as e: print(f加载失败: {file_path}, 原因: {e}) return docs def build_knowledge_base(docs_dir, output_dirfaiss_index): docs load_documents_from_dir(docs_dir) print(f共加载 {len(docs)} 个文档片段) text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , ., !, ?, , ;, , ,] ) chunks text_splitter.split_documents(docs) print(f切分后共 {len(chunks)} 个文本块) embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-m3, encode_kwargs{normalize_embeddings: True} ) vectorstore FAISS.from_documents(chunks, embeddings) vectorstore.save_local(output_dir) print(f知识库已保存到 {output_dir}) if __name__ __main__: build_knowledge_base(./documents)我把上面这段脚本存成了build_kb.py然后在documents目录里放了几份支付行业的公开文档做测试跑一遍之后FAISS索引就建好了。整个建库过程大概几分钟取决于文档数量和你电脑性能。如果你是支付行业文档里可能会有大量表格、图表、法规条款这些在纯文本切分时容易丢失排版信息建议在处理前先把表格转成文本描述比如“根据XX规定特约商户手续费率为0.6%”否则表格内容会被加载器丢掉或者揉成一团。4. 核心问答实现检索、Prompt与生成完整串起来知识库建好之后真正的RAG问答链路就要上场了。我见过太多人把检索和大模型生成当成两个独立步骤——先检索出来然后把拼接的文本丢给模型简单粗暴。这样也能跑但回答质量一言难尽。这一章我会把每个环节的关键参数、Prompt设计思路、上下文组装方法都详细拆开。4.1 检索策略相似度搜索的两个核心参数检索是RAG的“找材料”环节两个参数决定检索质量k值召回条数和相似度阈值。k值不是越大越好。k太小可能漏掉关键信息k太大无关信息混进来模型容易“跑偏”。我的经验值是5最多不超过8。retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 5} )除了相似度搜索还有一种叫mmr最大边际相关性的检索方式它会在“与问题相关”和“结果多样性”之间做平衡避免返回的5条结果全是同一个文档的不同片段、缺乏多样性。实测下来如果你的文档里有大量重复性条款mmr会明显改善回答质量。切换方式retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 5, fetch_k: 20} )这里fetch_k20的意思是先从库里捞20条候选再从中挑5条作为最终结果这样模型能看到更多不同来源的片段。代价是检索速度略慢但知识库不大时影响可以忽略。检索之后建议打印出召回内容看看。如果召回的片段和问题匹配度很高再往下走如果明显不对就别急着调Prompt先调检索。4.2 Prompt模板设计如何让大模型“守规矩”RAG的Prompt和其他Prompt不一样它必须明确告诉模型两件事第一只能使用提供的上下文回答不要编造第二如果上下文里没有答案要坦白说不知道。否则你会看到大模型一本正经地编造支付结算规则那在严肃场景里是灾难。我的Prompt模板长这样from langchain_core.prompts import ChatPromptTemplate template 你是一个专业的知识库问答助手。请基于以下资料片段回答用户问题。 回答要求 1. 只能使用资料片段中明确提到的信息禁止根据你自己的知识进行推测或编造。 2. 如果资料中没有提到相关内容直接回答“根据当前知识库内容未能找到相关信息”。 3. 回答时尽量保持原文的关键数据和条款表述不要擅自修改数字或日期。 4. 如果问题涉及多个方面请分点作答。 资料片段 {context} 用户问题 {question} prompt ChatPromptTemplate.from_template(template)这里有个细节{context}是检索到的多个文档片的拼接。拼接顺序会影响回答效果通常按相关性从高到低排列但我也试过把包含“问题关键词”的片段放前面效果更稳定。LangChain的MMR返回结果本身是排序的直接用就行。温度参数也要注意。知识库问答场景建议把temperature调到0.2到0.3之间。低了回答机械但忠实度高高了回答有创造性但容易偏离资料。支付行业这种强调准确性的场景我建议直接设0.2。4.3 完整RAG链路一条龙跑通问答终极代码长这样from langchain_ollama import ChatOllama from langchain_huggingface import HuggingFaceEmbeddings from langchain_community.vectorstores import FAISS from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser embeddings HuggingFaceEmbeddings( model_nameBAAI/bge-m3, encode_kwargs{normalize_embeddings: True} ) vectorstore FAISS.load_local( faiss_index, embeddings, allow_dangerous_deserializationTrue ) retriever vectorstore.as_retriever(search_kwargs{k: 5}) llm ChatOllama( modelqwen2.5:7b, temperature0.2 ) prompt ChatPromptTemplate.from_template(template) rag_chain ( {context: retriever, question: RunnablePassthrough()} | prompt | llm | StrOutputParser() ) response rag_chain.invoke(支付机构的备付金管理要求是什么) print(response)这就是一个标准的LangChain LCEL表达式链。retriever作为context的取值端用户问题同时传给question和检索器。整个过程问题进来 → 检索相关文档 → 填充Prompt → 模型生成 → 输出字符串。你可以把它封装成一个函数用FastAPI套一层就变成带Web接口的问答服务了。我实际运行时的体验是qwen2.5:7b在CPU模式下回答一段30字左右的内容大概需要10秒到20秒GPU会快很多。如果你只是做内部工具这个速度可以接受如果需要并发就要考虑用更大的模型服务器或者换量化版本。4.4 带引用来源的回答让结果更可信知识库问答最好把每个回答对应的文档来源也展示出来方便用户核验。支付行业合规场景里这条几乎必须做否则回答再准确没人敢信。实现方式也不复杂在生成回答时同时把检索到的文档元数据返回context_docs vectorstore.similarity_search_with_score(query, k5) context_text \n\n.join([doc.page_content for doc, _ in context_docs]) answer llm.invoke(prompt.format(contextcontext_text, questionquery)).content print(f回答{answer}) print(\n参考来源) for doc, score in context_docs: source doc.metadata.get(source, 未知来源) page doc.metadata.get(page, 未知页码) print(f- {source} 第{page}页 (相似度: {1 - score:.4f}))这里把FAISS的distance score转成相似度的计算方式是1 - score因为FAISS默认返回的是L2距离距离越小越相似。你在展示时可以只显示相似度高于某个阈值的结果比如0.6低于这个值说明召回的可信度不高直接告诉用户“搜索结果置信度较低”。5. 常见问题与调优实战踩坑记录与排查技巧这一章我把自己在这类项目上踩过的、以及在社区里高频出现的坑做一个速查清单每个问题后面是排查思路和解决方案。这些内容不会写在官方文档里但对你把项目落地到生产环境非常重要。5.1 高频报错速查表报错/现象原因分析解决方案ollama pull 卡住不动网络原因连不上默认模型仓库配置国内镜像源或拷贝已有模型文件FAISS加载时报allow_dangerous_deserialization错误LangChain新版本的安全机制加载时显式传allow_dangerous_deserializationTrue加载PDF内容为空扫描件无文字层需要OCR用paddleocr或先人工OCR处理回答总是乱编不按资料来Prompt约束不够或温度过高强化Prompt限制温度降到0.2以下检索结果相关性差切分粒度不对或嵌入模型不匹配调小chunk_size试试或换bge-m3模型问答速度太慢CPU推理7B模型算力不足换3B模型或开启GPU推理首次加载模型需要几GB内存模型文件大量化版本可降低资源占用用qwen2.5:7b-instruct-q4_K_M等量化版本文档更新后旧知识还在知识库重建的时机不对更新文档后重新跑一遍建库脚本并重建索引目录5.2 回答质量不达标时的系统性排查如果问答效果不理想别急着换模型先按照“加载 → 切分 → 索引 → 检索 → 生成”这条链逐个排查。第一步确认加载的文档内容本身没问题把切分后的文本块打印几条看是否完整、是否乱码。第二步用几个你知道答案的问题测试检索看检索出来的片段是不是包含正确答案的那一段如果连片段都检索不到问题出在切分或嵌入模型跟模型生成无关。第三步确认Prompt有没有把{context}正确填充进去我遇到过一个很隐蔽的问题context被截断了因为某个文档片段太长超过了上下文窗口模型只能基于截断后的文本回答效果自然差。排查问题最快的方法其实是把检索结果单独打印出来看。我在调优时经常做的一步是对一个测试问题打印top5召回的片段以及对应的相似度分数确认“正确答案”在不在里面。如果正确答案排在第6位或更靠后就调大k值看看如果正确答案根本不在库里就得回到切分环节检查是不是把关键内容截断了。这个方法简单、直接能帮你快速定位到底是检索环节还是生成环节出了问题。5.3 中文文档的特殊处理编码、表格与长文本中文文档的坑比英文多。第一是编码问题TextLoader加载TXT文件时如果指定encodingutf-8还报错可能是文件实际是GBK编码改成encodinggbk试试。第二是表格问题PDF里的表格在加载后会被打散成零散文本检索时会漏掉关键数据。最佳实践是在入库前把表格转成自然语言描述比如“交易手续费率表”转成“标准商户费率为0.6%优惠类商户费率为0.38%”。第三是长文本问题如果某个章节特别长超过切分块的大小会被硬切这时chunk_overlap的作用就体现出来了。建议对这类长段落的chunk_overlap值设置不低于150可以有效减少关键信息的丢失。5.4 进阶优化方向混合检索与重排序基础RAG跑通之后很多人会问“还有没有更准的方案”。我给出两个进阶方向按投入产出比排序。第一是混合检索用“关键词BM25检索 向量语义检索”并行召回再把两部分结果做合并去重。这个能显著提升包含精确术语或编号的查询命中率。LangChain里有EnsembleRetriever可以方便地组合两种检索器。第二是重排序检索召回的Top20条结果先不直接传给模型而是经过一个rerank模型重新打分再取Top5传给生成模型。重排序模型通常用bge-reranker-base它对“语义相关但表述不同”的匹配有更好的判断力。经过重排序之后回答质量的提升是能明显感受到的但代价是多了一个模型的推理开销。6. 写在最后关于LangChain和LangGraph的选择以及我的个人建议现在LangChain社区里经常有讨论以后是不是都用LangGraph了我自己的判断是LangChain更适合标准、线性的RAG流程代码简单概念直观是学习框架的最佳入口LangGraph的核心优势是状态图和循环控制当你需要多轮对话管理、多智能体协作、条件路由、人工审核节点这些复杂流程时再把项目演进到LangGraph不迟。对于本文这个知识库问答场景LangChain的LCEL表达链已经足够引入LangGraph是一种过度设计。根据我个人实际操作中的体会这个项目最值得投入时间优化的不是代码而是文档预处理。同样的代码喂给它的文档质量不同出来的回答天差地别。我建议你第一次跑通之后把精力花在清洗文档、调整切分策略、调试检索召回上这比反复换大模型更有效。最后再分享一个小技巧建库脚本不要只跑一次把它留好你的文档只要一更新就重新跑一遍保持知识库和源文档同步。这个习惯比任何算法调优都重要因为再好的RAG系统也救不回一个过期混乱的知识库。