FDE W5 Day 5 学习手册 · Text2SQL 最小 Demo

W5 Day5 · B 级（重要，需熟练）· 3.5h · 学完能讲透"自然语言如何安全变成只读 SQL 并解释回给用户"

一、Text2SQL 定位：特药理赔场景里它做什么

Text2SQL（又称 NL2SQL）是把自然语言问题转换成可在数据库执行的 SQL 的任务。在特药理赔 Agent 里，用户常问"3 月我报的奥希替尼花了多少""哪些保单的特药额度还没用完"——这类结构化、可聚合的问题，最适合走 SQL，而不是 RAG 或硬编。

二、端到端流程全景

最小可运行的 Text2SQL 链路是一条线性流水线，每一步都有明确职责与失败点：

• 数据路由判断：先判断该问题是不是该走 SQL（详见 Day6），避免拿聊天问题去查库。
• Schema Linking：把"特药报销"映射到具体表/字段（claim、drug、amount）。
• 生成只读 SQL：大模型产出 SELECT 语句。
• SQL 安全校验：拦截一切非只读、越表、危险操作（核心防线）。
• 执行计划 & 超时：先看执行计划是否全表扫/超成本，再设超时。
• 执行：在受限账号/连接池里跑。
• 结果解释：把行集转成"您 3 月特药报销合计 ¥12,400"。

三、数据路由判断（上游闸门，Day6 详述）

进入 Text2SQL 之前，先要判断"这个问题到底该不该用 SQL"。简要规则：问题涉及聚合统计 / 条件筛选 / 跨表关联且数据在结构化库里 → 走 SQL；涉及知识条款 / 文档内容 → 走 RAG；涉及实时状态 / 写操作 → 走业务 API。判断不准会出问题：把"特药目录怎么规定的"拿去查库，必然查不到。

四、Schema Linking 原理（准确率命门）

Schema Linking 是 Text2SQL 的准确率命门：把用户话术里的实体/概念，对齐到数据库真实的表名、字段名、枚举值。

• 用户说"报销金额" → 锁定 claim.clm_amt 而非 claim.paid。
• 用户说"奥希替尼" → 锁定 drug.name='奥希替尼'，不是模糊 LIKE。
• 用户说"上个月" → 锁定 claim.clm_date BETWEEN 上月首日 AND 上月末。

五、Schema Linking 工程做法：给模型喂对上下文

要让 Linking 准，关键在给模型喂对上下文。三个数据源：

5.1 元数据 / 数据字典

从 INFORMATION_SCHEMA 或自建数据字典抽取表结构：表名、字段名、类型、注释、主键外键、枚举取值。这是 Linking 的"地图"。

5.2 表注释 / 字段注释（中文注释尤其重要）

保险库里字段常是英文缩写（clm_amt），但业务词是中文。把中文注释写进 prompt，让模型知道 clm_amt = 理赔金额。你们 Java+大数据背景最熟：建表时就该有 comment。

5.3 候选裁剪（减少幻觉）

库有几百张表时，别把全库 schema 塞给模型（超长+干扰）。先用问题关键词做表召回（向量检索 / 关键词匹配表注释），只把 Top-K 相关表的结构喂进去。

# 伪代码：Schema Linking 召回
def link_schema(question, schema_index):
    # 1. 用问题召回相关表（关键词 or 向量）
    top_tables = schema_index.search(question, top_k=5)
    # 2. 组装成模型能懂的上下文
    ctx = "\n".join(format_table(t) for t in top_tables)
    # 3. 让模型输出 (table, column) 映射
    mapping = llm(f"问题：{question}\n可用表结构：\n{ctx}\n"
                 f"输出涉及的(表,字段)JSON")
    return mapping, ctx  # ctx 直接复用给后续 SQL 生成

六、SQL 生成：提示词与上下文构造

拿到 Linking 结果和表结构上下文后，构造 prompt 让模型生成 SQL。关键点：

