从需求到上线：基于 Spring AI 打造“AI 问数”Agent 的完整实践-智慧文博士

导读：

传统 BI 报表难以及时响应灵活多变的运营需求，而 Text-to-SQL（文本转SQL）技术正是打破这一数据壁垒的关键。本文将深度复盘佳杰云星技术团队如何基于 Java 生态（Spring AI Alibaba），从 0 到 1 构建生产级“AI 问数” Agent。文章将完整解析从解决大模型“幻觉”的 RAG 设计，到 SQL 执行的安全熔断，再到前端图表自动渲染的全链路代码实现与踩坑经验。

最近产品上线了一个新功能——「AI 问数」，一个完全基于 Spring AI（含 Spring AI Alibaba 扩展）开发的 AI Agent。它能让运营人员以及非技术同学用日常中文直接“聊天式”问数据，Agent 自动理解意图、生成 SQL、执行查询，再以交互式图表把结果漂亮地呈现出来。

这篇文章把从需求调研 → 场景定义 → 问题拆解 → 技术选型 → 全链路开发 → 上线优化整个过程完整拆解复盘一遍。

一、需求调研：为什么要做「AI 问数」？

2025 年上半年，我们的云运营平台很多客户的数据量已经突破千万级，而各个客户对于日常查询需求非常碎片化且有差异。

我们做了一次小范围调研（覆盖客户的运营、财务、营销等部门），得到的核心痛点如下：

痛点	具体描述	影响比例
报表固定报表不灵活	固定报表只能看平台中提供的固定报表数据，临时想看“教育行业客户的 11 月订单趋势”就卡死	85%
数据等待时间长	提数导出 → 分析报表 → 出结果，最快也要几个小时	62%
图表手动做太麻烦	拿到 Excel 后还要自己画图、调颜色	91%

调研结论非常明确：大家不是不想要数据，而是“要数据太难、太慢、太丑”。

于是我们定了目标：让所有人 30秒内看到自己想要的图表。

二、适用场景：到底能解决哪些实际业务问题？

「AI 问数」目前主要覆盖以下高频场景（按使用频率排序）：

日常运营监控
“最近 3 个月新用户数趋势”“最近7天订单走势”
临时领导/跨部门要数
“上个月某类产品订单占比最高的10个客户”“本周账单金额环比上周增长了多少”
多指标组合查询
“最近30天客户日活、付费金额、订单数量三条曲线放一张图上”

实际使用下来，85% 以上的日常提数需求都能被覆盖，剩下15% 极复杂需求，我们会引导走传统 BI 或版本迭代。

三、核心解决问题能力总结

传统方式	「AI 问数」	提升幅度
提数最快2小时~1天	平均20 秒出结果（含图表）	提升 400 倍+
只能看固定维度	任意自然语言自由组合	维度无限
结果是表格/Excel	直接交互式图表	体验跃升
需要定制开发	纯中文对话	成本降低

四、技术选型：为什么最终选了 Spring AI？

当时我们对比了以下几套方案（我们产品主要技术栈为 Java）：

方案	优点	缺点	最终评价
LangChain4j	社区最活跃，功能最全	Java生态适配一般，生产级稳定性稍弱	备选
Semantic Kernel (.NET)	企业级成熟	我们是Java栈，跨语言成本高	放弃
直接调用通义千问/DeepSeek API + 自研Agent	最灵活	重复造轮子，维护成本极高
Spring AI + Spring AI Alibaba	原生Spring风格、开箱即用、生产级稳定、NL2SQL模块现成、Agent框架优秀、与云运营平台相同技术栈（兼容性好）	社区比LangChain小	选中

最终决定：主线用 Spring AI 官方 + Spring AI Alibaba 的 DataAgent / Graph 模块，大模型底座先用通义千问 Qwen，后期可平滑切换 OpenAI-Like 的 LLM（如 DeepSeek）。

五、开发全过程完整复盘

5.1 架构设计

整体架构如下：

核心是把Agent + Tool Calling + RAG三者结合。

5.2 关键技术实现细节

1. 数据库 Schema 向量化（RAG）

我们把所有表的注释、中文别名、字段注释、历史高频SQL样例全部向量化存入向量引擎。

@Bean
publicVectorStore vectorStore() {
returnnewOpenSearchVectorStore(openSearchOps, embeddingModel);
}

// 上线前把所有表结构&注释灌入一次
vectorStore.add(documents);

用户提问时，先检索最相关的 8-12 个表&字段描述注入 Prompt，避免大模型“幻觉”生成不存在的字段。

2. Text-to-SQL Agent（核心）

我们基于 Spring AI Alibaba Graph 快速搭建 ReAct Agent：

@Bean
publicAgent dataQueryAgent(ChatModel chatModel, List<ToolCallback> tools) {
returnReActAgent.builder()
.chatModel(chatModel)
.tools(tools)// SqlExecutor + ChartGenerator
.systemPrompt(SYSTEM_PROMPT)// 含业务规则+安全限制
.build();
}

SYSTEM_PROMPT 里写了非常严格的规则：

必须使用中文别名
禁止 DELETE/UPDATE/DROP 等操作
结果集限制 5000 行等

3. SQL 执行安全控制

我们没有直接把 JDBC 暴露给大模型，而是封装了 SqlExecutor Tool：

先生成 SQL
用正则 + ANTLR 解析 SQL AST，检查是否只涉及允许的表
自动注入 WHERE user_id IN (...) 权限条件
执行前走 SQL审核规则（公司内部规则引擎）
执行超时 10s 自动熔断

4. 图表自动生成

这是我们自己扩展的一个 Tool：ChartGenerator

Agent 会在思考后决定：

数据类型 → 推荐图表类型（折线/柱状/饼等）
是否需要多系列
是否需要堆叠/双Y轴

然后调用 ChartGenerator 返回完整的 Chart Option JSON，前端直接渲染。

{
// X 轴上的标签
labels: ['一月', '二月', '三月', '四月', '五月', '六月', '七月'],
// 数据集数组 - 每个对象代表一条折线
datasets: [
{
label: '订单数量', // 图例显示的名称
data: [65, 59, 80, 81, 56, 55, 40], // Y 轴对应的数据值
borderColor: 'rgb(75, 192, 192)', // 折线颜色
backgroundColor: 'rgba(75, 192, 192, 0.2)', // 填充区域的颜色（若 fill: true）
fill: false, // 是否填充折线下方区域（false | true | '+-' | 'origin' 等）
tension: 0.4, // 曲线平滑度（0 = 直线，接近 1 更圆滑）
pointBackgroundColor: 'rgb(75, 192, 192)', // 数据点背景色
pointBorderColor: '#fff', // 数据点边框颜色
pointRadius: 5, // 数据点半径
borderWidth: 2, // 折线宽度
stepped: false, // 是否为阶梯线图（true/false/'before'/'after'）
},
// 可以添加更多 dataset 实现多条线
{
label: '订单金额（元）',
data: [45100.00, 60000.00, 35000.00, 70000.00, 88000.00, 65000.00, 50000.00],
borderColor: 'rgb(255, 99, 132)',
backgroundColor: 'rgba(255, 99, 132, 0.2)',
fill: false,
tension: 0.4,
borderWidth: 2,
}
]
}