LlamaIndex 不只是 RAG：把私有資料接上 Agent 的實作框架

我觀察到很多團隊在導入 LLM 時，第一個原型往往很快：把使用者問題放進 prompt，再把模型回覆顯示出來。但只要問題涉及公司文件、產品規格、客服紀錄或資料庫，真正的工程工作才開始出現。資料要從哪裡讀進來？PDF 的版面如何保留？文件要怎麼切分？檢索結果如何排序？Agent 什麼時候該查資料，什麼時候該呼叫工具？

這也是我認為 LlamaIndex 值得被重新理解的原因。它不只是「做 RAG 的套件」，而是一個把外部資料接到 LLM 與 Agent 之間的資料框架。官方目前將 LlamaIndex OSS 定位為建立 agentic applications 的開源 framework；README 同時保留了它最核心的資料框架精神：連接資料、建立結構、檢索相關上下文，再交給應用程式或模型使用。

先講結論：LlamaIndex 解決的是資料上下文工程

如果你的問題只是「怎麼呼叫一次模型」，LlamaIndex 可能顯得太重。但如果你的應用需要持續處理私有資料，並且希望把資料來源、索引、Retriever、Query Engine 與 Agent 工作流程拆成可以測試與替換的元件，它就很有價值。

我會把它的價值濃縮成三層：

資料接入層：把 PDF、文件、網頁、API、SQL 等來源轉成應用程式可以處理的 Document 或 Node。
上下文組織層：透過切分、metadata、index、embedding、retriever 與 reranker，決定模型看到哪些資料。
推理與工作流程層：將檢索結果交給 query engine、chat engine、Agent 或 Workflow，形成可互動的應用。

這個分層很重要，因為 RAG 的失敗通常不只來自模型。資料沒有正確載入、切分邊界錯誤、metadata 遺失、檢索召回不準，最後都會被誤認為是「LLM 不夠聰明」。LlamaIndex 的好處，是讓這些環節有比較清楚的程式設計邊界。

從官方架構看懂它為什麼能擴充

LlamaIndex 的 Python 套件採取 core 加 integrations 的命名方式。llama-index-core 提供核心抽象；另外再依照應用選擇 LLM、embedding、向量儲存、資料載入器或其他整合套件。官方 README 提到，LlamaIndex 有超過 300 個 integration packages，這種設計的重點不是讓你一次安裝全部，而是把供應商與核心流程解耦。

例如，核心程式可以使用通用的 LLM 與 Retriever 介面，底層再替換成不同模型供應商或向量資料庫。這讓團隊在早期原型階段可以快速開始，到了正式環境也能針對成本、延遲、資料隔離或部署方式替換元件。

不過，抽象層不是免費的。當你遇到檢索品質問題時，必須知道目前使用的是哪個 integration、哪一個 embedding、哪種 index，以及資料在何處被切分與持久化。只會呼叫高階 API，卻不理解底層資料流，仍然很難除錯。

實作一：先做一個可驗證的文件問答

我建議不要一開始就做多 Agent。先建立一個最小但可驗證的文件問答流程，確認資料真的能被找回來。以下範例示範使用本地目錄建立索引，再對資料提出問題：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("這份文件的核心結論是什麼？")
print(response)

這段程式很短，但不代表正式系統只需要這幾行。第一次驗證時，我會特別檢查三件事：

./data 裡的文件是否真的被載入，而不是讀取失敗後得到空索引。
問題的答案是否能在來源文件中找到，並且沒有把模型自身的常識誤認為檢索結果。
文件更新後，索引是否需要重建、增量更新或清除舊版本。

若要在本地建立乾淨環境，可以先用 uv init 建立專案，再執行 uv add llama-index。接著把一兩份可公開測試的文件放進 data，執行程式，確認至少能完成「載入、建立索引、查詢、輸出」這四個步驟。這個驗證點比先接十個資料源更重要，因為它能把環境問題與檢索問題分開。

實作二：把資料來源與模型供應商拆開

真正進入團隊專案後，我不會把所有設定直接寫死在單一 Python 檔案。至少應該把資料載入、模型設定、索引建立與查詢介面分開。概念上可以整理成以下結構：

app/
  settings.py       # 模型、embedding、環境設定
  ingest.py         # 資料載入與切分
  index.py          # 索引建立與持久化
  query.py          # query engine 或 agent
  evaluation.py     # 測試問題與檢索評估
data/

這樣做的原因很實際。當模型供應商變更時，不應該重新改寫資料載入流程；當向量資料庫從本地儲存換成遠端服務時，也不應該影響前端的問答介面。LlamaIndex 的 core 與 integration 分離，正好可以支援這種邊界。

另一個要點是持久化。原型可以每次啟動都重建 index，但正式服務通常需要保存索引，並且記錄資料版本、embedding 模型版本、切分參數與建立時間。否則當答案改變時，你很難判斷是原始文件更新、索引更新，還是模型設定改變。

實作三：再把檢索能力交給 Agent

當文件問答穩定後，才適合把它包成 Agent 的工具。Agent 的價值不是把「查資料」包裝成一個更酷的名稱，而是讓系統能根據任務選擇工具、執行多步驟工作，並在需要時回到資料索引。

