# Agent_Learning_Cookbook

**Repository Path**: geo_technology/Agent_Learning_Cookbook

## Basic Information

- **Project Name**: Agent_Learning_Cookbook
- **Description**: langchain简明教程
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-31
- **Last Updated**: 2026-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 应用开发教程

> 从本地跑起一个大模型，到把 RAG、Agent、MCP 做成能上线的系统。
>
> 本教程为内部学习材料：**全书不含任何标识、LOGO、水印与署名**。

---

## 一、这份教程适合谁

| 路径 | 适合的人 | 建议阅读顺序 | 预计投入 |
|---|---|---|---|
| **应用开发**（主线） | 会写 Python，想做 AI 应用 | 0 → 1 → 2 → 4 → 5 → 3 → 6 → 7 → 8 | 6–8 周 |
| **平台运维** | 要部署模型、管 GPU、保稳定 | 0 → 1 → 6 → 7 → 2 | 3–4 周 |
| **快速上手** | 只想先跑起来看效果 | 0.4 → 1.4 → 1.5 → 4.17–4.24 | 3 天 |

难度标记：**[入门]** 不需要前置知识 ｜ **[进阶]** 需要动手经验 ｜ **[实战]** 直接对应生产问题。

## 二、体例约定

每一章都是同一个骨架，方便你跳读：

```
## N.M 章节标题          [难度标记]
### 目标             ——  读完能做什么
### 要点             ——  核心结论，先看这个
### 动手             ——  可运行的最小示例
### 自测             ——  3 道题，答不上就回去看要点
### 常见坑           ——  别人踩过的坑，你直接绕开
```

其他约定：

- **代码可直接运行**。默认 Python 3.10+，除标注外不依赖付费服务。
- **不写死密钥**。所有密钥从环境变量读，仓库里只有占位符。
- **模型名只是举例**。模型迭代很快，看到具体名字请以你本地能拉到的版本为准，思路不变。
- **图一律用文字/表格/ASCII 表达**，不使用任何带标识的图片。
- 数值（显存、吞吐、成本）都是**量级参考**，必须在你自己机器上实测一遍。

## 三、目录与进度

状态：`✅ 已写` ｜ `🚧 正在写` ｜ `⏳ 计划中`

| 文件 | 内容 | 章数 | 状态 |
|---|---|---|---|
| [00-开始之前.md](00-开始之前.md) | 学习方法、环境、术语表、30 分钟跑通 | 4 | ✅ 已完成 |
| [01-大模型与本地部署.md](01-大模型与本地部署.md) | 原理速通、选型评测、本地推理、量化显存、本地vs云端 | 7 | ✅ 已完成 |
| [02-提示工程与应用骨架.md](02-提示工程与应用骨架.md) | 提示设计、结构化输出、可靠性、工程骨架 | 4 | ✅ 已完成 |
| [03-LangChain与编排.md](03-LangChain与编排.md) | LCEL、LangGraph、上下文工程、框架选型 | 5 | ✅ 已完成 |
| [04-RAG.md](04-RAG.md) | 解析切分、向量库、混合检索、高级RAG、评估、生产化 | 8 | ✅ 已完成 |
| [05-Agent与工具.md](05-Agent与工具.md) | Agent 范式、工具设计、护栏、多智能体、评估 | 7 | ✅ 已完成 |
| [06-MCP.md](06-MCP.md) | 协议、传输、原语、写服务、接客户端、安全 | 7 | ✅ 已完成 |
| [07-工程化与上线.md](07-工程化与上线.md) | 服务化、前端、观测、性能、评测、安全、部署 | 7 | ✅ 已完成 |
| [08-综合实战.md](08-综合实战.md) | 知识库问答、分析 Agent、文档流水线、离线部署、MCP 工作台 | 5 | ✅ 已完成 |
| [09-收尾.md](09-收尾.md) | 43 条坑手册、30 天计划、进阶方向 | 3 | ✅ 已完成 |
| [附录.md](附录.md) | 安装速查、显存估算表、提示词模板、工具 Schema、评估规范、参考资料 | 6 | ✅ 已完成 |

