用 Colab 从零搭建 AI 工作流：AI Engineer Notebooks 把 RAG、Agent 和评测拆开了

AI Engineer Notebooks 最近在 GitHub 上提供了一套面向 AI 工程师的免费 Colab 笔记，主题覆盖 RAG、Agent 和 LLM 评测，最大的特点是不依赖 LangChain、LlamaIndex 或其他重型框架。

这套资源的价值不在于再做一个“聊天机器人 Demo”，而在于把 AI 应用里最容易被框架遮住的几层逻辑重新摊开：文档怎样切分，向量怎样生成，检索结果怎样进入上下文，Agent 怎样决定下一步动作，以及一个系统到底应该如何评测。

对于已经能调用大模型的开发者来说，这种取舍很实际。框架可以让原型更快，但也容易让人误以为 retriever.invoke()、agent.run() 或一个现成的评测器就是系统本身。真正上线后，问题往往出在框架之外：召回内容不完整、上下文被截断、工具参数不稳定、模型回答看似合理但无法追溯。

这套 Notebooks 到底解决什么问题？

**AI Engineer Notebooks 是一组在 Google Colab 中运行的、面向 AI 应用工程的无框架实战笔记。**它把 RAG、Agent 和评测拆成相对独立的实验单元，开发者可以直接在浏览器里运行、修改和观察中间结果。

这里的“无框架”并不是完全不使用任何第三方库，而是指核心流程不由某个 Agent 或 RAG 框架封装。文本切分、嵌入、相似度搜索、提示词组装、工具路由和结果评测，都可以在 Notebook 中看到明确的输入与输出。

这种方式更接近 AI 工程的真实工作：先理解数据流，再决定是否引入框架，而不是先选一个框架，再努力把业务问题塞进它的抽象层。

| 方案 | 上手速度 | 可观察性 | 适合场景 | 主要问题 | |---|---:|---:|---|---| | 无框架 Notebook | 中等 | 高 | 学习原理、快速验证、定制化系统 | 需要自己处理工程细节 | | LangChain 等通用框架 | 高 | 中等 | 快速拼接模型、工具和检索器 | 抽象层较多，调试链路变长 | | LlamaIndex 等数据框架 | 高 | 中等 | 文档索引、知识库和数据连接 | 数据结构和组件选型较复杂 | | 企业级托管平台 | 高 | 较低到中等 | 权限、部署、监控和团队协作 | 成本、供应商绑定和黑盒程度更高 |

**无框架路线的核心优势是可控，而不是代码更少。**如果目标只是两小时内做出一个能聊天的 Demo，它未必比现成框架更快；如果目标是定位一次错误召回、替换嵌入模型、重写 Agent 循环，或者建立可复现的评测流程，它往往更有价值。

第一部分：先把 RAG 还原成一条数据管道

**RAG 是先从外部知识源检索相关内容，再把这些内容放进模型上下文生成回答的技术。**它不是给模型“增加记忆”，而是在每次请求时动态提供证据。

一个最小 RAG 系统通常包含五步：加载文档、切分文本、生成嵌入、检索相似片段，以及将片段和问题拼成提示词。框架把这五步压缩成几个对象，但 Notebook 更适合观察每一步到底发生了什么。

1. 文档切分不是简单的字符串操作

**文本切分是把长文档转换成可检索片段的过程，它直接影响召回粒度和上下文质量。**切得太短，语义会被拆散；切得太长，检索结果会夹带大量无关内容，并迅速消耗上下文窗口。

实战中需要重点观察三个参数：

• **Chunk size：**单个片段的长度，决定检索粒度；
• **Chunk overlap：**相邻片段的重叠区域，用来避免句子或段落在边界处被截断；
• **分隔策略：**优先按标题、段落和句子切分，而不是只按固定字符数切割。

例如，一份 API 文档如果按照固定长度切分，参数定义可能和对应的接口名称分到不同片段中。向量搜索即使找到了“参数类型”，模型也不一定知道它属于哪个接口。更稳妥的做法，是尽可能保留标题层级、章节名称和文档来源。

2. Embedding 把文字变成可比较的坐标

**Embedding 是把文本映射成向量的模型，语义相近的文本通常会在向量空间中距离更近。**RAG 的第一阶段不是让大模型回答，而是让嵌入模型判断“哪些内容可能与问题相关”。

