框架

LlamaIndex 全解析:從 RAG 函式庫到文件 Agent 平台

LlamaIndex 早已不只是「幫 LLM 讀文件」的套件——它把 RAG、Workflow、Agent 編排全部整合。本文從一行程式碼出發,帶你看架構設計,再分享實測踩坑經驗。

字級

GitHub 上 run-llama/llama_index 有 51,761 顆 Star,是 RAG 領域最熱門的專案之一。它最初定位是「幫 LLM 讀文件的函式庫」,但 2024 年之後官方把自己定位為 Document Agent and OCR platform——新增了 OCR、Workflow、AgentRunner 等功能,已經不再是單純的檢索框架了。

下面我會從一行程式碼、到架構、再到上手踩坑,把它徹底拆開來看。

它解決了什麼問題

LLM 有兩個明顯的短板:

  • 知識停留在訓練截止日,問 2024 年之後的事情就會胡說八道
  • 無法存取你的私有資料,合約、產品文件、內部 wiki 都看不到

LlamaIndex 的答案是:把「文件 → 切塊 → 建立索引 → 檢索 → 拼進 prompt」這條流程封裝成可複用的框架,你只負責餵資料和問問題。

核心受眾很明確:想做知識庫、FAQ bot、企業搜尋的工程師。在合規要求高的場景(法律合約、病歷、顧問報告)使用率特別高,因為可以本地部署。

怎麼使用

一行指令裝好就能跑:

pip install llama-index
export OPENAI_API_KEY=sk-...

最小可行範例:

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(llm=OpenAI(model="gpt-4o-mini"))
print(query_engine.query("文档里提到了哪些关键技术?"))

10 行程式碼,輸出真的是 LLM 呼叫結果,不是假的 demo 字串。SimpleDirectoryReader 是個被低估的設計——在一個資料夾裡放 PDF、Word、Markdown、圖片,它會自動辨識格式並呼叫對應的 Reader,不用自己寫 loader 邏輯。

進階用法:Workflow Agent(多步驟、帶工具)

from llama_index.core.agent.workflow import AgentWorkflow
import asyncio

workflow = AgentWorkflow.from_tools_or_functions(
    tools=[query_engine],
    llm=OpenAI(model="gpt-4o-mini"),
)

async def main():
    response = await workflow.run(user_msg="总结这三份 PDF 的共同主题")
    print(str(response))

asyncio.run(main())

注意:第二個範例裡的 AgentWorkflow 是 0.12.x 之後的 API,舊版本叫做 AgentRunner / ReActAgent。這是個坑,等等會提到。

它如何運作(架構)

三層抽象,越往下越接近原始資料,越往上越接近產品呼叫:

  1. Documents + Nodes:Document 是原始檔案,Node 是切塊後的 chunk(預設按 token 數切分,相鄰 chunk 之間會 overlap 以維持上下文連貫)
  2. Index:把 Node 灌進資料結構。VectorStoreIndex 是預設選擇(向量資料庫),也有 SummaryIndex(全文)、KeywordTableIndex(關鍵字)。VectorStoreIndex 不綁定特定向量庫,可以接入 Chroma、Qdrant、Weaviate、Pinecone、Milvus
  3. Retriever + QueryEngine:Retriever 負責從 Index 撈出相關 Node,QueryEngine 把 Node 組合成 prompt、呼叫 LLM、解析回傳結果。可以在這兩層之間插入 ResponseSynthesizer、NodePostprocessor(重排序、過濾)

2024 年新增的 Workflow 是關鍵升級。本質上是個 DAG 引擎,把多步驟流程(路由、子 Agent、迴圈、人工確認)寫成步驟鏈,每一步可以非同步、可以帶狀態。對標 LangGraph 的 StateGraph,但 API 更貼近 Python 慣用語法。

在程式碼層面,BaseIndex / BaseRetriever / BaseQueryEngine 都是抽象基底類別,要擴充就繼承這些類別,符合 llama-index「一切皆可插拔」的設計理念。

優缺點分析

優點:

  • Readers 生態真的齊全。Slack、Notion、Postgres、MongoDB、Discord、Google Drive、Confluence……100+ 官方 Reader,社群貢獻的更多。Loader 這塊 LlamaIndex 比 LangChain 做得更細緻
  • 文件品質第一梯隊。官方 tutorial、概念說明、API reference 都寫得清楚,範例都能跑通
  • TypeScript 版本同步維護。llamaindex(npm)跟 Python 版本功能大致對得上,前端專案可以直接使用
  • OCR 支援。新加入的 LlamaParse API 能解析複雜 PDF(表格、圖表、掃描件),準確率比開源 PDF 解析器高出不少

缺點:

  • API 變動頻繁。0.9.x 到 0.10.x 來了一次大改版,ServiceContext 消失了,OpenAIEmbedding 的匯入路徑也變了。0.11 到 0.12 又是另一波。我維護的專案每季都要 review 一次 deprecated warning
  • 抽象層比 LangChain 厚。想深度客製(例如換 retrieval 策略、改 prompt template)得讀源碼,理解 BaseQueryEngine 的內部流程
  • 中國模型支援要靠社群。通義、文心、ChatGLM、Kimi 都有第三方整合,但不像 OpenAI / Anthropic 那樣開箱即用
  • 依賴體積。完整安裝下來不小,pip install llama-index 預設會拉一堆 extras

適合:不想碰底層、一週要交出 demo 的團隊。

不適合:要做極簡自研、對依賴敏感的嵌入式場景;或已經在 LangChain 上深度客製過的專案。

實測心得

本地跑 LlamaIndex 0.12.x,環境是 M2 Mac、Python 3.11:

  • 資料:50 個 PDF,約 200 頁學術論文
  • 配置:VectorStoreIndex + Chroma(本地持久化)+ OpenAI text-embedding-3-small
  • 耗時:4 分 12 秒(含 PDF 解析和 embedding)
  • 問答:問了 10 個事實性問題,8 個答對,2 個出現幻覺(都是跨文件摘要類,例如「這些論文的共同方法論」)

同樣條件換成用 LangChain 自己寫,程式碼量大約是 2 倍,但幻覺率略低。我猜原因是 query 改寫做得比較細(多輪改寫 + HyDE)。

Workflow 跑了個多 Agent demo(一個負責摘要、一個負責驗證),啟動開銷 0.8 秒,比裸呼叫 OpenAI 多花 200ms,還可以接受。

OCR 路線用 LlamaParse 解析了 3 份含表格的財報 PDF,表格結構還原率明顯優於 pdfplumber。

誰該使用

適用情境:

  • 公司內部知識庫 / FAQ bot,一週內可上線
  • 法律、醫療、顧問產業的文件問答
  • 為現有產品加上「上傳檔案即可對話」功能

不適用情境:

  • 已經在用 LangChain 且深度客製過
  • 想要純本地、無外部 API 依賴——LlamaIndex 也支援,但得自己接 Ollama / vLLM
  • 只想做個簡單 demo,原生 OpenAI Assistants API 可能更快

如果對純本地有需求,可以參考官方的 local model 整合文件,接 Ollama 或 vLLM 都不複雜,只是要自己跑 embedding 模型。

總結

LlamaIndex 不是最輕量的框架,但生態完整度和文件品質確實能省下大量時間。它的代價是抽象層較厚、API 變化快。選型時想清楚一件事:你要的是「快速交差」還是「完全掌控」。前者選它,後者可能得自己動手。

來源: https://github.com/run-llama/llama_index