豆翔苏斌油

1. 立项背景和目标 NLP2SQL 是从零搭建的智能数据库查询 Demo。立项背景是想验证一条朴素的假设：让业务人员用自然语言直接查库，能不能用现有 LLM 加 LangChain 拼出一条端到端、不依赖写代码就能用的最短路径。 系统解决的核心问题是"懂业务的人查不到数据，懂数据的人问不到业务"——业务侧的需求（比如"研发部和市场部的人数对比"、"他们 薪资呢"）必须经过开发翻译成 SQL，且每次新需求都要排期。立项目标只有一句话：让用户用中文提问，系统自己生成 SQL、执行、总结结果，三步内拿到答案。 项目以 employees 示例库（5 张表、20 员工）为基准，覆盖统计、过滤、聚合、JOIN、模糊匹配、多轮引用 6 类典型问题。设计文档里明确写了不做什么：不支持写操作、不做多租户与权限隔离、不做生产监控、只支持 MySQL 一种方言、不引入 ReAct Agent 的多步推理——避免范围蔓延。 2. 软件功能与核心功能模块 系统暴露 6 个 HTTP 端点，对应 6 类能力，全部在 app/main.py 里实现。 主端点是 POST /api/v1/query，承担"自然语言→SQL→执行→总结"的全流程。辅助端点包括 GET /api/v1/schema/tables 和 /schema/tables/{name} 浏览库表和单表 schema、/schema/tables/{name}/sample 读样本行；POST /api/v1/schema/reload 在数据库结构变更后重建向量索引；GET 与 DELETE /api/v1/sessions/{sid} 拉取和清空多轮对话历史；GET /health 用于健康探活，GET /docs 是 Swagger UI，零额外成本即可调试。 核心代码按单一职责拆成 7 个模块。Pipeline 是 app/pipeline.py 里的编排器，run 方法按"检索 schema→生成 SQL→校验→执行→总结→写记忆"六步串行执行，任意一步失败都返回结构化 QueryResponse，含 sql_validated、validation_error、execution_time_ms 三个可观测字段。SQLGenerator 在 app/chains/sql_generator.py，负责调用 LLM 并把"LLM 自由输出"压成"纯 SQL"，需要剥离 think 标签、Markdown 代码块、按分号切分后逐条验证取第一条合法只读语句。validate_sql 在 app/chains/validator.py，是系统的安全防线，用 sqlglot 解析 AST，白名单只放 Select、Uni