AI Engineer Notebooks：无框架透明实现 RAG/Agent/Evals 的免费 Colab 教材

AI Engineer Notebooks：无框架透明实现 RAG/Agent/Evals 的免费 Colab 教材

大部分 AI 教程教你调 LangChain 的 API。这一套教你手写 RAG、手写 Agent 循环、手写 Evals——然后你才知道框架到底替你藏了什么、以及什么时候不该用它。

HN 112 分、GitHub 591 Star、MIT 协议、2026 年 8 月 11 日创建。calmrocks/ai-engineer-notebooks 把 AI Engineer / Forward Deployed Engineer（FDE）需要掌握的全套 applied-LLM 技能，做成了 12 模块、30 本可直接在 Google Colab 运行的笔记本。设计原则非常鲜明：不依赖 LangChain/LlamaIndex 等高层框架、全用原始 API 调用、全程可用 Groq 免费 API 跑、不需要信用卡。

配套有三份支撑文档：curriculum-plan.md 讲课程设计（为什么这个顺序学）、best-practices-and-anti-patterns.md 总结 28 条好坏实践、CAPSTONE.md 指导一个学期级的顶石项目设计。外加 3 个真实案例收尾（生产环境下客服助手调试、Pipeline vs Agent 成本对决、红队鲁棒性基准），不是简单跑个 Hello World 的 toy demo。

本文提纲

1. 为什么是它：5 条设计哲学直接击中工程师痛点
2. 完整课程地图：00 Setup → 12 Case Studies & Capstone（12 模块 30 本笔记本）
3. Framework-free 怎么做：RAG、Agent Loop、Evals 三个核心环节透明实现思路
4. Evals 是脊椎（Evals as the spine）：从头到尾反复出现的理念
5. 3 个 Case Studies：不是玩具，是真约束下的组合技
6. 3 份配套文档：课程规划/最佳反模式/顶石项目设计
7. 团队内训手册用法：如何用这套 591 Star 的仓库替代付费培训班
8. 同类对比：vs DeepLearning.AI / vs LangChain Academy / vs 内部文档自学

1. 为什么是它：5 条设计哲学直接击中工程师痛点

README 开头没废话，直接列 5 大"What makes this different"：

① Framework-free, on purpose

你先用原始 API 手写 agent loop、手写 RAG、手写 evals，搞懂 LangChain 和 LlamaIndex 到底替你做了什么之后，再决定要不要用。"Patterns are durable; wrappers churn."（底层模式是持久的，封装库三年河东三年河西。）

这一哲学让这套教程和市面上 95% 的 "LangChain 教程" 区分开。后者教你"怎么调这个 API 做出东西"，前者教你"东西是怎么被做出来的"。对面试和生产排障，两者价值差一个数量级。

② Evals are the spine

"Measure before you tune"（先量后调）在第 02 章（学习的第 2 步）就强制安装，之后每一节都会回来用 evals 验证你的改动。这个习惯是"能上线系统的工程师"和"只会跑 demo 的工程师"的分水岭。

很多团队做了半年 RAG，效果指标一条没有——prompt 改了无数次，到底是变好变差全靠人"感觉"。这套课程从第 2 步开始就不让你养成这种坏习惯。

③ Free to run, end to end

全程用 Groq 免费 API，不要信用卡。Groq 跑不了的两块（06 LoRA 微调、09 自托管服务）用"概念为主 + Colab-GPU fence 附录"，作者声明附录部分是在真实 Colab T4 上验证过的。免费这一点对学生、想转行的工程师、公司没报销预算的团队来说是决定性的门槛。

④ Real case studies, not toy demos

3 个 End-to-end 案例是在真实约束下展示技能组合：
- 一个在生产环境中被调试过的客服助手（不是模拟客服）
- 一个 Pipeline 方案 vs Agent 方案的成本与质量对决
- 一个红队鲁棒性基准（不是"怎么写 prompt"而是"怎么测系统被攻破"）

