文档检索 on KnightLi的博客

PageIndex 是什么？不用向量库的推理式 RAG 文档索引解析

Wed, 20 May 2026 23:51:37 +0800

VectifyAI/PageIndex 是一个很有意思的 RAG 项目。它不从“再建一个向量库”开始，而是把长文档先整理成类似目录的树状结构，再让 LLM 沿着这棵树做推理式检索。

截至本文整理时，GitHub 页面显示项目约有 31.8k stars、2.7k forks，许可证为 MIT。README 给它的定位是：Vectorless, Reasoning-based RAG，也就是无向量库、基于推理的 RAG。

它想解决什么问题

传统 RAG 的常见路径是：切块、向量化、写入向量数据库，再用相似度搜索召回片段。这套方法简单、通用，也很成熟，但在长篇专业文档里容易遇到几个问题：

相似度不等于真正相关。
文档结构被切块打散，章节关系丢失。
召回结果可解释性弱，很难说明为什么命中这一段。
对财报、监管文件、法律文书、技术手册这类材料，问题往往需要跨章节推理。

PageIndex 的思路是反过来：先把文档组织成语义树，再让模型像人类读目录、翻章节、逐层定位一样查找相关内容。

PageIndex 的基本工作流

README 里把 PageIndex 的检索分成两步：

为文档生成类似 Table-of-Contents 的树状结构索引。
通过树搜索做 reasoning-based retrieval。

这棵树不是简单的文件目录，而是面向 LLM 使用的文档结构。节点里会有标题、页码范围、摘要、子节点等信息。这样模型在回答问题时，不必一开始就面对大量零散 chunk，而是可以先判断应该进入哪个章节，再继续向下搜索。

这种方式更适合结构清晰但内容很长的文档，例如：

金融报告和 SEC filings。
监管材料和合规文档。
学术教材和论文。
法律文件。
技术手册和产品文档。
超过模型上下文窗口的大型 PDF。

和传统向量 RAG 的差异

PageIndex 的核心卖点可以概括成五点。

第一，不需要 Vector DB。它依赖文档结构和 LLM 推理来定位内容，而不是只做向量相似度搜索。

第二，不做传统 chunking。文档会按自然章节组织，而不是被切成固定长度片段。

第三，可解释性更强。检索路径可以对应到页码、章节和树节点，比“向量相似度命中某段文本”更容易追踪。

第四，检索是上下文感知的。问题、对话历史、领域背景都可以影响树搜索路径。

第五，更接近人类专家读文档的方式。人通常不是把整本文档切成小块再算相似度，而是先看目录，再定位章节，最后读细节。

这并不意味着向量库没有价值。更准确的说法是：PageIndex 适合那些“语义相似不够，需要结构和推理参与”的长文档场景。

本地怎么跑

README 提供了本地自托管方式。先安装依赖：

`1`	`pip3 install --upgrade -r requirements.txt`

然后在项目根目录创建 .env，写入 LLM API key。项目通过 LiteLLM 支持多模型：

`1`	`OPENAI_API_KEY=your_openai_key_here`

对 PDF 生成 PageIndex 结构：

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

也可以处理 Markdown：

`1`	`python3 run_pageindex.py --md_path /path/to/your/document.md`

常见可选参数包括：

--model
--toc-check-pages
--max-pages-per-node
--max-tokens-per-node
--if-add-node-id
--if-add-node-summary
--if-add-doc-description

README 里也提醒，本地开源版本使用标准 PDF 解析。如果是复杂 PDF，项目方的云服务会提供增强 OCR、树构建和检索流程。

Agentic Vectorless RAG 示例

项目还提供了一个 agentic vectorless RAG 示例，使用自托管 PageIndex 和 OpenAI Agents SDK。安装可选依赖后运行：

1
2

pip3 install openai-agents
python3 examples/agentic_vectorless_rag_demo.py

这个示例的价值在于，它把 PageIndex 从“生成文档树”推进到“让 Agent 使用文档树检索”。如果你正在做企业知识库、财报问答、法规问答或技术文档 Agent，这个示例比单纯看 README 更值得跑一遍。

云服务、MCP 和 API

PageIndex 不只是一个 GitHub repo。项目页面还给了几类入口：

自托管：用开源代码本地运行，适合试验和可控部署。
Chat Platform：类似 ChatGPT 的文档分析平台。
MCP / API：方便接入现有 Agent 或自动化流程。
Enterprise：面向私有化或本地部署。

这说明它的定位不是单纯的 demo，而是想把“推理式文档检索”做成一套可集成的文档智能基础设施。

适合哪些场景