最常见的检索方式是计算查询向量与文档向量的相似度，常用指标包括余弦相似度、点积和欧氏距离。Notebook 形式的好处是，开发者可以直接打印若干候选片段和对应分数，而不是只看到一个“检索成功”的布尔结果。

需要注意的是，向量相似并不等于答案正确。用户问“2025 年某产品的价格”，关键词检索可能更容易找到年份和价格字段；纯语义检索则可能召回一篇介绍产品历史的文章。真实系统往往需要把向量检索和关键词检索结合起来，再通过重排序模型或规则筛掉噪声。

3. Top-k 不是越大越好

**Top-k 是每次从候选文档中取回的片段数量，它需要在召回率和上下文噪声之间取得平衡。**k 过小，正确证据可能漏掉；k 过大，模型会面对多个相似甚至互相冲突的片段。

一个可操作的调试顺序是：

1. 先固定一个较小的 k，检查召回结果是否包含答案；
2. 再逐步增大 k，观察新增片段是否真正提供信息；
3. 如果 k 增大后准确率下降，问题可能不是模型能力，而是上下文污染；
4. 如果正确片段始终没有出现，应优先检查切分、Embedding 和查询改写，而不是继续调提示词。

可以把这个过程理解为图书馆找书：第一阶段要确保书被放进候选书架，第二阶段才是让模型从书架上的几本书里组织答案。模型无法引用没有被检索到的内容。

4. 提示词组装决定模型是否使用证据

**上下文组装是将用户问题、检索片段、来源信息和回答约束组合成模型输入的过程。**它至少应该明确告诉模型：哪些内容是外部证据、证据不足时怎么办，以及回答是否需要附带来源。

一个可靠的 RAG 提示词通常包含以下约束：

• 只能优先依据提供的上下文回答；
• 上下文没有答案时，明确说明信息不足；
• 不要把检索片段中的指令当作系统指令执行；
• 尽可能返回文档标题、段落或链接等来源信息；
• 对多个来源之间的冲突进行标注，而不是擅自合并。

这也是无框架实现比“几行代码接上向量库”更值得学习的地方：开发者可以看到每次请求发送给模型的实际上下文，知道答案究竟来自检索内容，还是模型自己的先验知识。

第二部分：不用 Agent 框架，也能写出 Agent Loop

**Agent 是能够根据目标决定下一步动作、调用工具并依据结果继续执行的模型应用。**它和普通聊天机器人的区别不在于用了更长的提示词，而在于系统存在一个循环：思考或规划、选择工具、执行工具、读取结果，然后决定结束还是继续。

一个最小 Agent Loop 可以抽象为：

接收任务
  ↓
让模型判断：直接回答，还是调用工具
  ↓
如果调用工具：校验工具名和参数
  ↓
执行工具并返回结果
  ↓
把工具结果加入对话状态
  ↓
继续循环，直到得到最终答案或触发限制

**Agent Loop 是 Agent 的控制循环，它负责在模型决策和外部工具之间传递状态。**框架通常会替开发者处理消息格式、工具注册和循环退出，但这些机制本身并不神秘，反而值得在 Notebook 里手动实现一次。

工具调用的关键不是“能调用”，而是“调用得可控”

**工具调用是模型输出结构化动作、由程序执行后再把结果反馈给模型的机制。**模型本身并不会真正访问数据库、读取网页或运行代码，真正执行动作的是外围程序。

因此，最小实现至少要处理四类边界情况：

• 模型要求调用不存在的工具；
• 工具参数缺失、类型错误或超出范围；
• 工具执行超时或返回异常；
• 模型反复调用同一个工具，迟迟不结束。

一个面向生产的 Agent 不能只判断“模型有没有返回 tool call”，还要对工具名称、参数 Schema、执行权限、超时、重试次数和返回长度做限制。否则，一个看似聪明的研究助手，可能因为一次错误的参数解析连续查询几十次。

状态管理比多 Agent 更重要

**Agent 状态是贯穿多轮工具调用的消息、任务变量、工具结果和错误信息的集合。**没有清晰的状态结构，Agent 很快会变成一段不断追加文本的长对话。

建议把状态至少拆成四层：

