PageIndex 工具链：让 AI Agent 读懂教材

Sun, 12 Jul 2026 17:56:08 +0800

背景链接到标题

上一篇对比了四种 PageIndex 检索方案的 Token 消耗，结论是手写 Agent 循环最省 Token，但每次都要自己写编排逻辑。

能不能把 PageIndex 的检索能力直接注册为 Agent 的原生工具，让 LLM 自己决定什么时候查、怎么查？

Opencode 支持自定义工具（TypeScript 插件），于是把 PageIndex 的三个查询能力封装成三个工具，注册到 Agent 的工具列表中。

三个工具链接到标题

qdrant-search — 语义搜索链接到标题

给定一个问题，通过 bge-m3 向量化后在 Qdrant 中检索，返回命中的教材、章节、页码和文本片段。用于快速定位"哪本书、哪一页"。

export default tool({
  description: "搜索教材内容（Qdrant 语义搜索），返回命中的教材页面及完整文本",
  args: {
    query: tool.schema.string().describe("搜索内容，如《平面向量的数量积》"),
    top_k: tool.schema.number().default(5),
    book: tool.schema.string().optional().describe("限定单书"),
  },
  async execute(args, context) {
    const script = path.join(root, "bin/qdrant-search")
    const cmd = `${script} "${args.query}" --top-k ${args.top_k || 5}`
    return execSync(cmd, { encoding: "utf-8" }).trim()
  },
})

pageindex-structure — 树结构链接到标题

给定 book_id，返回该教材的章节树（仅标题、摘要、页范围，不含正文）。轻量快速，用于查看章节结构。

四种 PageIndex 检索方案的 Token 消耗对比

Thu, 09 Jul 2026 15:21:34 +0800

背景链接到标题

PageIndex 是一个无向量（vectorless）、基于推理（reasoning-based）的 RAG 框架。核心思路是将文档解析为树状索引，让 LLM 通过推理来导航定位内容，而不是靠向量相似度搜索。

这次实验的数据源是一本人教版《物理必修第二册》扫描版 PDF。因为纯扫描件没有文字层，先用 MinerU（vlm-engine）OCR 提取了结构化文本，再插入  标记以使页码可追溯。最后用 PageIndex 对这份带页码的 markdown 建立树索引。

基于同一份数据，实现了四种检索方案，对比它们的实现差异和 Token 消耗。

四种方案的设计差异链接到标题

方案 A：简单查询链接到标题

两步走，两次独立 LLM 调用：

LLM #1 看树结构 → 返回行号范围
LLM #2 取内容 → 回答

没有验证步骤，LLM 一次定生死。

方案 B：手写 Agent 循环链接到标题

三步走，三次独立 LLM 调用：

LLM #1 identify_ranges → 返回候选行号列表
LLM #2 evaluate → 判断内容是否包含答案
LLM #3 final_answer → 基于内容给出最终回答

写了 for 循环遍历候选清单，显式 evaluate 确认命中后才回答。

Pageindex on OHTLY Blog

PageIndex 工具链：让 AI Agent 读懂教材

背景 链接到标题

三个工具 链接到标题

qdrant-search — 语义搜索 链接到标题

pageindex-structure — 树结构 链接到标题

四种 PageIndex 检索方案的 Token 消耗对比

背景 链接到标题

四种方案的设计差异 链接到标题

方案 A：简单查询 链接到标题

方案 B：手写 Agent 循环 链接到标题

背景链接到标题

三个工具链接到标题

qdrant-search — 语义搜索链接到标题

pageindex-structure — 树结构链接到标题

背景链接到标题

四种方案的设计差异链接到标题

方案 A：简单查询链接到标题

方案 B：手写 Agent 循环链接到标题