PageIndex 使用笔记

是什么

PageIndex 是 VectifyAI 开源的无向量、基于推理的 RAG 框架。核心思路：把文档解析为层级树结构，让 LLM 通过推理遍历树来检索，而不是 embedding + 向量数据库 + top-k 相似度匹配。

一句话：用”目录导航”替代”语义搜索”。

核心优势

官方 benchmark：Mafin 2.5（基于 PageIndex）在 FinanceBench 上达到 98.7% 准确率，超过传统向量 RAG。

适合场景

• 财务报告、SEC 文件（10-K、10-Q）
• 法律文件、合规手册
• 学术教材、技术文档
• 超长 PDF（超出 LLM 上下文窗口）
• 需要溯源到具体页码/章节的问答

不适合场景

• 需要亚秒级响应的高并发应用
• 大规模语料库的粗粒度语义过滤
• 结构扁平、无层级的数据

混合方案：先用向量搜索缩小候选范围，再用 PageIndex 精准检索。

安装

托管 API（推荐）

pip install -U pageindex

npm install @pageindex/sdk

本地开源版

git clone https://github.com/VectifyAI/PageIndex
pip install -r requirements.txt
# 设置 .env: OPENAI_API_KEY=xxx
python run_pageindex.py --pdf_path ./doc.pdf
# 或 markdown 模式
python run_pageindex.py --md_path ./doc.md

注意：markdown 模式要求原始文档层级结构完整，不推荐用于从 PDF/HTML 转换的 markdown。

Python SDK 快速上手

from pageindex import PageIndexClient

client = PageIndexClient(api_key="YOUR_API_KEY")

# 1. 提交文档
doc_id = client.submit_document("./annual-report.pdf")

# 2. 等待处理完成
import time
while True:
    status = client.get_document(doc_id)["status"]
    if status == "completed":
        break
    time.sleep(5)

# 3. 查询（通过 Chat API）
# 支持多文档、流式响应

Agentic 检索模式

官方提供三个核心工具，供 Agent 调用：

get_document(doc_id)           # 获取文档元信息
get_document_structure(doc_id) # 获取文档树结构
get_page_content(doc_id, pages) # 获取指定页内容

示例脚本：examples/agentic_vectorless_rag_demo.py（基于 OpenAI Agents SDK）

JavaScript SDK

import { PageIndexClient } from "@pageindex/sdk";

const client = new PageIndexClient({ apiKey: "YOUR_API_KEY" });

await client.submitDocument(file);
await client.getTree(docId);
await client.chatCompletions({ docIds: [docId], message: "..." });

MCP 集成

适合在 Claude、Cursor 等 MCP 客户端中使用：

# pageindex-mcp，MIT 协议，需要 Node.js >= 18

兼容：LangChain、CrewAI、OpenAI Agents SDK、任意 MCP 客户端。

REST API

Authorization: Bearer YOUR_API_KEY

GET  /v1/documents
POST /v1/documents
GET  /v1/conversations
POST /v1/conversations/:id/messages

Vision RAG（无 OCR）

支持直接用 PDF 页面图像 + 多模态 LLM（如 GPT-4.1）回答问题，适合含图表、复杂表格的文档。

定价（托管服务）

• 索引：1 积分/页（一次性）
• 查询：按 token 计费
• 额外积分：$0.01/个

性能注意事项

• 查询延迟高于向量检索（涉及 LLM 推理），参考值 0.5–3 秒
• 扫描版 PDF 的树生成较慢
• 索引时间约 5–15 分钟/100 页（非官方数据，仅供参考）

相关链接

• GitHub: https://github.com/VectifyAI/PageIndex
• 文档: https://docs.pageindex.ai
• MCP: https://github.com/VectifyAI/pageindex-mcp
• JS SDK: https://github.com/VectifyAI/pageindex-js-sdk