LlamaIndex：概述与安装

发表于 | 更新于 | 分类于 ， | 阅读 次
LlamaIndex 知识层概述：与 LangChain/LangGraph 的三层分工、包拆分与安装、Document→QueryEngine 最小示例、FunctionAgent 把检索当工具，以及推荐阅读顺序。

你已经能用 LangChain 把模型、消息、工具拼成管道，也能用 LangGraph 画带环的状态图。还缺一块：私有文档怎么变成可检索、可引用的上下文。手写会变成：PDF 解析、切块、向量库、混合检索、重排、引用回填各写一套。LlamaIndex 把这条「数据 → 索引 → 召回 → 合成」收成一等公民抽象。

段末注释：LlamaIndex 在本教程系列中指 Python 包生态（llama-index-core 及各类 llama-index-* 集成包），侧重知识层；消息 / 模型 / LCEL 见 LangChain，环与检查点见 LangGraph。三者可叠用，不是三选一。

下文配图均为科普示意，非官方架构图。

三层栈：LangGraph 编排、LangChain 能力、LlamaIndex 知识（科普示意）

1. 一句话定位

维度 内容
角色 LLM 应用的知识层：解析、切块、索引、召回、合成、把 QueryEngine 当 Agent 工具
输入 → 输出 常见为 Document / query: str → Response（含 source_nodes）
典型入口 VectorStoreIndex.from_documents()、as_query_engine().query()、FunctionAgent.run()
与 LangChain / LangGraph 检索质量走本层；ChatModel 胶水仍可用 LangChain；环、checkpoint、HITL 交给 LangGraph

出现背景：LlamaIndex 约 2022 年起把「把私有数据接到 LLM」做成产品，早期叫 GPT Index；2024 年起补 Workflows（事件驱动编排）和 FunctionAgent / AgentWorkflow。本系列示例按 0.14.x + 拆分包 写法。

2. LlamaIndex 在 Agent 栈中的位置

1
2
3
4
5
6
7
8
9
用户 / API
    ↓
LangGraph（可选）—— 图编排、checkpoint、interrupt
    ↓
LangChain（可选）—— ChatModel、Prompt、Tool、LCEL
    ↓
LlamaIndex —— Document / Node、Index、Retriever、QueryEngine
    ↓
向量库 / 解析器 / 本地推理 —— Qdrant、LlamaParse、Ollama…
层级 解决的问题 本目录是否专讲
Agent 通用概念（ReAct、选型） 为什么要工具、怎么评估 见 02.开发-16.Agent开发/
LangChain 怎么调模型、怎么绑工具、怎么串链 见 02.开发-16.Agent-langchain/
LangGraph 多步失败重试、会话恢复、人工审批 见 02.开发-16.Agent-Langgraph/
RAG 业务架构 切分策略、召回评测、忠实度口径 见 02.开发-15.RAG/
LlamaIndex 上述 RAG 步骤用哪套 API 落地 是

生产常见组合：LlamaIndex 管 ingest / index / retrieve / synthesize；LangGraph 管工具环、失败重试、HITL、会话恢复；LangChain 在图节点内当 ChatModel / Tool 胶水（也可全程用 LlamaIndex 自己的 LLM 封装）。

3. 包拆分地图（安装前必读）

LlamaIndex 是多包 monorepo，按需安装，不必一次装全站。

PyPI 包 职责 是否几乎必装
llama-index-core Document、Index、Retriever、QueryEngine、Agent、Workflow 抽象 是
llama-index 入门伞包：core + 一组 OpenAI 等默认集成 入门可选；本系列不依赖它
llama-index-llms-ollama 本地 Ollama 生成模型 本系列默认
llama-index-embeddings-ollama 本地 Ollama 嵌入 本系列默认
llama-index-llms-openai / llama-index-embeddings-openai 云端 OpenAI 按模型选
llama-index-vector-stores-* Qdrant / Milvus / pgvector 等 生产按需
llama-index-readers-* / LlamaHub 数据连接器 按数据源
llama-parse 复杂 PDF 版面解析 扫描件 / 双栏论文按需
llama-index-workflows Workflows 独立包；core 仍从 llama_index.core.workflow 再导出 编排专篇按需

