1. 从关键词匹配到结构导航PageIndex 到底在解决什么如果你最近在折腾 RAG 应用大概率会遇到一个很尴尬的场景用户问第三章第二节里提到的那个参数默认值是多少你的向量检索返回了一堆语义相似但位置完全不对的片段模型拿着这些片段开始一本正经地胡说八道。这不是模型的问题是检索层的问题——向量相似度天然不擅长处理结构定位这类需求。PageIndex 这个项目从名字就能看出来它想干的事给文档建立一个页面/章节级别的索引让检索不再只依赖语义向量而是结合文档本身的结构信息来定位内容。它要解决的核心痛点是传统 RAG 在长文档、结构化文档手册、规范、论文、合同、技术文档场景下找得到相关内容但找不准具体位置的问题。我先把话说清楚PageIndex 不是一个向量数据库也不是一个 LLM 框架它更像是夹在文档解析和向量检索之间的一层结构感知索引层。你可以把它理解成给文档做了一份目录 页码 章节树的元数据检索时先用结构缩小范围再用语义做精排。这个思路在 RAG 圈子里不算全新但 PageIndex 把它做成了一个相对独立、可复用的组件这是它的价值所在。这篇文章适合谁看三类人一是正在做 RAG 项目、被长文档检索准确率折磨的开发者二是想理解结构感知检索这套思路到底怎么落地的人三是手上有大量 PDF/Word/技术手册需要做知识库、但发现纯向量方案效果不稳定的团队。我会从原理、设计取舍、实操步骤、踩坑经验几个角度把它讲透尽量让你看完能直接上手改自己的检索链路。需要提前说明的是PageIndex 目前公开的资料相对零散很多细节需要结合 RAG 领域的通用实践来补全。下面涉及具体实现的部分我会明确标注哪些是项目本身的思路、哪些是我基于常见工程实践做的合理推断你按自己项目的实际情况调整。2. 为什么纯向量检索在长文档上会翻车2.1 向量相似度的本质局限它只懂像不像不懂在哪先把这个问题的根子讲清楚。向量检索的工作原理是把文本切成 chunk用 embedding 模型把每个 chunk 映射成一个高维向量然后算 query 向量和 chunk 向量的余弦相似度取 Top-K。这套机制的核心假设是语义相似的文本向量距离就近。问题在于用户的问题里往往包含两类信息一类是语义信息我在问什么概念另一类是结构信息这个东西在文档的哪个位置。向量检索只能捕捉前者对后者几乎无能为力。举个具体的例子一份 200 页的产品手册里面默认超时时间这个短语可能在 8 个不同章节出现分别对应不同的模块。用户问网络模块的默认超时时间是多少向量检索会把 8 个片段都捞出来因为它们语义高度相似但真正对的只有网络模块那一章的那个。更麻烦的是 chunk 切分本身。固定长度切分比如 512 token 一刀切会把章节边界切碎导致一个完整的逻辑单元被拆到两个 chunk 里检索时要么漏掉一半要么召回一个语义不完整的片段。而按语义切分虽然好一些但依然丢失了这个 chunk 属于哪一章、哪一节、第几页这种层级信息。2.2 长文档场景下 RAG 的三个典型瓶颈我把实际项目里最常遇到的三个瓶颈列出来你可以对照自己的场景看看中了几个瓶颈类型具体表现根因定位漂移召回内容相关但位置错误模型答非所问缺少结构元数据无法按章节/页码过滤上下文割裂答案跨章节单个 chunk 装不下chunk 切分破坏了文档逻辑结构召回噪声Top-K 里混入大量语义相似但无关的片段纯语义排序没有结构权重参与这三个瓶颈在短文本、FAQ 类知识库里不明显因为内容本身就是碎片化的。但一旦文档超过 50 页、有明确的章节层级问题就会集中爆发。这也是为什么很多团队做 demo 时效果惊艳一上真实文档就拉胯。2.3 PageIndex 的破局思路把目录变成可检索的一等公民PageIndex 的核心思路说白了就是把文档的结构信息提取出来作为检索的第一道过滤器。传统 RAG 的流程是切 chunk → 向量化 → 相似度检索PageIndex 在中间插了一层结构索引流程变成解析文档结构 → 建立章节树 → chunk 挂载到树节点 → 检索时先定位章节再语义精排。这个思路的价值在于它把结构信息从隐式变成了显式。文档的目录、章节标题、页码、层级关系这些在原始文档里本来就存在的信息被 PageIndex 提取出来变成了可查询的元数据。检索时如果用户的问题里带有位置线索第三章附录里关于配置的那一节系统就能先用结构信息把候选范围缩小到几个章节再在这个范围内做语义匹配准确率自然就上去了。打个比方传统向量检索像是在一个没有页码、没有目录的图书馆里靠内容感觉找书PageIndex 相当于先给你一份详细的目录和索引卡你可以先按分类找到书架再在书架上精挑细选。两者结合效率完全不是一个量级。3. PageIndex 的结构设计章节树、节点挂载与检索路由3.1 文档解析层怎么把 PDF/Word 变成一棵章节树PageIndex 的第一步是文档解析这一步的产出不是纯文本而是一棵章节树Section Tree。树的每个节点代表文档的一个结构单元携带标题、层级、起止页码、原始文本等属性。解析的关键在于识别文档的层级结构。对于有明确标题样式的文档比如 Markdown、带样式的 Word直接读样式就能拿到层级。但对于 PDF 这种视觉格式文档就得靠启发式规则字号大小、加粗、居中、编号模式1. 1.1 第一章都是判断层级的线索。我实测下来一套组合规则大致是这样的一级标题字号最大 加粗 可能居中或匹配第X章Part X模式二级标题字号次大 编号形如1.11.1.1三级及以下编号层级递增字号递减这里有个坑要提醒不要指望 100% 自动解析准确。真实文档的格式千奇百怪扫描版 PDF 更是直接没有文本层。我的建议是解析层做成自动 人工校正的混合模式自动解析出章节树后提供一个可视化界面让人快速核对和修正。这一步多花十分钟后面检索准确率的提升是数量级的。3.2 节点挂载chunk 不再是孤岛而是挂在树上的叶子传统 RAG 的 chunk 是平铺的彼此之间没有关系。PageIndex 的做法是让每个 chunk 知道自己属于哪个章节节点。具体实现上解析出章节树后把文档按章节边界切分每个章节内部的文本再按语义或长度切成 chunk每个 chunk 记录一个section_path字段比如[第3章, 3.2 配置项, 3.2.1 超时设置]。这个section_path就是后面检索路由的关键。它让每个 chunk 不仅知道自己是什么内容还知道自己在文档的什么位置。检索时这个路径信息可以作为过滤条件也可以作为排序的加权因子。我个人的经验是section_path最好存成结构化的数组而不是拼接字符串这样查询时可以做前缀匹配所有 3.2 开头的节点和层级聚合第3章下所有 chunk灵活性高很多。3.3 检索路由结构过滤 语义精排的两段式流程PageIndex 的检索流程我把它拆成两段第一段结构路由。系统先分析 query判断里面有没有结构线索。如果有明确的章节引用第X章关于XX的那一节直接用章节标题做匹配把候选范围锁定到相关节点及其子树。如果没有明确线索就用章节标题的 embedding 做一次粗筛选出 Top-N 个相关章节。第二段语义精排。在锁定的章节范围内对 chunk 做向量相似度检索取 Top-K 返回。因为候选范围已经缩小了这一步的噪声会大幅降低。这个两段式设计的好处是它把结构匹配和语义匹配解耦了。结构匹配负责缩小范围语义匹配负责精确定位各司其职。相比一上来就全库向量检索这种方式的召回精度和可解释性都更好——你甚至能告诉用户答案来自第3章第2节这对技术文档类应用来说是刚需。提示结构路由的阈值需要根据文档结构调整。章节少的文档20 个节点可以放宽章节多的文档要收紧否则第一段过滤太狠会漏掉正确章节。4. 把 PageIndex 接进现有 RAG 链路实操步骤与代码骨架4.1 环境准备与依赖选型PageIndex 本身是一个索引层它需要和文档解析、embedding、向量存储配合使用。我推荐的一套组合是文档解析PyMuPDFPDF、python-docxWord、markdownMarkdownEmbedding任意主流 embedding 模型中文场景建议用支持中文的模型向量存储本地小规模用FAISS生产环境用支持元数据过滤的向量数据库编排可以自己写也可以用 LangChain 之类的框架但 PageIndex 的结构路由逻辑建议自己实现框架里不一定有现成的安装依赖pip install pymupdf python-docx faiss-cpu sentence-transformers选型逻辑说明一下为什么向量库要选支持元数据过滤的因为 PageIndex 的结构路由本质上就是一次元数据过滤按section_path过滤如果向量库不支持这个能力你就得把全库向量捞出来自己过滤性能会很差。FAISS 本身元数据过滤能力弱所以它只适合做原型验证生产环境要换。4.2 构建章节树的核心代码下面是一段构建章节树的骨架代码以 PDF 为例import fitz # PyMuPDF def build_section_tree(pdf_path): doc fitz.open(pdf_path) tree {title: root, children: [], pages: [0, len(doc)-1]} stack [tree] for page_num, page in enumerate(doc): blocks page.get_text(dict)[blocks] for block in blocks: if lines not in block: continue for line in block[lines]: for span in line[spans]: text span[text].strip() size span[size] flags span[flags] # 启发式判断是否为标题 if is_heading(text, size, flags): level infer_level(text, size) node { title: text, level: level, pages: [page_num, page_num], children: [] } # 根据 level 找到合适的父节点 while len(stack) 1 and stack[-1].get(level, 0) level: stack.pop() stack[-1][children].append(node) stack.append(node) return tree def is_heading(text, size, flags): # 加粗 字号偏大 文本较短综合判断 is_bold bool(flags 2**4) return is_bold and size 12 and len(text) 50这段代码的关键在is_heading和infer_level两个函数它们决定了章节树的质量。实际项目里这两个函数需要根据你的文档样式反复调参没有万能公式。我的做法是先跑一批样本把识别结果可视化出来人工看哪些漏了、哪些误判了再针对性调整阈值。4.3 chunk 挂载与 section_path 生成章节树建好后把每个章节节点的文本内容切 chunk并挂上section_pathdef attach_chunks(tree, doc): chunks [] def traverse(node, path): current_path path [node[title]] # 提取该节点对应页面的文本 text extract_text(doc, node[pages]) for i, chunk_text in enumerate(split_chunks(text, size400, overlap50)): chunks.append({ text: chunk_text, section_path: current_path, section_title: node[title], chunk_id: f{-.join(current_path)}-{i} }) for child in node[children]: traverse(child, current_path) traverse(tree, []) return chunkssection_path用数组存好处是后面做前缀过滤很方便。chunk_id里带上路径方便调试时快速定位问题 chunk 来自哪里。4.4 两段式检索的实现检索部分的核心逻辑def pageindex_retrieve(query, chunks, embed_model, top_sections3, top_chunks5): # 第一段结构路由 section_titles list({tuple(c[section_path]) for c in chunks}) section_embeddings embed_model.encode([t[-1] for t in section_titles]) query_emb embed_model.encode([query])[0] section_scores cosine_similarity([query_emb], section_embeddings)[0] top_section_idx section_scores.argsort()[-top_sections:][::-1] candidate_paths [section_titles[i] for i in top_section_idx] # 第二段在候选章节内做语义精排 candidates [c for c in chunks if tuple(c[section_path]) in candidate_paths] if not candidates: candidates chunks # 兜底结构路由失败时退回全库 chunk_embeddings embed_model.encode([c[text] for c in candidates]) chunk_scores cosine_similarity([query_emb], chunk_embeddings)[0] top_chunk_idx chunk_scores.argsort()[-top_chunks:][::-1] return [candidates[i] for i in top_chunk_idx]这段代码里有个重要的兜底逻辑如果结构路由没找到任何候选章节就退回全库检索。这个兜底很关键因为结构路由依赖章节标题的质量标题起得烂或者 query 和标题对不上时硬走结构路由反而会漏掉正确答案。注意top_sections和top_chunks这两个参数需要根据文档规模和 query 类型调。文档章节多的时候top_sections可以设大一点5-8避免第一段过滤太狠。5. 实测中的意外情况结构路由失效的几种典型场景5.1 章节标题名不副实导致路由跑偏我踩过最深的坑是文档的章节标题起得太抽象。比如有一章叫高级特性里面其实讲的是缓存策略和并发控制但标题里完全没有这两个词。用户问缓存怎么配置结构路由阶段用缓存去匹配章节标题根本匹配不到高级特性这一章直接跑偏。这个问题的根因是结构路由依赖标题的语义质量但真实文档的标题质量参差不齐。解决办法有两个一是给章节标题做语义扩展用 LLM 给每个章节生成一段摘要路由时用摘要而不是原标题做匹配二是降低结构路由的权重把它当成加分项而不是硬过滤语义检索的结果依然保留只是结构匹配上的 chunk 排序靠前。我后来采用的是混合方案结构路由选出的章节给一个权重加成但不排除其他章节最终排序是语义分 结构分的加权和。这样既利用了结构信息又不会因为标题质量差而漏召回。5.2 跨章节问题答案不在任何单一节点里还有一种情况是用户的问题需要综合多个章节的信息。比如对比第2章和第4章里两种方案的优劣这种 query 天然跨章节结构路由如果只锁定一个章节就完蛋了。处理这类问题我的经验是在 query 分析阶段先做意图识别。如果检测到 query 里有对比区别分别这类词就放宽结构路由允许多个章节同时进入候选集。更激进的做法是对这类 query 直接跳过结构路由走全库语义检索 重排。结构路由不是万能的知道它什么时候不该用比知道它怎么用更重要。5.3 解析错误引发的连锁反应文档解析阶段的错误会一路传导到检索。我遇到过最离谱的一次是 PDF 里有个表格表格里的文字被解析成了标题因为字号大且加粗结果章节树里凭空多出几十个假节点检索时这些假节点疯狂抢占候选位置。这类问题的排查链路是这样的先看检索结果里有没有明显不合理的 chunk如果有回溯它的section_path看这个路径对应的章节是不是真实存在的。如果发现假节点就回到解析层调整is_heading的判断规则把表格内容排除掉。表格识别可以用page.find_tables()之类的 API 先标记出来解析标题时跳过表格区域。问题现象排查入口修复方向召回内容位置错误检查 chunk 的 section_path修正章节树解析规则正确章节未被路由到检查章节标题与 query 的匹配分增加标题摘要或降低路由权重跨章节问题答不全检查 query 意图识别放宽路由或跳过结构路由假节点抢占候选检查章节树节点数量排除表格/页眉页脚等干扰区域6. 结构感知检索的边界PageIndex 适合什么、不适合什么6.1 最适合的场景结构化长文档PageIndex 的价值在结构化长文档上体现得最充分。技术手册、产品文档、学术论文、法律合同、标准规范这类文档有清晰的章节层级用户的问题也经常带位置线索结构感知检索的收益非常明显。我实测过一份 300 页的技术规范纯向量检索的 Top-5 命中率大概在 60% 左右加上结构路由后能到 85% 以上提升是实打实的。另一个适合的场景是需要引用溯源的问答。技术文档类应用经常要求答案必须标注来源章节PageIndex 天然携带section_path返回结果直接就能给出来自第X章第Y节这个能力纯向量方案要额外做很多工作才能补上。6.2 不太适合的场景碎片化、无结构内容反过来如果你的知识库本身就是碎片化的——比如客服 FAQ、聊天记录、短文本评论——那 PageIndex 的结构路由基本没有用武之地因为压根没有结构可提取。这种情况下老老实实用向量检索 重排就行硬套结构索引只会增加复杂度。还有一种情况是文档结构极度混乱比如扫描版 PDF 没有文本层、或者格式完全不统一的用户上传文档。这种场景下解析层的成本会高到不划算除非你有很强的 OCR 和版面分析能力否则不建议上 PageIndex。6.3 和向量数据库、LLM 框架的关系这里要澄清一个常见误解PageIndex 不是向量数据库的替代品它和向量数据库是互补关系。向量数据库负责存向量、算相似度PageIndex 负责提供结构元数据、做检索路由。你可以把 PageIndex 理解成向量数据库前面的一层智能路由器。和 LLM 框架的关系也类似。LangChain 这类框架提供了 RAG 的编排能力但它的检索器默认是纯向量的。PageIndex 可以作为自定义 Retriever 接进去替换掉默认的向量检索器。我个人的做法是用框架做文档加载和 LLM 调用检索部分自己实现 PageIndex 的逻辑这样灵活度最高。提示如果你的向量数据库支持元数据过滤大部分生产级向量库都支持那 PageIndex 的section_path可以直接作为过滤字段存进去检索时用 filter 参数做结构路由不需要自己维护额外的索引结构。7. 几个能直接抄的调优技巧7.1 章节标题增强用 LLM 给每个节点生成摘要前面提到标题质量差会导致路由跑偏最有效的解法是给每个章节节点生成一段语义摘要。具体做法是把章节内的文本喂给 LLM让它生成一段 50-100 字的摘要路由时用摘要的 embedding 而不是原标题的 embedding。这样即使标题叫高级特性摘要里也会出现缓存并发这些关键词路由就能匹配上了。这个操作的成本是一次性的文档入库时跑一遍就行。对于章节数量多的文档可以只给一级和二级节点生成摘要三级以下节点数量太多性价比不高。7.2 结构分与语义分的加权融合不要用硬过滤用加权。我常用的公式是final_score alpha * semantic_score (1 - alpha) * structure_scorestructure_score可以用章节标题或摘要和 query 的相似度来算alpha根据文档结构调整结构化程度高的文档alpha可以设 0.6-0.7结构化程度低的设 0.8-0.9。这个加权方式比硬过滤鲁棒得多即使结构路由出错语义分也能兜底。7.3 缓存章节 embedding避免重复计算章节标题和摘要的 embedding 是固定的入库时算一次存起来就行检索时直接读缓存。我见过有项目每次检索都重新算一遍章节 embedding白白浪费算力。这个优化很简单但能省不少钱尤其是章节数量多、查询量大的场景。7.4 给 chunk 加上上下文前缀检索返回的 chunk 如果只有正文模型可能不知道这段内容属于哪个章节。我的做法是在 chunk 文本前面拼上一个上下文前缀比如[第3章 配置项 3.2 超时设置] 正文内容...。这样即使 chunk 被单独拿出来模型也能知道它的位置背景回答时更不容易跑偏。这个前缀在 embedding 时也可以带上让向量本身也包含位置信息。8. 我在实际项目里踩过的两个坑第一个坑是过度依赖结构路由。刚开始做的时候我觉得结构信息这么有用干脆把结构路由做成硬过滤结果遇到标题质量差的文档就大面积漏召回。后来改成加权融合效果稳定多了。这个教训是结构信息是锦上添花不是雪中送炭语义检索永远是基本盘结构路由是增强项。第二个坑是忽略了 chunk 切分和章节边界的关系。我一开始按固定长度切 chunk结果一个章节的最后一段和下一个章节的第一段被切进了同一个 chunksection_path只能标一个导致归属混乱。后来改成先按章节边界切章节内再按长度切chunk 的归属就清晰了。这个改动不大但对检索准确率的影响很明显。如果你正在做 RAG 项目我的建议是先把纯向量方案跑通测出 baseline再考虑引入 PageIndex 这类结构感知方案。不要一上来就上复杂架构否则出了问题你都不知道是哪个环节的锅。结构感知检索是个好思路但它解决的是特定场景的问题不是万能药。搞清楚你的文档有没有结构、用户的问题带不带位置线索再决定要不要上这才是理性的做法。
PageIndex 结构感知索引：解决长文档 RAG 检索定位漂移的工程实践
1. 从关键词匹配到结构导航PageIndex 到底在解决什么如果你最近在折腾 RAG 应用大概率会遇到一个很尴尬的场景用户问第三章第二节里提到的那个参数默认值是多少你的向量检索返回了一堆语义相似但位置完全不对的片段模型拿着这些片段开始一本正经地胡说八道。这不是模型的问题是检索层的问题——向量相似度天然不擅长处理结构定位这类需求。PageIndex 这个项目从名字就能看出来它想干的事给文档建立一个页面/章节级别的索引让检索不再只依赖语义向量而是结合文档本身的结构信息来定位内容。它要解决的核心痛点是传统 RAG 在长文档、结构化文档手册、规范、论文、合同、技术文档场景下找得到相关内容但找不准具体位置的问题。我先把话说清楚PageIndex 不是一个向量数据库也不是一个 LLM 框架它更像是夹在文档解析和向量检索之间的一层结构感知索引层。你可以把它理解成给文档做了一份目录 页码 章节树的元数据检索时先用结构缩小范围再用语义做精排。这个思路在 RAG 圈子里不算全新但 PageIndex 把它做成了一个相对独立、可复用的组件这是它的价值所在。这篇文章适合谁看三类人一是正在做 RAG 项目、被长文档检索准确率折磨的开发者二是想理解结构感知检索这套思路到底怎么落地的人三是手上有大量 PDF/Word/技术手册需要做知识库、但发现纯向量方案效果不稳定的团队。我会从原理、设计取舍、实操步骤、踩坑经验几个角度把它讲透尽量让你看完能直接上手改自己的检索链路。需要提前说明的是PageIndex 目前公开的资料相对零散很多细节需要结合 RAG 领域的通用实践来补全。下面涉及具体实现的部分我会明确标注哪些是项目本身的思路、哪些是我基于常见工程实践做的合理推断你按自己项目的实际情况调整。2. 为什么纯向量检索在长文档上会翻车2.1 向量相似度的本质局限它只懂像不像不懂在哪先把这个问题的根子讲清楚。向量检索的工作原理是把文本切成 chunk用 embedding 模型把每个 chunk 映射成一个高维向量然后算 query 向量和 chunk 向量的余弦相似度取 Top-K。这套机制的核心假设是语义相似的文本向量距离就近。问题在于用户的问题里往往包含两类信息一类是语义信息我在问什么概念另一类是结构信息这个东西在文档的哪个位置。向量检索只能捕捉前者对后者几乎无能为力。举个具体的例子一份 200 页的产品手册里面默认超时时间这个短语可能在 8 个不同章节出现分别对应不同的模块。用户问网络模块的默认超时时间是多少向量检索会把 8 个片段都捞出来因为它们语义高度相似但真正对的只有网络模块那一章的那个。更麻烦的是 chunk 切分本身。固定长度切分比如 512 token 一刀切会把章节边界切碎导致一个完整的逻辑单元被拆到两个 chunk 里检索时要么漏掉一半要么召回一个语义不完整的片段。而按语义切分虽然好一些但依然丢失了这个 chunk 属于哪一章、哪一节、第几页这种层级信息。2.2 长文档场景下 RAG 的三个典型瓶颈我把实际项目里最常遇到的三个瓶颈列出来你可以对照自己的场景看看中了几个瓶颈类型具体表现根因定位漂移召回内容相关但位置错误模型答非所问缺少结构元数据无法按章节/页码过滤上下文割裂答案跨章节单个 chunk 装不下chunk 切分破坏了文档逻辑结构召回噪声Top-K 里混入大量语义相似但无关的片段纯语义排序没有结构权重参与这三个瓶颈在短文本、FAQ 类知识库里不明显因为内容本身就是碎片化的。但一旦文档超过 50 页、有明确的章节层级问题就会集中爆发。这也是为什么很多团队做 demo 时效果惊艳一上真实文档就拉胯。2.3 PageIndex 的破局思路把目录变成可检索的一等公民PageIndex 的核心思路说白了就是把文档的结构信息提取出来作为检索的第一道过滤器。传统 RAG 的流程是切 chunk → 向量化 → 相似度检索PageIndex 在中间插了一层结构索引流程变成解析文档结构 → 建立章节树 → chunk 挂载到树节点 → 检索时先定位章节再语义精排。这个思路的价值在于它把结构信息从隐式变成了显式。文档的目录、章节标题、页码、层级关系这些在原始文档里本来就存在的信息被 PageIndex 提取出来变成了可查询的元数据。检索时如果用户的问题里带有位置线索第三章附录里关于配置的那一节系统就能先用结构信息把候选范围缩小到几个章节再在这个范围内做语义匹配准确率自然就上去了。打个比方传统向量检索像是在一个没有页码、没有目录的图书馆里靠内容感觉找书PageIndex 相当于先给你一份详细的目录和索引卡你可以先按分类找到书架再在书架上精挑细选。两者结合效率完全不是一个量级。3. PageIndex 的结构设计章节树、节点挂载与检索路由3.1 文档解析层怎么把 PDF/Word 变成一棵章节树PageIndex 的第一步是文档解析这一步的产出不是纯文本而是一棵章节树Section Tree。树的每个节点代表文档的一个结构单元携带标题、层级、起止页码、原始文本等属性。解析的关键在于识别文档的层级结构。对于有明确标题样式的文档比如 Markdown、带样式的 Word直接读样式就能拿到层级。但对于 PDF 这种视觉格式文档就得靠启发式规则字号大小、加粗、居中、编号模式1. 1.1 第一章都是判断层级的线索。我实测下来一套组合规则大致是这样的一级标题字号最大 加粗 可能居中或匹配第X章Part X模式二级标题字号次大 编号形如1.11.1.1三级及以下编号层级递增字号递减这里有个坑要提醒不要指望 100% 自动解析准确。真实文档的格式千奇百怪扫描版 PDF 更是直接没有文本层。我的建议是解析层做成自动 人工校正的混合模式自动解析出章节树后提供一个可视化界面让人快速核对和修正。这一步多花十分钟后面检索准确率的提升是数量级的。3.2 节点挂载chunk 不再是孤岛而是挂在树上的叶子传统 RAG 的 chunk 是平铺的彼此之间没有关系。PageIndex 的做法是让每个 chunk 知道自己属于哪个章节节点。具体实现上解析出章节树后把文档按章节边界切分每个章节内部的文本再按语义或长度切成 chunk每个 chunk 记录一个section_path字段比如[第3章, 3.2 配置项, 3.2.1 超时设置]。这个section_path就是后面检索路由的关键。它让每个 chunk 不仅知道自己是什么内容还知道自己在文档的什么位置。检索时这个路径信息可以作为过滤条件也可以作为排序的加权因子。我个人的经验是section_path最好存成结构化的数组而不是拼接字符串这样查询时可以做前缀匹配所有 3.2 开头的节点和层级聚合第3章下所有 chunk灵活性高很多。3.3 检索路由结构过滤 语义精排的两段式流程PageIndex 的检索流程我把它拆成两段第一段结构路由。系统先分析 query判断里面有没有结构线索。如果有明确的章节引用第X章关于XX的那一节直接用章节标题做匹配把候选范围锁定到相关节点及其子树。如果没有明确线索就用章节标题的 embedding 做一次粗筛选出 Top-N 个相关章节。第二段语义精排。在锁定的章节范围内对 chunk 做向量相似度检索取 Top-K 返回。因为候选范围已经缩小了这一步的噪声会大幅降低。这个两段式设计的好处是它把结构匹配和语义匹配解耦了。结构匹配负责缩小范围语义匹配负责精确定位各司其职。相比一上来就全库向量检索这种方式的召回精度和可解释性都更好——你甚至能告诉用户答案来自第3章第2节这对技术文档类应用来说是刚需。提示结构路由的阈值需要根据文档结构调整。章节少的文档20 个节点可以放宽章节多的文档要收紧否则第一段过滤太狠会漏掉正确章节。4. 把 PageIndex 接进现有 RAG 链路实操步骤与代码骨架4.1 环境准备与依赖选型PageIndex 本身是一个索引层它需要和文档解析、embedding、向量存储配合使用。我推荐的一套组合是文档解析PyMuPDFPDF、python-docxWord、markdownMarkdownEmbedding任意主流 embedding 模型中文场景建议用支持中文的模型向量存储本地小规模用FAISS生产环境用支持元数据过滤的向量数据库编排可以自己写也可以用 LangChain 之类的框架但 PageIndex 的结构路由逻辑建议自己实现框架里不一定有现成的安装依赖pip install pymupdf python-docx faiss-cpu sentence-transformers选型逻辑说明一下为什么向量库要选支持元数据过滤的因为 PageIndex 的结构路由本质上就是一次元数据过滤按section_path过滤如果向量库不支持这个能力你就得把全库向量捞出来自己过滤性能会很差。FAISS 本身元数据过滤能力弱所以它只适合做原型验证生产环境要换。4.2 构建章节树的核心代码下面是一段构建章节树的骨架代码以 PDF 为例import fitz # PyMuPDF def build_section_tree(pdf_path): doc fitz.open(pdf_path) tree {title: root, children: [], pages: [0, len(doc)-1]} stack [tree] for page_num, page in enumerate(doc): blocks page.get_text(dict)[blocks] for block in blocks: if lines not in block: continue for line in block[lines]: for span in line[spans]: text span[text].strip() size span[size] flags span[flags] # 启发式判断是否为标题 if is_heading(text, size, flags): level infer_level(text, size) node { title: text, level: level, pages: [page_num, page_num], children: [] } # 根据 level 找到合适的父节点 while len(stack) 1 and stack[-1].get(level, 0) level: stack.pop() stack[-1][children].append(node) stack.append(node) return tree def is_heading(text, size, flags): # 加粗 字号偏大 文本较短综合判断 is_bold bool(flags 2**4) return is_bold and size 12 and len(text) 50这段代码的关键在is_heading和infer_level两个函数它们决定了章节树的质量。实际项目里这两个函数需要根据你的文档样式反复调参没有万能公式。我的做法是先跑一批样本把识别结果可视化出来人工看哪些漏了、哪些误判了再针对性调整阈值。4.3 chunk 挂载与 section_path 生成章节树建好后把每个章节节点的文本内容切 chunk并挂上section_pathdef attach_chunks(tree, doc): chunks [] def traverse(node, path): current_path path [node[title]] # 提取该节点对应页面的文本 text extract_text(doc, node[pages]) for i, chunk_text in enumerate(split_chunks(text, size400, overlap50)): chunks.append({ text: chunk_text, section_path: current_path, section_title: node[title], chunk_id: f{-.join(current_path)}-{i} }) for child in node[children]: traverse(child, current_path) traverse(tree, []) return chunkssection_path用数组存好处是后面做前缀过滤很方便。chunk_id里带上路径方便调试时快速定位问题 chunk 来自哪里。4.4 两段式检索的实现检索部分的核心逻辑def pageindex_retrieve(query, chunks, embed_model, top_sections3, top_chunks5): # 第一段结构路由 section_titles list({tuple(c[section_path]) for c in chunks}) section_embeddings embed_model.encode([t[-1] for t in section_titles]) query_emb embed_model.encode([query])[0] section_scores cosine_similarity([query_emb], section_embeddings)[0] top_section_idx section_scores.argsort()[-top_sections:][::-1] candidate_paths [section_titles[i] for i in top_section_idx] # 第二段在候选章节内做语义精排 candidates [c for c in chunks if tuple(c[section_path]) in candidate_paths] if not candidates: candidates chunks # 兜底结构路由失败时退回全库 chunk_embeddings embed_model.encode([c[text] for c in candidates]) chunk_scores cosine_similarity([query_emb], chunk_embeddings)[0] top_chunk_idx chunk_scores.argsort()[-top_chunks:][::-1] return [candidates[i] for i in top_chunk_idx]这段代码里有个重要的兜底逻辑如果结构路由没找到任何候选章节就退回全库检索。这个兜底很关键因为结构路由依赖章节标题的质量标题起得烂或者 query 和标题对不上时硬走结构路由反而会漏掉正确答案。注意top_sections和top_chunks这两个参数需要根据文档规模和 query 类型调。文档章节多的时候top_sections可以设大一点5-8避免第一段过滤太狠。5. 实测中的意外情况结构路由失效的几种典型场景5.1 章节标题名不副实导致路由跑偏我踩过最深的坑是文档的章节标题起得太抽象。比如有一章叫高级特性里面其实讲的是缓存策略和并发控制但标题里完全没有这两个词。用户问缓存怎么配置结构路由阶段用缓存去匹配章节标题根本匹配不到高级特性这一章直接跑偏。这个问题的根因是结构路由依赖标题的语义质量但真实文档的标题质量参差不齐。解决办法有两个一是给章节标题做语义扩展用 LLM 给每个章节生成一段摘要路由时用摘要而不是原标题做匹配二是降低结构路由的权重把它当成加分项而不是硬过滤语义检索的结果依然保留只是结构匹配上的 chunk 排序靠前。我后来采用的是混合方案结构路由选出的章节给一个权重加成但不排除其他章节最终排序是语义分 结构分的加权和。这样既利用了结构信息又不会因为标题质量差而漏召回。5.2 跨章节问题答案不在任何单一节点里还有一种情况是用户的问题需要综合多个章节的信息。比如对比第2章和第4章里两种方案的优劣这种 query 天然跨章节结构路由如果只锁定一个章节就完蛋了。处理这类问题我的经验是在 query 分析阶段先做意图识别。如果检测到 query 里有对比区别分别这类词就放宽结构路由允许多个章节同时进入候选集。更激进的做法是对这类 query 直接跳过结构路由走全库语义检索 重排。结构路由不是万能的知道它什么时候不该用比知道它怎么用更重要。5.3 解析错误引发的连锁反应文档解析阶段的错误会一路传导到检索。我遇到过最离谱的一次是 PDF 里有个表格表格里的文字被解析成了标题因为字号大且加粗结果章节树里凭空多出几十个假节点检索时这些假节点疯狂抢占候选位置。这类问题的排查链路是这样的先看检索结果里有没有明显不合理的 chunk如果有回溯它的section_path看这个路径对应的章节是不是真实存在的。如果发现假节点就回到解析层调整is_heading的判断规则把表格内容排除掉。表格识别可以用page.find_tables()之类的 API 先标记出来解析标题时跳过表格区域。问题现象排查入口修复方向召回内容位置错误检查 chunk 的 section_path修正章节树解析规则正确章节未被路由到检查章节标题与 query 的匹配分增加标题摘要或降低路由权重跨章节问题答不全检查 query 意图识别放宽路由或跳过结构路由假节点抢占候选检查章节树节点数量排除表格/页眉页脚等干扰区域6. 结构感知检索的边界PageIndex 适合什么、不适合什么6.1 最适合的场景结构化长文档PageIndex 的价值在结构化长文档上体现得最充分。技术手册、产品文档、学术论文、法律合同、标准规范这类文档有清晰的章节层级用户的问题也经常带位置线索结构感知检索的收益非常明显。我实测过一份 300 页的技术规范纯向量检索的 Top-5 命中率大概在 60% 左右加上结构路由后能到 85% 以上提升是实打实的。另一个适合的场景是需要引用溯源的问答。技术文档类应用经常要求答案必须标注来源章节PageIndex 天然携带section_path返回结果直接就能给出来自第X章第Y节这个能力纯向量方案要额外做很多工作才能补上。6.2 不太适合的场景碎片化、无结构内容反过来如果你的知识库本身就是碎片化的——比如客服 FAQ、聊天记录、短文本评论——那 PageIndex 的结构路由基本没有用武之地因为压根没有结构可提取。这种情况下老老实实用向量检索 重排就行硬套结构索引只会增加复杂度。还有一种情况是文档结构极度混乱比如扫描版 PDF 没有文本层、或者格式完全不统一的用户上传文档。这种场景下解析层的成本会高到不划算除非你有很强的 OCR 和版面分析能力否则不建议上 PageIndex。6.3 和向量数据库、LLM 框架的关系这里要澄清一个常见误解PageIndex 不是向量数据库的替代品它和向量数据库是互补关系。向量数据库负责存向量、算相似度PageIndex 负责提供结构元数据、做检索路由。你可以把 PageIndex 理解成向量数据库前面的一层智能路由器。和 LLM 框架的关系也类似。LangChain 这类框架提供了 RAG 的编排能力但它的检索器默认是纯向量的。PageIndex 可以作为自定义 Retriever 接进去替换掉默认的向量检索器。我个人的做法是用框架做文档加载和 LLM 调用检索部分自己实现 PageIndex 的逻辑这样灵活度最高。提示如果你的向量数据库支持元数据过滤大部分生产级向量库都支持那 PageIndex 的section_path可以直接作为过滤字段存进去检索时用 filter 参数做结构路由不需要自己维护额外的索引结构。7. 几个能直接抄的调优技巧7.1 章节标题增强用 LLM 给每个节点生成摘要前面提到标题质量差会导致路由跑偏最有效的解法是给每个章节节点生成一段语义摘要。具体做法是把章节内的文本喂给 LLM让它生成一段 50-100 字的摘要路由时用摘要的 embedding 而不是原标题的 embedding。这样即使标题叫高级特性摘要里也会出现缓存并发这些关键词路由就能匹配上了。这个操作的成本是一次性的文档入库时跑一遍就行。对于章节数量多的文档可以只给一级和二级节点生成摘要三级以下节点数量太多性价比不高。7.2 结构分与语义分的加权融合不要用硬过滤用加权。我常用的公式是final_score alpha * semantic_score (1 - alpha) * structure_scorestructure_score可以用章节标题或摘要和 query 的相似度来算alpha根据文档结构调整结构化程度高的文档alpha可以设 0.6-0.7结构化程度低的设 0.8-0.9。这个加权方式比硬过滤鲁棒得多即使结构路由出错语义分也能兜底。7.3 缓存章节 embedding避免重复计算章节标题和摘要的 embedding 是固定的入库时算一次存起来就行检索时直接读缓存。我见过有项目每次检索都重新算一遍章节 embedding白白浪费算力。这个优化很简单但能省不少钱尤其是章节数量多、查询量大的场景。7.4 给 chunk 加上上下文前缀检索返回的 chunk 如果只有正文模型可能不知道这段内容属于哪个章节。我的做法是在 chunk 文本前面拼上一个上下文前缀比如[第3章 配置项 3.2 超时设置] 正文内容...。这样即使 chunk 被单独拿出来模型也能知道它的位置背景回答时更不容易跑偏。这个前缀在 embedding 时也可以带上让向量本身也包含位置信息。8. 我在实际项目里踩过的两个坑第一个坑是过度依赖结构路由。刚开始做的时候我觉得结构信息这么有用干脆把结构路由做成硬过滤结果遇到标题质量差的文档就大面积漏召回。后来改成加权融合效果稳定多了。这个教训是结构信息是锦上添花不是雪中送炭语义检索永远是基本盘结构路由是增强项。第二个坑是忽略了 chunk 切分和章节边界的关系。我一开始按固定长度切 chunk结果一个章节的最后一段和下一个章节的第一段被切进了同一个 chunksection_path只能标一个导致归属混乱。后来改成先按章节边界切章节内再按长度切chunk 的归属就清晰了。这个改动不大但对检索准确率的影响很明显。如果你正在做 RAG 项目我的建议是先把纯向量方案跑通测出 baseline再考虑引入 PageIndex 这类结构感知方案。不要一上来就上复杂架构否则出了问题你都不知道是哪个环节的锅。结构感知检索是个好思路但它解决的是特定场景的问题不是万能药。搞清楚你的文档有没有结构、用户的问题带不带位置线索再决定要不要上这才是理性的做法。