llamaindex

LlamaIndex 专家技能

LlamaIndex 是一个采用 MIT 许可证的 Python 框架，用于基于你的数据构建大模型应用。到 2026 年，它已从 RAG 索引库发展为事件驱动型工作流框架，并集成了生产运行时（llama-deploy）、Agent 编排（AgentWorkflow）、知识图谱构建（PropertyGraphIndex）和原生支持 OpenTelemetry 的可观测性。

该框架围绕七个核心原语构建：Reader（数据加载器）、Document/Node（分块内容模型）、Index（基于 Node 的数据结构）、Retriever（相关 Node 选择器）、Query Engine（检索器 + 合成）、Agent（带工具的大模型）和 Workflow（事件驱动编排）。

核心原则

在使用 LlamaIndex 构建时，每个决策都应遵循这些原则。请先阅读，再查看参考指南。

1. 将检索分块与合成分块解耦。 适合检索的嵌入表示与适合生成的上下文表示并不相同。使用 SentenceWindowNodeParser + MetadataReplacementNodePostProcessor 实现这种模式。
2. 先重排，再生成。 混合检索 + 重排器是生产级 RAG 的最低可行配置。
3. Agent 就是工作流。 FunctionAgent 和 AgentWorkflow 是预配置的工作流。需要自定义控制流时，可直接使用原始 Workflow。
4. 图不只是向量存储。 PropertyGraphIndex 增加了向量相似度无法提供的结构化路径遍历能力——结合两者可获得最高的检索质量。
5. 在同一进程中评估。 附加到 Span 的评估可保留输出与生成该输出的检索上下文之间的关联。

从哪里开始

该流水线从 Ingest 到 Deploy 共分为 9 个阶段。如果你加入时已有正在进行的工作，请找到合适的切入点：

你已有……	从哪个阶段开始	要做什么
什么都没有——空项目	Ingest	设置数据加载，然后按完整流水线逐步推进
某个目录中的文档	Chunk	选择分块策略，构建索引
可用的向量索引	Retrieve	添加混合搜索、重排和元数据过滤器
需要加固的现有 RAG 流水线	Deploy	添加可观测性、llama-deploy 和生产环境调试
需要衡量并提升质量	Evaluate	设置评估器、ParamTuner 和附加到 Span 的评分
什么都没有——正在比较框架	查看 Framework Routing Guide	不要启动流水线——先选对工具

流水线模式

不同任务需要不同程度的严谨性。请根据任务范围选择模式：

模式	适用场景	要运行的阶段	跳过
Quick	单次查询、单个来源、探索	Ingest → Chunk → Index → Retrieve	重排、元数据过滤器、可观测性、评估
Full	生产级 RAG、多个来源、合规性	Ingest → Chunk → Index → Retrieve → Agent/Workflow → Deploy → Evaluate	不跳过——运行所有阶段
Evaluate	基准测试、回归测试	Ingest → Chunk → Index → Evaluate	Retrieve、Agent、Workflow、Deploy（离线运行）
Graph	构建知识图谱	Ingest → Chunk → Graph → Retrieve	Agent、Workflow、Deploy（直接通过图索引查询）

经验法则：如果要交付给用户，请运行 Full 模式；如果正在探索，请运行 Quick；如果正在衡量，请运行 Evaluate。

快速参考

阶段	任务	方法	参考
摄取	加载数据	SimpleDirectoryReader("./data").load_data()	references/architecture.md
分块	将文档解析为节点	SentenceSplitter(chunk_size=1024)	references/rag-strategies.md
索引	构建向量索引	VectorStoreIndex.from_documents(docs)	references/rag-strategies.md
检索	混合搜索 + 重排序	BM25Retriever + CohereRerank	references/rag-strategies.md
Agent	多 Agent 编排	AgentWorkflow(agents=[...])	references/agent-patterns.md
工作流	事件驱动的管道	class MyFlow(Workflow): @step	references/workflows.md
图谱	知识图谱	PropertyGraphIndex.from_documents(docs)	references/property-graph-index.md
评估	RAG 评估	FaithfulnessEvaluator().evaluate_response(...)	references/evaluation-observability.md
部署	生产环境部署	deploy_workflow(workflow=MyFlow())	references/production-deployment.md

何时使用此技能

在以下情况下使用此技能：

• 基于企业或个人数据构建 RAG 管道
• 对比 LlamaIndex 与 LangChain、Haystack 或 DSPy
• 设计由专业 Agent 之间交接任务的多 Agent 系统
• 部署具备可观测性的生产级大模型应用
• 从非结构化文档构建知识图谱
• 调试常见的 LlamaIndex 故障（检索未命中、交接错误、异步问题）

何时不使用 LlamaIndex —— 框架选择指南

此技能属于一系列框架技能。选择合适的框架时，请使用以下路由表：