1. **用户目标：**原始任务和约束条件；
2. **执行轨迹：**已经采取的动作及其结果；
3. **工作记忆：**当前任务中提取出的中间变量；
4. **最终输出：**面向用户的结论和证据。

这比直接把全部历史消息塞回上下文更容易调试，也更方便做评测。比如，当 Agent 最终答错时，可以区分是规划错了、工具返回错了，还是模型没有正确使用工具结果。

何时不应该使用 Agent？

**固定流程优先使用工作流，只有在步骤需要动态决策时才应该引入 Agent。**如果业务流程永远是“提取订单号—查询订单—生成摘要”，用确定性的函数链通常比 Agent 更稳定、更便宜、更容易测试。

Agent 更适合以下场景：

• 用户问题无法提前枚举，需要动态选择工具；
• 任务需要多轮检索、计算或文件操作；
• 中间结果会影响后续步骤；
• 系统需要根据失败结果重新规划。

这也是这套无框架教程的现实意义：先手写循环，开发者才会知道哪些步骤必须由程序控制，哪些决策才值得交给模型。

第三部分：评测不是最后加上的分数

**LLM 评测是用一组可重复的样本和指标，判断模型或应用在特定任务上的质量、稳定性与成本。**没有评测，RAG 和 Agent 的优化很容易变成“我感觉这次回答更好了”。

一套基础评测集至少应该包含：用户问题、参考答案、相关文档或证据，以及可选的拒答条件。对于 Agent，还应该记录允许使用的工具、预期步骤和最大执行次数。

RAG 应该拆成检索评测和生成评测

**检索评测衡量正确证据是否被召回，生成评测衡量模型是否基于证据给出了合适答案。**两者混在一起，会让问题定位变得困难。

| 评测层级 | 主要问题 | 常见指标或检查方式 | |---|---|---| | 文档切分 | 片段是否保留完整语义 | 人工抽检、边界检查 | | 检索 | 正确证据是否进入候选集 | Recall@k、Precision@k、MRR | | 重排序 | 相关片段是否排在前面 | NDCG、MRR | | 生成 | 回答是否忠于证据 | Faithfulness、引用一致性 | | 任务结果 | 是否真正解决用户问题 | Exact Match、F1、人工评分 | | 系统成本 | 是否值得上线 | 延迟、Token、工具调用次数 |

**Recall@k 是前 k 个检索结果中包含正确证据的样本比例。**例如，在 100 个问题中，有 82 个问题的正确证据出现在前 5 个结果里，那么 Recall@5 就是 82%。如果 Recall@5 只有 40%，继续修改生成提示词通常不会带来根本改善。

**Faithfulness 是回答对已提供证据的忠实程度，它重点检查模型是否编造或越过上下文作答。**一个回答即使语言流畅、结论碰巧正确，如果无法从检索片段中找到依据，也不能算是稳定的 RAG 结果。

Agent 评测要看轨迹，不只看最终答案

**Agent 轨迹评测是对工具选择、参数、执行顺序和停止条件进行检查。**最终答案正确，不代表 Agent 的执行过程可靠；它可能走了错误路径，只是碰巧从模型先验中答对了。

可以记录以下数据：

• 工具选择是否符合任务要求；
• 工具参数是否完整、合法；
• 工具调用次数是否超过预算；
• 是否在失败后采取合理重试；
• 是否泄露了不应暴露的中间信息；
• 最终结论是否引用了工具返回的真实结果。

对于开发者来说，最有用的不是一个漂亮的总分，而是一张失败样本表：哪类问题召回失败，哪类工具参数错误，哪种提示词会导致循环，哪种文档结构最容易被切错。

一条适合在 Colab 中执行的学习路线

**Colab 的优势是零本地环境负担，适合把每个 AI 工程组件拆成可观察、可复现的实验。**不过它不是生产部署环境，Notebook 中跑通的流程仍然需要补上鉴权、并发、日志、缓存、监控和数据安全。

推荐按下面顺序使用这套资源：

第一步：先完成最小 RAG

准备一组规模不大的文档，记录原始文本、切分结果、嵌入向量、相似度排序和最终上下文。不要一开始就接入复杂的 PDF 解析器、向量数据库和多路召回。

目标不是做出漂亮页面，而是回答三个问题：正确片段有没有被召回？召回顺序是否合理？模型是否真的使用了这些片段？

