AutoRAG 2.0：把 RAG 管線換成一個會自己變聰明的圖書館員

同一個 repo 名稱，兩個世代的分岔

打開這個 repository 的第一件事是確認你點進的是哪一份文件。README 開頭就放了警示：原本那個 Python 寫的 RAG AutoML 工具，也就是自動替你的資料找出最佳 RAG 管線的版本，已經被移到 legacy/ 目錄。主線上的 AutoRAG 2.0 是另一套東西，定位寫得很直白，是一個自演化的圖書館員代理。

這個分岔對評估者來說比功能清單更重要。legacy 版本沒有被放棄，README 明講它持續維護，處理 bug fix、相依套件更新與 PyPI 發布，安裝方式仍是 pip install AutoRAG，新功能開發則全部集中在 2.0。所以如果你的團隊去年選了 AutoRAG 當管線最佳化工具，你的相依沒有斷，但你也不會再拿到新的最佳化能力。

兩個世代的語言也不同。repository 標示主要語言為 TypeScript，而 legacy 版本是 Python 生態。這代表 2.0 的整合面是 Node 端，設定物件、agent 建構子、parserOptions 都是 TypeScript 型別。想把 2.0 塞進既有 Python 服務的人，得先決定是另起一個 process 還是走 CLI。

授權欄位顯示為 NOASSERTION，這表示 GitHub 無法從 repository 內容自動判定出標準授權條款。要投入生產之前，這是你必須自己去看 LICENSE 檔案確認的事，不能靠這個欄位推測。

它解決的是「工具只給你檔案路徑」這件事

README 對問題的描述很具體。一般搜尋工具回傳的是一串檔案路徑與命中行，接下來開檔、讀上下文、判斷相關性、綜合出答案、記住這次什麼有效，全部由人來做。AutoRAG 的立場是：這些工作應該由代理做完，回傳的是編號過的知识單元，而不是原始 grep 輸出。

README 給的範例是一個問句「What were the key findings in the Q3 report?」，回傳三條帶頁碼範圍的結論，例如營收年增 23% 至 420 萬美元、三項新風險因子、以及員額目標短缺 12 人。這個範例的意義在於輸出格式：沒有檔案路徑，沒有行號，只有可據以行動的整理結果。

目標使用者因此不是在建 RAG 平台的工程師，而是手上有一批文件、想直接問問題的人。README 列出的語料類型包括 PDF、wiki、筆記、研究論文與知識庫。它同時強調不需要 RAG 相關背景，理由是本地嵌入模型（EmbeddingGemma via Ollama）與 MinSync 的自動安裝會把「RAG 水管工程」藏起來。

這裡有個值得注意的定位細節：AutoRAG 本身是專門的搜尋代理，不是其他模型角色的協調者。README 寫得很清楚，你只設定一個模型，那個模型擁有完整的檢索、閱讀、判斷與整理迴圈。模型與供應商來自使用者已驗證的執行環境，AutoRAG 不附帶私有的預設供應商。

檢索怎麼跑：MinSync 的 CDC 分塊與 ResultMerger

機制上，本地檢索由 MinSync 承擔。它維持一份共用的 CDC 分塊生命週期，BM25、向量與混合三種檢索都走同一條路徑，並透過 RetrievalMethodRegistry 接線。這三種方法在 MinSync 啟用時預設全部開啟，這點值得留意，因為它意味著首次使用就會觸發索引建立。

資料流大致是這樣：librarian 呼叫檢索工具取得候選，檢索工具提供候選路徑，但代理會再透過內建的 bash 工具直接開啟來源檔案，讀過原始素材之後才進行整理。多來源的結果經過 ResultMerger 做分數正規化與去重，最後合併成單一結果集。回傳結構是 SearchDocumentsResponse，內部映射保留真實來源（檔案路徑或 datasource id），供後續回饋與整理使用。

索引的對象不是原始檔案，而是解析後的 markdown 鏡像，放在 .autorag 底下，BM25、向量與混合檢索都查這份鏡像。這個設計選擇解釋了為什麼 parser 的品質會直接決定檢索品質：抽取失敗的 PDF，索引裡就是空的。

外部資料源走的是另一條路。README 說 AutoRAG 以聯邦方式就地查詢 CLI 擁有的 store，列舉了 katok、discrawl、qmd、msgvault、rclone 等，不強制把語料搬進中央索引，結果帶著來源原生的識別碼，例如 kakao:<chat>/<sender>/<chunk>，並且有 scope 檢查。外部資料源各自維持自己的 archive 與 index 生命週期，這與本地 MinSync 的索引是兩套東西。

