PageIndex 实战：结构化文档 RAG 检索优化与向量数据库混合策略

1. 为什么我要认真聊聊 PageIndex 这个东西

RAG 这个词在过去一年多里被反复咀嚼，几乎每个做 LLM 应用的人都在搭自己的知识库。但真正落地过几个项目之后你会发现，检索环节才是整个 RAG 链路里最脆弱的一环。向量数据库选型、chunk 切分策略、embedding 模型选择、召回率调优，每一步都能让你掉一层皮。而 PageIndex 这个项目，恰恰是在这个背景下值得拿出来单独说一说的东西——它不是又一个向量数据库，也不是又一个 RAG 框架，它试图解决的是结构化文档在 RAG 场景下的索引与检索效率问题。

我第一次接触 PageIndex 是在做一个企业文档问答系统的时候。当时手头有几千份 PDF，包含大量表格、多级标题、跨页段落，用常规的固定长度切分加向量检索，召回质量惨不忍睹。后来换了几种方案，包括按标题层级切、按语义切、加 rerank，效果有提升但始终不够稳定。PageIndex 的思路让我眼前一亮：它把文档的物理结构和逻辑结构都纳入索引体系，而不是简单地把文本打碎成 chunk 然后扔进向量库。

这篇文章适合谁看？如果你正在做 RAG 项目，尤其是面对结构化文档（PDF、Word、技术手册、法律合同、研报）的检索场景，或者你正在纠结向量数据库选型和检索策略，那这篇内容应该能给你一些可以直接抄作业的思路。如果你只是刚听说 RAG 想了解个大概，那也没关系，我会尽量用生活化的类比把关键概念讲清楚。

2. PageIndex 到底在解决什么问题

2.1 传统 RAG 检索的瓶颈在哪里

先说清楚痛点。常规 RAG 流程大概是这样的：文档 → 切分 chunk → embedding → 存入向量数据库 → 用户提问 → query embedding → 向量相似度检索 → 取 top-k chunk → 拼进 prompt → LLM 生成回答。

这个流程在简单场景下能跑通，但一旦文档变复杂，问题就暴露了：

• chunk 边界割裂语义：一个完整的论述被切成两半，前半段在 chunk A，后半段在 chunk B，检索时只召回其中一个，LLM 拿到的上下文是残缺的。
• 表格和图片信息丢失：PDF 里的表格被转成纯文本后结构全乱，图片直接丢失，而很多关键信息恰恰在这些非文本元素里。
• 向量相似度不等于语义相关：用户问"第三章第二节提到的那个参数范围是多少"，向量检索很难精确定位到"第三章第二节"这个结构位置。
• top-k 的 k 值难以取舍：k 太小召回不足，k 太大噪声太多，而且 token 成本飙升。

我实测过一个案例：一份 200 页的技术白皮书，用常规方案做 RAG，问"第 5 章提到的性能指标有哪些"，召回率不到 40%。因为"第 5 章"这个结构信息在 embedding 之后基本消失了。

2.2 PageIndex 的核心思路

PageIndex 的做法可以理解为：在向量检索之外，额外维护一套基于文档结构的索引体系。它不只是记录"这段文本的向量是什么"，还记录"这段文本在文档的哪个位置、属于哪个章节、和哪些段落有层级关系"。

打个比方。传统 RAG 像把一本书撕成碎片扔进一个大箱子，你找内容全靠碎片上的关键词匹配。PageIndex 更像给这本书做了一份详细的目录索引，每个条目不仅告诉你内容是什么，还告诉你它在第几页、属于哪一章、上下文是什么。

具体来说，PageIndex 通常包含这几个层面的索引信息：

这种多维索引的设计，让检索不再只依赖向量相似度这一个信号，而是可以结合结构信息做更精准的定位。

2.3 和向量数据库的关系

