LlamaIndex — 文档 Agent 与 RAG 框架

GitHub: run-llama/llama_index
Stars: 50,100+ | Language: Python (72.2%), Jupyter Notebook (25.2%) | License: MIT
官网: llamaindex.ai

项目速览

LlamaIndex（前身 GPT Index）是由 Jerry Liu 于 2022 年底创建的开源数据框架，定位为 “The leading document agent and OCR platform”。截至 2026 年 6 月，项目在 GitHub 上已获得超过 50,100 颗 Star，拥有 7,600+ Fork 和 490+ Release，是 RAG（检索增强生成）领域最活跃的项目之一。

LlamaIndex 的核心理念是构建 LLM 与外部数据之间的桥梁。它提供了一套完整的”数据摄取—索引—查询”管道，让 LLM 能够高效地访问、理解和推理私有数据。2025 年，LlamaIndex 从纯 RAG 框架进化为文档 Agent 平台，推出了 Agentic Document Workflows（ADW）、LlamaAgents（一键部署文档 Agent）、Workflows 1.0（轻量级 Agent 编排）和 LlamaParse v2（智能文档解析）等一系列重量级产品。

LlamaIndex 已从早期的单一 Python 库发展为包含 LlamaCloud（云端托管服务）、LlamaParse（文档解析引擎）和 LlamaAgents（Agent 部署平台）的完整生态系统，在文档智能处理领域建立了牢固的领先地位。

功能概述

Agentic Document Workflows — 智能文档处理架构

ADW 是 LlamaIndex 2025 年推出的核心架构，将传统 RAG 与 Agent 推理相结合。系统由 Document Agent 统一编排，执行以下流程：解析复杂文档结构（通过 LlamaParse）→ 提取关键信息 → 维护处理状态 → 检索相关知识库 → 依据业务规则生成决策建议。

以合同审核场景为例：Agent 解析合同条款结构，识别关键条款（责任、赔偿、终止等），交叉引用法规知识库，标记合规性问题，并推荐需要人工审查的重点区域。LlamaIndex 报告称，使用 ADW 后文档处理的直通率可达 90%+，而传统 OCR 系统仅能达 60-70%。

LlamaParse v2 — 智能文档解析引擎

LlamaParse 是 LlamaIndex 旗下的文档解析服务，2025 年发布的 v2 版本重新设计了整体架构，提供四个解析层级：

Fast：适用于简单 PDF 的快速文本提取
Cost Effective：平衡成本与准确度，适合大批量文档
Agentic：利用 LLM Agent 理解文档结构，支持复杂表格和图表
Agentic Plus：最高精度，支持多模态推理（图像+文本），成本比 v1 降低 50%

LlamaParse 能够将 PDF、Word、Excel、PPT、图片等多种格式的文档转换为 LLM 可理解的结构化 Markdown，自动识别标题层级、表格、列表和图像。

Workflows 1.0 — 轻量级 Agent 编排

Workflows 1.0 是 LlamaIndex 推出的独立 Agent 编排框架（Python 和 TypeScript 双语言支持），采用事件驱动、异步优先（async-first）的架构：

类型化状态（Typed State）：跨步骤的端到端类型安全
事件驱动通信：步骤之间通过事件传递消息，天然支持并行执行和扇出（fan-out）
资源注入（Resource Injection）：在运行时动态注入数据库客户端、LLM 等依赖
Human-in-the-Loop：内置审批/审查步骤，支持在最终输出前插入人工判断
OpenTelemetry 可观测性：原生支持分布式追踪

LlamaAgents — 一键部署文档 Agent

LlamaAgents 允许开发者通过 llamactl CLI 工具快速初始化和部署文档 Agent。内置预置模板包括：SEC 财报分析、发票处理、合同审核、保险理赔等。部署流程极其简洁：

llamactl init my-agent --template sec-insights
llamactl serve my-agent
llamactl deploy create my-agent

Agent 可以作为独立服务运行，对外暴露 REST API，便于集成到现有业务系统中。

MCP 与 A2A 集成

2025 年，LlamaIndex 添加了原生 MCP（Model Context Protocol）支持和 A2A（Agent-to-Agent）连接能力。文档 MCP Server 可以将文件查找、语义检索、结构化查询和文件操作暴露为标准工具，供任何支持 MCP 的 Agent 框架调用。这意味着在 LangChain 或 CrewAI 中构建的 Agent 也可以直接使用 LlamaIndex 的文档处理能力。

适用场景

企业文档智能审核

对于法律、金融、保险等需要处理大量文档的行业，LlamaIndex 的 ADW 架构可以自动化合同审核、合规检查、风险评估等流程。Document Agent 按业务规则逐项检查文档，标记异常并生成审核报告，大幅减少人工审查工作量。

