PageIndex 自托管部署与本地配置从克隆到跑通文档树索引的完整实操【免费下载链接】PageIndex PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndexPageIndex 是一个不依赖向量数据库的推理式 RAG 文档索引系统它把长 PDF 解析成语义化的层级树结构类似目录但面向 LLM 优化检索时由 LLM 在树上做推理定位而不是做向量相似度匹配。自托管版本让你在本机完成建索引这一步输出一个结构化的 JSON 文件后续检索可以接自己的应用。先弄懂它产出什么再谈配置跑 PageIndex 之前先明确它的输入输出这决定了你要准备什么输入一个 PDF或一个 Markdown 文件外加一个可用的 LLM API keyOpenAI 或其他经 LiteLLM 接入的提供商。输出./results/目录下的一份树结构 JSON每个节点包含章节标题、node_id、起止页码、可选的摘要。仓库里 examples/documents/results/ 有现成的样例输出比如q1-fy25-earnings_structure.json建议先打开看一眼心里有预期再去跑。注意它不产生向量、不需要向量数据库和嵌入模型所以本机对 GPU 没有硬性要求真正的主要开销是 LLM 的 API 调用量和 token 费用。本机能不能跑环境要求与依赖环境门槛很低核心是 Python 版本和一个有效的 API key要求说明Python ≥ 3.10见 pyproject.toml3.10–3.13 均可LLM API key默认走 OpenAI SDK换其他提供商时按provider/model格式配置系统依赖仅纯 Python 包PyPDF2、pypdfium2、litellm、python-dotenv 等见 requirements.txt内存解析本身不重瓶颈在 LLM 调用建议网络能稳定访问所用模型的服务端一个容易踩的坑仓库支持多 LLM但不带提供商前缀的模型名会直接走 OpenAI SDK此时必须有OPENAI_API_KEY用anthropic/...、google/...这类写法则走 LiteLLM 路由。两种写法混用时先想清楚 key 配在哪一边。首次跑通的最小步骤以下四条命令构成最短路径用仓库自带的任一测试 PDF 即可验证。git clone https://gitcode.com/GitHub_Trending/pa/PageIndex cd PageIndex pip3 install --upgrade -r requirements.txt在项目根目录创建.env写入一行OPENAI_API_KEY你的key旧的CHATGPT_API_KEY变量名仍作为别名兼容。然后python3 run_pageindex.py --pdf_path examples/documents/q1-fy25-earnings.pdf结束后检查两件事终端打印Tree structure saved to: ./results/...且该 JSON 里每个节点都有title、node_id、start_index、end_index。能对上说明链路通了。默认模式是 LLM 全程参与先扫描前 20 页找目录、再逐段让模型核对标题出现的页码。文档越长调用越多。如果你只是想快速看树结构用 Flash 模式python3 run_pageindex.py --pdf_path examples/documents/q1-fy25-earnings.pdf --flashFlashpageindex/flash/用版式统计的启发式规则直接提取结构不消耗 LLM 也能出树加--no-summary时完全不调模型只有生成节点摘要时才走 LLM。官方基准显示带优化时端到端约 218 秒/千页耗时与页数近似线性参数怎么调默认值与调整时机所有参数都能通过命令行传入缺省时读 pageindex/config.yaml。多数场景保持默认即可下面只说「什么时候值得动」参数默认值何时调整--modelgpt-4o-2024-11-20想用别的模型时非 OpenAI 模型写provider/model格式--toc-check-pages20文档前 20 页内没有目录常见于长技术文档时调大短文档可调小省调用--max-pages-per-node10章节普遍超长时调大想控制单节点体积、降低检索时上下文长度时调小--max-tokens-per-node20000换用小上下文模型时下调--if-add-node-summaryyes只要结构不要摘要时设no显著减少调用--if-add-doc-descriptionno下游 RAG 需要全文级摘要时设yes--flash关首次试跑、文档量大、想压低成本时优先开--optimize关树太深、检索时 LLM 要逐层下钻太多跳时开启需配合--flash做确定性合并加一轮 LLM 扩展压平结构一个实用的组合大批量文档先用--flash --no-summary出结构确认层级合理后再对少数关键文档跑--flash --optimize精修最后才考虑全量 LLM 标准模式。输出校验与报错定位验证成功的标准很简单results/下有 JSON节点页码单调递增且覆盖全文node_id不重复。常见失败按以下顺序排查启动即报错Either --pdf_path or --md_path must be specified、PDF file not found属于参数或路径问题直接看终端第一行。密钥或模型问题401/403/404 在代码中被标记为不可重试的错误见 pageindex/utils.py遇到就停下来检查 key 是否有效、模型名是否真实存在重试没有意义。PDF 读不出内容扫描版 PDF 没有文本层本地解析会得到空白页。自托管版本用的是标准 PDF 解析对复杂版式 PDF 效果有限这类文档要么先做 OCR 再转 Markdown 走--md_path要么换官方云服务不在本手册范围。--optimize报错requires --flash参数组合限制加上--flash即可。Markdown 输入与进阶玩法Markdown 用--md_path处理层级直接取#的个数##为二级因此只建议用于本身格式规范的 Markdown由 PDF/HTML 转来的文件多半层级失真官方也不推荐这条路径。跑通单文档后两个官方示例值得看examples/agentic_vectorless_rag_demo.py 演示了用树索引做 agentic 检索的完整闭环需额外安装openai-agentscookbook/ 里有向量检索、视觉 RAG 等 Notebook。批量处理多个 PDF 的话把run_pageindex.py包一层循环脚本即可注意按文档大小预估 token 预算。小结自托管 PageIndex 的边界很清晰本机负责「PDF 进、树结构 JSON 出」检索阶段由你接自己的 LLM 应用。默认配置加 Flash 模式是成本最低的起点参数只在目录缺失、节点过大、树过深这三种情况下再动。跑通一个样例 PDF 并检查results/里的 JSON就具备了上线自己文档的前提。【免费下载链接】PageIndex PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考