⑤ OpenAI-compatible throughout

全程是 OpenAI 兼容 API，所以学到的所有模式直接平移到 OpenAI 本体，（稍加改动）也能平移到 Anthropic。base URL 一换、所有 notebook 都能跑。

2. 完整课程地图：00 Setup → 12 Case Studies（12 模块 30 本笔记本）

MERMAID_BLOCK_0

每一本笔记本都是自包含（self-contained）：在 Colab 里打开就能装依赖、API key 走 Colab secrets、结尾都带练习题。下面挑每个模块最关键的笔记讲。

00 Setup：成本卫生与模型选型

00-environment.ipynb 讲 API key 怎么放进 Colab secrets、spend guards（消费守卫）怎么加、模型怎么选。很多 AI 工程师新人第一个坑就是：跑一周 notebook 忘关并发，账单爆 500 美元。这一步第 0 节就给堵上。

01 Model APIs：5 本从 prompt 到缓存

• 00-prompting-basics：Clear instruction / few-shot / output-format spec / step-by-step reasoning — 每条都跟着具体指标动（不是"感觉更好"，是数字涨了多少）
• 01-structured-output：稳定拿到 JSON，以及在哪种情况下结构化会崩（反例很重要）
• 02-tool-calling：function/tool calling 端到端，包含错误路径（多数教程只教成功路径，不教工具调用崩了怎么处理）
• 03-streaming：流式响应 + UI 需要什么（配合前端工程师的需求视角）
• 04-context-and-caching：上下文窗口预算管理、prompt caching、批量 vs 实时价格模型

02 / 04 Evals 双章：一次基础 + 一次进阶

02 只一本 01-measuring-outputs，在 01 节完成的任务上打指标。04 三本：
- 01-golden-sets：给 03 节的 RAG 系统构造 gold test set
- 02-llm-as-judge：Judge prompt 怎么写、与人类标注一致性、法官自己的失败模式（这是很多团队踩坑的地方——用 LLM 评质量，但是评本身有偏差）
- 03-regression-evals：把 Evals 当 CI 用——改 prompt 或换模型时自动抓质量回归。生产环境必备。

03 RAG：5 本里最特别的是 "Why RAG fails"

• 00-what-is-rag：15 行代码可跑 demo，讲 retrieve→augment→generate，以及"RAG 不等于 embeddings"（很多人把 RAG 和向量化混为一谈，RAG 是 retrieve + augment + generate 三段流程，embedding 只是检索的一种实现）
• 01-embeddings-retrieval：embedding 选型、向量检索、相似度常见陷阱
• 02-hybrid-and-reranking：关键字+向量混合检索、重排器、成本收益分析
• 03-chunking：真实脏语料上分块策略
• 04-why-rag-fails：诊断坏答案——检索质量瓶颈 vs 生成质量瓶颈。大多数团队把精力砸在更好的模型上，但问题根本是检索没捞对文档。

05 Agents：手写 agent loop 是本系列的亮点

这是和框架派教程差得最远的一节，6 本全是"别用框架"：

• 01-agent-loop-from-scratch：用原始 API 调用手写一个可跑的 agent loop。这一本是所有想理解 Agent 的人必读。看完你会明白：Agent 不是什么魔法，就是一个 while 循环 + parse tool_call → execute tool → 把 tool_output 填回聊天历史 → 再调模型。
• 02-tool-design：设计模型真正能用好的工具。模型讨厌什么工具？参数太多的、描述模糊的、名字像人的名字。好的工具 = 单一职责 + 清晰 docstring + 小输入空间。
• 03-guardrails-and-budgets：停止条件、成本/延迟预算、什么时候 pipeline 比 agent 好。很多团队一上来就想上 agent，其实 pipeline 更稳更便宜。
• 04-mcp-and-the-tool-ecosystem：讲 MCP（Model Context Protocol）到底标准化了什么、和原始 tool loop 怎么映射、什么时候该上 MCP。
• 05-skills-and-progressive-disclosure：打包可按需加载的可复用知识，即 SKILL.md 模式，以及 Tools/MCP/Skills 三者的定位关系。
• 06-harness-engineering：这一节一直默默教的"外围脚手架"学科——上下文装配 + 压缩、工具结果整形、验证循环。Harness（执行 harness）是一个没有被行业好好命名的重要工种，这本给了它名字。

