VectifyAI/PageIndex · 上手攻略
- 仓库：VectifyAI/PageIndex
- 链接：https://github.com/VectifyAI/PageIndex
- 分类：ai（RAG / LLM-infra）
- 作者：Tom
- 更新：2026-07-08
一、是什么
PageIndex 是一个无向量、基于推理的 RAG（检索增强生成）引擎，由 Vectify AI 开发。其核心理念是：传统向量 RAG 依赖"语义相似度"做检索，但这不等于"真正相关"——尤其在金融报告、法律文书、医疗文献等高度专业化的长文档场景，"相似"和"相关"的差距尤为明显。
PageIndex 模拟人类阅读长文档的方式——先看目录，再顺着结构找答案，而不是把所有文字切成小块然后做向量匹配。它的工作原理分两步：
- 构建文档树索引（Table-of-Contents 树）：将 PDF/文档解析为层次化的 JSON 树结构，每个节点含标题、摘要、页码范围和子节点；
- 推理式检索：LLM 在这个树结构上做推理式导航，而非向量相似度搜索，找到最相关的节点后提取原始内容喂给生成模型。
官方在 FinanceBench（金融文档 QA 基准）上取得了 98.7% 准确率，远超传统向量 RAG 方案。
二、解决什么问题
传统向量 RAG 的六大痛点，PageIndex 逐一对应解决：
| 痛点 | 向量 RAG 做法 | PageIndex 做法 |
|---|---|---|
| 查询-知识空间失配 | query embedding 与文档块做相似度匹配 | LLM 推理"这个问题该去哪个章节找" |
| 相似 ≠ 相关 | 语义相似但上下文不同，干扰大 | 按文档结构导航，保留完整语义单元 |
| 硬分块破坏完整性 | 512/1000 token 切块，截断段落/章节 | 按自然章节/页面检索，迭代补充相邻节点 |
| 无法融合对话历史 | 每轮 query 独立，无状态 | 推理过程自带上下文累积 |
| 文档内交叉引用难处理 | "见附录 G"等引用无法被向量召回 | 树结构中引用关系可被 LLM 理解 |
| 结果不可解释 | 只返回向量相似度最高的块 | 每个结果有明确的页码、节点路径可追溯 |
三、快速安装
环境要求
- Python ≥ 3.10
- LLM API Key（支持 OpenAI、Azure OpenAI 等，底层用 LiteLLM）
pip 安装
# 克隆仓库
git clone https://github.com/VectifyAI/PageIndex.git
cd PageIndex
# 安装依赖
pip3 install -r requirements.txt
# 配置 API Key（支持多 provider，示例为 OpenAI）
echo "OPENAI_API_KEY=sk-your-key-here" > .env
关键依赖说明
requirements.txt 中包含：
- litellm — 多模型统一调用（OpenAI / Azure / Anthropic / Gemini 等）
- PyMuPDF（或 pdfplumber）— PDF 解析
- tree-sitter 相关 — 文档结构解析
- openai-agents（可选）— Agentic RAG 示例需要
⚠️ 云服务版（chat.pageindex.ai）提供增强 OCR 和更高质量的树构建；本地开源版使用标准 PDF 解析，对复杂扫描 PDF 效果可能有限。
四、核心用法
4.1 生成分档树索引（本地）
# 处理 PDF，生成 JSON 树结构
python3 run_pageindex.py --pdf_path /path/to/your/document.pdf
# 可选参数
--model gpt-4o-2024-11-20 # 指定模型，默认 gpt-4o-2024-11-20
--toc-check-pages 20 # 从前 N 页提取目录信息，默认 20
--max-pages-per-node 10 # 每节点最大页数，默认 10
--max-tokens-per-node 20000 # 每节点最大 token 数，默认 20000
--if-add-node-id yes # 是否添加节点 ID，默认 yes
--if-add-node-summary yes # 是否添加节点摘要，默认 yes
--if-add-doc-description yes # 是否添加文档描述，默认 yes
4.2 处理 Markdown 文件
python3 run_pageindex.py --md_path /path/to/your/document.md
⚠️ Markdown 模式用
#标题层级判断节点深度，不适合从 PDF/HTML 转换来的 Markdown（层级信息往往丢失）。建议优先用--pdf_path。
4.3 最小化 Agentic RAG 示例
需要先安装 openai-agents：
pip3 install openai-agents
然后运行官方示例：
python3 examples/agentic_vectorless_rag_demo.py
该示例展示了：① 用 PageIndex 构建文档树 → ② 传入 OpenAI Agents SDK → ③ 在对话中做推理式检索 → ④ 最终生成答案的完整流程。
4.4 云端 API（免部署）
# 通过 MCP 接入
# 参考 https://pageindex.ai/developer
# 或直接调用 REST API
curl -X POST https://api.pageindex.ai/v1/index \
-H "Authorization: Bearer $PAGEINDEX_API_KEY" \
-F "file=@document.pdf"
4.5 Jupyter Notebook 快速体验
# 打开官方 Colab notebook
# https://colab.research.google.com/github/VectifyAI/PageIndex/blob/main/cookbook/pageindex_RAG_simple.ipynb
还提供了 Vision-based RAG notebook（直接用页面图片，无需 OCR）：cookbook/vision_RAG_pageindex.ipynb
五、典型适用场景
- 金融文档分析 — 招股书、年报、SEC 文件、财报电话会议记录
- 法律文书检索 — 合同条款、判决书、法规文档
- 医疗/科研文献 — 临床指南、药品说明书、医学论文
- 技术手册/标准文档 — API 文档、产品规格、合规文档
- 学术论文理解 — 长篇论文的快速定位与问答
不适合：短文本（FAQ、简单问答）、纯聊天场景、无结构纯文本。
六、坑与注意
| 坑 | 说明 |
|---|---|
| 复杂扫描 PDF 效果差 | 本地开源版用标准 PDF 解析器，扫描版 PDF（无文字层）建议用云端 API 的增强 OCR |
| 构建树索引有 API 成本 | 每份文档都要调用 LLM 做结构分析，大批量处理需考虑费用 |
| 树深度影响推理质量 | 建议 --max-pages-per-node 不要太大（默认 10 页），保证每个节点可被 LLM 完整理解 |
| 不支持实时更新的语料库 | 单文档场景为主；大规模语料需配合 PageIndex File System（见博客）或自行做增量索引 |
| 中文 PDF 支持 | 需确认 PDF 内嵌文字编码；部分中文 PDF 用标准解析器可能乱码 |
七、与同类对比
| 方案 | 检索方式 | 向量数据库 | 适用场景 | 成熟度 |
|---|---|---|---|---|
| PageIndex | 推理式树导航 | ❌ 不需要 | 长专业文档、多章节文档 | 生产级 |
| LlamaIndex | 混合（向量+关键词+知识图） | ✅ 需要 | 通用 RAG | 成熟 |
| LangChain RAG | 向量检索为主 | ✅ 需要 | 通用 RAG | 成熟 |
| Claude Code Agentic RAG | 直接让 Agent 读文件 | ❌ 不需要 | 代码库问答 | 成熟 |
| RAPTOR（层层摘要树） | 树形多粒度摘要 | 可选 | 长文档抽象理解 | 研究级 |
PageIndex 的核心差异：明确不走向量路线，把文档结构本身作为索引，用 LLM 推理代替向量相似度。这是目前少有的纯推理路线 RAG 框架，定位清晰。
八、一句话推荐结论
如果你处理的是金融报告、法律合同、学术论文等长篇专业文档，且对检索准确率和结果可解释性有较高要求，PageIndex 是一个值得尝试的方向——它用 LLM 推理代替向量匹配，98.7% FinanceBench 准确率的数字很有说服力；但如果你的语料库规模极大（百万级文档），需要配合其 PageIndex File System 或自行扩展。
来源：GitHub README、pageindex.ai/blog/pageindex-intro 技术博客、GitHub repo_cards 卡片（Stars 33,857 / 周增 +196 / 分类 ai / MIT 协议 / Python）