LlamaIndex 拆解:从 RAG 框架到文档 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。这是个坑,下面会说。
它怎么工作(架构)
三层抽象,越往下越接近原始数据,越往上越接近产品调用:
- Documents + Nodes:
Document是原始文件,Node是切分后的 chunk(默认按 token 数切,相邻 chunk 会有 overlap 保证上下文连贯) - Index:把 Node 灌进数据结构。
VectorStoreIndex是默认选择(向量库),也有SummaryIndex(全文)、KeywordTableIndex(关键字)。VectorStoreIndex不绑死某个向量库,可以塞 Chroma、Qdrant、Weaviate、Pinecone、Milvus - Retriever + QueryEngine:
Retriever负责从 Index 里捞相关 Node,QueryEngine把 Node 拼成 prompt、调 LLM、解析返回。可以在这两层之间塞ResponseSynthesizer、NodePostprocessor(重排序、过滤)
2024 年加进来的 Workflow 是关键升级。本质上是个 DAG 引擎,把多步流程(路由、子 Agent、循环、人工确认)写成步骤链,每步可以异步、可以带状态。对标 LangGraph 的 StateGraph,但 API 更 Pythonic。
代码层面,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 支持。新加的
LlamaParseAPI 能解析复杂 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 变化快。选型时想清楚一件事:你是要「快速出活」还是「完全掌控」。前者选它,后者可能得自己撸。