這裡要先分清楚三個層次：

Retriever 負責找出可能相關的資料。
Query Engine 或 Chat Engine 負責把查詢與上下文組合成回覆。
Agent 負責決定下一步要做什麼，例如查詢文件、呼叫 API 或執行另一個工具。

如果把三者混成一個黑盒，問題發生時就很難定位。我的做法是先為 Retriever 寫固定問題集，確認召回內容；再測試 Query Engine 的回答是否忠於上下文；最後才測試 Agent 的工具選擇與多步驟行為。

LlamaIndex 的 Workflow 也值得注意。對於需要多步驟、事件驅動或可重跑的 Agent 流程，Workflow 比把所有邏輯塞在一個巨大 prompt 裡更容易觀察與測試。你可以把「取得問題、查詢資料、整理上下文、產生答案、檢查結果」拆成不同步驟，讓每一步都有明確輸入與輸出。這種做法會增加一些程式碼，但換來的是更好的可維護性。

文件處理是成敗關鍵，不是附屬功能

很多 RAG 示範使用純文字檔，所以看起來檢索很簡單。企業資料卻可能包含表格、頁首頁尾、掃描影像、欄位、附件與版本標記。資料解析若在最前面就遺失結構，後面的 embedding 與生成再精準也救不回來。

LlamaIndex 生態除了 OSS framework，也在官方 README 中列出 LlamaParse 與相關文件代理能力。這些服務可以處理更複雜的文件解析、結構化擷取與索引流程，但它們是另外的雲端平台，不應該和開源核心混為一談。導入前要先確認資料是否能離開內網、API key 如何管理、費用如何估算，以及是否需要保留自建解析方案。

我的建議是先建立資料品質檢查表：文件是否完整、編碼是否正確、表格是否可讀、頁碼與來源 metadata 是否保留、同一文件的不同版本是否能辨識。這些檢查比調整 prompt 更接近 RAG 的根因。

LlamaIndex 的限制：它不會自動保證答案正確

第一個限制是檢索品質。框架可以提供組件，但無法替你決定最佳 chunk size、top k、metadata schema、embedding 模型或 reranking 策略。這些都需要用真實問題集評估。

第二個限制是成本與延遲。資料解析、embedding、向量搜尋、reranking 與 LLM 生成，每一層都可能產生費用或延遲。多步驟 Agent 會再增加工具呼叫次數。若只用「回答看起來合理」作為驗收標準，很容易忽略高峰流量與長文件造成的成本。

第三個限制是抽象層帶來的除錯負擔。當套件與 integration 很多時，版本相容性、API 變更、底層服務錯誤都需要被觀察。正式環境應該固定依賴版本，記錄檢索來源與延遲，並提供能重現問題的 trace。

第四個限制是安全。只要 Agent 能讀取私有資料或呼叫工具，就必須處理權限、資料範圍、提示注入、敏感資訊外洩與工具濫用。不能因為框架提供了 Agent 介面，就把所有文件與操作權限一次交給模型。

我會怎麼評估一個 LlamaIndex 專案

在我看來，評估重點不是「能不能在五行程式碼中跑起來」，而是以下五個問題：

資料能否被正確表示？ 來源、版本、權限與 metadata 是否完整。
檢索能否被量化？ 是否有一組真實問題，能測試召回率、排序與引用正確性。
元件能否替換？ LLM、embedding、向量儲存與解析器是否被清楚隔離。
流程能否觀察？ 能否知道 Agent 為什麼選工具、取了哪些上下文、花了多少時間與成本。
失敗是否可控？ 找不到資料、模型超時、外部 API 失敗或權限不足時，系統是否會安全降級。

這五題若答不出來，就算 demo 很漂亮，我也不會直接把它推進正式環境。

哪些團隊適合先試？

我會推薦以下團隊優先評估：已經有文件問答或知識庫需求、希望用 Python 建立 LLM 應用、需要連接多種資料來源，或預期未來會從單純 RAG 擴展到工具使用與 Agent workflow 的團隊。

相反地，如果需求只是一次性文字摘要、固定模板生成，或團隊沒有能力維護資料管線與評估集，直接引入完整框架可能會增加複雜度。這時候一個輕量的 API 呼叫加上明確的資料處理程式，反而更容易維護。

結語：先把資料流做好，再談 Agent

我對 LlamaIndex 的看法是：它真正的價值不在於替你包裝一個聊天視窗，而在於提供一組可組合的資料與推理元件，讓私有資料能比較有秩序地進入 LLM 應用。

最務實的導入順序是：先用少量文件驗證載入與檢索，再把模型、embedding、index 與儲存邊界拆清楚，接著建立評估問題集，最後才加入 Agent 與 Workflow。這個順序可能沒有「一天做出全自動 Agent」那麼吸睛，但比較能留下可維護、可觀察、可治理的系統。

如果你正在做企業知識庫、文件 Agent 或需要私有資料上下文的 AI 應用，LlamaIndex 值得放進候選清單。不過請把它當成資料上下文工程的基礎設施，而不是正確答案的保證器。

參考資料