知识库问答系统

LlamaIndex 提供完整的 RAG 管道：从多种数据源加载文档、智能分割、向量化索引，到混合检索（向量 + 关键词）、重排序（Reranker）和上下文压缩。相比 LangChain，LlamaIndex 的索引结构（如树索引、关键词表索引）更丰富，检索精度在文档密集型场景下更有优势。

多模态信息提取

结合 LlamaParse 的 Agentic Plus 模式，可以从包含图片、表格和文本的混合文档中提取结构化信息。例如，从产品手册中提取规格参数、从财务报告中提取数据表格、从技术文档中提取 API 定义等。

研究与竞争情报分析

LlamaIndex 的 Document Research Assistant 模式可以自动化研究流程：Outline Agent 规划大纲、Question Generator 生成关键问题、RAG Query Agent 逐一检索回答、Blog Writer 整合成报告、Critic Agent 审核并提出修改建议。

客服知识助手

将产品文档、FAQ、技术手册等数据索引入 LlamaIndex，构建智能客服知识库。Agent 可以根据用户问题自动检索相关文档段落并生成准确答案，同时标注信息来源以增强可信度。

快速上手

环境要求

Python 3.9+
OpenAI API Key（或其他 LLM 提供商）

安装

pip install llama-index llama-index-llms-openai llama-index-embeddings-openai

如需使用 LlamaParse：

pip install llama-parse

最简示例：文档问答

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 加载 data/ 目录下的所有文档
documents = SimpleDirectoryReader("data").load_data()

# 创建向量索引
index = VectorStoreIndex.from_documents(documents)

# 创建查询引擎
query_engine = index.as_query_engine()

# 提问
response = query_engine.query("这份文档的主要内容是什么？")
print(response)

源码架构

LlamaIndex 采用模块化的 monorepo 结构：

llama_index/
├── llama-index-core/              # 核心库
│   ├── indices/                   #   索引结构（向量索引、树索引、关键词表索引等）
│   ├── query_engine/              #   查询引擎（检索 + 合成）
│   ├── retrievers/                #   检索器抽象
│   ├── node_parser/               #   文档分割与节点解析
│   ├── callbacks/                 #   回调与事件系统
│   ├── agent/                     #   Agent 抽象与 ReAct Agent
│   ├── tools/                     #   工具系统
│   └── workflows/                 #   Workflows 1.0 编排引擎
├── llama-index-integrations/      # 集成生态
│   ├── llms/                      #   LLM 集成（OpenAI, Anthropic, Gemini 等）
│   ├── embeddings/                #   嵌入模型集成
│   ├── vector_stores/             #   向量数据库集成
│   ├── readers/                   #   数据加载器
│   └── postprocessor/             #   后处理器（重排序等）
├── llama-index-utils/             # 工具包
├── llama-dev/                     # 开发工具和脚本
├── docs/                          # 文档站点源码
└── scripts/                       # CI/CD 脚本

llama-index-core：框架的核心，包含索引结构、查询引擎、检索器、Agent 抽象和 Workflows 引擎。所有其他包都依赖此包。
llama-index-integrations：集成生态的 monorepo，组织为多个子包，涵盖 LLM、嵌入模型、向量数据库、数据加载器等。
工作流引擎：Workflows 1.0 是核心的新增模块，提供类型化状态、事件驱动通信和 Human-in-the-Loop 等 Agent 编排能力。

实操 Demo

下面是一个完整的文档问答系统 Demo，展示从文档加载到智能问答的全流程。

"""
完整的企业文档问答系统 Demo
功能：加载 PDF 文档 → 解析与分割 → 向量索引 → 混合检索 → 带引用的问答
"""

from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    Settings,
    StorageContext,
    load_index_from_storage,
)
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.postprocessor import SentenceTransformerRerank
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
import os

# ===================== 配置 =====================
os.environ["OPENAI_API_KEY"] = "sk-..."  # 替换为你的 API Key