**当前进度：57 / 57 章 + 6 个附录 —— 全书完稿**

代码目录：[`code/`](code/)（`requirements.txt` + 每章示例，可直接 `python` 运行）

## 四、环境一句话

```bash
# 1) 装依赖（推荐 uv，也可以用 python -m venv + pip）
uv venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
uv pip install -r code/requirements.txt

# 2) 起一个本地模型服务（二选一）
ollama serve                              # 轻量：先用这个
# 或者 vLLM（生产吞吐）：vllm serve <模型> --max-model-len 32768

# 3) 验收：能流式吐字就说明链路通了
python code/00_hello_local.py
```

## 五、学习纪律（重要）

1. **每章必须跑一遍代码**。看懂 ≠ 会写，跑通才有肌肉记忆。
2. **每章末尾的「自测」必须答**。答不上就是没掌握，回去看「要点」。
3. **每个概念都问一句"它解决什么问题、代价是什么"**。AI 领域名词更新极快，能辨明取舍的人才不会被名词牵着走。
4. **优先修坏掉的东西**。第 4 部分 RAG 的失败排查树、第 5 部分的护栏、第 7 部分的坑手册，都是实战最先用到的部分。

## 六、实测环境与验证情况

书中的代码不是"写完就发"，能跑的都在真实环境里跑过一遍。当前验证环境：

| 项目 | 配置 |
|---|---|
| 系统 | Windows 11 |
| Python | 3.13（书中要求 3.10+，均已兼容） |
| 显卡 | 6 GB 显存级 |
| 推理服务 | 本地轻量引擎，模型 `deepseek-r1:7b`（Q4） |

已验证的项目：

| 示例 | 结果 |
|---|---|
| `code/00_env_check.py` | ✅ 正确识别 GPU、显存、端口占用、缺失依赖 |
| `code/00_hello_local.py`（流式对话） | ✅ 正常流式输出 |
| `code/00_hello_local.py --tool` | ✅ 运行正常，并如实暴露"该模型不支持函数调用"这一现象 |
| `code/01_ollama_chat.py --long` | ✅ 输入 ~4800 token：8192 命中、2048 返回 400（已写入 1.4 实测记录） |
| `code/01_vram_calc.py` | ✅ 权重 + KV + 开销的估算与手算一致 |
| `code/01_router.py --demo` | ✅ 三档路由与降级链路按预期工作 |
| `code/01_bench_eval.py` | ✅ 12 道题实跑：输出上限 512 → 75.0%，1024 → 91.7%（已写入 1.2 实测记录） |
| `code/02_prompt_lab.py` | ✅ 3 用例 × 3 写法：弱写法 0/3、强写法 2/3、分隔符写法 3/3（已写入 2.8 实测记录） |
| `code/02_structured_output.py` | ✅ 走通"提取 → 校验 → 错误回灌 → 重试"链路 |
| `code/02_tool_schema.py --dry-run` | ✅ 参数校验、并行执行、幂等去重全部按预期 |
| `code/02_reliable_client.py --selftest` | ✅ 8/8 断言通过（429 重试、400 不重试、退避抖动、令牌桶、缓存、幂等、熔断） |
| `code/app_skeleton/`（含 `eval.py`） | ✅ 提示词 v1→v2→v3 实测：66.7% → 50.0% → **100%**（已写入 2.11 实测记录） |
| `code/03_lcel_basics.py` | ✅ 单链/并行/分支/回退/流式全部跑通（离线 + 真实模型） |
| `code/03_langgraph_agent.py` | ✅ ReAct 循环、thread_id 状态延续与隔离均正确 |
| `code/03_chat_tools.py` / `03_context_budget.py` | ✅ 工具循环、上下文裁剪决策按预期输出 |
| `code/04_17_diagnose.py` ~ `04_24_production.py` | ✅ 8 个章节脚本全部实跑：切分实验、混合检索对比、评估、权限/增量/缓存/延迟拆解 |
| `code/rag/`（小型 RAG 库） | ✅ Qdrant 内存 + 离线哈希嵌入全链路跑通，41 个脚本 0 编译失败 |
| `code/05_25` ~ `05_31`（Agent 7 章） | ✅ 全部实跑：链 vs Agent、三范式对比、工具设计、护栏四场景、多智能体成本、沙箱 7 例、轨迹评估 |
| `code/agent/`（Agent 集成库） | ✅ 工具注册表 / 护栏审批 / 三范式 / 轨迹 / 沙箱；全仓 55 个脚本 0 编译失败 |
| `code/06_32` ~ `06_38`（MCP 7 章） | ✅ 手写协议端到端跑通；**手写客户端成功连上官方 SDK 服务端**（协议兼容已验证）；安全四类攻击演示 |
| `code/minimcp/`（手写 MCP 实现） | ✅ 服务端 + 客户端 + 两个服务端样例；全仓 66 个脚本 0 编译失败 |
| `code/07_39` ~ `07_45`（工程化 7 章） | ✅ 全部实跑：SSE 流式 TTFT 150ms、取消生效、限流 429、埋点看板、缓存 193ms→0.002ms、并行工具省 58%、门禁拦下改坏版本 |
| `code/service/`（服务骨架） | ✅ FastAPI + SSE + 埋点 + 缓存 + 门禁 + 灰度；全仓 79 个脚本 0 编译失败 |
| `code/projects/p46` ~ `p50`（5 个实战） | ✅ 全部 exit=0：知识库问答（含评估与权限）、数据分析（含图表与意图拦截）、文档流水线（幂等/复核/增量）、离线包（校验和/篡改检测）、MCP 工作台（命名空间/租户） |
| `code/09_troubleshoot.py` | ✅ 43 条坑可按分类/关键词/编号检索，带章节出处 |
| `code/09_plan30.py` | ✅ 30 天计划可看/可标记/可重置（进度落盘） |
| `code/appendix_readiness.py` | ✅ 8 维度 24 项打分，输出就绪度报告与三个短板 |
| 全仓规模 | ✅ **88 个脚本 0 编译失败** |