官方文档常默认 OpenAI。未显式设置 Settings.embed_model / Settings.llm 时会打 OpenAI，与「本机已装 Ollama」无关。

4. 环境与安装

4.1 要求

  • Python 3.10+
  • 推荐虚拟环境：venv / conda / uv
  • 本系列默认本地 Ollama：先 ollama serve，再 pull 生成模型与嵌入模型

版本锚点（检索于 2026-08-20 PyPI）：

包 当时最新稳定版 备注
llama-index 0.14.23 伞包；依赖 llama-index-core>=0.14.23,<0.15
llama-index-core 0.14.23 知识层抽象
llama-index-workflows 独立包，core 再导出 Event 驱动编排

安装仍用 pip install -U ...；专篇若行为依赖小版本，在该篇标明「验证于 x.x.x」。

4.2 最小安装（Ollama 示例）

1
2
3
4
5
6
7
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -U llama-index-core llama-index-llms-ollama llama-index-embeddings-ollama

ollama pull qwen3.5:9b
ollama pull nomic-embed-text

云厂商示例：

1
2
pip install -U llama-index-llms-openai llama-index-embeddings-openai
export OPENAI_API_KEY="sk-..."   # 勿提交到 Git

4.3 验证安装

1
python -c "from importlib.metadata import version; print('ok', version('llama-index-core'))"

无报错即基础环境可用。

4.4 常见安装问题

现象 处理
ModuleNotFoundError: llama_index.llms.ollama 未装集成包：pip install llama-index-llms-ollama
本地模型却请求 OpenAI 未设 Settings.llm / Settings.embed_model
ServiceContext 找不到 0.10 后改为全局 Settings；对照官方 Settings
GPTSimpleVectorIndex 2023 旧 API；改用 VectorStoreIndex

5. 核心抽象（读专篇前的最小概念）

LlamaIndex 的主轴不是「消息列表」，而是 Document → Node → Index → Retriever →（Postprocessor）→ Response Synthesizer。

对象 做什么 接近谁
Document 一份原始来源（PDF、网页、API 结果） LangChain Document
Node 带 metadata / 父子关系的可索引块 切分后的 chunk，多了关系字段
Index（如 VectorStoreIndex） 为 Node 建可查询结构 LangChain VectorStore + 检索策略
Retriever 给定 query 返回相关 Node LangChain BaseRetriever
NodePostprocessor 重排、过滤、压缩 compressor / reranker
QueryEngine 检索 + 合成，一次问答 LCEL：retriever | prompt | model
ChatEngine 带历史的多轮数据对话 新项目优先 LangGraph checkpoint
FunctionAgent 把函数 / QueryEngine 当工具循环调用 LangChain create_agent
Workflow（@step + Event） 事件驱动多步编排 LangGraph 的近邻，不是同一模型
AgentWorkflow 多 Agent 交接 LangGraph Subgraph / handoff

Document 到 QueryEngine 的六站流水线（科普示意）

一次 Naive RAG 的数据流：

1
2
3
4
5
6
7
1. Reader 把文件变成 Document
2. NodeParser 切成 Node（chunk_size / overlap / metadata）
3. Embedding 写入 VectorStoreIndex
4. query 被编码，Retriever 取 top-k NodeWithScore
5. 可选 Postprocessor（rerank / 元数据过滤）
6. ResponseSynthesizer 把 Node + 问题交给 LLM
7. 返回 Response；引用看 response.source_nodes

段末注释：检索增强生成（retrieval-augmented generation，RAG）= 先检索相关片段，再让模型基于片段生成。QueryEngine 默认是这条 DAG；工具失败再检索、审批后再发信，要上 Agent 或 LangGraph。

6. LlamaIndex Workflows vs LangGraph

两边都叫「workflow」，运行时模型不同：

