01. 项目介绍与成品演示
1. 项目简介
做一个能听懂运营问题、能查真实电商数据、过程看得见的数据分析 Agent。
运营 / 客服在对话里问，例如：
- 「上周手机壳类目销量怎样？」
- 「评价里大家吐槽什么？」
- 「要不要把某个商品标成待复核？」
系统先决定走结构化查询还是语义检索，再组织证据回答；涉及高风险动作时，要人工确认才执行。
本节不写代码：先对齐目标、技术栈和整课路线，后续各节再逐块落地。
2. 学完你能得到什么
- 一个可运行的全栈项目：FastAPI + Vue 3 + LangGraph + MCP + RAG
- 搞清「NL2SQL / RAG / 路由 / Agent 图 / 人工确认 / 可观测」各自解决什么问题，以及它们为什么必须配合
- 简历与面试能讲清：为什么不能直接执行模型生成的 SQL、模糊评价为什么要上向量检索、哪些动作必须挡住等人确认
3. 适合谁
| 适合 | 不太适合 |
|---|---|
| 有 Python 基础，想做 Agent 实战 | 完全没写过 Python |
| 想把 NL2SQL、RAG、LangGraph 串成一条业务链 | 只想调 Chat 接口、不关心工程约束 |
| 需要参加企业面试、有能写进简历里的项目 | 已有同类电商 Agent 经验、只想看论文 |
没有 Vue / FastAPI 也可跟学；脚手架账号体系会复用，本课重点在「数据诊断 Agent」这一层。
4. 技术栈
| 层级 | 技术 | 职责 |
|---|---|---|
| 前端 | Vue 3 + Element Plus | 对话、过程区、商品/订单/评价只读页、观测看板 |
| 后端 | FastAPI + SQLAlchemy + JWT | 业务 API、鉴权、SSE |
| 库 | MySQL 8 | 商品 / 订单 / 评价及观测表 |
| 向量 | Chroma（本地目录） | 评价等非结构化文本的语义检索 |
| 编排 | LangGraph | 路由 → 查询 → 深挖 → 决策 →（可选）确认执行 |
| 工具 | FastMCP（stdio 子进程） | 查 MySQL / Chroma / 历史运行 |
| 模型 | OpenAI 兼容接口 | 对话与 Embedding（可配 DeepSeek / 通义 / 硅基流动等） |
5. 课程地图
| 模块 | 内容 |
|---|---|
| 业务数据底座 | 环境准备、表设计与种子数据 |
| 查询能力 | SSE 对话骨架、NL2SQL、SQL 安全、向量检索、查询路由 |
| 图编排 | LangGraph 状态图、证据准备、多智能体调度 |
| 行动与确认 | 诊断报告与预警、人工确认门、并发与失败恢复 |
| 工具与可观测 | MCP Server/Client、运行历史与反馈 |
| 多模态与收尾 | 图片描述接入检索、前端管理页、整体走查 |
6. 效果演示：三条路径
每个示例给出提问原文与观察重点，分别覆盖系统的三条主要路径。演示基于课程示例数据；SQL 由模型生成，语义召回受向量模型与索引内容影响，具体返回以当次运行结果为准。问题措辞会影响查询方式：识别到商品名、订单号或数量与统计口径时走结构化查询，否则默认语义检索（规则在「查询路由」一集展开）。
示例 1：用自然语言查询数据库（结构化查询）
输入：洗衣液 2L 有哪些评价？
- 过程区依次显示：调度 → 查询分析 Agent（路由判断 → 结构化查询）→ 报告决策 Agent；这一步下面是本次生成的 SQL 原文，可以拿去数据库执行核对；
- 系统先判断「该走 SQL」，再生成 SQL 去查，而不是把问题直接丢给大模型；
- 回答涉及的评价可在「评价数据」页面逐条核对；本例只保存低风险报告，不进入确认流程。
延伸阅读：NL2SQL、SQL 安全校验（查询能力）。
示例 2：换一种说法也能搜到（语义检索）
输入：跑鞋脱胶
- 该商品那条带图 1 星评价原文写的是「鞋底开胶了」，与提问用词不同，仍被召回；
- 图片描述入库后，这条评价的检索文本带「晒图内容」标记——视觉模型生成的描述与正文一起参与检索；描述失败时索引保留纯文字评价，结果里就没有这个标记；
- 「距离」衡量相似程度（余弦距离 = 1 − 余弦相似度），越小越相似；「语义检索」页面可以直接看命中片段与距离。
延伸阅读：向量检索与索引、图片描述接入检索。
示例 3：高风险操作必须人工确认
输入：轻云运动跑鞋的差评有点多，看看并处理。
- 证据触发预警或待复核动作时，系统暂停整组业务动作，弹出「需要人工确认」卡片，卡片里列出待执行动作与判断依据；确认后执行整组动作，取消则跳过，两种结果都记入运行历史；
- 低分评价按商品分别累计，达到阈值才规划预警与待复核（阈值与计数口径在「动作决策」一集展开）；
- 写入结果在「诊断报告」页面查看：诊断报告与预警通知两个页签，未读可逐条或一次性标记已读。
安全边界：系统能做到的止步于「标记 + 通知」，真正的处置仍由人做——Agent 在商品表上唯一能改的是一个两值字段，价格、库存、上下架、订单状态全部只读。
延伸阅读：动作决策、人工确认与恢复（行动与确认）。
7. 多智能体协作：三个角色
一次问答不是一个大模型从头干到尾：三个角色落在同一张 LangGraph 上，各自负责一组节点，角色之间由调度节点按固定规则交接——所以过程可回看、每一步可独立替换。
| 角色 | 负责的步骤 | 可以做什么 | 不做什么 |
|---|---|---|---|
| 调度 | 流程启动、Agent 之间的交接 | 按预定义流程交接任务、更新当前角色 | 不查数据、不规划业务动作 |
| 查询分析 Agent | 路由判断 → SQL / 语义查询 → 深挖 → 证据准备 | 检索数据、整理证据 | 不决定写什么数据 |
| 报告决策 Agent | 动作决策 → 人工确认 → 执行 | 按规则规划动作、必要时请求确认、执行允许的写操作 | 不负责找证据 |
在界面上：每一步的标签显示当前是哪个角色在工作，两个角色之间会经过一次「调度交接」，示例 3 能完整看到这一次交接。
8. 能力全景
成品的能力按四条线拆开，每条都写明「解决什么问题」和「实现上的关键点」——后面各节就是把这些逐块做出来。
查询与检索
- NL2SQL：把「洗衣液 2L 有哪些评价」这类问题变成可执行的 SQL，而不是让模型凭上下文编数字。关键点：提示词里交代表结构与允许的写法，生成之后先解析、再执行。
- SQL 安全校验：所有查询进库前先过 SQLGlot 解析查询结构。关键点：只允许 SELECT，可查的表走白名单（商品 / 订单 / 评价 / 观测表），支持 JOIN、分组统计与子查询；不支持 CTE、UNION、跨库查询、变量、锁定读与优化器提示；结果最多 200 行，并设执行超时。
- 报错自纠：SQL 执行报错时把错误信息回喂给模型重试一次。关键点：只重试一次，仍失败就如实说明，不无限循环；统计类问题查不出来时明确说「给不出统计结论」。
- 向量语义检索：评价、商品描述这类非结构化文本向量化入库，按语义找相关片段。关键点：Chroma 本地持久化；距离 ≤ 0.5 判为相关；「语义检索」页面可以直接输入一句话看命中片段与距离——做 RAG 最容易糊弄自己的就是「看起来答对了」。
- 查询路由：先决定去哪查，再动手。关键点：点名商品、订单号、数量与统计口径走结构化查询，模糊主题走向量检索；判不出来时走兜底并说明，不硬猜。
- 多轮对话与指代消解：同一会话里接住上文（「那它的差评呢」）。关键点：短期记忆只在会话内生效，进模型前先把指代对象补齐。
- 输入兜底：空问题、超长输入、与业务无关的提问都要有明确回应，不把底层错误抛给用户。
编排与协作
- LangGraph 状态图：把路由、查询、深挖、证据准备、决策、确认、执行串成显式流程。关键点：节点各管一件事，状态在节点之间传递；循环与分支都有上限。
- 三角色协作：调度、查询分析 Agent、报告决策 Agent 分工——找证据的不写数据，写数据的不找证据。关键点：角色之间由调度节点交接，职责边界写死在流程里而不是靠提示词约束。
- 过程可见：把当前角色、阶段与工具调用实时推到前端。关键点：SSE 事件里带角色与节点标识，过程区按角色分色显示。
- 多来源证据合并：结构化查询结果、语义召回片段、历史运行都会进同一份证据。关键点：重复片段合并、标注来源，供回答时引用。
- 相关性判断：决定召回结果能不能当证据。关键点：距离阈值；纯语义证据不参与高风险动作的判断；统计类问题不拿评价片段冒充统计结果。
行动与安全
- 诊断报告：每轮问答自动落一条报告，记录问题、关联商品、风险等级、证据条数与摘要。关键点：低风险自动保存，摘要只留前 500 字，完整内容回对话页看。
- 站内预警与待人工复核：低分评价按商品分别累计，达到阈值才规划预警与待复核。关键点：这是 Agent 在商品表上唯一能改的东西——价格、库存、上下架、订单状态全部只读。
- 人工确认门：动作里只要包含预警或待复核，整组业务动作挂起，等人在对话页确认或取消。关键点：确认前一行写操作都不会发生；取消即整组跳过；两种结果都记入运行历史。
- 并发保护与失败恢复：两次点击不能变成两次执行。关键点：确认走单进程锁；模型总结失败或执行中断时回到待确认状态，不留半执行结果。
- 一键巡检：首页按钮，用最近的数据跑一遍诊断，一次给出高风险报告、站内预警与待复核商品。
工程与前端
- MCP 工具化：把系统能力做成标准工具（查 MySQL / 检索 Chroma / 查历史运行），由 FastMCP Server 提供，主程序以 stdio 子进程拉起。关键点：对话图里的查询走 MCP，而不是直接调内部 service。
- 运行历史与反馈：每次运行可回看问题、路由、状态、总耗时与逐步步骤；对回答点赞点踩。关键点：运行记录、步骤、反馈三张观测表与看板共用同一份数据。
- 观测看板：按阶段统计耗时，并给出成功率、失败数、未完成数与点赞率。关键点：瓶颈一眼可见——那次实测里数据查询 11.4 秒，而意图路由、风险判断、动作决策都在几十毫秒。
- 图片描述接入检索：晒图先由视觉模型转成中文描述，再与评价正文一起向量化，图片里的内容因此也能被检索到。关键点：描述失败时降级为纯文字，不中断入库。
- Vue 管理端与调试页：对话、运行历史、诊断报告、观测看板、商品 / 订单 / 评价只读页、语义检索调试与用户管理。