PageIndex 比较适合这些任务：

长 PDF 问答。
财报、年报、招股书、监管文件分析。
法律和合规文档检索。
技术手册问答。
多章节教材或论文检索。
需要可解释检索路径的企业知识库。
给 Agent 提供结构化文档上下文。

如果你的材料本身很短、结构不明显，或者只是普通 FAQ，传统 embedding + vector DB 可能已经够用。PageIndex 的优势更容易出现在长文档、强结构、专业领域和需要推理的问题里。

需要注意什么

第一，PageIndex 仍然依赖 LLM。树构建、摘要和检索质量会受模型能力、提示词、文档解析质量影响。

第二，本地版本使用标准 PDF 解析，复杂扫描件、图表密集型 PDF、版式混乱材料可能需要 OCR 和更强的预处理。

第三，无向量库不等于零成本。树构建本身也会消耗模型调用和时间，尤其是大规模文档库。

第四，它更像是文档结构索引和推理检索框架，不是直接替代所有 RAG 技术栈。实际生产里，也可能和向量检索、关键词检索、权限控制、缓存、审计系统一起使用。

小结

PageIndex 的有趣之处在于，它把 RAG 的重点从“文本相似度召回”转向“文档结构 + LLM 推理”。对于长文档和专业文档，这个方向很值得关注。

如果你正在做企业文档问答、金融报告分析、法规检索或技术手册 Agent，可以把 PageIndex 当成一个新的 RAG 架构参考：先让文档有结构，再让模型沿着结构推理，而不是一开始就把所有内容切碎丢进向量库。

参考来源：

GitHub：VectifyAI/PageIndex

qmd：给 AI Agent 使用的本地 Markdown 文档搜索工具

Fri, 01 May 2026 03:12:57 +0800

qmd 是一个面向本地 Markdown 文档的搜索工具，重点服务对象是 AI Agent。

它解决的问题很具体：当你的项目里有大量 .md 文档时，AI 编程助手经常不知道该读哪一份、该引用哪一段、哪些说明才是最新的。靠全文 grep 可以找到关键词，但很难理解语义；直接把整套文档塞进上下文，又浪费窗口，还容易混入无关内容。

qmd 的思路是先为 Markdown 文档建立索引，再通过搜索接口把最相关的片段交给 AI 使用。它既可以作为命令行工具使用，也可以通过 SDK 集成，还可以作为 MCP Server 接入支持 MCP 的客户端。

它解决什么问题

真实项目里的文档通常不是一两篇 README。

你可能会有：

架构说明
API 文档
开发规范
部署流程
设计决策记录
故障排查笔记
需求文档
AI 使用说明
各种工具链备忘录

人类查文档时可以顺着目录慢慢看，但 AI Agent 更需要一个明确的检索入口。否则它可能会：

读错文档
漏掉关键约束
使用过时说明
把不相关内容塞进上下文
在回答里凭经验补全不存在的规则

qmd 的价值就在这里：它把本地 Markdown 文档变成可检索的知识源，让 AI 在需要上下文时先搜索，再基于匹配片段回答或执行任务。

搜索方式有什么特点

README 中提到，qmd 使用了多种检索方式组合：

BM25 关键词搜索
向量搜索
LLM reranking

BM25 适合处理明确关键词。比如你搜索某个函数名、配置项、错误码、文件名，它通常很直接。

向量搜索更适合语义问题。比如你问“这个项目怎么处理权限校验”，文档里未必正好写了“权限校验”四个字，但可能有相关的认证、访问控制、角色判断说明。

LLM reranking 则用于重新排序候选结果。前两步先把可能相关的内容找出来，再让模型判断哪些片段更符合当前问题。

这种组合比单纯关键词搜索更适合 AI Agent。因为 Agent 的问题往往不是固定关键词，而是任务意图。

为什么是 Markdown

Markdown 是开发项目里最常见的文档格式。

它足够简单，可以放进 Git；也足够结构化，有标题、列表、代码块、链接和表格。对 AI 来说，Markdown 也比 PDF、网页快照或截图更容易解析。

qmd 专注 Markdown，意味着它可以围绕开发文档做更直接的处理：

按标题和段落切分内容
保留代码块
保留文档路径
返回适合引用的片段
让 Agent 知道答案来自哪份文档

这比让 AI 随机扫描仓库更稳，也比把所有文档一次性塞进 prompt 更省上下文。

三种使用入口

qmd 提供 CLI、SDK 和 MCP Server 三种入口。

1. CLI

CLI 适合直接在终端里使用，也适合放进脚本。