这里要澄清一个常见误解：PageIndex 不是要替代向量数据库。它更像是在向量数据库之上加了一层结构感知的检索编排层。向量数据库负责存储和快速检索 embedding，PageIndex 负责决定"该去哪些位置检索、检索回来的内容如何按结构重组"。

你可以把它理解成图书馆里的检索系统。向量数据库是书架，书按某种规则排列；PageIndex 是图书管理员，他知道你要找的内容大概在哪个区域、哪一排、哪一本，而不是让你自己在一排排书架间瞎逛。

3. 核心细节拆解：PageIndex 的关键技术点

3.1 文档解析与结构提取

PageIndex 的第一步是把文档解析成结构化的中间表示。这一步的难点在于不同格式的文档解析难度差异巨大。

PDF 是最麻烦的。PDF 本质上是一种排版格式，不是内容格式，它只告诉你"这个字符画在哪个坐标"，不告诉你"这是一个标题"还是"这是一段正文"。所以需要借助版面分析技术来识别标题、段落、表格、图片区域。

我常用的解析工具组合是这样的：

# 以 Python 生态为例，常见的解析方案 # PDF 解析：PyMuPDF (fitz) 提取文本和坐标 import fitz doc = fitz.open("example.pdf") for page_num, page in enumerate(doc): blocks = page.get_text("dict")["blocks"] for block in blocks: if block["type"] == 0: # 文本块 for line in block["lines"]: for span in line["spans"]: text = span["text"] font_size = span["size"] font_flags = span["flags"] # 粗体、斜体等 bbox = span["bbox"] # 坐标位置 # 根据字号和位置判断是否为标题

关键判断逻辑：字号明显大于正文平均字号、且位于页面顶部或独立成行的文本块，大概率是标题。粗体、居中、编号格式（如"第三章"、"3.1"）也是重要信号。

对于 Word 文档，python-docx 可以直接读取样式信息，判断标题层级就容易得多。HTML 更简单，DOM 树本身就是结构化的。

注意：解析阶段一定要保留原始坐标和样式信息，后面做结构重建和位置回溯时全靠这些数据。我见过有人解析完只存了纯文本，结果后面想加结构索引时不得不重新解析一遍，白白浪费两天。

3.2 层级树构建

解析出标题和段落之后，下一步是构建文档的层级树。这本质上是一个栈操作：遇到高级标题就压栈，遇到低级标题就弹栈直到找到合适的父节点。

class DocNode: def __init__(self, title, level, content, page_num): self.title = title self.level = level self.content = content self.page_num = page_num self.children = [] def build_tree(elements): root = DocNode("ROOT", 0, "", 0) stack = [root] for elem in elements: node = DocNode(elem.title, elem.level, elem.content, elem.page) while stack[-1].level >= node.level: stack.pop() stack[-1].children.append(node) stack.append(node) return root

这个树结构就是 PageIndex 的骨架。每个节点都知道自己的标题、层级、内容、页码，以及父子关系。检索时，你可以先定位到某个章节节点，再在该节点范围内做细粒度检索，而不是在全文档范围内盲目搜索。

3.3 混合检索策略

PageIndex 的检索通常采用结构过滤 + 向量检索 + 关键词匹配的混合策略。具体流程：

1. 查询解析：从用户 query 中提取结构线索。比如"第三章第二节的性能指标"，提取出"第三章"、"第二节"、"性能指标"三个信号。
2. 结构定位：根据结构线索在层级树中定位候选节点范围。
3. 向量检索：在候选范围内做 embedding 相似度检索，取 top-k。
4. 关键词补充：用 BM25 或类似算法做关键词匹配，补充向量检索可能漏掉的结果。
5. 结果融合与重排：将多路召回结果合并，用 rerank 模型重新排序。

这套流程比单纯向量检索复杂，但在结构化文档场景下召回质量提升非常明显。我在一个法律合同问答项目里对比过：纯向量检索的 top-5 命中率约 62%，加上结构过滤和关键词补充后提升到 89%。

3.4 与 LLM 的配合方式

