LlamaIndex

一句话定位

一个以”数据 / RAG”为中心的 Python 框架：把私有数据通过 reader→node_parser→index→retriever→query_engine 的管线接入 LLM，再把检索能力封装成 tool，由建立在自研 Workflow(事件驱动状态机) 之上的 FunctionAgent / ReActAgent / AgentWorkflow 驱动，做”会查资料、能多 agent handoff”的 agentic 应用。

设计理念 / 顶层架构

LlamaIndex 的内核取舍是 “data framework first, agent second”——它最强的不是 agent 循环，而是把任意数据变成可检索上下文的那条管线；agent 只是消费这套检索能力的上层。设计要点：

• 大型 monorepo + namespace 包：仓库分 llama-index-core(骨架)、llama-index-integrations(300+ 第三方 LLM/embedding/vector store 插件)、llama-index-instrumentation(可观测)、llama-index-utils。import 含 core 即用核心、不含即用集成包：from llama_index.core.llms import LLM vs from llama_index.llms.openai import OpenAI（README:29-43）。本笔记聚焦 llama-index-core。
• RAG 管线为一等公民：Document → NodeParser(切块) → Index(VectorStoreIndex 等) → Retriever → QueryEngine/ChatEngine。索引对象用 as_retriever() / as_query_engine() / as_chat_engine() 一键降级成不同消费形态（indices/base.py:489,491,518）。
• agent = Workflow 之上的状态机：2024 起新 agent 全部重写在自研 Workflow 引擎上。BaseWorkflowAgent 同时继承 Workflow + pydantic BaseModel（agent/workflow/base_agent.py:87），用 @step 装饰的方法 + Event 在步骤间流转构成 ReAct 式循环。注意 Workflow 引擎本身已外移到独立 workflows 包，core 只做 re-export（workflow/workflow.py:1、workflow/context.py:1）。
• 全局 Settings 单例：Settings.llm / Settings.embed_model / Settings.node_parser 惰性解析默认依赖，避免到处传 LLM（settings.py:18,34）。
• 检索即工具：RetrieverTool / QueryEngineTool 把”查知识库”封装成普通 tool 交给 agent，这是 LlamaIndex 把 RAG 与 agent 缝合的关键接口（tools/retriever_tool.py:26）。

最小示例（取自 README，RAG 主线）：

import os
os.environ["OPENAI_API_KEY"] = "YOUR_KEY"

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 1. 读数据 → 2. 建向量索引（自动切块+embedding）
documents = SimpleDirectoryReader("YOUR_DATA_DIRECTORY").load_data()
index = VectorStoreIndex.from_documents(documents)

# 3. 降级成 query engine 检索增强问答
query_engine = index.as_query_engine()
print(query_engine.query("YOUR_QUESTION"))

# 进阶：把检索封成 tool 交给 agent
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import QueryEngineTool

tool = QueryEngineTool.from_defaults(query_engine, name="docs", description="查内部文档")
agent = FunctionAgent(tools=[tool])   # llm 缺省取 Settings.llm
# response = await agent.run(user_msg="根据文档回答…")

组件实现（横向逐项）

设计权衡与特性

• RAG 深度是护城河：相比 ConnectOnion/Swarm 这类”agent 优先”框架，LlamaIndex 在数据接入、切块、索引(向量/树/关键词/property graph)、检索(fusion/auto-merging/recursive/router)、重排、RAG 评估上铺得极厚。要做”基于私有知识库的 agent”，它的电池最全。
• agent 重写在自研 Workflow 上：好处是 agent 与任意自定义 Workflow 同构、可组合、事件可观测、原生 async/流式；代价是概念栈更深(Event/step/Context/StartEvent/StopEvent)，且 Workflow 引擎已外移到 workflows 独立包，core 仅 re-export——读源码时真正的调度逻辑不在本仓库内（待确认其完整实现）。
• multi-agent = handoff 模型：AgentWorkflow 的多 agent 协作走 OpenAI Swarm 同款”handoff 工具切换当前 agent + 共享 memory/state”，按 can_handoff_to 白名单治理，属轻量编排；没有复杂的 supervisor/层级图(那类需求要自己用 Workflow 手写)。
• 三种 agent 互补：FunctionAgent(原生 function calling，主推)、ReActAgent(无 function calling 模型的文本 ReAct 协议+输出解析+错误重试)、CodeActAgent(写代码即行动)。from_tools_or_functions 据模型能力自动二选一。
• 集成生态庞大但分散：300+ integrations 各自独立版本/包，灵活但依赖与版本管理复杂；核心包(llama-index-core 0.14.x)与集成包需配套升级。
• 治理偏弱：HITL 靠 Workflow 事件可实现，但内核无工具审批、权限沙箱或危险操作拦截——工具默认在本进程直接执行，安全边界需调用方自建。
• 待确认：①Workflow 调度/并发/重试的真正实现在外部 workflows 包，本仓库只见 re-export；②AgentWorkflow 限制 initial_state 不支持 per-agent(multi_agent_workflow.py:136)。

关联

• component-taxonomy · multi-agent-orchestration · single-vs-multi-agent
• 同范式(rag / 数据中心)：llamaindex · 同为 handoff 多 agent：swarm · 源码：agents-example/llamaindex/