你可以把文档目录索引起来，然后用命令搜索相关内容。对开发者来说，CLI 是最容易验证效果的入口：先看它能不能搜到正确文档，再考虑接入更复杂的工作流。

这类工具放在本地项目里很有用。比如你可以在改代码前先搜索设计文档，在排错前先查故障笔记，在写接口时先查 API 约定。

2. SDK

SDK 适合把 qmd 接入自己的工具。

如果你正在做内部开发助手、文档问答系统、代码审查机器人或项目知识库，可以通过 SDK 调用搜索能力，而不是让用户直接敲命令。

SDK 的好处是可以更自由地控制：

搜索目录
查询内容
返回数量
结果格式
后续是否交给模型总结

这适合需要深度集成的场景。

3. MCP Server

MCP 是 qmd 对 AI Agent 最有价值的入口。

通过 MCP Server，支持 MCP 的客户端可以把 qmd 当作一个文档搜索工具来调用。这样 Agent 在执行任务时，不必猜项目规则，而是可以先检索本地 Markdown 文档。

典型流程可以是：

用户要求 AI 修改某个功能
AI 先调用 qmd 搜索相关设计文档
qmd 返回最相关的 Markdown 片段
AI 基于文档约束再修改代码

这比“开新会话时手动把所有规则贴进去”更自然，也更适合长期项目。

适合什么场景

qmd 适合这些场景：

项目里有大量 Markdown 文档
AI Agent 经常需要查项目规则
团队希望 AI 回答时引用本地文档
文档分散在多个目录里
需要在 CLI、SDK、MCP 之间复用同一套检索能力
想减少 AI 编程助手凭空猜测项目约定
想把本地知识库接入 Claude Desktop、Claude Code 或其他 MCP 客户端

如果你的项目只有一份很短的 README，直接让 AI 读取文件就够了。

但如果文档已经增长到几十篇、几百篇，或者你希望 Agent 每次先查文档再行动，这类索引工具就有意义。

和 grep 有什么区别

grep、rg 这类工具非常适合精确搜索。

比如你知道要找 DATABASE_URL、authMiddleware、404、docker compose，直接搜关键词通常最快。

qmd 更适合你不知道精确词的情况。

例如你想问：

这个项目的发布流程是什么
新增 API 时要遵守哪些规范
之前有没有记录过缓存策略
AI 修改代码前应该读哪些文档
某个模块的设计背景在哪里

这些问题往往需要语义检索，而不是只匹配一个词。qmd 的 BM25 + 向量 + reranking 组合，就是为了让这类问题更容易找到正确上下文。

和 RAG 有什么关系

qmd 可以看作一个面向 Markdown 文档的轻量 RAG 组件。

它不试图替你完成整套问答系统，而是专注在“把相关文档片段找出来”这一步。至于后续怎么使用这些片段，可以交给 CLI、SDK、MCP 客户端或你自己的 Agent 流程。

这种定位比较实用。很多项目并不需要一个庞大的知识库系统，只需要让 AI 在本地文档里查得准一点、快一点，并且能把结果带回当前任务。

使用时要注意

第一，文档质量仍然重要。

检索工具只能帮你找到已有内容。如果文档本身过时、重复、互相矛盾，AI 仍然可能拿到错误上下文。把 qmd 接入 Agent 之前，最好先清理关键文档。

第二，索引范围不要过宽。

把整个仓库所有 Markdown 都塞进去不一定更好。比如依赖包文档、临时记录、旧方案草稿可能会污染结果。更好的做法是明确哪些目录是可信文档源。

第三，搜索结果需要保留来源。

AI 使用文档片段时，最好知道它来自哪份文件、哪个章节。这样人类复核时才能追溯，也能减少“看起来像文档结论，其实只是模型总结”的问题。

第四，不要完全替代人工判断。

qmd 能提高上下文召回质量，但它不是项目真理源的替代品。重要变更仍然要看当前代码、测试结果和最新需求。

适合怎样的团队

如果你的团队已经开始把 AI Agent 放进日常开发流程，qmd 这类工具会很有价值。

尤其是下面几种团队：

文档写得比较多
项目历史比较长
新人和 AI 都需要快速理解背景
经常维护架构决策记录
有大量 Markdown 规范文档
希望 AI 修改代码前先查规则

它的目标不是让 AI “全知全能”，而是让 AI 少猜一点，多查一点。

参考

tobi/qmd

最后一句

qmd 的价值，是把本地 Markdown 文档变成 AI Agent 能稳定调用的搜索入口。

当项目文档从“给人看的说明”变成“给人和 AI 都能检索的上下文源”，AI 编程助手才更容易按项目规则做事。