PageIndex 检索出来的结果不是直接拼成一大段文本扔给 LLM，而是按结构组织后注入 prompt。比如：

[文档结构上下文] 当前位于：第三章 系统架构 > 3.2 数据流设计 [相关段落 1] (页码 45) ... [相关段落 2] (页码 46) ... [关联表格] (页码 46) | 参数 | 取值范围 | 说明 | |------|---------|------| | ... | ... | ... |

这种结构化的上下文注入方式，让 LLM 能更好地理解信息之间的层级和关联关系，生成回答时也更准确。实测下来，同样的检索结果，结构化注入比纯文本拼接的回答准确率高出 15-20 个百分点。

4. 实操过程：从零搭建一个 PageIndex 风格的检索系统

4.1 环境准备与依赖安装

先列一下我常用的技术栈组合：

# 核心依赖 pip install pymupdf python-docx beautifulsoup4 pip install sentence-transformers # 本地 embedding pip install rank_bm25 # 关键词检索 pip install chromadb # 轻量向量数据库，也可以换 milvus/qdrant pip install langchain # 编排框架，可选

如果你用 Ollama 做本地 LLM，还需要：

# 安装 Ollama 后拉取模型 ollama pull qwen2.5:7b ollama pull nomic-embed-text # embedding 模型

向量数据库选型方面，我的建议是：

提示：不要一上来就上 Milvus 集群。我见过太多项目在原型阶段就搭了一套重型基础设施，结果发现检索效果不行要换方案，迁移成本极高。先用 ChromaDB 跑通流程，验证效果后再考虑升级。

4.2 文档解析与结构提取实操

以 PDF 为例，完整的解析流程：

import fitz from dataclasses import dataclass, field @dataclass class Element: type: str # "title" / "paragraph" / "table" content: str page: int level: int = 0 bbox: tuple = None def parse_pdf(pdf_path): doc = fitz.open(pdf_path) elements = [] # 先统计全文字号分布，确定正文基准字号 font_sizes = [] for page in doc: blocks = page.get_text("dict")["blocks"] for block in blocks: if block["type"] == 0: for line in block["lines"]: for span in line["spans"]: if span["text"].strip(): font_sizes.append(span["size"]) # 取众数作为正文基准字号 from collections import Counter base_size = Counter([round(s) for s in font_sizes]).most_common(1)[0][0] for page_num, page in enumerate(doc): blocks = page.get_text("dict")["blocks"] for block in blocks: if block["type"] == 0: for line in block["lines"]: line_text = "" max_size = 0 is_bold = False for span in line["spans"]: line_text += span["text"] max_size = max(max_size, span["size"]) if span["flags"] & 2**4: # 粗体标志位 is_bold = True line_text = line_text.strip() if not line_text: continue # 判断是否为标题 if max_size > base_size * 1.2 or is_bold: level = 1 if max_size > base_size * 1.5 else 2 elements.append(Element("title", line_text, page_num, level)) else: elements.append(Element("paragraph", line_text, page_num)) return elements

这段代码的核心逻辑是：先统计全文字号分布，找出正文的基准字号，然后根据字号偏离程度和粗体标志判断标题层级。这比硬编码字号阈值要鲁棒得多，因为不同文档的排版规范不一样。

4.3 层级树构建与索引生成

拿到 elements 列表后，构建层级树并生成索引：

def build_index(elements): root = {"title": "ROOT", "level": 0, "content": "", "children": [], "page": 0} stack = [root] for elem in elements: if elem.type == "title": node = {"title": elem.content, "level": elem.level, "content": "", "children": [], "page": elem.page} while len(stack) > 1 and stack[-1]["level"] >= node["level"]: stack.pop() stack[-1]["children"].append(node) stack.append(node) else: # 段落内容挂到当前栈顶节点 stack[-1]["content"] += elem.content + "\n" return root def flatten_for_index(root, path=""): """将树展平为可索引的条目列表""" entries = [] current_path = f"{path} > {root['title']}" if root['title'] != "ROOT" else "" if root["content"].strip(): entries.append({ "path": current_path, "title": root["title"], "content": root["content"], "page": root["page"] }) for child in root["children"]: entries.extend(flatten_for_index(child, current_path)) return entries

