Day 017｜LlamaIndex 入门：让数据和 Agent 更自然地连起来
系列：100 天系统学习 AI Agent 开发
当前阶段：RAG、知识库与工具边界
今日目标：LlamaIndex 的优势是围绕数据、索引、查询引擎、工具和 Agent 组织知识能力。
学框架最容易发生的事：API 会了，数据链路还是模糊
前几天已经把 RAG 拆成资料、切分、metadata、改写和评测。到了 LlamaIndex，如果只记住几行初始化代码，反而可能把这些边界重新藏回框架里。今天我更想弄明白：它在数据与 Agent 之间分别放了哪些抽象，每一层解决什么问题。
我暂时把 LlamaIndex 看成一套“以数据为中心的组织工具”，而不是一个自动提升答案质量的开关。资料不可信、chunk 不完整、权限过滤缺失，换框架都不会自然消失。
从原始资料到 Agent 动作
名称会随版本和具体用法有差异，但责任划分很稳定：
| 概念 | 我自己的理解 | 不应该期待它自动完成什么 |
|---|---|---|
| Agent | 根据目标和上下文选择下一步动作 | 不替代权限、重试与业务校验 |
| Tool | 向 Agent 暴露一个描述清晰的能力 | 不应把整个系统做成一个万能工具 |
| Workflow | 显式组织事件、步骤、状态和终止条件 | 不保证每个步骤的内容正确 |
| Index/Retriever | 让资料可以被找到 | 不判断召回片段是否足以支持结论 |
| Query Engine | 把检索与回答组合起来 | 不等同完整任务规划 |
放进学习助手会是什么形状
假设资料是 Day 001–016 的 Markdown，目标是回答“错误处理和重试有什么区别”。我希望链路中保留这些可检查对象：
{"request":{"question":"参数缺失应该重试吗？","user_id":"example-user","allowed_sources":["public-learning-notes"]},"retrieval":{"query":"参数缺失 错误分类 重试","filters":{"topic":"error-handling"},"top_k":3},"response":{"answer":null,"citations":[],"status":"not_run"}}框架可以帮我连接这些部分，但 request 里的权限范围、top_k 的选择、回答状态和引用规则仍要自己定义。尤其不应把 user_id 交给模型自由生成。
Agent、Tool、Workflow 怎么选
一个实用判断是看“下一步是否确定”：
- 已知输入 day，查对应学习计划：普通函数工具足够；
- 用户可能问计划、概念或进度，需要选择不同工具：交给 Agent 做有限路由；
- 导入资料 → 检索 → 判断证据 → 追问/回答 → 保存 trace：用 Workflow 明确步骤更合适。
如果一个流程每次都是固定顺序，硬把每一步都交给 Agent 决策，只会增加不确定性、延迟和费用。反过来，如果问题类型很多、工具选择确实依赖语义，塞满 if/else 也会难维护。框架选择应服务于不确定性的位置。
今天只做“概念对照”，不假装跑通
我会用下面的表检查阅读是否真正落地：
| 追问 | 应能回答 |
|---|---|
| 原始文档在哪一步变成可检索片段？ | 文档读取与 Node/chunk 构造阶段 |
| 谁决定调用知识查询？ | Agent 或明确路由规则 |
| 谁保证用户只能看允许资料？ | 应用与检索层权限过滤 |
| 检索无结果怎么办？ | Workflow 路由到追问或拒答 |
| 怎么知道改动变好了？ | 固定数据集、召回记录和回答评测 |
等真正接 SDK 时，还要以当时的官方文档核对类名、构造参数和异步调用方式。本文刻意不写一段未经安装验证的“完整代码”，避免让 API 外形掩盖设计。
我对框架的阶段性态度
框架最有价值的不是让我少写十行代码，而是给数据、工具和流程一个共同语言；它最大的风险，则是让我误以为抽象存在就等于边界已经设计好。下一篇 FunctionAgent 会缩到一个函数工具，看看最小能力该如何写清输入、输出和错误。
面试官会追问：为什么选 LlamaIndex，而不是自己拼 RAG？
我不会回答“因为封装方便”。更完整的取舍是：它在文档加载、节点解析、索引、检索器、Query Engine 和 Agent Workflow 之间提供一致抽象，适合数据密集型 Agent；代价是抽象层增加，性能问题和隐式默认值更难发现。
验证框架价值时，我会保留一个不依赖框架的基线接口：ingest、retrieve、answer、evaluate。然后比较同一数据集下的实现代码量、可观测性、扩展自定义 reranker 的难度与升级成本。框架可以替换，评测集和领域接口不能跟着丢。
面试加分点是能指出：选择框架的依据不是 Star 数，而是任务形态、团队熟悉度、可调试性和退出成本。
今日检查清单
- 能画出 Document 到 Agent 的完整数据路径
- Agent、Tool、Workflow 各自承担不同责任
- 权限、版本、重试和评测没有交给框架“默认处理”
- 固定流程优先确定性编排，语义选择才用模型
- 真正编码前重新核对当前官方 API