1. 为什么“上传 PDF 聊天”远远不够我最早做个人知识库的时候也走过那条最省事的路把一堆 PDF 丢进向量库接个大模型问一句答一句。头两天觉得挺爽第三天就崩了——同一份合同我改了三版它把旧版和新版的内容混在一起答问一个跨章节的问题它只捞到半句话最要命的是它答得头头是道我却找不到这句话到底出自哪一页没法核对。这就是“上传 PDF 聊天”和真正的个人 RAG 知识库之间的差距。前者是个玩具后者要解决四个硬问题版本治理同一份文档的多个版本怎么共存、怎么默认用最新、父子分块小块用来精准命中大块用来喂给模型足够上下文、混合检索纯向量检索在关键词、编号、专有名词上经常翻车得配上全文检索、可引用回答每句话都要能回溯到原文的具体位置。这套东西适合谁适合那些文档量在几百到几千份、对准确性有要求、又不想把资料传到别人服务器上的个人用户——比如做研究的、写方案的、管合同和标书的、整理技术文档的。它不需要多贵的硬件一台普通笔记本就能跑起来但需要你把上面四个环节都想清楚。下面我按自己实际搭过的一套方案把每个环节拆开讲透。2. 整体架构设计与技术选型思路2.1 先想清楚数据流再动手写代码很多人一上来就装框架、拉模型结果数据流是乱的。我建议先把整条链路画在纸上原始文档 → 解析成结构化文本 → 版本登记 → 分块父块子块→ 建索引向量索引全文索引→ 检索混合重排→ 组装上下文 → 生成带引用的回答。这条链路里每一步都会影响后面的效果。比如解析阶段如果把 PDF 的表格拍扁成一行文字后面检索再强也救不回来版本登记如果没做检索时就会新旧混答。所以我的原则是上游尽量保留结构下游才有得选。2.2 技术选型为什么是这套组合我最终用的组合是解析用PyMuPDF Unstructured向量库用Qdrant本地 Docker 跑全文检索用SQLite FTS5轻量、零依赖嵌入模型用BGE-M3中英文都稳还支持稀疏向量重排用BGE-reranker生成模型本地用Qwen2.5-7B-Instruct量化版或者按需调云端 API。选 Qdrant 而不是 FAISS是因为它原生支持payload 过滤——版本治理要靠这个检索时能直接按doc_id is_latest过滤不用自己写一堆后处理。选 SQLite FTS5 而不是 Elasticsearch是因为个人场景下 ES 太重FTS5 单文件、零运维配合jieba分词做中文全文检索完全够用。选 BGE-M3 是因为它一个模型同时输出稠密向量和稀疏向量混合检索时不用维护两套嵌入模型省事。提示如果你的文档以英文为主嵌入模型可以换成bge-large-en-v1.5体积更小、速度更快中文为主就别省M3 的中文表现明显更好。2.3 版本治理为什么必须放在最前面版本治理不是“锦上添花”它是整个知识库可信度的地基。我踩过的坑是一开始没做版本同一份《需求规格说明书》v1 和 v2 都在库里问“登录接口的超时时间是多少”它把 v1 的 30 秒和 v2 的 60 秒都捞出来然后编了个“30 到 60 秒之间”的答案。这种错误在技术文档里是致命的。我的做法是给每份文档一个稳定的doc_id比如用文件名去掉版本号后的哈希每次上传新版本时把旧版本的is_latest置为false新版本置为true。检索时默认只查is_latesttrue但保留一个“查历史版本”的开关。这样既保证默认答案是最新的又能在需要追溯时查到旧版。3. 父子分块让检索命中准、上下文够3.1 为什么单一粒度的分块一定会失败分块粒度是个两难块切得小比如 200 字向量检索命中率高但喂给模型的上下文太碎它答不完整块切得大比如 2000 字上下文够了但向量被平均掉检索经常命中不到真正相关的那一段。我试过固定 512 token 切分结果是问细节问题命中率还行问“这一章讲了什么”就完全抓瞎。父子分块就是来解决这个矛盾的。核心思想是用子块做检索用父块做生成。子块切得小200-300 字保证检索精准每个子块记录自己属于哪个父块1000-1500 字命中子块后把对应的父块整体喂给模型。这样检索和生成各取所需。3.2 父子块的具体切分参数与计算我的切分参数是这样的父块目标 1200 字子块目标 250 字子块之间重叠 50 字父块之间重叠 100 字。为什么这么定因为嵌入模型 BGE-M3 的最佳输入长度在 512 token 以内250 个中文字大约 350 token留有余量而生成模型 Qwen2.5-7B 的上下文窗口是 32K一次喂 3-5 个父块约 6000 字完全没问题。切分时我优先按语义边界切而不是硬按字数。具体做法是先用Unstructured把文档解析成带标题层级的元素列表然后按标题层级聚合——一个三级标题下的内容如果不超过 1200 字就作为一个父块超过就按段落再切。子块则在父块内部按句子边界切保证不切断句子。# 父子分块核心逻辑示意 def build_parent_child(elements, parent_size1200, child_size250, child_overlap50): parents [] for section in group_by_heading(elements): # 按标题层级聚合 text section.text if len(text) parent_size: parents.append({text: text, heading: section.heading}) else: for chunk in split_by_paragraph(text, parent_size): parents.append({text: chunk, heading: section.heading}) # 为每个父块生成子块 result [] for p_idx, parent in enumerate(parents): children split_by_sentence(parent[text], child_size, child_overlap) for c_idx, child in enumerate(children): result.append({ parent_id: p_idx, child_text: child, parent_text: parent[text], heading: parent[heading] }) return result3.3 父子分块的存储结构存储上我用了两张表或两个 collectionparents存父块全文和元数据children存子块向量、子块文本和指向父块的parent_id。检索时先查children拿到parent_id再去parents取全文。这样向量库只需要索引小块的子块检索效率高而生成时用的是完整父块。注意父块不要重复存储。如果多个子块命中同一个父块去重后再喂给模型否则上下文里会出现重复内容既浪费 token 又可能让模型困惑。4. 混合检索向量 全文 重排的三段式4.1 纯向量检索的三个死穴纯向量检索在语义相似上很强但有三类查询它经常翻车精确编号比如“GB/T 19001-2016 第 7.5.3 条”、专有名词比如某个内部系统代号、否定和限定比如“不含附件的报价”。这些查询里关键词的精确匹配比语义相似更重要。我实测过一个案例问“ISO 27001 的 A.8.2 条款讲什么”纯向量检索返回的是“信息安全管理体系概述”这种泛泛的段落因为“A.8.2”这个 token 在嵌入时被稀释了。加上全文检索后FTS5 直接命中包含“A.8.2”的段落效果立竿见影。4.2 混合检索的融合策略RRF 而不是加权求和向量检索和全文检索的分数不在一个量纲上直接加权求和需要调参很麻烦。我用的是RRFReciprocal Rank Fusion倒数排名融合对每个结果分数 1 / (k rank)k 通常取 60。然后把两路结果的 RRF 分数相加排序。这个方法不需要归一化对两路检索的分数尺度不敏感实测比加权求和稳。def rrf_fusion(vector_results, bm25_results, k60, top_n20): scores {} for rank, doc in enumerate(vector_results): scores[doc.id] scores.get(doc.id, 0) 1 / (k rank 1) for rank, doc in enumerate(bm25_results): scores[doc.id] scores.get(doc.id, 0) 1 / (k rank 1) return sorted(scores.items(), keylambda x: -x[1])[:top_n]4.3 重排把最相关的顶到最前面RRF 融合后取 top 20再用BGE-reranker做交叉编码重排取 top 5 喂给模型。重排模型是 query 和 document 一起编码的精度比双塔的向量检索高很多但速度慢所以只用在候选集上。这一步是“可引用回答”质量的关键——重排后的 top 5 通常就是真正相关的那几段。检索阶段方法候选数作用召回向量 FTS5各 20保证不漏融合RRF20合并两路结果重排BGE-reranker5保证精准生成LLM 父块3-5 父块保证上下文完整4.4 版本过滤怎么嵌进检索版本过滤放在召回阶段向量检索时用 Qdrant 的filter参数限定is_latesttrueFTS5 查询时加WHERE is_latest1。这样旧版本根本不会进入候选集从源头杜绝新旧混答。如果用户明确要查历史再放开这个过滤。5. 可引用回答让每句话都能回溯5.1 引用不是加个链接那么简单很多人以为“可引用”就是在回答末尾附几个文档链接。这不够。真正的可引用要求回答里的每个事实性陈述都能对应到原文的具体片段。用户点一下就能看到原文那一句而不是打开一个 50 页的 PDF 自己找。我的做法是给每个父块和子块都分配一个稳定的chunk_id格式是doc_id#parent_idx#child_idx。生成时我在 prompt 里要求模型用[1]、[2]这样的标记标注每句话的来源并在上下文里给每个父块编号。生成后我把标记替换成可点击的引用指向对应的chunk_id。5.2 引用标注的 prompt 设计prompt 里我会明确写“每个事实性句子后面必须标注来源编号编号对应上下文中的[来源 N]。如果某句话是你根据常识补充的标注[常识]。”这样模型不敢乱标也方便我事后核查。实测下来加了强制标注要求后模型的幻觉明显减少——因为它知道每句话都要“交出处”。提示如果模型经常漏标或乱标可以在 prompt 里给一两个示例few-shot效果会好很多。示例要选那种“一句话对应一个来源”的简单案例。5.3 引用回溯的界面实现前端我用的是简单的 Streamlit回答里[1]是可点击的点开后右侧展开对应的父块原文并高亮命中的子块。这样用户能一眼看到“模型这句话是从哪来的”。如果原文是 PDF我还会用 PyMuPDF 定位到具体页码给出页码提示。6. 实操全流程从零搭一套本地 RAG 知识库6.1 环境准备与依赖安装我用的环境是 macOS Docker Python 3.11。Qdrant 用 Docker 跑其他都是 Python 包。核心依赖pymupdf、unstructured、qdrant-client、FlagEmbedding、jieba、streamlit。# 启动 Qdrant docker run -d -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant # 安装 Python 依赖 pip install pymupdf unstructured qdrant-client FlagEmbedding jieba streamlit6.2 文档解析与版本登记解析时我优先用 PyMuPDF 提取文本和页码表格用pdfplumber单独处理。解析完给文档算一个doc_id文件名去版本号后的 SHA1然后查库如果doc_id已存在把旧版本is_latest置 false插入新版本。import hashlib, fitz def parse_pdf(path): doc fitz.open(path) pages [] for i, page in enumerate(doc): pages.append({page: i 1, text: page.get_text()}) return pages def make_doc_id(filename): base re.sub(r[_-]?v?\d(\.\d)*, , filename) # 去掉版本号 return hashlib.sha1(base.encode()).hexdigest()[:16]6.3 建索引向量 全文双写子块向量写入 Qdrant同时把子块文本和父块文本写入 SQLite。FTS5 表用jieba预分词后存入查询时同样分词。这里有个细节FTS5 默认不支持中文分词必须自己预处理。import sqlite3, jieba def init_fts(db_path): conn sqlite3.connect(db_path) conn.execute(CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(child_id, text, doc_id, is_latest)) return conn def insert_fts(conn, child_id, text, doc_id, is_latest): seg .join(jieba.cut(text)) conn.execute(INSERT INTO chunks_fts VALUES (?,?,?,?), (child_id, seg, doc_id, is_latest))6.4 检索与生成的串联检索时并行跑向量和 FTS5RRF 融合重排取 top 5然后按parent_id去重取父块组装上下文。生成时把父块编号要求模型标注引用。整个流程我封装成一个query()函数Streamlit 里直接调。def query(question, use_historyFalse): vec_hits vector_search(question, latest_onlynot use_history) bm25_hits fts_search(question, latest_onlynot use_history) fused rrf_fusion(vec_hits, bm25_hits) reranked rerank(question, fused)[:5] parents fetch_parents_dedup(reranked) context format_context(parents) answer generate(question, context) return answer, parents7. 常见问题与排查技巧实录7.1 检索命中不准怎么办先看是召回问题还是重排问题。把 RRF 融合后的 top 20 打出来如果正确答案不在里面是召回问题——检查子块切分是否太碎、嵌入模型是否适合你的语言如果正确答案在里面但没进 top 5是重排问题——换更强的 reranker 或调整候选数。7.2 模型答非所问或编造内容九成是上下文组装的问题。检查喂进去的父块是不是真的相关有没有混入无关内容。另外 prompt 里要明确“只根据上下文回答上下文没有就说不知道”。我还会在生成后做一次引用校验如果回答里的[N]对应的父块里找不到相关句子就标记为“待核查”。7.3 版本治理的常见坑最大的坑是doc_id不稳定。如果文件名一变doc_id就变了版本就串不起来。我的做法是维护一个映射表手动确认哪些文件是同一份文档的不同版本。另外删除文档时不要物理删除把is_latest置 false 并加is_deleted标记保留追溯能力。问题现象可能原因排查方向新旧版本混答版本过滤没生效检查检索 filter 和 FTS 的 is_latest细节问题答不出子块太大或太小调整子块到 200-300 字关键词查不到没做全文检索加 FTS5 jieba引用对不上chunk_id 映射错检查父子块 id 生成逻辑回答太泛父块太大或重排弱缩小父块、加强 reranker7.4 性能与成本的平衡本地跑 7B 模型一次查询大概 3-5 秒含检索和生成可以接受。如果文档量超过 5000 份Qdrant 建议开 HNSW 索引并调大ef_construct。嵌入可以离线批量做不用每次查询都算。重排模型如果嫌慢可以只在候选数大于 10 时才启用。8. 几个我踩过的坑和私房技巧第一个坑是PDF 解析的表格。PyMuPDF 提取表格会变成一堆乱序文本我后来用pdfplumber单独抽表格转成 Markdown 表格再入库检索和生成都清楚多了。第二个坑是子块重叠。重叠太多会导致同一段内容被多次命中去重逻辑必须做在父块层面而不是子块层面。私房技巧分享两个。一是给父块加标题前缀在父块文本前面加上它所属的章节标题路径如“第 3 章 3.2 节 接口设计”这样即使父块被单独取出模型也知道它在文档里的位置回答时能带上上下文。二是查询改写用户的问题往往口语化我会先用一个小模型把问题改写成 2-3 个检索友好的查询分别检索后合并结果召回率能提升不少。还有一个关于版本治理的心得不要试图自动判断哪个版本更新。文件修改时间不可靠复制粘贴会变版本号格式也不统一。我的做法是上传时让用户手动确认“这是新版本还是新文档”一次确认后面就稳了。这个交互成本很低但省掉了无数麻烦。最后说一个可引用回答的细节引用编号不要用全局递增而是按本次回答里出现的顺序重新编号。否则用户看到[7]会以为前面还有 6 个引用体验很割裂。生成后做一次重编号把用到的来源按出现顺序排成[1]、[2]干净利落。 
长河君 · 2026/10/6 17:30:38 · 阅读 1.2k 从玩具到生产级：个人RAG知识库的版本治理、父子分块与混合检索实战
1. 为什么“上传 PDF 聊天”远远不够我最早做个人知识库的时候也走过那条最省事的路把一堆 PDF 丢进向量库接个大模型问一句答一句。头两天觉得挺爽第三天就崩了——同一份合同我改了三版它把旧版和新版的内容混在一起答问一个跨章节的问题它只捞到半句话最要命的是它答得头头是道我却找不到这句话到底出自哪一页没法核对。这就是“上传 PDF 聊天”和真正的个人 RAG 知识库之间的差距。前者是个玩具后者要解决四个硬问题版本治理同一份文档的多个版本怎么共存、怎么默认用最新、父子分块小块用来精准命中大块用来喂给模型足够上下文、混合检索纯向量检索在关键词、编号、专有名词上经常翻车得配上全文检索、可引用回答每句话都要能回溯到原文的具体位置。这套东西适合谁适合那些文档量在几百到几千份、对准确性有要求、又不想把资料传到别人服务器上的个人用户——比如做研究的、写方案的、管合同和标书的、整理技术文档的。它不需要多贵的硬件一台普通笔记本就能跑起来但需要你把上面四个环节都想清楚。下面我按自己实际搭过的一套方案把每个环节拆开讲透。2. 整体架构设计与技术选型思路2.1 先想清楚数据流再动手写代码很多人一上来就装框架、拉模型结果数据流是乱的。我建议先把整条链路画在纸上原始文档 → 解析成结构化文本 → 版本登记 → 分块父块子块→ 建索引向量索引全文索引→ 检索混合重排→ 组装上下文 → 生成带引用的回答。这条链路里每一步都会影响后面的效果。比如解析阶段如果把 PDF 的表格拍扁成一行文字后面检索再强也救不回来版本登记如果没做检索时就会新旧混答。所以我的原则是上游尽量保留结构下游才有得选。2.2 技术选型为什么是这套组合我最终用的组合是解析用PyMuPDF Unstructured向量库用Qdrant本地 Docker 跑全文检索用SQLite FTS5轻量、零依赖嵌入模型用BGE-M3中英文都稳还支持稀疏向量重排用BGE-reranker生成模型本地用Qwen2.5-7B-Instruct量化版或者按需调云端 API。选 Qdrant 而不是 FAISS是因为它原生支持payload 过滤——版本治理要靠这个检索时能直接按doc_id is_latest过滤不用自己写一堆后处理。选 SQLite FTS5 而不是 Elasticsearch是因为个人场景下 ES 太重FTS5 单文件、零运维配合jieba分词做中文全文检索完全够用。选 BGE-M3 是因为它一个模型同时输出稠密向量和稀疏向量混合检索时不用维护两套嵌入模型省事。提示如果你的文档以英文为主嵌入模型可以换成bge-large-en-v1.5体积更小、速度更快中文为主就别省M3 的中文表现明显更好。2.3 版本治理为什么必须放在最前面版本治理不是“锦上添花”它是整个知识库可信度的地基。我踩过的坑是一开始没做版本同一份《需求规格说明书》v1 和 v2 都在库里问“登录接口的超时时间是多少”它把 v1 的 30 秒和 v2 的 60 秒都捞出来然后编了个“30 到 60 秒之间”的答案。这种错误在技术文档里是致命的。我的做法是给每份文档一个稳定的doc_id比如用文件名去掉版本号后的哈希每次上传新版本时把旧版本的is_latest置为false新版本置为true。检索时默认只查is_latesttrue但保留一个“查历史版本”的开关。这样既保证默认答案是最新的又能在需要追溯时查到旧版。3. 父子分块让检索命中准、上下文够3.1 为什么单一粒度的分块一定会失败分块粒度是个两难块切得小比如 200 字向量检索命中率高但喂给模型的上下文太碎它答不完整块切得大比如 2000 字上下文够了但向量被平均掉检索经常命中不到真正相关的那一段。我试过固定 512 token 切分结果是问细节问题命中率还行问“这一章讲了什么”就完全抓瞎。父子分块就是来解决这个矛盾的。核心思想是用子块做检索用父块做生成。子块切得小200-300 字保证检索精准每个子块记录自己属于哪个父块1000-1500 字命中子块后把对应的父块整体喂给模型。这样检索和生成各取所需。3.2 父子块的具体切分参数与计算我的切分参数是这样的父块目标 1200 字子块目标 250 字子块之间重叠 50 字父块之间重叠 100 字。为什么这么定因为嵌入模型 BGE-M3 的最佳输入长度在 512 token 以内250 个中文字大约 350 token留有余量而生成模型 Qwen2.5-7B 的上下文窗口是 32K一次喂 3-5 个父块约 6000 字完全没问题。切分时我优先按语义边界切而不是硬按字数。具体做法是先用Unstructured把文档解析成带标题层级的元素列表然后按标题层级聚合——一个三级标题下的内容如果不超过 1200 字就作为一个父块超过就按段落再切。子块则在父块内部按句子边界切保证不切断句子。# 父子分块核心逻辑示意 def build_parent_child(elements, parent_size1200, child_size250, child_overlap50): parents [] for section in group_by_heading(elements): # 按标题层级聚合 text section.text if len(text) parent_size: parents.append({text: text, heading: section.heading}) else: for chunk in split_by_paragraph(text, parent_size): parents.append({text: chunk, heading: section.heading}) # 为每个父块生成子块 result [] for p_idx, parent in enumerate(parents): children split_by_sentence(parent[text], child_size, child_overlap) for c_idx, child in enumerate(children): result.append({ parent_id: p_idx, child_text: child, parent_text: parent[text], heading: parent[heading] }) return result3.3 父子分块的存储结构存储上我用了两张表或两个 collectionparents存父块全文和元数据children存子块向量、子块文本和指向父块的parent_id。检索时先查children拿到parent_id再去parents取全文。这样向量库只需要索引小块的子块检索效率高而生成时用的是完整父块。注意父块不要重复存储。如果多个子块命中同一个父块去重后再喂给模型否则上下文里会出现重复内容既浪费 token 又可能让模型困惑。4. 混合检索向量 全文 重排的三段式4.1 纯向量检索的三个死穴纯向量检索在语义相似上很强但有三类查询它经常翻车精确编号比如“GB/T 19001-2016 第 7.5.3 条”、专有名词比如某个内部系统代号、否定和限定比如“不含附件的报价”。这些查询里关键词的精确匹配比语义相似更重要。我实测过一个案例问“ISO 27001 的 A.8.2 条款讲什么”纯向量检索返回的是“信息安全管理体系概述”这种泛泛的段落因为“A.8.2”这个 token 在嵌入时被稀释了。加上全文检索后FTS5 直接命中包含“A.8.2”的段落效果立竿见影。4.2 混合检索的融合策略RRF 而不是加权求和向量检索和全文检索的分数不在一个量纲上直接加权求和需要调参很麻烦。我用的是RRFReciprocal Rank Fusion倒数排名融合对每个结果分数 1 / (k rank)k 通常取 60。然后把两路结果的 RRF 分数相加排序。这个方法不需要归一化对两路检索的分数尺度不敏感实测比加权求和稳。def rrf_fusion(vector_results, bm25_results, k60, top_n20): scores {} for rank, doc in enumerate(vector_results): scores[doc.id] scores.get(doc.id, 0) 1 / (k rank 1) for rank, doc in enumerate(bm25_results): scores[doc.id] scores.get(doc.id, 0) 1 / (k rank 1) return sorted(scores.items(), keylambda x: -x[1])[:top_n]4.3 重排把最相关的顶到最前面RRF 融合后取 top 20再用BGE-reranker做交叉编码重排取 top 5 喂给模型。重排模型是 query 和 document 一起编码的精度比双塔的向量检索高很多但速度慢所以只用在候选集上。这一步是“可引用回答”质量的关键——重排后的 top 5 通常就是真正相关的那几段。检索阶段方法候选数作用召回向量 FTS5各 20保证不漏融合RRF20合并两路结果重排BGE-reranker5保证精准生成LLM 父块3-5 父块保证上下文完整4.4 版本过滤怎么嵌进检索版本过滤放在召回阶段向量检索时用 Qdrant 的filter参数限定is_latesttrueFTS5 查询时加WHERE is_latest1。这样旧版本根本不会进入候选集从源头杜绝新旧混答。如果用户明确要查历史再放开这个过滤。5. 可引用回答让每句话都能回溯5.1 引用不是加个链接那么简单很多人以为“可引用”就是在回答末尾附几个文档链接。这不够。真正的可引用要求回答里的每个事实性陈述都能对应到原文的具体片段。用户点一下就能看到原文那一句而不是打开一个 50 页的 PDF 自己找。我的做法是给每个父块和子块都分配一个稳定的chunk_id格式是doc_id#parent_idx#child_idx。生成时我在 prompt 里要求模型用[1]、[2]这样的标记标注每句话的来源并在上下文里给每个父块编号。生成后我把标记替换成可点击的引用指向对应的chunk_id。5.2 引用标注的 prompt 设计prompt 里我会明确写“每个事实性句子后面必须标注来源编号编号对应上下文中的[来源 N]。如果某句话是你根据常识补充的标注[常识]。”这样模型不敢乱标也方便我事后核查。实测下来加了强制标注要求后模型的幻觉明显减少——因为它知道每句话都要“交出处”。提示如果模型经常漏标或乱标可以在 prompt 里给一两个示例few-shot效果会好很多。示例要选那种“一句话对应一个来源”的简单案例。5.3 引用回溯的界面实现前端我用的是简单的 Streamlit回答里[1]是可点击的点开后右侧展开对应的父块原文并高亮命中的子块。这样用户能一眼看到“模型这句话是从哪来的”。如果原文是 PDF我还会用 PyMuPDF 定位到具体页码给出页码提示。6. 实操全流程从零搭一套本地 RAG 知识库6.1 环境准备与依赖安装我用的环境是 macOS Docker Python 3.11。Qdrant 用 Docker 跑其他都是 Python 包。核心依赖pymupdf、unstructured、qdrant-client、FlagEmbedding、jieba、streamlit。# 启动 Qdrant docker run -d -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant # 安装 Python 依赖 pip install pymupdf unstructured qdrant-client FlagEmbedding jieba streamlit6.2 文档解析与版本登记解析时我优先用 PyMuPDF 提取文本和页码表格用pdfplumber单独处理。解析完给文档算一个doc_id文件名去版本号后的 SHA1然后查库如果doc_id已存在把旧版本is_latest置 false插入新版本。import hashlib, fitz def parse_pdf(path): doc fitz.open(path) pages [] for i, page in enumerate(doc): pages.append({page: i 1, text: page.get_text()}) return pages def make_doc_id(filename): base re.sub(r[_-]?v?\d(\.\d)*, , filename) # 去掉版本号 return hashlib.sha1(base.encode()).hexdigest()[:16]6.3 建索引向量 全文双写子块向量写入 Qdrant同时把子块文本和父块文本写入 SQLite。FTS5 表用jieba预分词后存入查询时同样分词。这里有个细节FTS5 默认不支持中文分词必须自己预处理。import sqlite3, jieba def init_fts(db_path): conn sqlite3.connect(db_path) conn.execute(CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(child_id, text, doc_id, is_latest)) return conn def insert_fts(conn, child_id, text, doc_id, is_latest): seg .join(jieba.cut(text)) conn.execute(INSERT INTO chunks_fts VALUES (?,?,?,?), (child_id, seg, doc_id, is_latest))6.4 检索与生成的串联检索时并行跑向量和 FTS5RRF 融合重排取 top 5然后按parent_id去重取父块组装上下文。生成时把父块编号要求模型标注引用。整个流程我封装成一个query()函数Streamlit 里直接调。def query(question, use_historyFalse): vec_hits vector_search(question, latest_onlynot use_history) bm25_hits fts_search(question, latest_onlynot use_history) fused rrf_fusion(vec_hits, bm25_hits) reranked rerank(question, fused)[:5] parents fetch_parents_dedup(reranked) context format_context(parents) answer generate(question, context) return answer, parents7. 常见问题与排查技巧实录7.1 检索命中不准怎么办先看是召回问题还是重排问题。把 RRF 融合后的 top 20 打出来如果正确答案不在里面是召回问题——检查子块切分是否太碎、嵌入模型是否适合你的语言如果正确答案在里面但没进 top 5是重排问题——换更强的 reranker 或调整候选数。7.2 模型答非所问或编造内容九成是上下文组装的问题。检查喂进去的父块是不是真的相关有没有混入无关内容。另外 prompt 里要明确“只根据上下文回答上下文没有就说不知道”。我还会在生成后做一次引用校验如果回答里的[N]对应的父块里找不到相关句子就标记为“待核查”。7.3 版本治理的常见坑最大的坑是doc_id不稳定。如果文件名一变doc_id就变了版本就串不起来。我的做法是维护一个映射表手动确认哪些文件是同一份文档的不同版本。另外删除文档时不要物理删除把is_latest置 false 并加is_deleted标记保留追溯能力。问题现象可能原因排查方向新旧版本混答版本过滤没生效检查检索 filter 和 FTS 的 is_latest细节问题答不出子块太大或太小调整子块到 200-300 字关键词查不到没做全文检索加 FTS5 jieba引用对不上chunk_id 映射错检查父子块 id 生成逻辑回答太泛父块太大或重排弱缩小父块、加强 reranker7.4 性能与成本的平衡本地跑 7B 模型一次查询大概 3-5 秒含检索和生成可以接受。如果文档量超过 5000 份Qdrant 建议开 HNSW 索引并调大ef_construct。嵌入可以离线批量做不用每次查询都算。重排模型如果嫌慢可以只在候选数大于 10 时才启用。8. 几个我踩过的坑和私房技巧第一个坑是PDF 解析的表格。PyMuPDF 提取表格会变成一堆乱序文本我后来用pdfplumber单独抽表格转成 Markdown 表格再入库检索和生成都清楚多了。第二个坑是子块重叠。重叠太多会导致同一段内容被多次命中去重逻辑必须做在父块层面而不是子块层面。私房技巧分享两个。一是给父块加标题前缀在父块文本前面加上它所属的章节标题路径如“第 3 章 3.2 节 接口设计”这样即使父块被单独取出模型也知道它在文档里的位置回答时能带上上下文。二是查询改写用户的问题往往口语化我会先用一个小模型把问题改写成 2-3 个检索友好的查询分别检索后合并结果召回率能提升不少。还有一个关于版本治理的心得不要试图自动判断哪个版本更新。文件修改时间不可靠复制粘贴会变版本号格式也不统一。我的做法是上传时让用户手动确认“这是新版本还是新文档”一次确认后面就稳了。这个交互成本很低但省掉了无数麻烦。最后说一个可引用回答的细节引用编号不要用全局递增而是按本次回答里出现的顺序重新编号。否则用户看到[7]会以为前面还有 6 个引用体验很割裂。生成后做一次重编号把用到的来源按出现顺序排成[1]、[2]干净利落。