06-11 后续模块：适配 → 安全 → 运维 → 服务 → 系统设计 → 客户技艺

• 06 Adaptation：Fine-tune vs RAG vs Prompt 决策三角，LoRA/QLoRA 的成本和内容，以及 Colab T4 上真跑一次 LoRA 的附录。
• 07 Security：直接间接 Prompt Injection、输出处理、PII、过度权限（excessive agency）。OWASP LLM Top 10 全过一遍，先演示怎么攻破、再演示怎么防守（先 live fail，再 defend）。
• 08 Operations：全链路 tracing、安全 prompt 日志、成本/延迟/错误指标、漂移检测；重试+退避+超时+fallback model+验证+熔断器+优雅降级；MLflow 端到端把 eval harness 接入实验追踪、模型版本注册、按阶段晋升。
• 09 Serving · Inference：服务框架对比、推理性能调优。
• 10 ML System Design：设计推理服务系统一课。
• 11 Customer Craft：Scoping & Discovery（项目边界划定与需求发现）—— 这是 FDE / Applied AI 工程师的软技能硬指标，AI 教程很少教这一块，这份教了。

12 Case Studies：3 个顶石案例 + CAPSTONE.md

本节是把前面所有技能在真实约束下合成实战：

1. 01-customer-support-assistant：一个生产环境被调试过的客服助手
2. 02-contract-extraction-pipeline-vs-agent：合同抽取场景下，Pipeline 方案 vs Agent 方案的成本与质量对决（最常被问的决策场景）
3. 03-red-team-robustness-benchmark：红队鲁棒性基准（不是"怎么写好系统"而是"怎么系统地测试它的安全漏洞"）

以及单独的 CAPSTONE.md：指导你做一个学期级的顶石项目设计——涵盖项目范围、验收标准、里程碑设计、Evals 计划、红队测试计划、交付物、展示建议。

3. Framework-free 怎么做：RAG、Agent Loop、Evals 三个核心环节透明实现思路

很多工程师第一次看到"Framework-free"的第一个反应是"那岂不是很累？"。但关键认知是：框架替你省的是重复代码，不是理解。当你第一次学的时候，省理解是亏的。下面三小段从 README + curriculum-plan 里整理出这门课的"透明"体现在哪。

RAG 不透明实现通常长什么样

框架派入门 RAG 大概长这样：

from langchain_community.vectorstores import FAISS
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain.chains import RetrievalQA
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="llama3")
retriever = FAISS.from_texts(chunks, HuggingFaceEmbeddings()).as_retriever(k=3)
qa = RetrievalQA.from_chain_type(llm=llm, chain_type="stuff", retriever=retriever)
result = qa.invoke("问题")

三行就跑起来了，但是问题来了：
- RetrievalQA 的 chain_type="stuff" 到底把 chunk 和问题是怎么拼的？
- Retriever 默认相似度度量是什么？对中文语料会不会塌？
- 召回前 3 条还是前 10 条？如果 3 条都错了怎么办？
- 如果某段 chunk 太长，怎么塞进去？截断哪里？

这些全部被框架替你"默认参数化"了，除非你遇到生产问题被打爆，否则永远不会看。

Framework-free 这门课怎么做：先手写"15 行可运行的 RAG demo"，让你看到 retrieve → augment → generate 三段是怎么接起来的，然后再一步步加 embeddings → hybrid → reranking → chunking，并在每一步用第 04 章的 evals 对指标打分。所有默认参数的决策都是你跑实验跑出来的，不是框架作者替你决定的。

