简介这套基于 RAG检索增强生成的知识库问答系统项目完整覆盖文本加载、分块、向量化、检索与生成回答的全流程融合 SpringBoot 与 Python 技术栈面向人工智能、通信工程、自动化、电子信息、物联网等计算机相关专业的在校学生、教师及开发者可直接用于毕业设计、课程设计、项目立项演示或二次开发。项目源码在导师指导下完成答辩评审分达 95 分所有代码均经过运行验证功能稳定既能作为完整优秀项目参考也便于在此基础上调整实现其他问答场景。压缩包共 22 个文件以 11 个 Python 脚本为核心涵盖后端服务、提示词配置、向量库检索与文本嵌入等关键模块另配前端页面、环境配置文件、说明文档及图片资源整体仅 69KB结构清晰易检索。包内完整呈现 RAG 系统的工程化实现思路适合希望从零搭建知识库问答应用的学习者对照实践目前已有 262 人学习下载具有不错的参考与复用价值。1. 基于 RAG 的知识库问答系统为什么企业知识库最终都会走到检索增强这一步当老板要求把几千份产品手册和内部规范变成一个能直接问答的系统时最直接的做法是把 PDF 全扔给大模型“读一遍”但没人敢这么干——幻觉会把答案砸在墙上。基于 RAG 的知识库问答系统就是为这个场景存在的先通过检索去文档库里找候选证据再让大模型只根据证据作答把“靠记忆”改成“靠查证”。这套链路如今已经是 rag 知识库落地最成熟的做法一线 rag 实战里不管做的是个人笔记问答、企业客服还是售后知识库骨架基本都是同一副。适合谁适合手里有文档但不敢直接喂给 LLM 的人也适合想照着源码和设计文档把这套链路吃透、从零搭出可维护问答系统的开发者。这篇我把设计选型、代码骨架、参数调优和踩坑记录一次讲透你跟着能跑通跑通了能改进改进完能上线。2. 拆开 RAG 的链路从文档入库到答案生成先搞懂检索成立的前提2.1 三个单元的分工索引、召回、生成谁拖后腿最明显RAG 系统按数据流可以拆成三个阶段索引阶段把原始文档切成块、做向量化、写入向量库召回阶段把用户问题向量化在库里做相似度检索取回最相关的若干片段生成阶段把检索结果拼进 prompt交给大模型整理成答案。这三段里最容易被轻视的是索引。很多人第一次搭 RAG拼命调 prompt 和大模型参数结果答案还是很差最后发现是入库那一步就坏了文档切得太大向量化后语义被稀释切得太碎一个完整方案被拆得七零八落Embedding 模型选得不对问题里的关键词在向量空间里根本找不到对应段落。索引坏了后续再多优化都是给断桥铺沥青。召回段的问题则是“看起来正常实际不准”。similarity_search 返回了 top_k 结果但你真的把它们逐条读过吗很多情况下前三段和问题有关第四段就开始跑题而大模型分不清哪句是依据哪句是噪声把噪声也写进答案里。生成段相对好调现在的模型指令遵循能力已经很强只要 prompt 结构清晰、禁止模型自由发挥幻觉能压下去大半。一句话总结索引决定天花板召回决定下限生成决定风格。2.2 选型Embedding 模型与向量库怎么选BGE 系列为什么是稳妥起点选型不需要追求最好追求容错率高。中文场景至今最稳的 Embedding 方案还是 BGE 系列。以 BAAI/bge-m3 为例它支持中文、英文、中英混合检索输出向量维度 1024在 C-MTEB 中文评测榜上一直排在前列。它最大的优势是同时支持 Dense稠密向量和 Sparse稀疏向量两种检索方式给 Hybrid Search 留了后路不用换模型就能做多路召回。模型维度中文效果多语言是否建议生产用bge-m31024优秀支持推荐bge-large-zh-v1.51024优秀中文特化中文场景可用text-embedding-3-small1536良优秀预算充足可选jina-embeddings-v31024良支持任务类型多配置复杂向量库方面原型阶段用 Chroma 或 FAISS 就够了部署简单、文档全、内存友好生产环境建议换 Milvus 或 Qdrant支持分布式和过滤索引。如果你的整套后台是 Java 技术栈想少维护一套 Python 服务可以关注 langchain4j 这个 Java 版的 RAG 框架它把 Embedding、向量存储、Prompt 编排都做了 Java 封装配合 Spring Boot 发布 API 很顺手后面做管理后台也顺理成章。团队里如果都是 Java 出身不熟悉 Python 生态这可以少走很长一段弯路。2.3 一个最小可用的工程设计从加载文档到向量入库入库流程不能是“读 PDF → 直接切 → 灌进库”这么草率。实际工程里我会在入口加一层文档规范化PDF、Word、Markdown、HTML 统一转成带标题层级信息的纯文本图片型 PDF 先走 OCR 再入文本管道表格转成 Markdown 表格保留列结构。这一步很多人嫌麻烦但恰恰是后面所有准确率优化的地基。文本切块的设计要结合文档结构。最常见做法是按标题层级切分先定位一级标题和二级标题把每个二级标题下的内容作为一个语义块如果块太长再按 RecursiveCharacterTextSplitter 结构切分。切完给每块打上元数据来源文件名、章节标题、页码、块编号。元数据在后期排查答案来源时非常重要否则用户问你“这个答案出自哪里”你只能摊手。3. 用 Python 把 RAG 问答跑通代码骨架与参数落位3.1 文档切分与向量化入库chunk_size 与 overlap 怎么定下面是一段可直接跑通的入库代码用 LangChain 组件把 PDF 加载、切分、Embedding 和入库串起来。如果你更偏好自己写原生流程也可以参考它的接口设计。# ingest.py - 文档入库脚本 from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 1. 加载 PDF保留每页文本 loader PyPDFLoader(product_manual.pdf) documents loader.load() # 2. 按层级分隔符切块优先按段落、句号切避免把一句话劈成两半 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每块目标字符数中文场景 400~800 均可 chunk_overlap80, # 相邻块重叠 80 字符保住跨块上下文 separators[\n\n, \n, 。, , , , ], # 分隔符优先级从高到低 ) chunks text_splitter.split_documents(documents) # 3. 给每个块打唯一 ID 与来源元数据 for i, chunk in enumerate(chunks): chunk.metadata[chunk_id] fmanual_{i:04d} chunk.metadata[source_file] product_manual.pdf # 4. 加载 BGE-M3 做向量化 embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-m3) # 5. 写入 Chroma目录持久化 vectordb Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./vector_db, ) vectordb.persist() print(f入库完成共 {len(chunks)} 个块)chunk_size 和 chunk_overlap 是最值得花时间调的两个参数。chunk_size 定 500 适合产品手册这类说明文每块能容纳一个完整功能点如果文档是合同、法律条文这种长句为主我建议提到 800避免一个条款被切进两个块。chunk_overlap 的作用是让块与块之间有重复的边界文本这样检索到前一块时后一块的开头信息不会完全丢失但重叠太大不仅费存储还会导致检索结果里出现大量内容重复的段落。一般 overlap 取 chunk_size 的 15%~20% 是经验线。HuggingFaceEmbeddings 首次运行会从 HuggingFace 下载 BGE 权重如果服务器离线需要提前到模型 hub 下载好放到本地目录后用 model_name 指向本地路径。入库后建议顺手做一次抽样检查用相似度搜索打印几个问题和对应片段确认向量库没有整体错位。3.2 检索与问答串联top_k、相似度阈值、prompt 模板的配合入库只是开始真正的问答循环在下面这段代码里。核心动作是问题向量化 → 向量库检索 → 按相似度过滤 → 拼 prompt → 交给模型生成。# query.py - 问答服务核心逻辑 from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_core.prompts import ChatPromptTemplate from langchain_community.llms import Ollama embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-m3) vectordb Chroma(persist_directory./vector_db, embedding_functionembeddings) query 这台设备支持哪些网络制式 # 检索 top 6距离越小表示越相似 docs_with_scores vectordb.similarity_search_with_score(query, k6) # 用阈值过滤明显不相关的片段BGE 用 L2 距离通常 0.6 以下比较可靠 filtered [(doc, score) for doc, score in docs_with_scores if score 0.6] # 没有合格片段时明说不知道不要硬答 if not filtered: print(知识库中没有找到相关内容请补充资料后重试。) exit(0) context \n\n.join(doc.page_content for doc, _ in filtered) prompt ChatPromptTemplate.from_messages([ (system, 你是企业内部知识库助手。请只依据上下文作答不要使用你自己的常识补全上下文不足时直接回答【不知道】。), (human, 上下文\n{context}\n\n问题{question}), ]) llm Ollama(modelqwen2.5:7b, temperature0.1) answer llm.invoke(prompt.format(contextcontext, questionquery)) print(答案, answer)top_k 与阈值要配合着调不要只调一个。top_k 取 6 是因为生成阶段需要一定的上下文冗余模型可以从多个片段里交叉验证同一结论但如果不过滤阈值top 6 里可能混进两三段无关文本模型分不清主次答案就会被带偏。我的经验是top_k 取 4~8阈值先放开看看真实召回分数分布再压到能滤掉 20% 结果的位置。prompt 里那句“不要使用你自己的常识补全”非常关键。知识库问答不像闲聊用户要的是依据而非模型“觉得”。Ollama 的本地模型如 qwen2.5:7b 已经能较好遵循这条指令若用云端模型同样有效。temperature 设置为 0.1 而非 0是为了让输出有轻微多样性同时不至于随机跑偏。3.3 第一次跑通的验证方法考一套你自己的题别急着上指标跑通之后先别追求 hit rate赶紧做一件事从你的文档里挑 20 个问题自己先写出标准答案再让系统回答人工看答得对不对。这一步能快速暴露链路里最明显的断点比如检索回来的段落是不是牛头不对马嘴、prompt 有没有把答案格式带偏。我通常会把验证题分成三类直接型答案原封不动在文档某一段里推理型需要拼合两三段信息才能得到答案拒答型文档里根本没有答案。第三类特别重要因为很多 RAG 系统在“该说不知道时不说不知道”上栽跟头。测完把失败案例记录下来归类到检索失败、上下文不足、模型不听指令三类原因再决定动哪个环节。4. 让 RAG 真正可用命中率优化的五个可调参数4.1 查全率与查准率hit rate 与 MRR 在 RAG 里的意义聊到 rag hit rate先明确一个现实RAG 的上限由召回决定。hit rate 指的是对于测试集中的每个问题正确答案所在的片段是否出现在召回的 top_k 结果里。而 MRRMean Reciprocal Rank更进一步看正确答案排在召回结果的第几位——排得越靠前生成阶段越不容易被噪声干扰。用一个小脚本就能统计 hit rate# evaluate_hit_rate.py - 召回命中率评估 from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-m3) vectordb Chroma(persist_directory./vector_db, embedding_functionembeddings) test_set [ {question: 设备的工作温度范围是多少, gold_text: 工作温度范围是 -10℃ ~ 45℃}, {question: 设备是否支持蓝牙 5.0, gold_text: 支持蓝牙 5.0}, # 至少准备 30 个样本太少统计没有意义 ] def check_hit(question, gold_text, k5): docs vectordb.similarity_search(question, kk) return any(gold_text[:20] in doc.page_content for doc in docs) hit_count 0 for item in test_set: if check_hit(item[question], item[gold_text]): hit_count 1 print(fHit Rate 5 {hit_count / len(test_set):.2%})gold_text 的匹配不要用整句取 15~20 个字符的开头片段做包含判断即可因为切块可能把原句拆开严格等值匹配会误判为漏召回。hit rate 低于 0.7 时不要急着调生成段问题大概率出在切块或 Embedding 上。4.2 重排rerank是性价比最高的优化什么时候加、加在哪如果 hit rate 还行但答案质量一般问题往往不是没召回而是召回的排序不合理。向量相似度排序在长文档场景下经常把“相关但非核心”的段落排在前面真正关键的一句话沉在 top 10 之后。这时候就该加重排。常见做法是二次检索先用向量检索取回 top 50再用一个轻量级的 Cross-Encoder 重排模型对所有候选重新打分取重排后的 top 4 进入 prompt。中文场景我常用 BAAI/bge-reranker-v2-m3它和 bge-m3 出自同门配合使用效果最稳定加载方式如下。# rerank.py - 向量召回 重排 from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from FlagEmbedding import FlagReranker embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-m3) vectordb Chroma(persist_directory./vector_db, embedding_functionembeddings) query 保修政策是什么有效期多久 candidates vectordb.similarity_search(query, k50) reranker FlagReranker(BAAI/bge-reranker-v2-m3, use_fp16True) pairs [[query, doc.page_content] for doc in candidates] scores reranker.compute_score(pairs) doc_score_pairs sorted(zip(candidates, scores), keylambda x: x[1], reverseTrue) for doc, score in doc_score_pairs[:4]: print(f分数: {score:.3f} | 片段: {doc.page_content[:80]})rerank 不是每次都必须。系统刚搭好、文档量少于几百段时直接向量检索基本够用当文档量过了几千段、或者问题文档覆盖度很广时重排的效果会非常明显。需要留意的是 rerankers 每次处理一对文本延迟比向量检索高一个量级实际部署时可以用并发或缓存缓解或只对前 50 个候选做重排。4.3 多路召回与 Hybrid SearchBM25 和向量检索互补的真实场景向量检索擅长语义相似、用词不同的情况比如问“设备怎么连不上网”原文写的是“无法连接 Wi-Fi”。但它对精确关键词不敏感——你问“型号 ABC-2000”向量检索可能把包含 ABC-2000 的文档排到第 20 位。这种场景下 BM25 这类稀疏检索能精准命中关键词。多路召回就是把两者结果合并后再去重。落地时可以用 bge-m3 的 Sparse 能力也可以单独接一个 Elasticsearch 做 BM25 索引再把两路候选按分数归一化后合并。我一般用加权分dense 分数占 0.6sparse 分数占 0.4再按合并分取 top 20 进 rerank。这样既能处理语义改写又能锁定精确型号。合并代码里要注意一点分数方向要统一。Chroma 返回的距离越小越相似BM25 是分数越大越相关不统一方向前直接求和会把结果搞反。5. RAG 落地避坑指南我在知识库问答项目里遇到的六类问题5.1 现象检索结果里混入大量无关段落出题考它却答非所问原因向量相似度并不等同于“语义相关性”。长文本里不少段落包含了相同词汇但表达的是完全不同的事情比如“温度”既可能出现在设备参数里也可能出现在运输存储说明里。检索时两者分数接近模型就把运输温度当成工作温度答了出去。解决第一步加阈值过滤把低置信片段拦在 prompt 外第二步上 rerank让 Cross-Encoder 做更精细的语义匹配第三步在切块时尽量让每块聚焦单一主题避免一个块里混进多类信息。5.2 现象文档更新后旧的答案还在“复活”原因向量库的 upsert 机制没处理好。很多人入库时只做新增没有按 source_file 删除旧向量导致旧版本和新版本的段落同时存在检索时旧内容偶尔排在前面。更多时候是更新任务只在本地执行了线上库根本没有触发重建。解决入库时先按 metadata 里的 source_file 删掉该文件全部向量再执行新增。用 Chroma 时批量删除没有直接的 where 接口可以先查出该文件对应的所有向量 ID再调用 delete。同时写一个简单的更新脚本入口确保文档变更后能一键重建索引。5.3 现象长文档切分后上下文断裂答案缺关键条件原因这是 RecursiveCharacterTextSplitter 的通病。一个操作步骤可能被切进两个块里步骤和前置条件分离模型检索到后半段时不知道前置条件是什么。比如“若电压超过 240V请先断开电源再拔插模块”如果条件在上一块、动作在下一块答案就会变成“直接拔插模块”。解决最有效的是父文档检索器Parent Document Retriever检索时先按小块匹配拿到命中后返回其所属的完整大块进入 prompt上下文完整度大幅提升。也可以调整分隔符顺序把“。”排在“\n”之后尽量让段落自然成块。如果切块策略已经定型可以在入库时额外保存每个块的父块 ID在生成阶段做一次父块合并。5.4 现象同一个问题两次回答不一致生成结果不稳定原因LLM 生成天然带随机性temperature 没有压到足够低或者 prompt 结构不够收敛。另一个幕后黑手是检索结果本身不稳定向量库有更新、并发检索时缓存失效、重排模型加载中途出现變異都会让同一问题的上下文漂移。解决把 temperature 调到 0.1并固定随机种子同时在问答链路里加日志记录每次检索命中的 chunk_id 列表。如果两次回答不同但 chunk_id 完全一致问题在生成模型如果 chunk_id 不一致问题在检索或索引根本不用调 prompt。这个排查顺序能省掉大量与模型“搏斗”的时间。5.5 现象中文专有名词和英文缩写被 Embedding 模型“看漏”原因bge-m3 虽然是多语言模型但对中英混合的专有名词仍存在稳定匹配盲区。比如文档里写“SDK 版本号 V2.3.1”用户问“软件开发工具包版本”两者的向量表达距离较远检索直接漏掉。还有类似“光模块”和“SFP”这种中英混称也很容易失配。解决在入库前做一次术语归一化把同义术语统一成规范表达例如将“软件开发工具包”统一替换为“SDK”将“光模块”替换为“SFP 光模块”。归一化词表从历史检索失败案例里收集维护成本不高但命中率回报很明显。另外对这类专业缩写在入库时额外写一遍别名倒排记录检索时先对 query 做别名扩展再走向量检索。6. 从 RAG 走向 Agentic RAG把知识库从一个问答接口变成能干活的任务系统6.1 让系统自己决定要不要查库路由与工具调用的最小改造跑通基础问答后下一个自然进化方向是 Agentic RAG。“不问就查”和无脑读取全部上下文都是浪费理想状态是系统先判断问题是否真的需要外部知识。有些问题比如“你是谁”“帮我写一段欢迎词”靠模型自身能力就能解决不必消耗检索链路。最小改造做法是加一个意图路由层用轻量级分类把问题分成“查库”和“不查库”两路查库问题再细分走向量检索还是 BM25 精确检索。这本质上是把设计模式里常见的策略模式用到 Agent 编排里不同意图对应不同处理策略。开源社区里打着 agentic rag 旗号的框架很多但自己用几十行代码实现一个足够简单的路由反而更可控、更利于排查。# router.py - 极简意图路由 def route_to_retriever(query: str) - str: # 规则优先级高出现明确型号、设备名走精确检索 import re if re.search(r[A-Z]{2,}-\d{3,}, query): return bm25 # 语义兜底交给分类模型或简单关键词表 kb_keywords [说明, 参数, 保修, 配置, 怎么, 如何] if any(kw in query for kw in kb_keywords): return vector return llm_only路由之后可以继续加工具调用让模型自己决定调用哪一个搜索工具并组装答案。但我的建议是这一步要控制规模先做 r1 路“规则路由 两路检索”跑两周看实际日志里路由决策对不对再考虑上模型自决策。否则 Agent 的自由度会把系统的可解释性拉到谷底。6.2 评估是一等公民用断言脚本守住每次改版的底线RAG 系统最怕的是每次改动一个参数答案在测试集上好了 5%上线后实际体验差了 20%。要防住这种翻车必须建立一套可重复的评估流程。除了 hit rate 和 MRR还应该加三类生成侧断言答案中是否出现“不知道”但标准答案有内容答案是否引用了上下文之外的实体同一问题连续回答两次语义是否一致性达标。把这些断言写成脚本挂进改动流程里# eval_generation.py - 生成质量简易断言 def eval_answer(question, context, answer): # 规则1必须包含上下文里的关键实体 import re key_entities re.findall(r[A-Z]{2,}-\d{3,}, context) missing [e for e in key_entities if e not in answer] # 规则2上下文明显不足时模型必须说不知道 if len(context) 50 and 不知道 not in answer: return False, 上下文不足但模型没有拒答 if missing: return False, f答案缺少实体: {missing} return True, 通过这套脚本不需要完美能拦住明显回归就够。我习惯把评估结果输出成一个 JSON 文件每次调参后对比前后两版看到底是整体提升还是某个场景被牺牲。做到这一步你手里的 RAG 方案就已经不再是“写完就扔”的课程设计而是一个能持续迭代、能说清楚哪里好哪里不好的生产级项目。我个人的习惯是在每次改版后固定跑一遍 50 题测试集哪怕只改了 prompt 里一个词也不跳过。这看起来麻烦但避免了大量“改好了这道题、弄坏了那道题”的隐性倒退。RAG 系统的坑就是这样踩过一遍才有体感希望帮到你。本文还有配套的精品资源点击获取