文件裡也提供了檢索方法與文件類型的對應表：純文字與設定檔適合 grep，研究論文與密集散文適合向量檢索，法律文件與規格書適合 BM25，混合集合則用 hybrid。這張表是建議而非自動判斷，實際選哪一種仍取決於代理的判斷與記憶。

安裝與設定：從 autoInstall 到 maxChunkSize

啟動路徑上，MinSync 在首次使用時會自動把一個已驗證的 release 安裝到 <workspace>/.autorag/bin，這個行為由 autoInstall 控制，預設為 true。只有在你自己管理該 binary 時才應該設成 false。

關閉的方式有兩層。整組本地索引可以用 "minSync": false 停掉，只停詞彙檢索則用 "bm25": false。這個區分在實務上有用：向量檢索與 BM25 的資源特性不同，你可能想留一邊。

嵌入端點的設定走 CLI flag：autorag init --embedder-*。README 明確表示 AutoRAG 不會強迫使用 TEI 或任何外部嵌入服務，預設是本地路徑。當你使用 context window 較小的本地嵌入模型時，需要調整 minSync.maxChunkSize，對應的 CLI 參數是 --minsync-max-chunk-size。這個參數與模型選擇是綁在一起的，換模型就要重看一次。

Parser 端有一個可程式化調整的區塊。建構 agent 時可以傳入 parserOptions.thinExtract，欄位包括 minPages、minChars、minCharsPerPage、timeoutMs、hybrid 與 hybridMode。README 給的範例值是多頁 PDF 少於 800 字元、或每頁平均少於 40 字元、且至少三頁時觸發，透過 OpenDataLoader 的 docling-fast 後端重試，hybridMode 設為 "auto"，逾時 30 秒。密集的 PDF 不會重試，單頁 PDF 與圖片也不會走 hybrid，也不會把 hybrid 當第一條路徑。

這些預設值透露了一個判斷：專案作者認為薄抽取是罕見的例外，不值得為它付出每次解析都跑兩條路徑的成本。這個取捨是否適合你的語料，取決於你的 PDF 有多少是掃描件或排版異常。

自我演化記憶的邊界在哪裡

README 用了不少篇幅描述自演化記憶：每次搜尋都會學到東西，包括哪些檢索方法對哪類查詢有效、哪些文件區域產出較高、以及呼叫者透過明確回饋表達什麼有用。它把新鮮的 AutoRAG 形容成什麼都試，用久了的 AutoRAG 則知道該往哪裡看，並強調這不是靜態設定，而是從真實使用中學到的行為。

這是整份文件裡最需要保留態度的一段。文件沒有說明記憶以什麼格式儲存、放在哪個路徑、是否可匯出、是否可重設、遺失後如何重建，也沒有說明多個 workspace 之間是否共享。它同樣沒有給出學習效果的量化描述。對於需要可重現性的團隊來說，一個會隨使用歷程改變行為的檢索代理，意味著同一句查詢在不同時間點可能得到不同結果，而這個差異不容易歸因。

回饋機制倒是相對明確：呼叫者可以提供 explicit feedback，而結果的內部映射保留了真實來源，讓回饋能對應回具體的文件與區塊。這是可觀測性的基礎，但文件沒有展開回饋如何影響後續檢索排序。

如果你的場景需要稽核每一次檢索決策，這裡就是你要先自己驗證的地方。建議在正式採用前，先確認記憶的儲存位置與清除方式，否則你會在排查「為什麼上週查得到、這週查不到」時缺少工具。

什麼情況下它是錯的工具

第一個明確的排除條件是：你要的是 RAG 管線的自動調校與評測。這正是 legacy 版本在做的事，也是這個 repository 過去的身分。主線 2.0 的定位是檢索代理，不是管線最佳化器。repository 的 topics 仍掛著 automl、benchmarking、rag-evaluation、llm-evaluation，這些標籤反映的是整個 repository 的歷史，不代表主線功能。看到這些標籤就以為 2.0 會幫你跑 benchmark 比較不同 chunking 策略，是很容易犯的誤判。

第二個排除條件是集中式治理需求。如果你需要一個所有文件都進去、有統一權限模型與統一審計日誌的索引，AutoRAG 的聯邦式設計是反方向。它刻意不建立中央索引，代價是查詢行為取決於各資料源自己的 archive 與 index 生命週期，你無法用單一指令重建全部狀態。