Agent Loop 不透明实现通常长什么样

你在 LangChain 里用 ReAct / OpenAI Tools Agent，两行创建 AgentExecutor，然后 invoke。整个 while 循环、tool parse、错误重试、停止条件都在黑匣子里。一旦 Agent 出现无限循环、重复调同一个工具，你只能靠 max_iterations 硬卡，并不知道到底是 tool_description 写烂了、prompt 不完整，还是框架本身有 bug。

Framework-free 的 01-agent-loop-from-scratch 怎么做：

# 原始 API 手写的 agent loop 核心轮廓（课程核心思想）
while not should_stop(messages, budget):
    resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
    msg = resp.choices[0].message
    messages.append(msg)
    if msg.tool_calls:
        for tc in msg.tool_calls:
            result = execute_tool(tc.function.name, tc.function.arguments)
            messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
    else:
        break  # 模型输出最终回答
return messages[-1].content

当然课程里比这个骨架复杂得多：加了 guardrails、budget、verify loop、tool error recovery 等。核心是——这整个循环你自己亲手写，之后你再看 LangChain 的 AgentExecutor 源码会心想"这不就是我第 05-01 课写的东西嘛"。

Evals as CI 怎么做

04-evals/03-regression-evals.ipynb 把 Evals 和 CI 对齐：就像软件团队 push 代码跑单元测试一样，AI 工程团队改 prompt/换模型/换 chunking 策略，必须自动跑一次 regression evals。有 2 种关键 evals：
- Golden set accuracy：标准集上的分数（RAG 系统答案和标准答案的吻合度 / LLM as judge 的打分 / 结构化输出 schema validation 通过率）
- Latency + cost：成本和延迟是生产约束，不是优化项，必须和质量一起作为 CI 通过条件

课程把 Evals 和 CI 的等价性讲透了，很多团队对此的认知甚至是零。

4. 配套文档：curriculum-plan / best-practices-and-anti-patterns / CAPSTONE

三份文档是仓库的骨架，价值不亚于笔记本本体：

curriculum-plan.md：为什么这个顺序学

详细解释每一节为什么放在这个位置、学习目标是什么、完成时间估算、前置技能要求。团队做培训计划的时候可以直接拿来当 syllabus。

best-practices-and-anti-patterns.md：28 条好坏实践

这份文档写得特别直白，完全是踩坑总结的风格。举几个例子：

好的（Best Practices）：
- Measure before you tune — 先量后调（已反复强调）
- Version prompts and evals together — prompt 版本和 evals 版本一起版本化
- Budget everything — 给每一次调用（agent step、RAG step）都定 budget
- Retrieval first, generation second — RAG 系统烂，80% 是检索烂，不是生成烂
- Fail closed, not open — 安全兜底策略：失败时保守不输出，不是失败时瞎猜

坏的（Anti-Patterns）：
- Eval once then forget — 上线前跑一次 evals，之后再也不跑（等同于软件没有 CI）
- Fine-tune as a first move — 很多团队"模型不准？我们微调一下吧"——事实上这是成本最高、数据要求最硬、效果最不稳定的最后一张牌
- No tool error handling — 工具调用只写"happy path"，工具超时/返回错误时agent必然崩
- Evals that always pass — 指标定义得太宽或 LLM judge prompt 写得太松，结果永远 98%，上线后却一片骂声（这是最常见的反模式，大家都懂但没人愿意改）
- Agent when pipeline is enough — 能写一个 if/else 解决的事情，不要让 Agent 决定。确定性 vs 决策性要有明确边界

CAPSTONE.md：顶石项目设计指南

指导你自己定义一个端到端 AI 工程项目，包括：
- 项目范围（什么做、什么不做）
- 验收标准（Evals 通过条件 + 延迟/成本预算 + 安全基线通过率）
- 里程碑（Week 1-6）
- Evals 计划（golden set 怎么采、LLM judge 怎么写、regression evals 怎么自动化）
- 红队测试计划
- 交付物清单
- 展示建议（怎么给 stakeholder 演示）