LangGraph LlamaIndex Workflows
调度单位 节点读写共享 State，边决定下一拍 @step 消费 / 发出类型化 Event
状态 TypedDict + reducer，编译期契约 Context；默认 run 之间无记忆，要显式传入
持久化 checkpointer + thread_id 一等公民 有 durable/checkpoint，文档与生态厚度弱于 LangGraph
HITL interrupt / Command(resume=...) wait_for_event 能做、不是默认心智
擅长 有环 Agent、审批、可恢复长任务 RAG 多步 DAG（改写 → 多路召回 → 重排 → 合成）

选型：流程形状是「知识管道」→ LlamaIndex；是「状态机 + 环」→ LangGraph。 不必在 LlamaIndex 里再造一套 Pregel。

7. 最小可运行示例

先 ollama serve，并已 ollama pull qwen3.5:9b 与 nomic-embed-text。把待问文档放进 ./data/。

7.1 知识层：QueryEngine

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

# 关键参数：必须同时关掉默认 OpenAI
Settings.llm = Ollama(model="qwen3.5:9b", request_timeout=120.0, temperature=0)
Settings.embed_model = OllamaEmbedding(
    model_name="nomic-embed-text",
    base_url="http://localhost:11434",
)

# 输入：./data 下的文本 / PDF
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
qe = index.as_query_engine(similarity_top_k=5)

# 输出：Response；引用在 source_nodes
resp = qe.query("这篇文献的实验对象是什么物种？")
print(resp)
for n in resp.source_nodes:
    print(n.node_id, n.score, n.metadata)

预期形态：答案句含物种名（措辞会变）；至少打印若干 node_id / score / metadata。生产异步服务用 await qe.aquery(...)。

要点：

  • Settings 是进程级默认；也可在 from_documents(embed_model=...)、as_query_engine(llm=...) 局部覆盖。
  • query() 一次走完检索 + 生成；审计看 source_nodes，不要只信 str(resp)。
  • 避免每次启动全量重建：
1
2
3
4
index.storage_context.persist("storage")
# 下次：
from llama_index.core import StorageContext, load_index_from_storage
index = load_index_from_storage(StorageContext.from_defaults(persist_dir="storage"))

7.2 Agent：QueryEngine 当工具

有 native function calling 的模型优先 FunctionAgent；无工具调用的模型用 ReActAgent。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import QueryEngineTool

search = QueryEngineTool.from_defaults(
    query_engine=qe,
    name="paper_search",
    description="检索本地论文，回答方法、剂量、物种等事实问题。",
)

agent = FunctionAgent(
    tools=[search],
    llm=Settings.llm,
    system_prompt="只根据检索结果回答；没有证据就说不知道。",
)

async def main():
    # 输入：自然语言任务；输出：Agent 终态文本
    print(await agent.run("实验对象是什么物种？"))

asyncio.run(main())

多轮要显式传 Context，默认两次 run 之间无记忆。多角色交接用 AgentWorkflow。有环、审批、进程重启续跑时，把同一个 QueryEngine 包成工具交给 LangGraph 节点，不要在 QueryEngine 上硬撑。

重要配置参数（入门）