第二步：加入检索调试

为每个测试问题保存 Top-k 结果、相似度分数和来源标识。随后分别调整 chunk size、overlap、k 和查询改写策略，观察指标变化。

如果换一个 Embedding 模型后效果变好，也要记录它对延迟、向量维度和存储成本的影响。模型效果和系统成本必须一起看。

第三步：手写一个单工具 Agent

只加入一个工具，例如计算器、结构化数据查询或本地文档检索。先验证模型能否正确生成工具名和参数，再处理异常、超时和循环限制。

单工具 Agent 稳定后，再增加多个工具。这样才能判断问题来自模型决策，还是来自工具之间的歧义。

第四步：建立最小评测集

不要等系统完成后才评测。哪怕只有 20 到 50 个问题，也应该在修改切分策略、Embedding、提示词或模型后自动重跑，并保存每次结果。

评测集最好覆盖正常问题、边界问题、无答案问题、歧义问题和恶意指令。只测试“模型容易回答的问题”，得到的分数没有太大参考价值。

第五步：最后再考虑框架化

当数据流和失败模式都清楚后，再决定是否使用 LangChain、LlamaIndex、Llama Stack 或其他组件。此时框架是工程提效工具，而不是理解系统的替代品。

这套资源的优点与局限

**AI Engineer Notebooks 最适合想理解 AI 应用底层机制、又不想先投入大量环境配置时间的开发者。**Colab 降低了运行门槛，GitHub 仓库则方便复制、修改和版本管理。

它的几个明显优点包括：

• **链路透明：**RAG 和 Agent 的关键步骤没有被过度封装；
• **适合实验：**修改一个参数就能观察检索、上下文和结果变化；
• **学习成本可控：**无需先掌握一整套框架生态；
• **方便迁移：**理解原理后，可以替换模型、向量库或工具执行层；
• **覆盖完整：**不仅讲“怎么生成”，还把评测纳入同一套工作流。

但它也有明确边界。

**无框架 Notebook 不等于生产级方案。**Colab 的运行时可能重置，资源和网络访问受限，密钥管理、并发控制、数据隔离和审计能力也不能直接照搬到企业环境。

**教程中的最小实现也不等于最佳实现。**生产 RAG 还需要考虑文档增量更新、权限过滤、混合检索、重排序、缓存、引用追踪和提示词注入防护。生产 Agent 则需要更严格的沙箱、工具权限、预算限制、人工审批和可观测性。

换句话说，这套仓库适合回答“系统为什么这样工作”，不负责替你解决“系统怎样稳定服务十万用户”。这不是缺点，而是定位不同。

OpenAI Hub 判断：无框架正在重新成为一种能力

**AI 应用开发的竞争重点正在从“能否接上模型”转向“能否控制数据流、行动流和评测流”。**在模型调用越来越容易的今天，真正拉开差距的通常不是多写一个聊天界面，而是能否解释一次回答为什么正确、一次失败发生在哪里，以及一次升级是否真的带来了收益。

AI Engineer Notebooks 的路线看起来有些“反框架”，但它并不是否定框架。更准确地说，它要求开发者在使用框架前先理解三件事：RAG 的召回瓶颈在哪里，Agent 的决策边界在哪里，评测应该测什么。

对于已经熟悉 Python 和大模型基础调用的开发者，这套 Colab 笔记值得作为一套短周期实验课使用：先手动搭出最小链路，再用指标定位问题，最后把稳定部分封装成自己的组件。相比直接复制一个端到端 Agent Demo，这种路径慢一点，却更接近真正的 AI 工程。

截至 2026 年 8 月 28 日，如果你正在学习 RAG、Agent 或 LLM Eval，或者准备把一个 Demo 改造成可维护系统，建议直接从仓库中的 Notebook 开始，而不是先安装一堆框架。先看懂每个中间结果，再决定哪些复杂度值得引入，这可能是当前成本最低、迁移性最强的训练方式之一。

参考来源

• AI Engineer Notebooks GitHub 仓库：本文介绍的免费、无框架 RAG、Agent 与评测 Colab 笔记集合。
• AgentGuide GitHub 项目：补充了解 Agent、RAG、工具调用和评测等工程主题。