文件檢索 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 編程助手才更容易按專案規則做事。