场景	优先选择	原因
我有需要查询的文档	LlamaIndex	数据摄取、混合检索、重排序和知识图谱都是一等功能
我有需要编排的 Agent	LangGraph	状态机语义、时间回溯调试和人工介入暂停是其核心设计
我有需要封装为 Agent 的工具	PydanticAI	具备依赖注入的类型安全 Agent 定义，对大模型调用的抽象最少
基于 PDF、SQL、Slack 和 200 多种数据源进行数据密集型 RAG	LlamaIndex	LlamaHub 连接器、用于文档的 LlamaParse，以及开箱即用的混合检索
带检查点的复杂多 Agent 状态机	LangGraph	图拓扑控制——监督者、子图、分层团队、内置检查点机制
注重 Agent 的应用，类型安全比数据管道更重要	PydanticAI	将 Agent 定义为 Pydantic 模型，支持 DI 和结构化输出——数据层由你的代码负责
文档解析质量很重要（表格、图表、手写内容）	LlamaIndex	LlamaParse 专为此类场景打造
生产级 NLP 搜索管道	Haystack	对于特定于搜索的工作负载，其管道组合模型更成熟
以优化为导向的提示词编程	DSPy	编译后的提示词程序，而非检索管道

参考文件

参考内容	何时加载	文件
核心架构	了解 7 个原语、Settings、数据流	references/architecture.md
RAG 策略	构建从基础到高级的 RAG 流水线	references/rag-strategies.md
Agent 模式	使用 AgentWorkflow 进行多 Agent 编排	references/agent-patterns.md
工作流	事件驱动的步骤组合与持久化执行	references/workflows.md
生产与部署	llama-deploy、调试、故障模式	references/production-deployment.md
属性图索引	知识图谱构建与混合检索	references/property-graph-index.md
评估与可观测性	指标、追踪、附加到 span 的评分	references/evaluation-observability.md
集成生态系统	向量存储、LlamaHub、LlamaParse、生态系统	references/integration-ecosystem.md
常见问题与故障排除	常见错误及其修复方法	references/faq-and-troubleshooting.md
完整 RAG 示例	从摄取到部署的完整端到端流水线	references/example-rag-pipeline.md
评估工作流	ParamTuner、评估器、批量评分、最佳实践	references/evaluation-workflow.md

模板文件

模板	使用时机	文件
基础 RAG	单一来源查询、入门	templates/basic-rag.py
Agentic RAG	带有 Agent 路由的多源数据	templates/agentic-rag.py
自定义工作流	自定义控制流、分支逻辑	templates/custom-workflow.py
生产部署	将工作流封装为微服务	templates/production-deploy.py

脚本

脚本	用途	文件
check-setup	验证 LlamaIndex 安装与配置	scripts/check-setup.py

故障排除 — 结构化恢复指南

出现问题时，请找到对应症状并遵循恢复路径：

检索与回答质量

症状	可能原因	立即修复	永久修复	参考
回答质量差或出现幻觉	混合检索未配置重排器	将 CohereRerank(top_n=5) 添加为 node_postprocessor	生产环境中的任何 RAG 都必须进行重排	references/rag-strategies.md
检索遗漏显而易见的内容	默认分块破坏了语义	改用 SemanticSplitterNodeParser(breakpoint_percentile_threshold=95)	使用 ParamTuner 调整分块大小	references/rag-strategies.md
返回了错误租户的数据	缺少元数据筛选器	添加 MetadataFilters(filters=[ExactMatchFilter(key="tenant_id", ...)])	始终在检索器级别配置元数据筛选器	references/rag-strategies.md
只有一种类型的查询效果良好	仅使用单一检索策略	通过混合检索器组合 BM25 与向量检索	添加 RouterQueryEngine，根据查询类型进行路由	references/rag-strategies.md

Agent 与工作流故障

症状	可能原因	立即修复	永久修复	参考
交接后 Agent 静默等待	AgentWorkflow 交接错误	扩展 FunctionAgent.take_step，重新定位最后一条用户消息	在所有生产环境中的 Agent 上应用交接修复	references/agent-patterns.md
工作流未运行	忘记使用 await	在 w.run(...) 和所有步骤调用前添加 await	所有步骤方法都是异步协程	references/workflows.md
步骤已执行，但结果丢失	状态未持久化	使用 ctx.store.edit_state() 保存共享状态	只有 ctx.store 会在各步骤间保留	references/workflows.md
崩溃导致所有进度丢失	没有检查点快照	在步骤完成时添加 Context.to_dict() 保存操作	持久化工作流需要显式设置检查点	references/workflows.md

部署与可观测性

症状	可能原因	立即修复	永久修复	参考资料
llama-deploy 已部署，但请求超时	Redis 未运行	启动 redis-server	Redis 是必需的 — 没有它，控制平面将无法路由	references/production-deployment.md
可观测性 UI 中缺少 Spans	调用 Instrumentation 太晚	将 instrument() 调用移到工作流实例化之前	始终在创建任何 Workflow 对象之前进行 Instrumentation	references/production-deployment.md
返回的数据错误（跨租户）	缺少元数据筛选器	为所有检索器添加租户筛选器	在检索器层级进行筛选，而不是在后处理阶段	references/production-deployment.md

恢复工作流

发生任何故障时，请遵循以下流程：

1. 从上表中识别症状
2. 应用立即修复 — 让系统恢复运行
3. 实施永久修复 — 防止问题再次发生
4. 通过评估进行验证 — 对保留的查询集运行 FaithfulnessEvaluator
5. 记录修复方法 — 将根本原因添加到 references/faq-and-troubleshooting.md