展平后的 entries 就是我们要索引的基本单元。每个条目都带有完整的标题路径，比如"第三章 系统架构 > 3.2 数据流设计"，这个路径信息在检索时非常有用。

4.4 混合检索实现

检索部分把结构过滤、向量检索、关键词检索串起来：

from rank_bm25 import BM25Okapi import chromadb class PageIndexRetriever: def __init__(self, entries, embedding_model): self.entries = entries self.embedding_model = embedding_model # 初始化向量库 self.client = chromadb.Client() self.collection = self.client.create_collection("doc_index") # 批量写入 texts = [e["content"] for e in entries] embeddings = embedding_model.encode(texts).tolist() self.collection.add( embeddings=embeddings, documents=texts, metadatas=[{"path": e["path"], "page": e["page"]} for e in entries], ids=[str(i) for i in range(len(entries))] ) # 初始化 BM25 tokenized = [list(e["content"]) for e in entries] # 中文按字切，英文需分词 self.bm25 = BM25Okapi(tokenized) def search(self, query, top_k=5, path_filter=None): # 1. 向量检索 query_emb = self.embedding_model.encode([query]).tolist() where = {"path": {"$contains": path_filter}} if path_filter else None vec_results = self.collection.query( query_embeddings=query_emb, n_results=top_k * 2, where=where ) # 2. BM25 检索 tokenized_query = list(query) bm25_scores = self.bm25.get_scores(tokenized_query) bm25_top = sorted(range(len(bm25_scores)), key=lambda i: bm25_scores[i], reverse=True)[:top_k * 2] # 3. 结果融合（简单加权） scores = {} for i, doc_id in enumerate(vec_results["ids"][0]): scores[int(doc_id)] = scores.get(int(doc_id), 0) + 1.0 / (i + 1) for i, doc_id in enumerate(bm25_top): scores[doc_id] = scores.get(doc_id, 0) + 0.5 / (i + 1) # 4. 排序返回 ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)[:top_k] return [self.entries[doc_id] for doc_id, _ in ranked]

这个实现里，向量检索和 BM25 的权重是 1.0 和 0.5，实际项目中需要根据数据特点调。结构化文档通常 BM25 权重可以高一些，因为专业术语的精确匹配很重要。

4.5 与 LLM 对接生成回答

最后一步，把检索结果组织成结构化上下文，注入 prompt：

def build_prompt(query, retrieved_entries): context_parts = [] for entry in retrieved_entries: part = f"[来源：{entry['path']}，页码 {entry['page']}]\n{entry['content']}" context_parts.append(part) context = "\n\n---\n\n".join(context_parts) prompt = f"""你是一个文档问答助手。请根据以下文档片段回答用户问题。 如果文档中没有相关信息，请明确说明"文档中未找到相关内容"，不要编造。 文档片段： {context} 用户问题：{query} 回答：""" return prompt

用 Ollama 调用本地 LLM：

import requests def ask_llm(prompt): response = requests.post( "http://localhost:11434/api/generate", json={ "model": "qwen2.5:7b", "prompt": prompt, "stream": False } ) return response.json()["response"]

整套流程跑通后，你就有了一个结构感知的 RAG 系统。相比纯向量方案，它在结构化文档上的表现会好很多。

5. 常见问题与排查技巧实录

5.1 解析阶段的问题

问题一：PDF 解析出来全是乱码

这种情况通常是 PDF 使用了非标准字体编码，或者文档本身是扫描件。对于扫描件，需要走 OCR 流程，推荐 PaddleOCR 或 Tesseract。对于字体编码问题，可以尝试用 pdfplumber 替代 PyMuPDF，它对某些编码的处理更好。

