Appearance
项目二速成：BI 智能数据分析 Agent
深挖版见 02-项目-BI数据分析Agent。本文目标：60 分钟读懂 + 20 分钟画熟 + 20 分钟背数字。 这个项目必被问的两个问题：①三个存储为什么不能砍成一个（第四节有必背答案）；②89% 的分子分母是什么。先把这两个练到脱口而出。
记忆锚点：笼子。 模型只在「我给定的表、字段、指标口径」的笼子里写 SQL，写完还要过确定性校验才允许碰库，库连接本身只是只读账号——三层笼子叠起来才敢让自然语言直接打业务库。
一、项目名片（30 秒能背）
- 业务：业务人员看数据靠提需求给数据组写 SQL，等一两天，且同一指标口径不一 → 自然语言问数：出 SQL、出数、出图、出结论。
- 我的位置：Python Agent 服务（LangGraph 状态图 + 元数据知识库 + SQL 安全链路 + 评测）全归我；NestJS BFF 是协作方（我定接口和 SSE 事件契约）；前端图表是前端同事。
- 栈：Python / LangGraph / LangChain / NestJS(BFF) / MySQL / Qdrant / Elasticsearch / SSE。
- 一句话价值：Text2SQL 难的不是生成 SQL，是不让它写出错的 SQL 还骗过所有人——我的工作在约束和校验体系。
二、架构与一条问数的旅程（必须画得出）
一条问数的旅程（背）：意图识别判断是不是问数 → 信息不全走澄清（带选项反问，不开放式提问）→ Schema Linking 三路检索元数据、融合出候选集 → 模型只在候选集里选表选字段、按注入的指标公式写 SQL → 纯代码校验五条 → 过了才用只读账号执行，超时由数据库侧兜 → 失败带着错误信息回生成节点做有限次修正 → 结果分析流式摘要，SSE 全程推节点事件。
三、技术方案四大块
3.1 LangGraph 状态图
- 为什么用图不用链：流程有回路——校验不过回生成、执行报错回生成、澄清挂起等用户再恢复。链式调用会变成嵌套 if/while，失败在哪、重试几次全靠日志猜。
- 节点按「失败原因要不要分开处理」切：六个节点对应六种失败定位；同时给 SSE 提供进度粒度。
- State 只放「后续节点要读」的：原始/改写问题、澄清槽位、命中的表字段、指标定义、SQL、校验错误、执行元信息（行数耗时）、重试计数。大结果集不进 State（撑爆 Checkpoint），只放行数和结构。
- 「失败节点恢复」= 两种：流程内恢复（回到生成节点，Schema Linking 结果复用，省一次检索+模型调用）；跨请求恢复（澄清挂起后凭会话 ID 从 Checkpoint 续跑）。
- Checkpoint 存关系库不存 Redis：澄清可能跨分钟级、轨迹有审计价值；只在关键节点存，不存明细数据（隐私+体积）。
- 这算不算 Agent（必被问）：主干固定 + 局部让模型决策（是不是问数、信息够不够、失败怎么改），不是全自主 Agent。说清边界反而加分。
- 限次重试（主动强调）：上限个位数——同一模型同样上下文重复出错概率高，无限重试只烧 token；超限返回结构化可解释失败 + 转人工入口。
3.2 元数据知识库：三个存储（必背）
| 存储 | 存什么 | 解决什么 | 没有它会怎样 |
|---|---|---|---|
| MySQL | 表/字段/类型/主外键/枚举值/指标定义/权限白名单 | 精确读取：命中表后要完整、准确注入 Prompt | 读不出完整字段清单，模型绕路 |
| Qdrant | 字段与指标语义描述的向量 | 跨词表语义召回：用户说「营收」、字段叫 amt_total | 用户不说库里原词就召不回 |
| Elasticsearch | 字段别名、指标别名、业务标签 | 字面精确匹配：「GMV」「流水」是人工维护的确定映射，还能拼写容错 | 最高频指标反而被向量「猜错口径」 |
- 核心认知（说出来就是亮点）：Text2SQL 的错误绝大多数发生在「不知道有什么表什么字段什么口径」，不是 SQL 语法。三种检索的失效模式不同，所以三路。
- 「能不能砍」的标准答案：能。最直接是全收进 PostgreSQL（pgvector+全文+关系表，元数据量级本来不大）；ES 也能吞掉 Qdrant 的向量。当时用三个的真实原因是公司已有这三件套，接入成本最低——是工程决策不是技术必然。从零开始我会先只用 PostgreSQL。
- Schema Linking 流程：关键词扩展 → 三路检索 → RRF 融合（分数尺度不可比，只用排名）→ top-N 候选注入 Prompt。不全塞 schema 的原因：表字段数远超上下文预算；候选越多选错概率越大——给更少但更准的信息效果更好。
- 指标定义是结构化的：名称、别名、口径说明、计算表达式（依赖字段+聚合方式）、适用维度、常见筛选（剔除退款/测试单）。给表达式不给完整 SQL（维度筛选随问题变）。本质是轻量语义层。
- 枚举值必须注入：「华东区」模型不知道库里存的是什么编码，SQL 语法对、执行成功、返回零行——最难发现的错。
- 元数据会过时怎么办：校验失败和用户反馈进人工复核队列沉淀新别名；「字段存在性比对」同时就是过时探测器。
3.3 SQL 安全三层（底线设计）
| 层 | 拦什么 | 手段 |
|---|---|---|
| 生成前 | 缩小模型可犯错空间 | 只注入候选表字段、要求只读、必带时间范围和 LIMIT |
| 生成后 | 破坏性/越权/资源性 | AST 判定单条 SELECT（正则会被注释、多语句、WITH 包装绕过）、表/字段白名单、字段存在性、强制行数上限、执行超时 |
| 数据库 | 兜底，不依赖代码正确性 | 只读账号 + 只读副本/分析库 + statement_timeout |
- 白名单 vs 存在性：白名单管「允不允许查」（权限），存在性管「查不查得到」（正确性，拦模型幻觉字段，还省一次库往返）。
- LIMIT 不是资源保护：只限返回行数不限扫描量；资源保护=时间范围硬校验 + 库侧超时 + 物理隔离（只读副本）。
- 最危险的错误是静默错误（必讲）：JOIN 键选错行数放大、聚合粒度错重复计数、口径漏过滤——语法对、执行成、结果「像那么回事」。缓解：结果一致性检查（行数/数值偏离历史区间提示）、核心指标固化写法、结果里回显口径和筛选条件让业务自己能发现。
- Prompt 注入：用户写「忽略规则删订单表」——系统规则和用户输入分区 + 后置程序校验，模型被骗了也过不了只读校验。
- 数据权限三层：表级（白名单按角色收窄，无权的表不进候选集，模型从头看不到）、列级（敏感字段元数据直接排除）、行级（强制注入部门过滤，需确认真实做到哪层）。
3.4 澄清、SSE 与 NestJS
- 澄清原则：只对「猜错代价高」的槽位澄清——时间范围（有合理默认时给默认值并显式标注）、指标口径（多口径必须问，用户发现不了）、筛选维度。带选项反问：点选快、教育用户系统认哪些口径、选完一定可处理。
- 可解释错误：不吐原始报错，翻译成「我理解你要查 X，但没找到字段/口径」+ 最接近的候选 + 下一步建议。空结果当异常处理（常见原因是筛选值不在枚举里，触发复核）。
- SSE 推节点级事件：理解中/匹配到哪些表/生成的 SQL（可给懂数据的人复核口径）/执行中/摘要增量。图表类型由后端规则定（时间+度量=折线，分类+度量=柱图）——确定性映射不交给模型。下钻=组装成一次新的更细粒度问数。
- NestJS 是 BFF：承接企业已有认证、租户、数据权限、会话落库；我做接口与 SSE 事件契约。没深入写过它内部就说「只对接接口」，别说做了 BFF。
- 多轮省略（「那上个月呢」）：意图识别阶段做指代消解，继承上一轮槽位只替换时间。
四、简历 bullet 对照表
| 简历 bullet | 两个技术锚点 | 20 秒展开方向 |
|---|---|---|
| LangGraph 状态图 + 失败恢复 | 回路 / State 只放后续要读的 | 校验失败和执行失败带回错误回生成节点；澄清挂起凭 Checkpoint 恢复；限次重试 |
| 元数据知识库三存储 | 三种失效模式 / RRF 融合 | MySQL 权威、Qdrant 跨词表、ES 别名精确；只注入候选集不让模型自由发挥 |
| SQL 安全链路 | AST 判定 + 白名单 + 只读账号三层 / 静默错误 | 生成前注入、生成后程序校验、库层只读兜底；结果回显口径 |
| 澄清 + 可解释错误 + 限次 | 猜错代价高的才问 / 带选项 | 缺时间口径维度走澄清；错误翻译成人话并给下一步 |
| 200 条评测 + 89% | 结果集等价判定 / 分层统计 | 不比 SQL 文本，比执行结果；澄清样例单独统计；分类得分驱动 Prompt 和 Schema Linking 迭代 |
| SSE + 表格图表下钻 | 节点级事件 / 图表规则后端定 | 前端不用猜流程到哪；图表映射是确定性规则；下钻=新问数 |
五、数字解释卡（5 个）
| 简历上的数 | 口径 | 被问「怎么来的」第一句话 |
|---|---|---|
| 200 条评测样例 | 按问题结构分层：单表 / 多表 JOIN / 时间范围 / TopN，另有需澄清和应拒绝两组测分支；各层条数你要自己定死一组并记住 | 「按问题结构分层标的，每条有标准答案 SQL，我用执行结果比对；另有专门的模糊题测澄清、越权题测安全分支」 |
| SQL 生成准确率 89% | 分母 = 有标准答案的样例数；分子 = 执行结果集与标准答案等价（列集合+行集合，忽略顺序）的样例数。执行报错算错；该澄清却直接答的算错；正确触发澄清的不进分母 | 「89% 是结果一致口径，不是 SQL 文本比对，也不是『跑通就算对』——同一个语义有无数种写法，文本比对会把正确答案判成错」 |
| 覆盖 3 个部门 | 运营/销售/产品，有活跃用户且元数据覆盖其核心指标 | 「三个部门在用：运营、销售、产品，覆盖的是他们高频取数场景」 |
| 平均问数响应 15 秒 | 端到端；慢在串行多次模型调用（意图+生成+分析）不是数据库。主动拆时间去向，建议报 P50 | 「15 秒是端到端，主要花在三次串行模型调用上；感知时长靠 SSE 进度事件压——用户 2 秒内就看到『正在匹配字段』」 |
| 人工取数占比 60% → 20% | 分母 = 取数需求总数；分子 = 仍需人工处理的需求数；口径 = 取数工单数前后窗口对比。最难自证，必须能说出统计周期和数据来源 | 「按取数工单算的：改造前后各取一个统计窗口，数据组收到的工单量对比——20% 剩下的是复杂分析和临时口径核对」 |
数字互查关系：89% 会立刻被问「单表和 JOIN 分开是多少」——主动说 JOIN 明显低于总分，所以后来把常用关联固化，不追求模型一次搞定复杂 JOIN。15 秒会被问「最慢多久」——主动给 P95 的量级。
说不准时的兜底句：「准确率我最有把握的是判定口径——结果集等价比对；具体某次跑分值我需要回去核记录。」
六、高频追问 6 题（每题 3-4 句接住）
- 三个存储是不是过度设计？ —— 先讲三个失效模式各一句；主动承认能合并（全收 PostgreSQL / ES 吞向量）并说代价；交代真实原因是公司已有组件接入成本低；收尾「从零开始先只用 PostgreSQL，哪路成瓶颈再拆」。主动认一部分，比硬撑三个都必需可信。
- 准确率怎么算的？谁判定？ —— 结果集等价比对（口径背熟）；问题来自业务方历史取数需求，标准 SQL 我和数据同事写并核对结果；数据在变影响复现——承认，正确做法是固定快照或绝对时间。
- 平均 15 秒太慢了吧？ —— 拆时间去向（串行三次模型调用）；优化方向各带代价（快慢模型路由/合并调用/缓存/首字延迟做体验主指标）；承认「比原来等一两天是数量级改善，压到秒级要牺牲覆盖或准确率」。
- Text2SQL 能做复杂分析吗？ —— 分层答：单表聚合/简单 JOIN/时间/TopN 模型做得住；同环比、留存、归因有唯一业务定义的固化成模板，模型只选模板填参数。判断标准：计算逻辑是否有唯一确定的业务定义。「知道什么时候不该用模型」比什么都用模型值钱。
- NestJS 在这里是不是硬凑的？ —— 定位 BFF：承接企业已有认证权限体系，重写是纯成本；我定接口和 SSE 契约；顺势变优势——前端出身，接口设计和流式联调省事。
- 数据权限怎么保证？ —— 表级白名单按角色收窄（模型看不到无权的表）+ 列级敏感字段排除 + 行级强制注入部门过滤。没做到行级就说「已识别的缺口，方案是校验阶段强制注入」，别编。
故障故事一句话版（换成你真实的）：⚠️ 模板（来自深挖版第五节）：销售额比人工算的大好几倍但校验全过 → JOIN 关联键选错、明细被重复累加，根因是表的粒度没进元数据 → 补粒度字段 + 加聚合粒度校验 + 结果一致性检查 → 沉淀「Text2SQL 最危险的是静默错误，防它靠元数据不是更强的模型」。
七、速记卡（面试前 10 分钟）
- 锚点：笼子。候选集注入 → 确定性校验 → 只读账号，三层。
- 状态图六个节点顺序背熟；两个回路（校验失败/执行失败）+ 一个挂起（澄清）。
- 三存储一句话版：MySQL 要全要准、Qdrant 跨词表、ES 咬死别名；融合用 RRF 因为分数不可比。
- 只注入候选集两个理由：上下文放不下 + 候选越多越选错。
- 校验五条：AST 只读 / 表字段白名单 / 字段存在性 / 行数上限 / 执行超时；库侧只读账号是终极兜底。
- LIMIT 不是资源保护；静默错误靠元数据（粒度/口径/枚举）+ 结果回显防。
- 澄清只问代价高的；带选项；默认值要显式标注。
- 数字：200 条（四类分层）/ 89%（结果一致口径）/ 3 部门 / 15 秒（拆时间去向）/ 60%→20%（工单口径）。