mm_agent_tutorial

基于多模态理解生成模型的智能体构建教程（目录）

目标：从“多模态模型 + 工具调用 + 协作协议 + 评测与蒸馏”出发，系统讲清楚如何设计、实现、评估并部署可落地的多模态智能体（Multi-modal Agent）。

文件组织：index.md + chapter1.md + chapter2.md + …（每章独立可阅读；案例章可选读）

阅读路线

快速入门（2~3 小时）：第 1、3、4、7、10、11 章
工程落地（1~2 周）：第 1~10 章 + 你最相关的案例章（第 11~17）
研究/训练/蒸馏（2~4 周）：第 8~10 章 + 第 18 章 + 附录 C/D

第一部分：多模态 Agent 通用方法论（Ch1–Ch10）

第 1 章多模态智能体概览

1.1 什么是多模态 Agent：从“模型”到“系统”
1.2 典型能力边界：看懂/听懂/读懂 vs 真的“会做”
1.3 参考架构总览：LLM/VLM + Tools + Memory + Policy
1.4 常见应用形态
- 1.4.1 文档理解（PDF/截图/表格）
- 1.4.2 代码与软件工程
- 1.4.3 具身与自动驾驶（VLA）
- 1.4.4 多模对话与人机协作
1.5 关键工程挑战：可靠性、成本、延迟、可控性、评测
1.6 “智能体能力”拆解：感知 → 推理 → 决策 → 执行 → 反馈
1.7 本教程的统一术语与符号约定（含多模内容表示）
1.8 本章练习：用最小闭环搭一个“看图+查资料+写总结”微型 Agent

第 2 章多模态输入输出与上下文管理

2.1 多模态数据形态与难点
- 2.1.1 图像：分辨率、裁剪、patch/token 成本
- 2.1.2 音频：ASR、端点检测、说话人分离（可选）
- 2.1.3 视频：采样策略、关键帧、时间对齐
- 2.1.4 文档：PDF 版面、表格、公式、图注、页码引用
2.2 上下文窗口与预算：token/latency/cost 三角
2.3 多模态“可读化”：从原始输入到可推理表示
- 2.3.1 视觉摘要（caption/region notes）
- 2.3.2 版面结构（layout tree）
- 2.3.3 表格结构化（rows/cols/cells）
2.4 片段化与分层：Chunk / Section / Document / Corpus
2.5 长文档策略：Map-Reduce、Refine、Query-focused reading
2.6 引用与可追溯：页码、段落、坐标、证据片段
2.7 常见坑位清单：丢图/错表/断章取义/引用漂移
2.8 本章练习：同一 PDF 用三种读取策略对比质量与成本

第 3 章 Tool Call：工具调用设计与编排

3.1 为什么需要 Tool：从“回答”到“行动”
3.2 Tool Call 基础模式
- 3.2.1 函数签名（schema）与参数校验
- 3.2.2 工具输出注入（tool result）与上下文污染
- 3.2.3 同步/流式/并行调用（工程视角）
3.3 工具路由（Tool Routing）
- 3.3.1 规则路由 vs 模型路由 vs 混合路由
- 3.3.2 工具选择的可解释性与可控性
3.4 失败恢复与重试策略
- 3.4.1 幂等（idempotency）与副作用管理
- 3.4.2 超时、限流、降级、熔断
3.5 工具安全：最小权限、沙箱、输入净化、输出过滤
3.6 常见工具族谱（按能力分层）
- 3.6.1 浏览器/检索
- 3.6.2 代码执行/Notebook
- 3.6.3 文件系统/对象存储
- 3.6.4 数据库/向量检索
- 3.6.5 多模态工具（PDF 渲染、表格抽取、图表解析）
3.7 本章练习：为“研究 Agent”设计一组可扩展工具 schema

第 4 章 Agent Loop：规划-执行-反思的闭环

4.1 智能体控制循环：Observe → Think → Act Reflect
4.2 典型范式
- 4.2.1 ReAct（推理-行动交织）
- 4.2.2 Plan-and-Execute（计划与执行解耦）
- 4.2.3 Reflexion（自我反思与修复）
- 4.2.4 Tree/Graph of Thoughts（分支搜索）
4.3 任务分解：子任务、依赖、里程碑、验收标准
4.4 预算感知（Budget-aware）：成本/时间/工具配额
4.5 终止条件：何时停、何时求助人类、何时 handoff
4.6 结构化输出：报告、代码补丁、行动计划、工单
4.7 本章练习：给同一任务实现两种 loop 并对比指标

第 5 章记忆与知识：RAG、多模态检索与状态管理

5.1 记忆类型：短期/长期/会话外存储
5.2 RAG 的正确打开方式（尤其在多模态场景）
- 5.2.1 文本检索 vs 图文检索 vs 结构化检索
- 5.2.2 查询改写（Query rewriting）
- 5.2.3 证据融合与冲突处理
5.3 状态机与工作记忆：任务状态、工具状态、用户偏好
5.4 个性化与隐私：该记什、不该记什么
5.5 “遗忘/更新”策略：过期知识、版本控制、回滚
5.6 本章练习：为座舱机器人设计“可审计的个性化记忆”