# 全局设置 LLM 和嵌入模型
Settings.llm = OpenAI(model="gpt-4o", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

# ===================== 1. 加载文档 =====================
print("[1/4] 正在加载文档...")
# 将你的 PDF、Word、TXT 等文档放入 ./documents 目录
documents = SimpleDirectoryReader(
    input_dir="./documents",
    recursive=True,
    required_exts=[".pdf", ".txt", ".md", ".docx"]
).load_data()
print(f"  加载了 {len(documents)} 个文档")

# ===================== 2. 文档分割 =====================
print("[2/4] 正在分割文档...")
node_parser = SentenceSplitter(
    chunk_size=512,        # 每块 512 token
    chunk_overlap=50,      # 重叠 50 token
    separator=" ",
    paragraph_separator="\n\n",
)
nodes = node_parser.get_nodes_from_documents(documents)
print(f"  分割为 {len(nodes)} 个节点")

# ===================== 3. 构建向量索引 =====================
print("[3/4] 正在构建向量索引...")

# 尝试从磁盘加载已有索引，不存在则新建
PERSIST_DIR = "./storage"
if os.path.exists(PERSIST_DIR):
    storage_context = StorageContext.from_defaults(persist_dir=PERSIST_DIR)
    index = load_index_from_storage(storage_context)
    print("  从磁盘加载了已有索引")
else:
    index = VectorStoreIndex(nodes, show_progress=True)
    index.storage_context.persist(persist_dir=PERSIST_DIR)
    print(f"  索引已构建并持久化到 {PERSIST_DIR}")

# ===================== 4. 混合检索 + 重排序 =====================
print("[4/4] 正在配置查询引擎...")

# 配置检索器：检索 top-20 候选文档
retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=20,
)

# 配置重排序器：将 20 个候选压缩为 top-5 最相关
reranker = SentenceTransformerRerank(
    model="BAAI/bge-reranker-base",
    top_n=5,
)

# 组装查询引擎
query_engine = RetrieverQueryEngine(
    retriever=retriever,
    node_postprocessors=[reranker],
    response_mode="compact",  # 将检索结果压缩后一次性传给 LLM
)

# ===================== 5. 交互式问答 =====================
print("\n" + "="*50)
print("  文档问答系统已就绪，输入你的问题")
print("  输入 'quit' 退出")
print("="*50 + "\n")

questions = [
    "这份文档的核心主题是什么？请总结要点。",
    "文档中提到了哪些关键数据或指标？",
    "根据文档，主要的风险或挑战有哪些？",
]

for i, question in enumerate(questions, 1):
    print(f"[问题 {i}] {question}")
    response = query_engine.query(question)
    print(f"[答案] {response}\n")

    # 展示引用来源
    print("  [引用来源]")
    for j, source_node in enumerate(response.source_nodes):
        score = source_node.score if source_node.score else "N/A"
        file_name = source_node.metadata.get("file_name", "unknown")
        print(f"    {j+1}. [{file_name}] (相似度: {score:.4f})")
        # 展示来源文本的前 100 个字符
        snippet = source_node.text[:100].replace("\n", " ")
        print(f"       摘要: {snippet}...")
    print()

print("Demo 运行完毕！")

运行前准备：

# 安装依赖
pip install llama-index llama-index-llms-openai llama-index-embeddings-openai \
            llama-index-postprocessor-flag-embedding-reranker \
            sentence-transformers

# 创建文档目录并放入测试文件
mkdir -p documents
echo "LlamaIndex 是一个用于构建 RAG 应用的强大框架..." > documents/intro.txt

# 运行
python rag_demo.py

特性	LlamaIndex	LangChain	Dify
定位	文档 Agent 和 RAG 平台	通用 Agent 工程平台	低代码 Agent 应用平台
Stars	50,100+	139,000+	145,000+
核心优势	文档解析（LlamaParse）与索引结构业界领先	Agent 编排（LangGraph）生态最丰富	可视化工作流 + 一键部署，非开发者友好
RAG 能力	原生顶级支持：树索引、关键词表、混合检索、重排序、上下文压缩	通过链组合实现，生态丰富但索引结构不如 LlamaIndex 专用	内置 RAG 引擎，可视化配置，开箱即用
Agent 模式	ADW + Workflows 1.0 + LlamaAgents	create_agent + LangGraph + Middleware	可视化 Agent 节点 + ReAct/Function Calling 策略
适用场景	文档密集型 RAG、智能文档处理、知识库问答	需要复杂编排的通用 Agent 应用	需要快速搭建和部署的团队协作场景
学习曲线	中等：RAG 概念直观，高级功能（Workflows）需要学习	中等：概念较多，但 1.0 API 已大幅简化	低：拖拽式操作，可视化界面

参考资源

官方文档: https://docs.llamaindex.ai/
GitHub 仓库: https://github.com/run-llama/llama_index
LlamaCloud: https://cloud.llamaindex.ai/
LlamaParse: https://docs.cloud.llamaindex.ai/llamaparse/
Workflows 1.0 博客: https://www.llamaindex.ai/blog/announcing-workflows-1-0
Agentic Document Workflows: https://www.llamaindex.ai/blog/introducing-agentic-document-workflows
Discord 社区: https://discord.gg/llamaindex