Spring AI Alibaba DataAgent快速上手教程：15分钟从零部署你的第一个NL2SQL数据分析平台（含避坑清单）
【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgent
想不用写 SQL 就能查数据？Spring AI Alibaba DataAgent是一个基于 Spring AI Alibaba Graph 打造的企业级智能数据分析 Agent，核心能力是NL2SQL（Text-to-SQL）数据问答，还内置 Python 深度分析、智能报告生成、RAG 知识增强和 MCP 服务器能力。跟着本文的 15 分钟部署教程，你将从零搭建出第一个 NL2SQL 数据分析平台，文末还附上了新手高频踩坑清单。
🧭 1分钟认识 DataAgent：它比 Text-to-SQL 工具强在哪
传统 Text-to-SQL 工具只能"翻译"自然语言为 SQL，而 DataAgent 是一个完整的 AI 智能数据分析师：
| 能力 | 说明 |
|---|---|
| 智能数据分析 | 基于 StateGraph 的 NL2SQL 转换，支持复杂多表查询与多轮对话意图理解 |
| Python 深度分析 | 在任务级容器沙盒中执行生成的 Python 代码，支持动态依赖与资源限制 |
| 智能报告 | 分析结果自动汇总为含 ECharts 图表的 HTML/Markdown 报告 |
| 人工反馈机制 | Human-in-the-loop，允许用户在计划生成阶段干预调整 |
| RAG 检索增强 | 接入向量库对业务元数据、术语库做语义检索，提升 SQL 生成准确率 |
| 多模型调度 | 全面兼容 OpenAI 接口规范，可动态切换 Qwen、DeepSeek 等主流模型 |
整体架构如下图所示（前端 Nuxt + 管理端 Spring Boot + Graph 工作流）：
📋 第一步：环境准备清单（2 分钟）
开始部署前，请确认本机已安装以下环境：
| 组件 | 版本要求 | 备注 |
|---|---|---|
| JDK | 17+ | 后端运行必需 |
| MySQL | 5.7+ | 存储平台业务数据 |
| Node.js | 22+ | 前端运行必需 |
| pnpm | 11+ | 前端包管理 |
| Docker | 任意稳定版 | 仅工作流执行 Python 步骤时必需，纯 SQL 分析可不装 |
| 向量数据库 | 可选 | 默认使用内存向量库，开箱即用 |
💡 新手提示：如果只想体验 SQL 数据问答，Docker 和向量库都可以先不装，默认内存向量库即可跑通全流程。
获取代码：
git clone https://gitcode.com/gh_mirrors/da/DataAgent🗄️ 第二步：导入数据库（3 分钟）
DataAgent 的测试 SQL 脚本位于 sql 目录，共 4 个文件：
schema.sql— 平台功能相关的表结构data.sql— 平台功能相关的数据product_schema.sql— 模拟电商业务表结构（用于数据问答演示）product_data.sql— 模拟业务数据
导入命令：
mysql -u root -p your_database <>spring: datasource: url: jdbc:mysql://127.0.0.1:3306/saa_data_agent?useUnicode=true&characterEncoding=utf-8&allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 你的密码也可以不改文件，直接用环境变量覆盖：
export DATA_AGENT_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/saa_data_agent?useSSL=false&serverTimezone=Asia/Shanghai' export DATA_AGENT_DATASOURCE_USERNAME=root export DATA_AGENT_DATASOURCE_PASSWORD=你的密码⚠️ 注意：
saa_data_agent库是存DataAgent 平台自身数据的，不是 Agent 分析的数据来源，别搞混了。
🚀 第四步：启动前后端（3 分钟）
启动后端（默认端口 8065）：
./mvnw -pl>cd />🤖 第五步：配置 AI 模型（2 分钟）
进入模型配置页面，新增模型并填入你的 API Key 即可。系统内置支持 OpenAI、DeepSeek 等主流提供商，只需填模型名称和 API Key：
![]()
- 标准提供商：填 Model Name + API Key 即可。
- 本地模型（Ollama/自建网关）：需遵循 OpenAI 接口协议，准确填写 base-url 和 completions-path。
- 配置后调用失败？建议先用 Postman 单独测试接口连通性，排除网络问题。
🛠️ 第六步：创建你的第一个数据智能体（3 分钟）
首页默认有 4 个未对接数据的占位智能体，可删除后新建。点击右上角"创建智能体"，只需输入名称，其余选默认：
![]()
6.1 配置数据源
进入智能体配置页，在数据源管理中添加你的业务数据库（第二步导入 product 数据的 MySQL 实例），然后勾选要参与分析的表，最后点击右上角"初始化数据源"：
![]()
![]()
初始化成功后，列表页会显示连接状态，用来验证数据源连接是否正常：
![]()
6.2 配置语义模型与业务知识（可选但强烈推荐）
这是 NL2SQL 准确率的关键：
- 语义模型：定义业务术语到物理字段的映射，例如
customerSatisfactionScore→csat_score。 - 业务知识：定义业务规则，例如"GMV = 商品交易总额，含付款和未付款订单金额"。配置后记得点击**"同步到向量库"**。
- 预设问题：可为智能体配置常用问题，方便快速体验。
![]()
![]()
配置完成后点击"前往运行界面"，开始第一次数据问答。
📊 第七步：第一次 NL2SQL 数据问答
运行界面左侧是历史会话，右侧是输入框和请求参数配置。输入一个业务问题（如"各品类销售额排名前 5 的是哪些？"）点击发送：
![]()
Agent 会自动完成意图识别 → 计划生成 → SQL 生成 → 执行 → 报告生成，最终产出一份含 ECharts 图表的 HTML 分析报告，点击"下载报告"即可下载：
![]()
🎛️ 四种运行模式按需切换
模式 作用 适用场景 默认模式 自动生成计划并执行，输出分析报告 日常使用 人工反馈模式 生成计划后等你确认，可调整再执行 需要人工把关 仅 NL2SQL 模式 只生成并执行 SQL，不产出报告 快速取数 显示 SQL 运行结果 执行后展示 SQL 原始结果 调试校验
![]()
![]()
⚠️ 避坑清单：新手最容易踩的 6 个坑
- 两个 MySQL 库搞混：
saa_data_agent库存平台数据；Agent 分析的数据源要在智能体配置里单独添加，两者互不替代。 - 忘记"初始化数据源"：添加数据源并选表后必须点击"初始化数据源"，否则表结构元数据不会录入，Agent 无法生成 SQL。
- 业务知识忘记"同步到向量库"：只添加不同步，RAG 检索不到，模型理解业务术语的能力会打折。
- JDK 版本太低：必须 JDK 17+，JDK 8/11 会直接编译失败。
- Python 分析不工作：工作流执行 Python 步骤依赖 Docker 沙盒，先
docker info确认 Docker 已启动；纯 SQL 场景可忽略。 - 本地模型调用失败：Ollama 等自建网关必须走 OpenAI 兼容协议，base-url 与 completions-path 拼成的完整地址要能独立调通。
📚 延伸学习
部署跑通后，建议按以下路径深入：
- 完整配置手册：快速开始
- 系统分层与 StateGraph 工作流设计：架构设计
- 向量库扩展、模型依赖管理：开发者指南
- API Key 调用、MCP 服务器、Python 沙盒高级配置：高级功能
- 语义模型 / 业务知识最佳实践：知识配置最佳实践
后端核心代码位于 contenteditable="false">【免费下载链接】DataAgentSpring AI Alibaba DataAgent![]()
项目地址: https://gitcode.com/gh_mirrors/da/DataAgent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
