简介基于RAG大模型技术的私有知识库智能问答系统完整源码包面向AI应用开发者、毕业设计学生以及需要构建企业内部知识问答系统的技术工程师。系统覆盖大模型通用领域知识问答、本地私有知识库问答、实时互联网搜索问答、AI代理问答和大模型推荐系统五大核心场景并配有完整的RAG评估流水线和评估方案为模型效果调优提供量化依据。压缩包共467个文件、约107.26MB包含145个Python后端源码文件、70个Vue3前端JavaScript文件、32个CSS样式文件、23个Markdown说明文档、9个PDF资料以及Dockerfile、环境变量配置和向量索引文件等前后端代码分离目录组织清晰便于按模块查阅。已有382人学习浏览。资源从零到一完整实现了百万级Wiki语料、Markdown、PDF等私有语料的预处理与优化流程集成了MySQL关系型数据库与Milvus向量数据库支持细粒度用户权限管理和主流在线及开源大模型的灵活切换同时提供Docker容器部署方案。系统还实现了通用问答、私有知识库问答等五大场景的工程衔接直接可作为毕业设计完整方案或企业私有知识库问答系统的工程参考。1. 用 RAG 大模型私有知识库做智能问答能省下外包开发的几千行代码吗一个常见场景公司内部有几十份产品手册、规章制度、故障记录员工每天在群里问“报销流程是什么”“这个报错怎么处理”答案散落在聊天记录和文档里。人工回复费时直接用通用大模型又怕泄露数据。这时候基于 RAG 大模型技术开发的私有知识库智能问答系统成了很多团队的首选。它不重新训练模型而是“先检索、再生成”——把私有文档切成片段存进向量库用户提问时先找出相关片段再拼进提示词交给大模型回答。源码加部署教程听着很诱人但真正落地时切分策略、向量库选型、相似度阈值这些细节才是决定它能不能替代人工客服的关键。这篇笔记不聊理论玩具只说怎么把一套 RAG 私有知识库问答系统从源码跑通、调好参数并塞进真实业务。2. 拆解 RAG 的检索-增强-生成链路为什么私有知识库选它而不是微调2.1 从“搜文档”到“答问题”RAG 解决的核心矛盾传统企业知识库只是“能搜到文件”用户拿到的是一堆网页链接和 PDF 名称还得自己再读一遍。RAG 的思路是让大模型直接基于检索到的内容生成一段连贯回答。它的链路分四步文档加载、文档切分、向量化入库、提问时检索增强。前端用户感知不到但后端最关键的是“检索”这一步决定了生成质量的上限。如果检索回来的片段本身不对大模型再厉害也只会一本正经地胡说八道。我见过很多团队把 RAG 当成“大模型 文件搜索”的缝合怪上来就把全部 PDF 丢进去然后狂问问题。结果系统回答得头头是道但细节全是编的。原因很简单默认的切分参数对长文档不友好一个知识点被切成了两半检索只召回了一半另一半全靠模型幻想补齐。RAG 不是黑匣子它的问题大部分出在文档处理和召回参数上而不是模型本身。2.2 RAG 与微调、与纯大模型问答的边界有朋友会问既然要大模型理解私有文档为什么不直接做微调微调是把新知识固化进模型权重适合“改变说话风格”或“固定某种回答格式”但私有知识库的核心诉求是“内容准、能追溯”。企业文档更新频繁微调一次要好几个小时还容易灾难性遗忘。RAG 只需要替换向量库里的文档片段分钟级生效。另一个区别是成本微调需要更多显存和训练数据RAG 用开源小模型加一块普通 GPU 就能跑起来。那纯大模型问答呢直接把文档塞进上下文最多只能容纳几千字企业知识库动辄几十万字超长文本会严重丢细节还伴随昂贵的 token 开销。RAG 相当于给大模型配了一个“随时查的索引”只在回答问题时取出相关片段。所以确定场景时我的判断标准很简单知识需要频繁更新、回答需要引用原文、数据不能出内网这三点只要中了两条就别碰微调优先做 RAG。2.3 最小可运行系统的三大件文档库、向量检索、生成模型一套能跑的私有 RAG 问答系统最少包含三部分。第一是文档预处理把 PDF、Word、Markdown 读进来按段落或固定长度切块第二是向量检索用嵌入模型把文本块变成向量存进向量库用户提问时也用同一套嵌入模型转成向量做相似度搜索第三是生成模型把检索回来的 top_k 个文本块和用户问题拼成提示词交给 LLM 生成答案。很多源码包会在这三层外面再包一层 Web 界面或 API 服务但核心就这三样。部署教程的价值在于帮你把那几百个文件里最关键的几个配置项找出来。如果你拿到源码后先去改界面、改按钮文案那方向就错了。第一步应该是把文档加载、向量库存储、问答接口这三段代码串起来跑通一个“问一句答一句”的最小闭环再考虑工程化装饰。3. 用 Langchain Ollama 把私有知识库问答跑起来代码骨架与参数设置3.1 选型落地本地部署的嵌入模型和向量库怎么配私有化部署的核心要求是数据不出内网所以优先选能完全本地跑的组件。嵌入模型我常用 BAAI/bge-small-zh它在中文语义检索上的效果好于很多开源同尺寸模型显存占用也低。LLM 可以用 Ollama 拉取 qwen2.5:7b 或 llama3.1:8b个人机器 16G 内存能跑16G 显存能跑得比较舒服。向量库图省事用 Chroma纯本地文件式存储适合单机数据量超过几十万条再考虑 Milvus 或 Qdrant。安装环节不细说只用 pip 装几个库langchain、chromadb、langchain-community、sentence-transformers。Ollama 如果装在另一台机器注意把 API 地址改成http://ip:11434。下面这段代码完成“加载文档 → 切分 → 向量化 → 入库”全流程这是整个系统里最值得反复打磨的一段。from langchain_community.document_loaders import DirectoryLoader, PyMuPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 1. 读取 docs 目录下所有 PDF loader DirectoryLoader(./docs, glob*.pdf, loader_clsPyMuPDFLoader) documents loader.load() print(f加载到 {len(documents)} 个文档) # 2. 切分chunk_size300, overlap50 text_splitter RecursiveCharacterTextSplitter( chunk_size300, chunk_overlap50, separators[\n\n, \n, 。, , , , ] ) chunks text_splitter.split_documents(documents) print(f切分成 {len(chunks)} 个片段) # 3. 嵌入模型本地 bge-small-zh embedding HuggingFaceEmbeddings(model_nameBAAI/bge-small-zh) # 4. 入库 Chroma vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db # 向量库落地目录 ) vectorstore.persist()切分参数chunk_size300是按中文字数算的不是 token 数。300 字大概是一段半到两段文字能保证每个片段有一个相对完整的语义单元。chunk_overlap50让相邻片段有 50 字的重叠避免一句话在中间被截断后两头都搜不到。这两个值是经验基数不是最优解后面要根据业务文档类型调。3.2 文档切分chunk_size 和 overlap 的第一波调参很多人拿到源码后不改切分参数直接跑结果知识库里的文档全是几千字的大块头检索时一次只能取三块每块都覆盖不了完整答案链。反过来如果把每个段落切成 50 字那么回答“报销流程是什么”这种需要上下文连续的问题时检索回来的片段可能只有“报销需要填写单据”这几个字后面跟的“找谁签字、何时到账”全被切到另一个块里了。调参有个笨办法先按文档的自然段落分再对过长段落用固定大小切。RecursiveCharacterTextSplitter的分隔符顺序是优先按段落、再按句号、逗号、换行切。如果你的文档是问答式、条目式的可以把chunk_size放到 500overlap 放到 80让每个条目尽量完整。如果文档是大量长叙述300 字左右更稳妥。判断切分好坏的标准是把任一片段单独拿出来看它是否自带上下文信息——比如“这个型号”指代的是哪个型号“该方法”说的是哪种方法。如果指代不明说明切小了。3.3 召回与重排top_k、相似度阈值、rerank 的取舍向量检索不是把 top_k 设大就完事。top_k控制取回几个片段喂给 LLM。太小容易漏太大容易把不相关的也塞进来导致模型回答被噪声带偏。我一般初始设 4 到 6。相似度阈值更关键Chroma 默认返回距离值距离越小越相关。设置一个阈值的目的是当所有候选片段都不够相关时直接告诉用户“知识库里没有这个答案”而不是让大模型硬答。常见做法是量一下正常问题召回片段的最小距离然后取它的 1.2 倍作为边界。下面的代码展示问答检索部分包含了阈值判断和提示词组装。注意不同向量库的相似度度量方式不同Chroma 默认用 L2 距离值越小越相关FAISS 默认用内积需要换算。from langchain_community.llms import Ollama def search_and_answer(query, top_k4, score_threshold1.3): # 向量检索 docs vectorstore.similarity_search_with_relevance_scores(query, ktop_k) # 过滤掉不相关的片段 valid_docs [(doc, score) for doc, score in docs if score score_threshold] if not valid_docs: return 知识库中暂时没有找到相关的内容请换个说法再试。 # 按相关性降序排列拼成上下文 context \n\n.join([doc.page_content for doc, _ in valid_docs]) prompt f你是一个企业知识库问答助手。请严格依据下面的资料回答问题。 如果资料中没有答案直接说“资料中未覆盖这个问题”不要编造。 资料 {context} 问题{query} 答案 llm Ollama(modelqwen2.5:7b, temperature0.1) return llm.invoke(prompt)score_threshold是这里最需要人工测的参数。不同嵌入模型、不同领域文档的得分分布差异很大别照抄。temperature0.1是为了让回答尽量稳定少一点创造性减少胡编概率。如果业务允许模型在找不到答案时说“不知道”这个温度可以保持很低如果你希望回答更自然一点可以调到 0.3但必须接受偶尔的自由发挥。3.4 问答接口提示词模板如何把上下文塞进大模型提示词模板的质量直接影响回答是否“守规矩”。一个常见误区是把所有资料一股脑倒进去然后问“根据以上内容回答……”。当背景资料里有冲突信息时模型可能会自己挑一个站得住的说法。我的做法是在提示词里明确“只能依据资料回答禁止用外部知识补充”并把资料按相关性编号让模型在答案中标注引用了第几条资料。prompt_with_citation f你是一个严谨的企业内部知识库助手。 以下是按相关性从高到低排列的资料片段每条以 [n] 开头 [1] {valid_docs[0][0].page_content} [2] {valid_docs[1][0].page_content} ...省略其余 回答规则 - 只使用上述资料不能联想外部知识 - 如果资料相互矛盾指出矛盾并给出更靠前的资料作为参考 - 回答开头先给出结论再简述依据引用格式如“依据[1]”。 问题{query} 回答把引用格式写进提示词后续做答案溯源就很容易——前端显示“依据[1]”时可以把对应的原始文档链接也带出来。这是 RAG 系统从“看起来像 AI”升级到“可解释、可追溯”的关键一步。很多源码包没把这层做全部署时需要自己补上。4. 私有知识库部署避坑5 个会让人翻车的常见问题与排查方法4.1 切分太碎答案上下文被拆丢现象问“这种情况应该联系哪个部门处理”系统答“应该联系相关部门”完全没给出具体名称。 原因答案关键信息在文档的下一段而切分点刚好把“联系信保中心”这句话切到了下一个 chunk。检索只召回上一段模型看不到真正的办理部门。 解决先把chunk_overlap提高到 50100 字再检查是不是文档标题、表格导致切分位置不对。如果文档是流程图配文字说明光靠文本切分永远拆不完整需要先人工把图文配对再切分。另一个思路是让检索的top_k稍微调大到 6使上下文跨块覆盖。4.2 相似度阈值设太高系统经常答“我不知道”现象明明是知识库里的内容换个说法问就成了“找不到”。 原因不同嵌入模型对同义句的向量距离并不像人想的那样接近。比如“发票丢了怎么办”和“发票遗失如何处理”如果阈值卡得太紧召回距离全部超标被当成无结果处理。 解决建一个 20 条左右的问题集跑一遍检索打印每道题返回的最小距离。用这些实际数值分布来确定阈值而不是拍脑袋设 0.8 或 1.5。我见过不少系统阈值看似很合理但文档里的专业术语一换分数就完全不同。放宽阈值的同时一定要有 rerank 或者让模型判断资料是否相关否则会引入一堆低质量片段。4.3 多轮历史对话让回答开始胡编现象用户先问“系统登录失败怎么办”再问“那如果是忘记密码呢”第二条回答里出现了第一条里根本没有的排错步骤。 原因多轮对话把历史记录也拼进了提示词模型误以为历史中的“建议重启服务”是后续问题的答案来源于是交叉编造。 解决最简单的方式是每一轮都只基于当前问题检索不把历史上下文塞进检索键。如果必须支持多轮则把历史对话摘要成“用户己经确认了 A 场景正在问 B 场景”再用摘要去检索而不是把原始聊天记录丢进 prompt。RAG 的核心是“每次回答都基于文档片段”历史对话只能帮助理解当前提问的指代不能作为答案来源。4.4 表格、扫描件和图片进知识库后检索质量骤降现象把带表格的 PDF 直接转文本后表格内容变成一堆空格和数字堆砌问“哪个月的退货率最高”根本答不对。 原因RAG 的文本检索对结构化表格不敏感。表格的语义藏在表头“月份”和“退货率”的对应关系里但普通 PDF 抽取后把这些元素线性铺开上下文顺序丢失。扫描件更是只抽出了空白文本。 解决优先把表格转成 Markdown 或 CSV 格式再作为一个小片段单独入库扫描件必须先用 OCR 识别常见做法是 PaddleOCR 或 Tesseract识别后再做断句。图片本身目前的文本嵌入模型拿不到语义要么用多模态模型做图生文要么把图片的关键描述写在文档正文里否则检索不到是正常的不是你代码的错。4.5 显存不足就卡死换 CPU 推理该怎么调现象源码默认用 GPU 推理 7B 模型普通办公电脑显存只有 6G一启动服务就报 CUDA out of memory。 原因7B 模型 fp16 权重就需要约 14G 显存加上 KV cache 和中间层开销16G 以下很难跑完整模型。源码包里通常没写清楚这一点。 解决把 Ollama 中的模型换成量化版本比如 qwen2.5:7b 的 q4_K_M 量化版内存占用降到 4G 左右CPU 也能慢慢跑。同时降低生成长度num_predict设为 256减少回复时缓存占用。如果还是不够换 3B 级别模型或者改请求接口为远程 GPU 服务。真正在生产环境跑单独一台 24G 显存的卡是省钱又安全的底线。5. 上线前用评测集把系统“拷问”一遍一个可复制的验证闭环5.1 构造 20 条领域问题而不是随便问几句手工点几个问题说“效果不错”远远不够。你需要准备一份评测集包含三类问题一是文档里能直接找到答案的“直答型”二是需要跨多个片段才能归纳的“综合型”三是文档里根本不存在答案的“拒答型”。20 条里建议直答 10 条、综合 6 条、拒答 4 条。每条问题要记录对应的正确答案来源片段方便后面判断检索是否命中。5.2 用脚本批量跑评测把“感觉还行”变成可量化指标写一个脚本遍历评测集调用检索函数把每次的召回片段、相似度分数、最终回答全量保存成 JSON。然后人工或半自动检查回答的正确性记录三个指标答案正确率、引用命中率、拒答准确率。引用命中率是看回答中提到的依据片段是否真的在召回列表里它比答案本身更能反映系统背调是否跑偏。import json import time eval_questions [ {question: 请告诉我设备故障的报修流程是什么, expected_source: service_process.md}, {question: 员工年假最长的单位可以累计到多少天, expected_source: hr_policy.md}, {question: 公司有没有关于宠物零食报销的规定, expected_source: None}, # 拒答 ] results [] for item in eval_questions: start time.time() answer search_and_answer(item[question], top_k4, score_threshold1.3) elapsed time.time() - start results.append({ question: item[question], expected_source: item[expected_source], answer: answer, elapsed_seconds: round(elapsed, 2), }) with open(eval_results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2)expected_source字段需要你自己维护不要奢望自动化完全替代人工判断。跑完后的理想状态是直答型题目答对 8 条以上综合型能答对 4 条以上拒答型至少有 2 条明确说出“找不到”。如果达不到回到上一章的避坑清单逐项检查按顺序先调 chunk_overlap再调 top_k最后调阈值。5.3 按评测结果反向调参的优先级顺序看到评测结果不要盲目调 LLM 提示词。我一个习惯是如果问题能搜到相关内容但回答不对说明切分或提示词有误如果连相关内容都没搜出来那就是检索问题调 LLM 是白费功夫。具体的调参顺序我总结为先看召回片段里有没有正确答案 → 没有就调 chunk 和 top_k → 有但回答仍然错误 → 调提示词模板和温度。这个顺序能避免大量无效尝试。评测脚本建议每天跑一次因为知识库文档会更新参数不会永远有效。5.4 RAG 的边界哪些业务问题不该指望它最后说点不好听的。RAG 非常擅长“找资料、归纳、引用”但在两类问题上会显得很笨一是需要跨全库推理的复杂分析比如“基于过去一年的故障记录预测今年哪个月故障率最高”这应该交给数据分析脚本别硬塞给 RAG二是流程性操作指引比如“教我如何开通云服务器”文档里有详细步骤RAG 能背出来但用户真正要的是可交互的流程图不是一段文字。认清边界后反而能把 RAG 用在最有价值的地方客服问答、制度查询、FAQ 自动回复。不要试图让它替代所有信息获取场景。这套系统我从选型到上线大概花了一个月最深的教训是“参数不能抄作业必须要用自己的文档评测”。把评测脚本固化到部署流程里每次换模型、换文档格式、换切分策略都先跑一遍同一个评测集省下的是反复人工抽查的半天时间。希望这篇笔记能帮少走几个我走过的弯路祝你的私有知识库问答系统早日跑出靠谱答案。本文还有配套的精品资源点击获取