基于RAG与混合检索的本地知识工作台搭建实战

1. 为什么我要自己搭一套知识工作台先说结论市面上现成的知识库工具我几乎试了个遍最后发现没有一个能同时满足PDF 深度解析 Markdown 原生支持 可持续追问这三个条件。要么是 PDF 解析出来全是乱码要么是 Markdown 里的代码块和数学公式被吃掉要么是问了两三轮之后 AI 就开始胡编乱造。所以我花了大概三周时间搭了一套自己的知识工作台核心思路就是RAG检索增强生成 结构化文档预处理 多轮追问链路。这套东西解决的核心问题是你手头有一堆 PDF 论文、Markdown 笔记、项目文档、网页剪藏散落在各个文件夹里想用的时候找不到找到了又记不住细节。传统的全文搜索只能匹配关键词你搜缓存穿透它给你返回所有包含这四个字的段落但你想问的是我这个项目里缓存穿透是怎么处理的它就无能为力了。AI 知识库的价值就在于它能理解你的意图从你的资料里找到相关片段然后组织成一段人话回答你。适合谁来参考这套方案我觉得三类人最需要一是手头积累了大量技术文档但没时间整理的开发者二是做研究需要频繁查阅 PDF 文献的学生或研究员三是团队里负责维护内部知识库的运维或技术管理者。不需要你是 AI 专家但最好懂一点 Python因为整个流程涉及文档解析、向量化、检索这几个环节纯靠现成工具拼凑会有很多坑。我搭这套工作台的核心组件包括文档解析层处理 PDF 和 Markdown、向量存储层存 chunk 和 embedding、检索层混合检索 重排序、生成层LLM 调用 追问管理。下面我按模块拆开讲每个环节都会说清楚为什么这么选、怎么操作、踩过什么坑。2. 整体架构设计与技术选型思路2.1 为什么不用现成的 SaaS 知识库一开始我也想过直接用现成的省事。但实际用下来有几个硬伤。第一是数据隐私我的项目资料里有些是内部文档传到第三方平台总归不放心。第二是解析质量不可控很多平台对 PDF 的解析就是简单提取文本表格、公式、代码块全丢而我的资料里恰好这些占比很高。第三是追问能力弱大部分工具只支持单轮问答你追问那这个方案的缺点呢它就不知道你在说什么了。自己搭的好处是每个环节都可控。PDF 解析不好我可以换解析器检索不准我可以调 chunk 策略追问断了我可以改 prompt 和上下文管理逻辑。代价是要花时间调试但一次搭好之后长期受益。2.2 核心架构分层整套工作台我分成四层每层职责明确层级职责核心组件文档解析层把 PDF/Markdown 转成结构化文本PyMuPDF、markdown-it、自定义清洗规则向量存储层文本分块、向量化、存储BGE-M3、ChromaDB检索层混合检索、重排序、上下文组装BM25 向量检索、BGE-Reranker生成层LLM 调用、追问管理、引用溯源本地模型或 API、对话历史压缩这个分层的好处是每层可以独立替换。比如你不想用 ChromaDB换成 Milvus 或 Qdrant 只需要改存储层的接口。你不想用 BGE 系列模型换成别的 embedding 模型也只影响向量化环节。2.3 关键选型背后的逻辑PDF 解析选 PyMuPDF 而不是 pdfplumberpdfplumber 对表格支持好但速度慢处理大文件时体验很差。PyMuPDF 速度快对文本和图片的提取都够用表格虽然弱一点但我后来用 Camelot 单独处理表格页组合起来效果最好。实测下来一份 200 页的技术文档PyMuPDF 提取文本大概 3 秒pdfplumber 要 15 秒以上。Embedding 选 BGE-M3 而不是 OpenAI 的 text-embeddingBGE-M3 支持多语言、长文本8192 token而且可以本地跑不依赖网络。对于中文技术文档BGE-M3 的检索效果明显好于通用模型。我做过对比测试同样 50 个查询BGE-M3 的 top-5 命中率是 86%通用模型是 72%。向量库选 ChromaDB 而不是 FAISSFAISS 性能更好但它是纯向量检索不支持元数据过滤。ChromaDB 支持按来源文件、文档类型过滤这在追问场景下很重要——用户问那篇论文里怎么说的我需要能按文件名过滤。ChromaDB 的性能够用几万条 chunk 的检索延迟在 50ms 以内。检索策略用混合检索而不是纯向量纯向量检索对语义匹配好但对精确关键词匹配差。比如你搜BGE-M3向量检索可能返回一堆讲 embedding 的段落但不一定包含这个具体型号。BM25 能精确匹配关键词两者结合再用 Reranker 重排效果最稳。实测混合检索比纯向量检索的准确率提升约 20%。3. PDF 与 Markdown 解析的实操细节3.1 PDF 解析文本、表格、图片分开处理PDF 是最麻烦的格式因为它本质上不是结构化文档而是一堆绘制指令。同样一段文字在不同 PDF 里的底层表示可能完全不同。我踩过的坑包括扫描版 PDF 提取出来是空白、双栏排版提取出来顺序错乱、表格提取出来变成一堆散落的数字。我的处理流程是这样的import fitz # PyMuPDF def parse_pdf(file_path): doc fitz.open(file_path) full_text [] for page_num, page in enumerate(doc): # 先判断是否是扫描页 text page.get_text() if len(text.strip()) 50: # 文本太少可能是扫描页走 OCR pix page.get_pixmap(dpi200) img_path f/tmp/page_{page_num}.png pix.save(img_path) text ocr_image(img_path) # 调用 OCR 引擎 # 检测表格区域 tables page.find_tables() if tables.tables: for table in tables: table_text table.to_markdown() text text.replace(table.extract()[0][0], table_text) full_text.append(f!-- page {page_num 1} --\n{text}) return \n\n.join(full_text)这里有几个关键点。第一是扫描页检测我用文本长度做阈值少于 50 个字符就认为是扫描页走 OCR。这个阈值不是绝对的你可以根据文档类型调整。第二是表格转 MarkdownPyMuPDF 的find_tables能识别表格区域转成 Markdown 表格后保留结构比纯文本好很多。第三是页码标记我在每页开头插入 HTML 注释标记页码这样后续检索到某个 chunk 时能知道它在原文档的哪一页方便溯源。注意PyMuPDF 的表格识别不是 100% 准确复杂表格合并单元格、嵌套表格经常识别错。我的做法是识别结果先转 Markdown如果发现某页表格特别复杂就手动修正或者用 Camelot 重新提取。不要指望全自动关键文档还是要人工过一遍。3.2 Markdown 解析保留结构和语义Markdown 比 PDF 好处理因为它本身就是结构化的。但直接按行读取会丢失层级信息比如你不知道某个段落属于哪个标题下面。我的做法是解析成 AST抽象语法树然后按标题层级切分。import markdown from markdown.extensions import tables, fenced_code, codehilite def parse_markdown(file_path): with open(file_path, r, encodingutf-8) as f: content f.read() # 解析成 HTML保留结构 html markdown.markdown( content, extensions[tables, fenced_code, codehilite, toc] ) # 按标题切分 sections split_by_heading(content) return sections def split_by_heading(content): lines content.split(\n) sections [] current_heading root current_content [] for line in lines: if line.startswith(#): if current_content: sections.append({ heading: current_heading, content: \n.join(current_content) }) current_heading line.strip(#).strip() current_content [] else: current_content.append(line) if current_content: sections.append({ heading: current_heading, content: \n.join(current_content) }) return sections这样切分的好处是每个 chunk 都带有标题上下文。检索的时候如果匹配到某个段落我能知道它属于哪个章节回答时可以引用在《XXX》的缓存策略一节中提到。代码块和数学公式要特殊处理。Markdown 里的代码块如果直接当普通文本处理向量化后会丢失语义。我的做法是把代码块单独提取出来用代码专用的 embedding 模型比如 CodeBERT向量化检索时如果查询包含代码相关词汇优先检索代码块。数学公式同理用 LaTeX 源码存储检索时匹配公式编号或关键词。3.3 文档清洗去掉噪音保留信号原始文档里有很多噪音页眉页脚、水印、广告、无关的参考文献列表。这些如果不清理会严重影响检索质量。我的清洗规则包括去掉重复出现的页眉页脚统计每行在文档中出现的频率超过 80% 页面的行认为是页眉页脚去掉纯数字行页码去掉过短的段落少于 10 个字符合并被错误换行拆散的段落如果一行结尾没有标点下一行开头是小写字母则合并清洗这一步看起来简单但效果很明显。我做过对比清洗前检索 top-5 命中率是 68%清洗后提升到 82%。因为很多噪音文本会干扰向量匹配去掉之后信号更清晰。4. 向量化与检索策略的深度调优4.1 文本分块不是越细越好分块chunking是 RAG 里最容易被忽视但影响最大的环节。分得太细上下文丢失检索到的片段没有足够信息回答问题分得太粗噪音太多向量表示不精确。我试过几种策略分块策略优点缺点适用场景固定长度 512 token实现简单切断语义通用按段落分块语义完整长度不均结构化文档按标题层级分块上下文清晰长章节需再切Markdown滑动窗口 256/128不丢边界冗余多精确检索我最终用的是混合策略先按标题层级切分如果某个章节超过 800 token再用滑动窗口切成 512 token 的子块重叠 128 token。这样既保留了标题上下文又控制了单块长度。def chunk_by_heading_with_sliding(sections, max_tokens800, chunk_size512, overlap128): chunks [] for section in sections: content section[content] tokens tokenize(content) if len(tokens) max_tokens: chunks.append({ heading: section[heading], content: content, tokens: len(tokens) }) else: # 滑动窗口切分 for i in range(0, len(tokens), chunk_size - overlap): chunk_tokens tokens[i:i chunk_size] chunk_text detokenize(chunk_tokens) chunks.append({ heading: section[heading], content: chunk_text, tokens: len(chunk_tokens), window_start: i }) return chunks提示overlap 不要设太大128 token 足够了。设太大比如 256会导致冗余 chunk 太多检索时返回一堆相似内容反而降低回答质量。4.2 向量化BGE-M3 的实际表现BGE-M3 是我目前用过最适合中文技术文档的 embedding 模型。它有三个优势支持 8192 token 长文本、多语言、检索效果好。我实测过同样一批技术文档BGE-M3 的检索准确率比 m3e-base 高约 15%比 text-embedding-ada-002 高约 20%。向量化的时候有个细节要注意查询和文档要用不同的前缀。BGE 系列模型训练时用了指令前缀查询要加为这个句子生成表示以用于检索相关文章文档不加。如果不加前缀检索效果会下降 5-10%。from FlagEmbedding import BGEM3FlagModel model BGEM3FlagModel(BAAI/bge-m3, use_fp16True) def embed_documents(texts): # 文档不加前缀 return model.encode(texts, batch_size12, max_length8192)[dense_vecs] def embed_query(query): # 查询加前缀 prefixed f为这个句子生成表示以用于检索相关文章{query} return model.encode([prefixed], max_length8192)[dense_vecs][0]向量维度是 1024存储用 float32 的话10 万条 chunk 大概占 400MB 内存。如果内存紧张可以用 float16 或者量化到 int8精度损失很小。4.3 混合检索BM25 向量 重排序纯向量检索的问题是它对精确匹配不敏感。比如你搜BGE-M3 的 max_length 是多少向量检索可能返回一堆讲 embedding 的段落但不一定包含这个具体参数。BM25 能精确匹配BGE-M3和max_length这两个关键词两者结合效果最好。我的检索流程是BM25 检索 top-20向量检索 top-20合并去重得到候选集用 BGE-Reranker 重排序取 top-5组装上下文送给 LLMfrom rank_bm25 import BM25Okapi from FlagEmbedding import FlagReranker # BM25 检索 bm25 BM25Okapi(tokenized_corpus) bm25_scores bm25.get_scores(tokenize(query)) bm25_top np.argsort(bm25_scores)[-20:] # 向量检索 query_vec embed_query(query) vec_scores cosine_similarity(query_vec, doc_vectors) vec_top np.argsort(vec_scores)[-20:] # 合并 candidates list(set(bm25_top) | set(vec_top)) # 重排序 reranker FlagReranker(BAAI/bge-reranker-v2-m3, use_fp16True) pairs [[query, docs[i]] for i in candidates] rerank_scores reranker.compute_score(pairs) final_top [candidates[i] for i in np.argsort(rerank_scores)[-5:]]重排序这一步很关键。我实测过不加 Reranker 的 top-5 准确率是 72%加了之后提升到 89%。因为向量检索和 BM25 各有偏好Reranker 能综合判断哪个片段真正相关。4.4 追问管理让对话有记忆单轮问答很简单但追问就复杂了。用户问这个方案有什么缺点你需要知道这个方案指的是上一轮讨论的那个方案。我的做法是维护一个对话历史每次追问时把历史压缩成摘要和当前问题一起送给 LLM。class ConversationManager: def __init__(self, max_history5): self.history [] self.max_history max_history def add_turn(self, question, answer): self.history.append({q: question, a: answer}) if len(self.history) self.max_history: self.history self.history[-self.max_history:] def build_query(self, current_question): if not self.history: return current_question # 把历史压缩成上下文 history_text \n.join([ f用户{h[q]}\n助手{h[a][:200]} for h in self.history[-3:] ]) return f对话历史\n{history_text}\n\n当前问题{current_question}这里有个技巧历史不要全量传只传最近 3 轮而且助手的回答只截取前 200 字。因为 LLM 的上下文窗口有限全量传会挤占检索结果的空间。另外追问时检索的 query 要用当前问题 上一轮问题的组合这样能保持语义连贯。5. 常见问题与排查技巧实录5.1 检索不准先查分块再查模型检索不准是最常见的问题。我的排查顺序是先看分块是否合理再看 embedding 模型是否适合最后看检索策略。分块问题的典型表现是检索到的片段总是缺头少尾或者包含大量无关内容。解决办法是调整 chunk_size 和 overlap或者改用按语义分块用 LLM 判断段落边界。模型问题的典型表现是语义相似的查询检索结果差异很大。解决办法是换模型或者检查是否加了正确的前缀。BGE 系列一定要加查询前缀这个坑我踩过。策略问题的典型表现是精确关键词搜不到或者语义匹配但关键词不匹配。解决办法是加 BM25 混合检索或者调 Reranker 的权重。5.2 回答胡编检查上下文和 promptLLM 胡编幻觉通常是因为上下文里没有相关信息但模型还是硬答。解决办法有两个一是 prompt 里明确要求如果上下文中没有相关信息回答根据现有资料无法回答二是检索时设一个相似度阈值低于阈值的片段不送给 LLM。def build_prompt(query, contexts): context_text \n\n.join([ f[来源{c[source]}]\n{c[content]} for c in contexts ]) return f基于以下资料回答问题。如果资料中没有相关信息请直接说根据现有资料无法回答不要编造。 资料 {context_text} 问题{query} 回答注意阈值不要设太高否则会漏掉相关信息。我一般设 0.3余弦相似度低于这个值的片段基本不相关。5.3 追问断片检查历史管理和检索 query追问断片的典型表现是第二轮回答还行第三轮开始答非所问。原因是历史管理有问题或者检索 query 没有包含历史信息。我的解决办法是追问时检索 query 用上一轮问题 当前问题的组合而不是只用当前问题。这样检索到的片段既包含当前问题的相关信息也包含上一轮的上下文。def build_retrieval_query(current_question, history): if not history: return current_question last_q history[-1][q] return f{last_q} {current_question}5.4 性能瓶颈向量检索和 LLM 调用性能瓶颈通常在两个地方向量检索和 LLM 调用。向量检索慢是因为数据量大或者索引没建好。ChromaDB 默认用 HNSW 索引几万条数据检索延迟在 50ms 以内。如果超过 100ms检查是否用了暴力检索。LLM 调用慢是因为模型太大或者网络延迟。本地跑 7B 模型生成 200 字回答大概 3-5 秒。如果用 API延迟取决于网络。我的做法是流式输出用户看到第一个字就开始显示体验好很多。问题排查方向解决办法检索不准分块、模型、策略调 chunk_size、换模型、加 BM25回答胡编上下文、prompt加阈值、改 prompt追问断片历史管理、检索 query压缩历史、组合 query性能慢索引、模型用 HNSW、流式输出6. 几个让我少走弯路的实操心得第一个心得是不要追求全自动。我一开始想做一个完全自动化的流水线PDF 丢进去就出知识库。实际做下来发现关键文档的解析和清洗还是需要人工介入。比如某份 PDF 的表格识别错了你不修正的话后续检索和回答都会受影响。我的做法是解析后生成一个预览人工快速过一遍标记有问题的页面然后针对性修正。第二个心得是检索日志要留着。我每次检索都会记录 query、检索到的 chunk、最终回答。这样当用户反馈回答不对时我能回溯是检索错了还是生成错了。如果是检索错了调检索策略如果是生成错了调 prompt。没有日志的话排查全靠猜。第三个心得是小模型够用。我一开始用 70B 的模型做生成效果确实好但速度慢、成本高。后来换成 7B 的模型配合好的检索和 prompt效果差距不大但速度快了 5 倍。对于知识库问答这种任务检索质量比模型大小更重要。第四个心得是定期重建索引。文档更新后旧的向量还在库里会导致检索到过时信息。我的做法是每周重建一次索引或者文档更新时增量更新。增量更新要注意删除旧 chunk否则会有重复。这套工作台我用了大概半年目前管理着 2000 多份文档包括 PDF 论文、Markdown 笔记、项目文档。日常查询的准确率在 85% 左右追问能连续 5-6 轮不跑偏。当然还有很多可以优化的地方比如多模态检索图片、表格、知识图谱增强、自动摘要生成。但核心的 RAG 链路已经跑通了剩下的就是按需迭代。如果你也想搭一套我的建议是从小规模开始。先拿 10-20 份文档跑通流程调好分块和检索再逐步扩大规模。不要一上来就搞几千份文档那样调试起来很痛苦。另外工具选型不要纠结BGE-M3 ChromaDB 任意 LLM 这个组合已经能覆盖 90% 的场景先把流程跑通再考虑优化。