### 最终冒烟测试（全仓 48 个可离线脚本）

| 结果 | 数量 | 说明 |
|---|---|---|
| 通过 | **45** | 全部 `exit=0` |
| 需要参数的 | 2 | `01_vram_calc.py`、`appendix_readiness.py --self`（不带参数会等输入） |
| 需要交互/外部服务的 | 1 | `04_17_diagnose.py`（交互问答）、外加 `01_bench_eval.py`/`01_ollama_chat.py`/`00_hello_local.py`/`01_vllm_bench.py` 需真实模型或推理服务 |

上述"需要参数"的三个都已用正确参数单独验证通过（见附录 B、E 与 4.17）。

**因硬件缺失暂未实跑**（写法按官方文档，且已标注需自测）：`code/01_vllm_bench.py`（需高性能引擎与多卡环境）。

**第 4 部分最重要的实测发现**（细节见 4.21）：混合检索**不是无条件变好**。当向量通道用的是弱嵌入时，它贡献的是噪声，「BM25 + 噪声」的 MRR（0.579）反而低于纯 BM25（0.778）；而加上重排后回到 0.833。**融合会把两路的错误也一起融合**——上混合前必须先单独测两路。

**第 5 部分最重要的实测发现**（细节见 5.26 / 5.31）：

- 同一个"第一次参数写错"的坑：ReAct 成功但 11 步最啰嗦；Plan-Execute 5 步最省事但**整单报废**（不会改计划）；Reflexion 成功但 token 翻近一倍（131 vs 68）。
- 多智能体做同一件事花了 **222 token vs 单 Agent 33 token**（6.7 倍），换到的只是"子任务可并行"。
- **Agent 自报成功率 0.833，客观成功率只有 0.667**——差的那条是"模型不查数据直接编答案，还说自己成功"。**成功标准必须外部化。**

**第 6 部分最重要的实测发现**（细节见 6.35 / 6.37）：