问题二：标题识别不准

最常见的坑是把页眉页脚识别成标题。解决方法是在解析时过滤掉每页顶部和底部固定区域的文本块。另外，有些文档的标题和正文用同样字号但用颜色区分，这时候需要额外提取颜色信息做判断。

实操心得：我一般会先拿 3-5 份代表性文档做解析测试，人工检查标题识别结果，根据错误模式调整判断规则。不要指望一套规则适配所有文档，按文档类型分别配置解析策略才是正道。

问题三：表格解析后结构丢失

PyMuPDF 提取表格能力有限，复杂表格建议用 camelot 或 tabula。但这两个工具对 PDF 质量要求较高，扫描件基本没戏。我的做法是：先用 PyMuPDF 提取表格区域的文本，保留行列坐标信息，然后在索引时把表格单独标记为 table 类型，检索到表格时把原始坐标信息也传给 LLM，让它自己理解结构。

5.2 检索阶段的问题

问题一：召回结果不相关

先检查 embedding 模型是否适合你的语言和领域。中文文档用 nomic-embed-text 效果一般，建议换 BGE 系列或 m3e。另外，chunk 粒度也很关键——太细丢失上下文，太粗噪声多。我的经验是：结构化文档按章节节点做 chunk，每个 chunk 控制在 500-1500 字，效果比较平衡。

问题二：结构过滤后召回为空

这通常是查询解析出了问题。用户问"第三章"，但文档里写的是"Chapter 3"或者"3. 系统设计"。解决方法是维护一个同义词映射表，把常见的结构表达归一化。另外，结构过滤应该作为加权信号而不是硬过滤，否则一旦解析错误就会导致完全召回不到。

问题三：top-k 结果重复度高

相邻 chunk 内容重叠导致的。解决方法是在索引时做去重，或者在检索后做 MMR（最大边际相关性）重排， penalize 与已选结果相似度高的候选。

5.3 常见问题速查表

5.4 性能优化技巧

当文档量上去之后，检索延迟会成为瓶颈。几个优化方向：

• 索引预过滤：如果查询能确定文档范围（比如按部门、按类型），先用元数据过滤再检索，减少候选集。
• 向量量化：用 PQ 或 SQ 量化减少内存占用和检索时间，代价是轻微精度损失。
• 缓存：对高频查询做结果缓存，尤其是结构定位那一步，同一章节的查询可以复用。
• 异步检索：向量检索和 BM25 检索并行执行，最后合并结果。

我在一个 5000+ 文档的项目里，通过元数据预过滤 + 向量量化，把 P99 检索延迟从 800ms 压到了 120ms 左右。

6. 一些踩坑之后的个人体会

PageIndex 这套思路的核心价值，不在于它用了多先进的技术，而在于它把文档的结构信息当成了检索的一等公民。过去我们做 RAG，注意力全在 embedding 模型和向量数据库上，忽略了文档本身的结构信息其实是非常强的检索信号。

我踩过最大的坑是：一开始觉得结构解析太麻烦，想直接用纯文本加向量检索搞定，结果在结构化文档上反复翻车，最后不得不回头补上结构解析这一环。如果一开始就按 PageIndex 的思路来做，能省下至少两周的返工时间。

另一个体会是：不要追求一步到位。先跑通"解析 → 索引 → 检索 → 生成"的最小闭环，用真实数据验证效果，再逐步优化各个环节。我见过太多项目卡在解析阶段追求完美，结果迟迟出不了 demo，最后项目被砍。

最后分享一个小技巧：在检索结果注入 prompt 时，除了内容和路径，把相邻节点的标题也带上。比如检索到"3.2 数据流设计"的内容，把"第三章 系统架构"和"3.3 存储方案"的标题也附上。这样 LLM 能感知到当前内容在文档中的位置和上下文，回答的连贯性和准确性都会更好。这个改动很小，但实测效果提升明显。