PageIndex 快速指南：无分块、无向量库的推理 RAG 文档索引，三步跑通

PageIndex 快速指南：无分块、无向量库的推理 RAG 文档索引，三步跑通

【免费下载链接】PageIndex📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndex

PageIndex 是一个面向长文档的文档索引引擎：它把 PDF 或 Markdown 整理成一棵层级树状索引，再由大模型在树上做推理检索（reasoning-based RAG）找到答案所在的章节。全程不建向量数据库，也不做人工分块。下面用 5 分钟带你搞懂它是什么、能干什么、怎么开始。

长文档问答为什么经常"答非所问"

你有没有这种经历：把一份几百页的年报丢给基于向量库的 RAG 系统，问"本季度 EBITDA 调整项有哪些"，它却返回一堆"看起来相关"的段落。问题出在三个地方：

• 相似不等于相关。向量检索靠语义相似度打分，但"相似"的段落未必包含答案，真正相关的段落可能措辞完全不同。
• 分块切断上下文。传统做法把文档切成固定长度的碎片再分别向量化，一个跨页的表格、一个章节内的递进论证，都会被拦腰截断。
• 答案来源说不清。检索结果是一堆近似片段，你很难回答"它到底是从哪页、哪个章节来的"。

PageIndex 的思路是换个方向：不猜"哪段文字和问句像"，而是让模型像查目录一样，沿着文档结构推理出该去哪个章节，再精读那一节。

它是怎么工作的：先建"目录树"，再做"树上推理"

PageIndex 分两步，整个过程类似一位专家翻阅专业资料：

1. 生成树状索引。它先解析整份文档，产出一棵"目录树"：每个节点是一节内容，带有标题、起始/结束页码、内容摘要和子节点。
2. 基于树做推理检索。提问时，把整棵树交给 LLM，让它推理"哪些节点最可能包含答案"，只精读对应章节，而不是对全库做相似度扫描。

一个节点长这样：

{ "title": "Financial Stability", "node_id": "0006", "start_index": 21, "end_index": 22, "summary": "The Federal Reserve ...", "nodes": [ { "title": "Monitoring Financial Vulnerabilities", "node_id": "0007" } ] }

每个节点都锚定明确的页码范围，所以每一步检索路径都可回溯、可解释——这也是它和"黑箱向量搜索"最大的区别。

三步完成首次运行

先拿到代码：

git clone https://gitcode.com/GitHub_Trending/pa/PageIndex cd PageIndex

第一步：装依赖

pip3 install --upgrade -r requirements.txt

第二步：配置密钥

在仓库根目录新建.env文件，写入你的 LLM API 密钥（支持 LiteLLM 多模型写法）：

OPENAI_API_KEY=your_openai_key_here

第三步：生成你的第一棵树

python3 run_pageindex.py --pdf_path /path/to/your/document.pdf

解析完成后，树结构会保存到results/<文档名>_structure.json。跑通这一步，你就已经完成了从"原始 PDF"到"可推理索引"的完整流程。

两个常用变体：

# 快速模式：结构提取不用 LLM，几秒出树 python3 run_pageindex.py --pdf_path /path/to/your/document.pdf --flash # Markdown 文档：按标题层级建树 python3 run_pageindex.py --md_path /path/to/your/document.md

实测：数字说话

• FinanceBench 98.7% 准确率。基于 PageIndex 的金融文档问答系统 Mafin 2.5，在金融文档问答基准 FinanceBench 上拿到 98.7% 的准确率，大幅超过传统向量 RAG 方案，尤其在 SEC 文件、财报披露这类复杂文档上表现稳定。
• 索引生成耗时可预期。PageIndex Flash 的基准测试覆盖 9 个从 9 页到 1098 页的 PDF（比特币白皮书、DeepSeek-R1 论文、联邦储备 2023 年报、机器学习教材等），耗时与页数近似线性，拟合约为218 秒 / 1000 页，R² = 0.924，见上方图表。
• 有一个完整可跑的端到端例子。examples/agentic_vectorless_rag_demo.py 基于 OpenAI Agents SDK，用自托管 PageIndex 实现了"智能体式"无向量 RAG，装完可选依赖即可直接运行：

pip3 install openai-agents python3 examples/agentic_vectorless_rag_demo.py

进阶与避坑

这些配置你可以按文档调

配置在 pageindex/config.yaml，也可用命令行参数覆盖：

• 目录检查页数toc_check_page_num决定模型在前多少页中寻找目录信息；目录靠后的文档可以适当调大。
• 节点页数上限max_page_num_each_node控制单个节点"粒度"：调大→树更浅但单节点更粗，调小反之。

几个容易踩的坑

• --pdf_path和--md_path二选一，同时传会直接报错。
• Markdown 模式靠#的个数判断标题层级（##是二级、###是三级）。如果你的 Markdown 是从 PDF/HTML 转来的，多数转换工具丢掉了原始层级，不建议直接用这个模式。
• 本仓库走的是标准 PDF 解析，适合结构清晰的电子文档（财报、监管文件、学术教材、技术手册）；复杂扫描件、图片型 PDF 建议走云端的增强 OCR 管线。
• 多文档检索时，官方给了三种工作流（按元数据 / 按语义 / 按描述），见 examples/tutorials/doc-search/；树的检索策略示例见 examples/tutorials/tree-search/。

延伸资源与部署方式

• cookbook/：两个可运行的 Notebook——最小化的推理式 RAG（pageindex_RAG_simple.ipynb）和无需 OCR、直接在页面图像上检索的视觉 RAG（vision_RAG_pageindex.ipynb）。
• pageindex/：核心源码；pageindex/flash/ 是秒级建树的快速模式，pageindex/integrations/ 提供 OpenAI Agents、Anthropic SDK、Claude Agent SDK 的集成入口。
• 部署上有两条路：自托管，即直接用这个开源仓库本地运行；云服务，通过 Chat 平台、MCP 或 API 接入增强管线（含增强 OCR 与树构建）。

克隆仓库，挑一份你手头最长的 PDF，用--flash跑出你的第一棵树——这就是体验 PageIndex 推理 RAG 最快的方式。

【免费下载链接】PageIndex📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndex