NL2SQL
Natural Language to SQL：把用户的自然语言问题自动转成可执行 SQL（常再接查库、出图、自然语言解释），是智能问数 / 数据分析 Agent 的核心能力段。
简介
NL2SQL（自然语言转 SQL）解决的是「业务会问、不会写 SQL」与「分析师重复写查询」之间的鸿沟。在 智能数据分析Agent 链路里，它通常不是终点：成功的问数产品往往是 意图理解 → SQL 生成 → 安全校验 → 执行 → 可视化/总结 的管道，NL2SQL 只是中间生成层。
与「聊天式写一段 SQL 给人对着改」不同，生产向 NL2SQL 必须处理：方言与 schema 对齐、字段语义、权限与只读边界、危险语句拦截、结果体量控制、流式反馈。大模型能生成看似正确的 SQL，却也可能 DROP TABLE、SELECT * 扫全表或编造不存在的列——因此工程上常把「能生成」与「能安全执行」拆开。
在 Vibe Coding / Agent 编程语境下，NL2SQL 还带来契约问题：流式字段、工具调用参数、图表配置结构一旦靠猜，前后端会连环翻车。实践共识是：先最小测试拿到真实 I/O 字段，写进文档，再集成；联调时以后端已测通的 SQL/响应字段为真源。
关键信息
| 维度 | 内容 |
|---|---|
| 类型 | 能力 / 技术模式（常作为 Agent 子链路） |
| 输入 | 自然语言问题 + schema/语义映射 + 权限上下文 |
| 输出 | SQL 文本 → 查询结果 →（可选）图表配置与自然语言回答 |
| 常见框架组件 | LangChain SQLDatabase、create_sql_agent；PandasAI 等（本地表/DataFrame 路径） |
| 安全层 | AST/解析器校验（如 sqlglot）、黑名单、只读账号、LIMIT、沙箱 |
| 关联概念 | 智能数据分析Agent、Schema语义映射、数据分析Agent安全围栏、假测试通过、MCP 模型上下文协议 |
核心特性
1. 不只是「生成 SELECT」
可用的 NL2SQL 系统通常包含：意图分类（统计/明细/趋势）、表与字段选择、条件与时间窗、聚合与排序、分页/LIMIT、错误重试与解释。东哥实战中在现成 create_sql_agent 不合拍后，自研为：理解意图 → 生成 SQL → 校验 → 查库 → 图表配置 → 总结回答，并用 SSE 全程流式吐出。
2. 现成组件 vs 自研编排
LangChain 等提供 SQLDatabase、create_sql_agent 等开箱路径，适合快速验证。但编排粒度、中间态暴露、与前端图表协议的贴合度往往不够——文档调研（MCP 查官方）说明「有组件」，最小测试说明「字段与流程是否合用」；不合用就应用自研管道，而不是硬套 Agent 黑盒。
3. 安全必须在执行前
AI 生成的 SQL 不可默认信任。sqlglot 一类 AST 级检查可拦截删表、禁止 SELECT *、强制 LIMIT，相当于给生成层戴枷锁。这与 数据分析Agent安全围栏 的黑名单/沙箱/只读账号互补：一层管语句形态，一层管运行时权限与资源。
4. Schema 与语义映射是准确率前置条件
字段缩写、业务黑话、多表口径未对齐时，模型会「生成能跑但答错」的 SQL。Schema语义映射（销售额→sales 等）和干净预处理决定上限；云端场景还要把可查询表/列白名单化。
5. 验收要跑真实依赖，防假通过
只测「接口 200」或 mock SQL 不等于 NL2SQL 可用。正确完成证明包括：真实模型 Key、真实（或约定沙箱）库、可见的 SQL 文本与结果摘要、图表/回答与数据一致；同会话可能跳过重新生成，需新会话复测（见 假测试通过）。
6. 契约文档是前后端联调的真源
流式 chunk 字段、工具调用参数位置、结构化 JSON 形状应在最小 .py 测试中记录，并写回开发文档。后续 AI 集成与前端适配都对照这份样板，避免双边同时猜字段。
不同素材中的观点
-
2026-07-23-woshipm-ai-backend-test-first-debug（东哥 · Vibe Coding 第 6 篇）：NL2SQL 是后端核心难关之一。流程是 docs-langchain MCP ask 调研 → 最小测试记千问/组件真实字段 → 发现现成编排不合拍后自研管道 + sqlglot 安全校验 + SSE；字段规范追加进开发文档后再集成。强调测试先行与「维护文档不维护代码」。
-
2026-07-23-woshipm-vibe-coding-system-pitfalls（系列第 7 篇）：联调与 e2e 验收把 NL2SQL 放进全链路 提问→意图→SQL→查库→出图→回答；未配 API Key 的「假通过」、同会话记忆跳过 NL2SQL 都是高发坑。后端已测字段成为前端适配真源。
-
2026-07-05-juejin-intelligent-data-analysis-agent：产品化问数 Agent 中，云端优先 SQL 下推计算；客户端可用 Pandas 路径。强调预处理、Schema 映射、安全围栏与报告四段输出——NL2SQL/代码生成只是执行层一环，不是产品的全部。
实用信息
- 落地顺序建议：① 只读库账号 + schema 导出 ② 字段语义表 ③ 最小 NL2SQL 脚本（固定 3～5 个业务问题）④ 记录 SQL 与结果 ⑤ 加 AST/规则校验 ⑥ 再接 SSE/前端 ⑦ 真实 Key 全链路验收。
- 最小测试问题集示例：「各区域近 30 天销售额」「Top 10 客户订单量」「异常退货率趋势」——覆盖聚合、排序、时间窗。
- 硬约束清单：禁 DDL/DML 写删、禁无 LIMIT 的大扫描、表白名单、列级权限、超时与行数上限、审计日志留 SQL。
- 对 AI 的指令要点：先查官方组件文档 → 先写独立测试文件 → 字段写入任务文档 → 禁止在字段未证实前全量集成。
- 适用：智能问数、运营分析助手、内部 ChatBI、数据分析 Agent。
- 不适用：口径未定义、无稳定 schema、需要复杂权限行级策略却未建模、结论直接触发资金/合规动作且无人复核。