PageIndex 自托管部署：三步在本地搭好无向量文档索引

PageIndex 自托管部署：三步在本地搭好无向量文档索引

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

PageIndex 是一个基于推理的文档索引系统，它把长篇 PDF 变成层级树状目录，再让大模型在树上"读目录、找章节"完成检索，全程不用向量数据库，也不切块。本指南带你完成 PageIndex 自托管部署：从装依赖、配密钥到调参优化，让本地文档索引跑起来并越用越快。

先搞懂它解决什么问题

传统 RAG 靠向量相似度召回，"相似"不等于"相关"——财务条款、法规文本这类长文档里，真正有用的段落往往措辞和提问完全不同。PageIndex 的思路更像人类专家：先给文档生成一份"目录树"（PageIndex 文档索引树），检索时由 LLM 在这棵树上做树搜索推理，每一步都带明确的章节和页码出处，结果可追溯、可解释。

核心源码在这里：pageindex/page_index_classic.py，默认参数在 pageindex/config.yaml。

动手前准备好三样东西：

• Python 3.8+ 环境
• 一个有效的 OpenAI API 密钥（索引和摘要都靠 LLM）
• 4GB 以上可用内存，文档越长越吃资源

最快上手：三步跑通第一个 PDF

第一步，拿到代码并安装依赖。依赖清单很短，核心是 litellm、openai、pypdfium2、PyPDF2：

git clone https://gitcode.com/GitHub_Trending/pa/PageIndex cd PageIndex pip3 install --upgrade -r requirements.txt

第二步，在项目根目录建一个.env文件写入密钥：

OPENAI_API_KEY=your_openai_key_here

注意键名是OPENAI_API_KEY，写错名字是新手最常见的坑。通过 litellm 你还可以把模型换成其他供应商的格式（如provider/model），后面讲参数时会提到。

第三步，直接对一份 PDF 发起索引：

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

跑完后终端会提示Tree structure saved to: ./results/xxx_structure.json。入口脚本是 run_pageindex.py，输出目录固定为当前目录下的results/。

关键参数详解

默认值对一般文档够用，但下面这几个参数直接决定树的质量和成本，值得逐个认识。它们既能改 pageindex/config.yaml，也能用命令行参数临时覆盖。

一个取舍提醒：--max-pages-per-node调大，树更短、API 调用更少，但检索时模型要读的段落更粗；调小则相反。

提速与内存调优：大文档场景

文档上百页时，默认参数下建树又慢又贵。三个思路按性价比排序：

1. 先试 Flash 模式。它用版面统计启发式直接抽结构，不耗 LLM 就能出树，速度快一个量级：

python3 run_pageindex.py --flash --pdf_path document.pdf

摘要仍会调 LLM；加--no-summary可完全离线出结构。Flash 的实现和基准测试在 pageindex/flash/，下面是官方给出的端到端耗时随页数增长曲线，大致是 218 秒 / 1000 页的线性关系：

2. 给 Flash 加--optimize。它会先做确定性合并，再让 LLM 做一轮展开，降低树搜索的检索成本，适合建好后要反复检索的场景。

3. 手动调小节点规模。内存不够或上下文紧张时，把--max-pages-per-node从 10 降到 5~8，配合--toc-check-pages收紧目录扫描范围；再大的文档建议分批处理，而不是一次性喂进去。

怎么判断部署成功了

三条验证路径，由浅入深：

• 看产出文件：results/下生成了<文档名>_structure.json，里面应是嵌套的title/start_index/end_index/nodes结构，页码区间连续且不重叠。仓库里带了几份现成样本可以直接对照，见 examples/documents/results/。
• 人工抽查：随机挑 2~3 个节点，翻到start_index对应页确认标题对得上；层级是否合理（章节嵌套、无孤节点）。
• 跑一次真实检索：按 examples/tutorials/tree-search/ 里的树搜索提示词，把树和查询喂给 LLM，看它返回的node_list是否指向正确章节。能稳定命中，说明这条 PageIndex 本地部署链路完整可用。

常见报错与排查

现象：启动即报认证失败 / 401。原因：.env不存在、键名拼错（比如写成CHATGPT_API_KEY），或密钥本身过期。 解法：确认根目录下.env里是OPENAI_API_KEY=...，用 curl 单独验证密钥有效后再跑。

现象：处理大文档时内存爆掉或长时间无响应。原因：节点过大导致单次塞给 LLM 的文本超限，解析中间态占内存。 解法：--max-pages-per-node降到 5~8，--max-tokens-per-node同步调小；仍不行就分批处理。

现象：闪退提示 "PDF file not found" 或扩展名错误。原因：路径不对，或文件不是.pdf后缀。 解法：run_pageindex.py会校验扩展名与文件存在性，用绝对路径重试即可。

现象：树结构混乱、层级错乱。原因：扫描件或复杂版式 PDF 超出标准解析能力（自托管模式用的是常规 PDF 解析）。 解法：换--flash模式重建；对重度扫描文档考虑先做高质量转换再走--md_path流程。

现象：Markdown 模式层级完全不对。原因：该模式靠#数量判断层级（##是二级、###是三级），PDF 转出来的 Markdown 往往丢了原始层级。 解法：检查并手工修正标题层级，或对转换工具的输出做清洗。

更多玩法

• Markdown 文档：同样的命令换个参数即可，python3 run_pageindex.py --md_path /path/to/doc.md，节点摘要、ID 等开关与 PDF 模式通用。
• 批量处理：写个循环遍历目录里的 PDF 逐个调用 run_pageindex.py 即可，每份文档各自落一个 JSON 到results/，天然适合夜间跑批。
• 接上 Agent 问答：装pip3 install openai-agents后运行 examples/agentic_vectorless_rag_demo.py，能看到自托管 PageIndex 配合 OpenAI Agents SDK 的端到端无向量 RAG 效果。
• 集成框架：pageindex/integrations/ 提供了 OpenAI Agents、Anthropic SDK 等的接入层，配合 cookbook/ 里的 notebook 可以扩展到视觉 RAG 等场景。

把 PageIndex 跑在自己的机器上，意味着文档数据不出内网、检索行为完全可控，敏感文档和企业合规场景尤其吃香。装好依赖、配好密钥，剩下的就交给那些参数去微调了。

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