• 显式给 schema：CREATE TABLE 注释版 + 字段中文含义。
• 给 few-shot：2~3 个"问题→SQL"样例，固定输出风格。
• 强制只读：prompt 里写明"只输出 SELECT，禁止 INSERT/UPDATE/DELETE/DDL"。
• 低 Temperature：T=0，SQL 要确定性、可复现。
• 方言对齐：库是 MySQL 就别生成 PostgreSQL 语法。

prompt = f"""
你是保险理赔库 SQL 助手。数据库为 MySQL。
可用表结构（含注释）：
{ctx}
要求：
1. 仅生成一条只读 SELECT，禁止任何写操作/DDL；
2. 只能使用上述表；金额用 clm_amt，日期用 clm_date；
3. 输出纯 SQL，不要解释。
问题：{question}
"""

七、SQL 安全校验总览（守门员）

安全校验是流水线的守门员，在 SQL 真正执行前用确定性代码逐条检查。它和"生成"解耦：生成可能错，校验必须 100% 可靠。

八、只读限制 + 白名单表

只读：解析 SQL 的 AST（抽象语法树），只允许 SELECT（及 CTE 里的 WITH...SELECT），拒绝一切 DML/DDL。比正则更稳——正则会被注释、换行绕过。

白名单表：从 SQL 提取所有表名，逐一校验是否在"本 Agent 可读表集合"内。特药理赔 Agent 只允许 claim / policy / drug / member 等，绝不许碰 user_credential / payment_account。

九、参数化 + 行数限制 + 执行计划检查

9.1 参数化（防注入）

用户原话（如药品名）绝不能字符串拼进 SQL，必须走预编译/绑定变量：WHERE drug_name = ?。这同时防 SQL 注入（用户输入 ' OR '1'='1）和语法错。

9.2 行数限制

自动给查询追加 LIMIT N（如 200），或校验用户写的 LIMIT 不超过阈值。防"SELECT * FROM claim"返回百万行拖垮连接。

9.3 执行计划检查

执行前先 EXPLAIN，看是否全表扫描、是否缺索引、预估行数/成本是否超标。超标则拒绝或改写，避免慢查询占满连接池。

十、执行与超时控制（最后兜底）

通过校验的 SQL，在受限连接里执行：独立连接池、低权限账号、语句超时（如 3s）。超时即杀掉查询返回"查询过慢，请缩小范围"。

十一、结果解释：SQL → 自然语言

SQL 跑出的是行集/聚合值，要转成用户能懂的自然语言。原理：把 SQL 结果 + 原始问题，喂给模型生成解释。

answer = llm(f"""
用户问题：{question}
SQL：{sql}
查询结果（{len(rows)} 行）：{rows}
请用一句中文回答用户，含关键数字；若结果为空见下方规则。
""")

十二、空结果与异常处理

两种要特殊处理的情形：

• 空结果：SQL 正常但 0 行（如"查不存在的保单"）。要如实说"未查到相关记录"，不能编造"您报销 0 元"误导（0 元和没记录是两回事）。
• 执行异常：超时/权限/语法（校验漏网）。要兜底：提示用户换种问法、转人工，或走降级（如返回近 30 天概览）。

十三、面试达标线①：完整讲清 Text2SQL 流程（含安全校验每一环）

1. 路由判断：确认问题该走 SQL（聚合/筛选/关联）。
2. Schema Linking：用数据字典+中文注释+表召回，把话术映射到(表,字段)。
3. 生成：低 T，prompt 含 schema 与"仅 SELECT"约束。
4. 安全校验（五关）：只读(AST)、白名单表(含JOIN/子查询)、参数化、行数 LIMIT、EXPLAIN 检查。
5. 执行：受限连接池 + 语句超时。
6. 结果解释：数字来自真实结果，空结果如实说，异常友好兜底。

十四、面试达标线②：为什么必须只读+白名单、Schema Linking 怎么做才准

十五、Day 5 自测清单

十六、高频面试题速记卡