第 6 章 Agent Handoff：任务移交与协作协议

6.1 Handoff 的动机：能力边界、责任边界、产品边界
6.2 Handoff 的类型
- 6.2.1 同构移交（同类 Agent 间）
- 6.2.2 异构移交（研究→执行、对话→检索、感知→控制）
- 6.2.3 人类移交（Human-in-the-loop）
6.3 上下文打包：handoff packet 设计
- 6.3.1 目标、约束、已完成工作
- 6.3.2 证据与引用（可验证）
- 6.3.3 风险与不确定性声明
6.4 协作中的冲突：版本、事实、权限、优先级
6.5 评估 handoff：成功率、时延、信息损失、用户体验
6.6 本章练习：把“DeepResearch 结论”移交给“写作 Agent”生成报告

第 7 章 OpenAI Harmony 格式与多模态消息协议

7.1 为什么需要统一协：可移植、可观测、可评测
7.2 消息结构（概念层）
- 7.2.1 role / content parts（text/image/audio）
- 7.2.2 tool call / tool result 的边界
- 7.2.3 系统提示、开发提示、用户提示的职责划分
7.3 多模态 payload 的组织
- 7.3.1 图片引用、分辨率策略、局部标注
- 7.3.2 文档页引用（page index / bbox）
7.4 Harmony 与多智能体：如何表达“转交/协作/仲裁”
7.5 协议兼容性：日志、trace、训练数据的可复用
7.6 本章练习：把一段多轮对话+工具调用导出成标准化 trace

第 8 章 Multi-Agent：从单体到群体协作

8.1 多智能体的收益与成本：质量、鲁棒性、费用、延迟
8.2 常见组织结构
- 8.2.1 Manager–Worker（经理-工人）
- 8.2.2 Specialist Swarm（专家群）
- 8.2.3 Debate / Critic（辩论-审稿）
- 8.2.4 Blackboard（共享黑板）
8.3 协作协议设计：任务分配、接口、验收、仲裁
8.4 多态协作：视觉专家、文档专家、代码专家、控制专家
8.5 资源调度：并行、优先级、动态扩缩容
8.6 本章练习：用“三专家 + 审稿人”提升 PDF 研究任务正确性

第 9 章与仿真系统互动：闭环、采样与安全

9.1 仿真环境的价值：可控、可重复、可规模化
9.2 环境接口设计：Observation / Action / Reward / Done
9.3 部分可观测与不确定性：belief state 与信息收集动作
9.4 多模态观测：相机、地图、日志、传感器、HUD/仪表
9.5 安全护栏：动作约束、规则引擎、紧急刹车、回放审计
9.6 数据采集：轨迹、失败案例、边界条件
9.7 本章练习：用“仿真回放 + 工具调用”构建可复现 bug case

第 10 章 Trace 构造、蒸馏与 Benchmark 评测体系

10.1 为什么要 trace：调试、回归、训练数据、合规审计
10.2 Trace 的最小字段集（建议 schema）
- 10.2.1 观测动作、工具输入输出、时间戳、版本号
- 10.2.2 证据片段与引用（用于可验证回答）
10.3 用于蒸馏的 trace：从“过程数据”到“训练样本”
- 10.3.1 行为克隆（imitation）
- 10.3.2 偏好数据（pairwise / rubric）
- 10.3.3 自监督/合成数据（self-play / critique）
10.4 常见 Benchmark 版图（按能力分层）
- 10.4.1 工具使用与 Web 交互类
- 10.4.2 代码修复与软件工程类
- 10.4.3 多模态理解（文档/图表/图像问答）类
- 10.4.4 具身/驾驶/控制类
10.5 评测方法学：离线评测、在线 A/B、红队、回归测试
10.6 指标设计：成功率、成本、时延、稳定性、可解释性
10.7 本章练习：搭建一个“可回放、可打分、可回归”的评测管线

第二部分：典型多模态智能体案例（Ch11–Ch17）

每个案例章遵循统一模板：目标与边界 → 架构 → 工具与数据 → 关键算法/策略 → 评测 → 工程化 → 展练习

第 11 章 DeepResearch 智能体：多模态研究与长文档 PDF

11.1 任务定义：从问题到“可引用的结论”
11.2 文献/网页/内部资料的统一采集层
11.3 多模态 PDF 处理流水线
- 11.3.1 页渲染、版面解析、图表与表格抽取
- 11.3.2 图注/表注对齐与跨页引用
- 11.3.3 结构化索引：章节树 + 证据库
11.4 研究策略：检索计划、证据竞争、冲突消解
11.5 引用系统：可点击证据、页码定位、引用去重
11.6 多智能体协作：检索员/阅读员/审稿员/写作员
11.7 失败模式：幻觉引用、断章取义、过度概括
11.8 扩展练习：把研究结果导出为报告/PPT/知识图谱