第三個是環境限制。MinSync 需要把 binary 安裝到 workspace 底下的 .autorag/bin，這在某些容器或唯讀檔案系統的部署環境裡行不通。文件沒有列出支援的平台清單，這是採用前必須自己確認的項目。

第四個是單模型架構的取捨。一個模型負責檢索、閱讀、判斷與整理全部環節，好處是延遲低、設定少，代價是你無法針對不同階段換用不同模型。如果檢索需要便宜的小模型、整理需要強推理的大模型，這個架構不給你這個選項。

與傳統 RAG 框架的差異不在功能表上

拿它跟 LlamaIndex 或 LangChain 這類框架比，差異不在於誰支援更多向量資料庫。那些框架的預設心智模型是：你定義一個 ingestion 管線，把文件切塊、嵌入、寫進索引，然後在查詢時組裝 retriever 與 synthesizer。文件是資料，索引是你的資產，管線是你的程式碼。

AutoRAG 2.0 把這些都收進代理內部。文件留在原地，索引是代理自己維護的副產品，放在 .autorag 底下，而且索引的是解析後的 markdown 鏡像而非原始檔。你設定的不是管線，是一個模型與一組來源路徑。

第二個差異是閱讀行為。傳統框架的 retriever 回傳 chunk，答案由 LLM 根據 chunk 生成。AutoRAG 的代理在整理之前會用 bash 直接開檔讀取，檢索工具的候選只是線索。這讓它能處理「檢索命中但上下文不足」的情況，代價是每次查詢的檔案讀取次數不受你控制。

第三個差異是對外部資料源的態度。框架通常要求你把資料拉進來；AutoRAG 選擇就地查詢 CLI store，並讓結果帶著來源原生識別碼。README 把這一點稱為持久的差異點，並指向一份 competitive landscape 文件。這個主張是否成立取決於你實際使用的資料源是否落在它支援的清單裡，清單目前列的是 katok、discrawl、qmd、msgvault、rclone 這幾個。

維護成本與版本節奏

從 release 紀錄看，v2.4.1 在 2026 年 9 月 5 日發布，v2.4.0 在前一天，v2.3.0 則在 8 月 24 日。這是相當密集的節奏，最近一次 push 在 9 月 9 日。對採用者而言，這代表兩件事：功能在快速變動，以及升級需要成本。

升級成本的主要來源是設定介面。thinExtract 的參數、minSync 的欄位、embedder 的 CLI flag 都屬於會隨版本調整的表面。文件裡特別提到 thinExtract 是 parser 擁有的 gate，且可透過 trusted programmatic parserOptions 調整，這暗示未來可能還有其他 parser 層級的選項會開放。

另一個成本來源是 MinSync binary 的生命週期。autoInstall 會在首次使用時安裝一個已驗證的 release，但文件沒有說明已安裝的 binary 如何隨 AutoRAG 版本更新，也沒有說明版本不符時的行為。如果你在 CI 或容器映像裡預先安裝，就得自己追蹤對應關係。

授權方面，repository 的 license 欄位是 NOASSERTION，無法從中得知條款。legacy 版本以 PyPI 套件形式發布，主線的散布方式與授權約束需要直接查閱 repository 的 LICENSE 檔案。這不是法律意見，只是提醒你不要把 NOASSERTION 當成寬鬆授權來讀。

最後要記得，這個 repository 同時承載兩條維護線。legacy 版本仍在收 bug fix 與相依更新，主線在加新功能。如果你同時依賴兩者，issue 會進同一個追蹤系統，回報時要標清楚是哪一版。

編輯結論

如果你手上是一堆散落的 PDF、wiki 匯出、筆記與研究論文，而且不想先把它們灌進某個集中式索引，AutoRAG 2.0 的聯邦式檢索與本地 MinSync 索引值得先做一次小規模驗證。如果你需要的是可重現的 RAG 管線調校與 benchmark 報表，主線已經不是那個工具，請直接看 legacy/ 目錄下的 Python 版本，它仍在維護模式中持續發布 PyPI 套件。動手前先確認三件事：你的執行環境能否讓 MinSync 自動安裝到 <workspace>/.autorag/bin，你的嵌入模型 context window 是否需要調降 minSync.maxChunkSize，以及你的 PDF 是否會觸發 thinExtract 的 docling-fast 重試路徑。

官方來源

1. Issues
2. Marker-Inc-Korea/AutoRAG on GitHub
3. Project website
4. README
5. Releases