- **协议本身极简**：JSON-RPC 2.0 + 每行一个 JSON，20 行就能实现一个能跑的服务端。
- **手写客户端成功连上官方 SDK 服务端**（`mcp 2.3.0`），握手/tools/resources/prompts 全通——说明协议是真正的"标准"，不是某家的私有格式。
- **一个真实的坑**：教学包最初建在 `code/mcp/`，结果把官方 `mcp` 包遮蔽了，`import mcp.server.mcpserver` 直接失败。**永远不要用依赖的名字给本地包命名**（最终改名为 `minimcp`）。
- **MCP 2.x 把 `FastMCP` 改名为 `MCPServer`**，网上大量 1.x 教程的导入路径已失效。
- **安全**：工具投毒能把完整注入塞进系统提示（实测"天真宿主"原样透传）；清洗能命中 6 条规则但仍属启发式；**真正的防线是白名单 + 指纹 + 命名空间 + 最小权限**。

**第 7 部分最重要的实测发现**（细节见 7.39–7.45）：

- **流式的价值可量化**：SSE 首字 **150ms**，整段返回要等约 450ms；取消能真正传导到上游（`gen.close()` 后生成器状态变为"已关闭"）。
- **缓存是数量级差异**：真调模型 **193ms/次** vs 缓存读取 **0.002ms/次**；但语义缓存对不同问法会答错——**缓存键必须含 user/tenant，否则是数据泄露**。
- **并行工具省 58%**（601ms → 252ms），前提是工具彼此独立。
- **门禁要双条件**：只有绝对门槛会让人在"及格线附近一路下滑"；实测基线 25% → 新版 100% 通过，改坏版本 0% 被拦。
- **踩到一个真实正则坑**：PII 脱敏先匹配身份证再匹配卡号，会把 19 位卡号切成 `<身份证>3`——**看着脱敏成功，其实泄露了两位数字**。改用一次扫描的交替式正则（长模式在前）修复。

**第 8 部分最重要的实测发现**（细节见 8.46–8.50）：

- **语料范围会伪装成"能力提升"**：只看 1 篇文档的租户 hit@1=1.000，全库只有 0.583。**报指标必须带语料范围。**
- **"没抽到"和"抽错了"是两种问题**：文档流水线里 6 个文件有 2 个进复核队列（缺订单号）、1 个进错误队列（空文件），只有 3 个正常入库；改一个文件后**只重处理 2 个**。
- **规则/模板必须"具体→泛化"排序**：否则"每个城市的销售额"会被"销售额"规则抢先命中，返回门店维度。
- **意图检查要早于 SQL 生成**："把 orders 表删了"在自然语言层就被拦，连 SQL 都没生成。
- **目录实际是 57 章不是 53 章**：最初汇总表相加算错（各分部合计 57），已修正 README 与目录文件。

教程里所有"数值"都标注为**量级参考**——因为不同机器差异极大。**你的第一次实测，比读十遍文档有用。**

---

## 七、全书交付清单

| 项 | 数量 |
|---|---|
| 正文部分 | 10 个部分（0–9） |
| 正文章节 | **57 章** |
| 附录 | 6 个（A–F） |
| 中文字数 | 约 **4.8 万字** |
| 可运行脚本 | **88 个** |
| 可复用库 | `rag/`（9 模块）、`agent/`（7 模块）、`minimcp/`（4 模块）、`service/`（5 模块） |
| 端到端项目 | 5 个（`projects/p46`–`p50`） |
| 标识/水印/署名 | **无**（封面、页眉页脚、代码注释均无） |

### 建议的阅读入口

- 第一次来：从 [00-开始之前.md](00-开始之前.md) 的 0.4 开始，先跑通一个闭环。
- 只想解决问题：查 [09-收尾.md](09-收尾.md) 的 43 条坑手册，跑 `code/09_troubleshoot.py --search <现象>`。
- 要上线：过 [附录.md](附录.md) 的附录 E.4 就绪度自检。
- 想照着做完一个系统：直接看 [08-综合实战.md](08-综合实战.md)，五个项目都能跑。