参数（API 名） 类型 / 默认值 功能说明 作用与影响 参考起点 / 常用范围 配置指导
Settings.llm LLM 实例 / 默认 OpenAI 全局生成模型；QueryEngine / Agent 未局部指定时使用 未设则打云端 API；设错模型则工具调用失败 Ollama(model="qwen3.5:9b") 本系列必设；与 embed 成对出现
Settings.embed_model Embedding 实例 / 默认 OpenAI 切块入库与 query 编码 未设则本地 LLM 仍会请求 OpenAI embedding OllamaEmbedding(model_name="nomic-embed-text") 与生成模型分开 pull
Settings.chunk_size int / 1024 NodeParser 默认块长（token 量级） 过大混入噪声，过小切断方法句 256～1024 方法节、表格宜偏小并加 overlap
Settings.chunk_overlap int / 20 相邻 Node 重叠 过小丢跨段指代，过大重复占上下文 20～128 与 chunk_size 联动，约 10%～20%
similarity_top_k int / 2 as_query_engine / as_retriever 召回条数 过小漏证据，过大稀释注意力与费用 5～10（入门） 后面有 rerank 可先放大再截断
response_mode str / "compact" 合成器如何把多 Node 喂给 LLM compact 拼上下文；refine 逐段迭代更稳也更贵；tree_summarize 适合长汇总 compact / refine / tree_summarize 单事实用 compact；综述用 tree_summarize
Ollama.request_timeout float / 30 单次生成 HTTP 超时秒数 过短误杀本地慢模型 60～180 长上下文加大
FunctionAgent.system_prompt str Agent 角色与引用约束 不写「无证据则拒答」时易把工具噪声写成事实 短系统提示 + 工具 description 工具 description 决定会不会被选中

8. 推荐阅读顺序

配合 LlamaIndex-00.知识点索引 使用。

阶段 专篇主题 你会获得什么
1 Document、Node、Reader 会把文件变成带 metadata 的块
2 NodeParser、IngestionPipeline 会切分、会增量入库
3 VectorStoreIndex 与 persist 会建索引、会避免全量重建
3b PropertyGraphIndex 会抽边、会沿 hop 回填原文
4 Retriever、hybrid、Router 会多路召回与分流
5 QueryEngine、ResponseSynthesizer、source_nodes 会问答且能审计引用
6 NodePostprocessor / Rerank 会压噪声
7 FunctionAgent + QueryEngineTool 检索成为工具
8 Workflows RAG 多步 DAG 的事件编排
9+ 作为 LangGraph 节点 环、checkpoint、HITL

若完全没接触过 RAG 评测口径，并行阅读 02.开发-15.RAG/ 的阶段概述（方法层，非本目录 API）。

9. 何时只用 LlamaIndex、何时上 LangGraph

场景 建议
单库文档问答、要引用 只 LlamaIndex QueryEngine
多索引路由（论文 vs SOP vs SQL） LlamaIndex RouterRetriever / RouterQueryEngine
改写 + 混合检索 + 重排的 DAG IngestionPipeline + Retriever + Postprocessor；复杂再上 Workflows
工具失败重试、多步规划 LangGraph；检索节点里调 LlamaIndex
进程重启续跑、发信前审批 LangGraph checkpointer + interrupt
线性 prompt | model、无私有库 只 LangChain，不必上 LlamaIndex

10. 调试与观测（入门）

手段 用法
打印 source_nodes node_id、score、metadata、text 前 200 字
Settings.callback_manager Token 计数、事件回调
向量库自检 建完索引用同一句 query 看 top-k 是否含金标准段
OpenTelemetry / Phoenix 可选 llama-index-instrumentation；LangGraph 侧仍用 LangSmith

11. 易踩坑

  1. 未设 Settings.embed_model：生成走 Ollama，嵌入仍打 OpenAI。
  2. 只 print(str(response))：丢掉引用，无法审计幻觉。
  3. 每次启动 from_documents 全量重建：应用 persist 或外部向量库。
  4. 用 QueryEngine 硬撑多步工具环 / HITL：控制流交给 LangGraph。
  5. 照抄 2023 import：GPTSimpleVectorIndex、ServiceContext 已失效。
  6. 把 FunctionAgent 的 Context 当成生产 checkpointer：进程退出即失；要持久化用 LangGraph Saver。

小结

  • LlamaIndex 提供 Document / Node / Index / Retriever / QueryEngine，是 Agent 应用的知识层。
  • 安装按包拆分：llama-index-core + LLM/Embedding 集成包；Python 3.10+；本系列默认 Ollama。
  • 先跑通 Reader → VectorStoreIndex → query + source_nodes，再把 QueryEngine 包成 FunctionAgent 工具。
  • 出现环、持久化、审批时，检索仍用本层，编排转到 LangGraph。

参考链接

-------------本文结束感谢您的阅读-------------