别做「语法正确但业务错误」的 Text-to-SQL！我把它升级成了懂业务的数据分析智能体

项目地址：GitHub - DataWhisperer
当前版本：V3.9.1 | 技术栈：Python + FastAPI + Milvus + DashScope + RAG

做 Text-to-SQL 的开发者，大多都踩过同一个致命的坑：
生成的 SQL 语法完美、执行不报错，但查出来的结果和业务口径对不上——GMV 算不算退款？客单价按订单数还是用户数？时间维度按下单还是支付？

只靠数据库表结构写 SQL，永远逃不开「语法正确，业务错误」的死局。

这也是我把 DataWhisperer 迭代到 V3 版本的核心原因：从「会写 SQL 的工具」，变成「懂业务规则的数据分析智能体」。

先快速回顾三个版本的核心演进：

版本	核心命题	核心能力
V1	能不能跑通？	打通自然语言→SQL→查询→可视化的基础链路
V2	能不能治理？	Prompt 版本化、SQL 自动修复、基础效果评测
V3	能不能落地？	RAG 业务口径增强、产品化控制台、全维度评测中心、对话式交互

---

一、核心突破：用 RAG 让系统「懂指标」，解决语义正确的根问题

V1 的输入只有「表结构 + 用户问题」，模型只能靠字段名猜业务含义；V3 新增了「业务指标口径检索」环节，完整链路变成：

用户问题 → 读取表结构 → 检索指标口径 → 组合上下文生成SQL → 安全校验 → 执行查询 → 图表+结论

这一步看似只多了一个检索动作，本质是让系统从「翻译机器」变成了「懂业务的分析助手」。

我的设计原则：知识源与索引层分离

我没有直接把业务知识丢进向量库当黑盒，而是做了两层设计：

• 知识源：Markdown 文件。每个指标单独一个 md 文件，写清名称、别名、计算口径、关联表字段、SQL 建议和注意事项，人可直接编辑、审查、版本管理。
• 索引层：Milvus 向量库。仅负责把 Markdown 内容向量化，做语义召回，索引可以随时重建，不会出现「向量库存了什么没人知道」的情况。

一句话总结：Markdown 负责准确，Milvus 负责快。

渐进式迭代：从本地匹配到向量检索，全程带兜底

我没有一步到位上 Milvus，而是分四步验证，每一步都保留降级方案：

1. 本地关键词匹配：先把核心指标写成文件，用关键词+别名精确命中，先解决「有没有」的问题；
2. 混合检索补充：加入本地 n-gram 相似度召回，覆盖「平均每单消费」这类客单价的同义表达；
3. 接入 Milvus 向量检索：用语义召回解决更模糊的自然语言提问，Milvus 不可用时自动回退本地检索；
4. 升级 Embedding：替换为 DashScope text-embedding-v4，未配置 API Key 时自动兜底本地哈希方案。

很多人做项目喜欢一步上最复杂的方案，但开源项目要能让别人 clone 下来就跑，兜底比完美更重要。

---

二、产品化升级：从开发者调试台，到完整的数据分析工作台

V1/V2 的界面更像个 API 调试页，而真实的数据分析智能体，不该只有一个输入框。
V3.5 之后我把控制台拆成了 5 个工作区，覆盖从数据管理到效果验证的全流程：

1. 数据结构管理页

支持上传建表 SQL、数据字典、字段说明等多格式文件，统一管理 schema 资料，后续可扩展自动解析、自动补全说明。

2. RAG 知识库管理页

不再让开发者手动改本地 Markdown，提供可视化的知识库上传、预览、删除入口。业务人员也能上传指标口径、分析规则、SQL 样例，让 RAG 脱离纯手工维护阶段。

3. 对话式 AI 查数体验（V3.9 核心优化）

把「输入框+按钮+右侧结果」的表单模式，改成了更自然的对话交互：

• 首页放推荐问题，点击直接运行，新用户零思考成本上手；
• 分析过程时间线可展开，从理解问题到生成结论的每一步都透明；
• 结论逐字流式输出，降低等待焦虑；
• 结果自带追问建议，引导用户持续深度分析，而不是查完就走。

---

三、工程化底线：大模型项目，不可测就不可迭代

我一直觉得：大模型项目最容易自欺欺人——改一版 prompt，觉得效果变好了，但到底好没好、哪里退化了，全靠感觉。

所以 V3 我花了很大精力做评测中心，这也是整个项目最不像 Demo 的地方。

三类核心评测，全维度覆盖质量

1. Text-to-SQL 生成质量评测：校验 SQL 语法、业务逻辑片段匹配度；
2. SQL 安全边界评测：拦截写入、删除、DDL、多语句等风险操作，保证只读查询；
3. RAG 指标检索评测：验证问题是否命中正确指标、有没有误召回。

前端直观展示综合通过率、各维度得分、质量趋势、错误案例归因，版本迭代效果一目了然，再也不用「凭感觉说变好」。

支持自定义测试集

内置 100 条 Text-to-SQL 回归用例，同时支持用户上传 JSON/JSONL/CSV 等格式的自有测试集，用自己的业务场景验证系统效果，而不是只能跑几个内置演示问题。

---

四、细节体验：让查出来的结果，变成能拿走的资产

很多数据分析工具都有一个通病：页面上看着很好，结果根本带不走。
V3.8 专门做了「结果资产化」优化：

• 图表导出：支持复制 PNG、下载 SVG、复制 ECharts 配置，贴 PPT、二次编辑都能用；
• 表格导出：支持复制 Markdown、Word 友好 HTML、下载 CSV，无缝对接文档工具；
• SQL 审阅：生成的 SQL 自带中文注释，附带只读校验、语法校验、执行验证结果，业务人员能看懂，数据团队能快速审阅。

---

五、整体架构与当前状态

核心架构

用户问题
  ↓
FastAPI 接口层
  ↓
DataAnalysisOrchestrator 编排层
  ├─ Schema Tool：读取数据库结构
  ├─ Metric Retriever：指标口径检索（本地/Milvus 双模式）
  ├─ PromptRegistry：版本化提示词管理
  ├─ SQL Tool：SQL 生成 + 安全校验 + 自动修复
  ├─ Query Tool：只读查询执行
  ├─ Chart Tool：图表推荐与生成
  └─ Insight Tool：业务分析结论生成
  ↓
统一响应（SQL + 表格 + 图表 + 结论 + 过程 + 追问）
  ↓
Web 控制台

当前质量保障

本地 pytest 测试用例 51 个全部通过，ruff 代码规范校验全通过，覆盖 API 契约、SQL 安全、检索兜底、文件操作、评测逻辑等核心链路。

---

六、后续规划

V3 已经完成了从 Demo 到产品雏形的跨越，接下来会继续往「企业级数据分析 Copilot」的方向迭代：

• RAG 文件自动切片 + Milvus 一键同步
• 数据结构文件自动解析 schema
• SQL 样例库检索增强
• 多模型效果对比评测
• MCP 工具化与多智能体协作

---

最后

从 V1 到 V3，我最大的感受是：真正能落地的大模型应用，核心从来不是模型本身，而是围绕模型搭建的整套业务系统。
它需要清晰的业务口径、可靠的安全边界、可度量的质量体系，还有一个用户愿意打开的界面。

如果你也在做 Text-to-SQL、RAG、大模型评测相关的方向，欢迎来项目交流：
👉 GitHub - DataWhisperer

💬 讨论：你们做 Text-to-SQL 遇到过最头疼的坑是什么？是业务口径对齐、SQL 准确率还是安全问题？欢迎评论区聊聊～