5. 团队内训手册用法：如何用这套 591 Star 的仓库替代付费培训班

这仓库作者自己说它是作为 calm.rocks 上那篇 "Plan: Transitioning to Forward Deployed Engineer / AI Engineer" 的动手配套。我想说：这份 591 Star 的仓库作为团队内训手册，性价比是非常高的。 怎么用：

1. 内训 12 周滚动：一周一本重点笔记本，30 本拆成 12 周（周平均 2-3 本）。周一对齐学习目标，周五做练习题和 evals review。
2. CAPSTONE 作为结业项目：每人或 2 人小组自选一个真实业务问题，按 CAPSTONE.md 设计交付，作为内训考核。
3. best-practices 作为 code review 标准：把 28 条好坏实践打印出来贴在评审室墙上，prompt 代码 review 时逐条对照。
4. 新人 FDE / AI Engineer 入职标配：把仓库 fork 到公司私有仓库，加一份公司专属 00a-corp-setup.ipynb 讲公司怎么拿 API keys、内部有哪些 LLM 服务、公司 evals 模板怎么填，新人到岗第一周跑这套。
5. 成本可忽略：Groq 免费 API，不用公司申请预算；Google Colab 免费版足够支撑前 9 节；只有 06 和 09 的 GPU 附录需要 Colab Pro 或自家 GPU。

6. 同类对比：vs DeepLearning.AI / vs LangChain Academy / vs 内部文档自学

维度	calmrocks/ai-engineer-notebooks	DeepLearning.AI LLM Ops / RAG Specializations	LangChain Academy / LangSmith	内部文档 + 自学
Framework-free 透明实现	✅ 全程原始 API，亲手写	❌ 多半课程用 LangChain / LlamaIndex	❌ 全是自家框架示例	✅ 可以，但缺系统路径
是否免费	✅ Groq 免费 API + Colab 免费层	❌ 需 Coursera Plus / DeepLearning.AI 付费	✅ 免费，但必须 LangSmith 账号	✅ 免费
Evals 作为脊椎贯穿	✅ 02 章强制+之后每章回	⚠️ 独立一门 Evals 课，不贯穿	⚠️ LangSmith 有 evals，但要配合 LangChain	❌ 靠自己觉悟
生产级 Case Studies	✅ 3 个真实约束下的组合案例	⚠️ 有一些 Final Project，但偏松散	⚠️ 参考文档有 templates	❌ 需要自己找
Hands-on Colab 笔记本	✅ 30 本自包含 + 一键打开	✅ 配套 lab 有，但常闭源或云端受限	✅ 官方 notebook 模板	❌ 自己搭环境
Security + LLMOps + 服务化	✅ 07/08/09/10 四章全有	⚠️ LLMOps 单独一门，Security 很薄	⚠️ Security 几乎不谈，LLMOps 在 LangSmith	❌ 最需要自己摸索的部分
FDE 客户技艺	✅ 11 章 Scoping & Discovery 独一份	❌ 不覆盖	❌ 不覆盖	❌ 完全不覆盖
CAPSTONE / 顶石指导	✅ 独立 CAPSTONE.md 专业指导	⚠️ 有 Final Project 但薄	❌ 没有	❌ 没有
更新速度	⭐⭐⭐⭐ 2026-08 新建维护积极	⭐⭐ 视频课生产周期长，更新慢	⭐⭐⭐ 随产品更新	⭐ 全靠自己

一句话结论：DeepLearning.AI 给你"证书 + 权威背书体系"；LangChain Academy 教你"LangChain 产品家族怎么用"；ai-engineer-notebooks 教你"如果你要裸手写一套生产级 AI 系统该怎么办"，然后你再去判断什么时候值得加框架。三条路线不冲突，但如果你团队缺的是能上线系统的工程师，不是需要证书的员工，裸手写这套是时间投入回报率最高的选择。

---

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。