Spring AI Alibaba DataAgent：智能数据查询系统

摘要

Spring AI Alibaba DataAgent是一个基于Spring AI框架构建的智能数据查询系统，通过自然语言处理技术将用户的自然语言查询转换为SQL语句，并执行查询生成分析报告。系统采用状态图（StateGraph）架构，实现了意图识别、证据召回、查询增强、模式召回、SQL生成与执行、Python数据分析、报告生成等完整的数据分析流程。本文深入分析系统的架构设计、核心组件实现、数据流转机制，为开发者提供全面的技术参考。

1. 项目应用场景

Spring AI Alibaba DataAgent主要应用于以下场景：

1.1 业务数据分析

• 场景描述：业务人员无需掌握SQL语法，通过自然语言直接查询业务数据库
• 典型用例："查询最近一个月销售额最高的前10个产品"
• 价值：降低数据分析门槛，提升业务决策效率

1.2 数据探索与洞察

• 场景描述：数据分析师通过自然语言快速探索数据，发现数据规律
• 典型用例："分析用户购买行为，找出购买频次与客单价的关系"
• 价值：加速数据探索过程，支持复杂多步骤分析

1.3 智能报表生成

• 场景描述：自动将查询结果转换为结构化的分析报告
• 典型用例：生成包含数据可视化、趋势分析、建议措施的HTML报告
• 价值：自动化报告生成，提升工作效率

1.4 多数据源统一查询

• 场景描述：支持MySQL、PostgreSQL、H2、达梦等多种数据库
• 典型用例：跨数据库的数据关联查询和分析
• 价值：统一查询接口，简化多数据源管理

2. 学习目标

基于对项目核心代码的分析，设定以下学习目标：

2.1 核心架构理解

• 目标：深入理解基于状态图（StateGraph）的工作流编排机制
• 关键代码：spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/config/DataAgentConfiguration.java
• 学习要点：
  • 状态图的节点定义与边连接
• 条件路由（ConditionalEdges）的实现机制
• 状态管理策略（KeyStrategy）的设计

2.2 流式处理机制

• 目标：掌握基于Reactor的流式数据处理和SSE（Server-Sent Events）推送
• 关键代码：spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/service/graph/GraphServiceImpl.java
• 学习要点：
  • Flux流的创建与转换
• 流式输出的封装与推送
• 错误处理与完成回调

2.3 NL2SQL转换技术

• 目标：理解自然语言到SQL的转换流程，包括查询增强、模式召回、SQL生成与优化
• 关键代码：
  • spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/node/QueryEnhanceNode.java
• spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/node/SqlGenerateNode.java
• 学习要点：
  • 查询改写与关键词提取
• 向量检索在模式召回中的应用
• SQL质量评估与多轮优化

2.4 向量检索与知识库

• 目标：掌握基于向量数据库的语义检索和知识召回机制
• 关键代码：spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/node/EvidenceRecallNode.java
• 学习要点：
  • 文档向量化与存储
• 相似度检索与混合搜索
• 业务知识库的构建与应用

2.5 计划生成与执行

• 目标：理解多步骤执行计划的生成、验证与执行机制
• 关键代码：
  • spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/node/PlannerNode.java
• spring-ai-alibaba-data-agent-chat/src/main/java/com/alibaba/cloud/ai/dataagent/node/PlanExecutorNode.java
• 学习要点：
  • 计划的结构化表示（Plan、ExecutionStep）
• 计划验证与修复机制
• 人工反馈集成

3. 目录结构分析

项目采用多模块Maven结构，清晰的职责划分：

spring-ai-alibaba-data-agent/ ├── spring-ai-alibaba-data-agent-chat/ # 核心功能模块（不可独立启动） │ ├── src/main/java/com/alibaba/cloud/ai/dataagent/ │ │ ├── config/ # 配置类 │ │ │ ├── DataAgentConfiguration.java # 状态图配置与Bean定义 │ │ │ └── DataAgentProperties.java # 配置属性 │ │ ├── node/ # 状态图节点实现 │ │ │ ├── IntentRecognitionNode.java # 意图识别节点 │ │ │ ├── EvidenceRecallNode.java # 证据召回节点 │ │ │ ├── QueryEnhanceNode.java # 查询增强节点 │ │ │ ├── SchemaRecallNode.java # 模式召回节点 │ │ │ ├── TableRelationNode.java # 表关系分析节点 │ │ │ ├── FeasibilityAssessmentNode.java # 可行性评估节点 │ │ │ ├── PlannerNode.java # 计划生成节点 │ │ │ ├── PlanExecutorNode.java # 计划执行节点 │ │ │ ├── SqlGenerateNode.java # SQL生成节点 │ │ │ ├── SqlExecuteNode.java # SQL执行节点 │ │ │ ├── SemanticConsistencyNode.java # 语义一致性校验节点 │ │ │ ├── PythonGenerateNode.java # Python代码生成节点 │ │ │ ├── PythonExecuteNode.java # Python代码执行节点 │ │ │ ├── PythonAnalyzeNode.java # Python分析节点 │ │ │ ├── ReportGeneratorNode.java # 报告生成节点 │ │ │ └── HumanFeedbackNode.java # 人工反馈节点 │ │ ├── dispatcher/ # 路由分发器 │ │ │ ├── IntentRecognitionDispatcher.java # 意图识别路由 │ │ │ ├── QueryEnhanceDispatcher.java # 查询增强路由 │ │ │ ├── TableRelationDispatcher.java # 表关系路由 │ │ │ ├── FeasibilityAssessmentDispatcher.java # 可行性评估路由 │ │ │ ├── PlanExecutorDispatcher.java # 计划执行路由 │ │ │ ├── SQLExecutorDispatcher.java # SQL执行路由 │ │ │ ├── SqlGenerateDispatcher.java # SQL生成路由 │ │ │ ├── SemanticConsistenceDispatcher.java # 语义一致性路由 │ │ │ ├── PythonExecutorDispatcher.java # Python执行路由 │ │ │ └── HumanFeedbackDispatcher.java # 人工反馈路由 │ │ ├── service/ # 业务服务层 │ │ │ ├── graph/ # 图服务 │ │ │ │ ├── GraphService.java # 图服务接口 │ │ │ │ └── GraphServiceImpl.java # 图服务实现 │ │ │ ├── llm/ # LLM服务 │ │ │ ├── nl2sql/ # NL2SQL服务 │ │ │ ├── vectorstore/ # 向量存储服务 │ │ │ ├── schema/ # 模式服务 │ │ │ ├── semantic/ # 语义模型服务 │ │ │ ├── business/ # 业务知识服务 │ │ │ └── hybrid/ # 混合检索服务 │ │ ├── dto/ # 数据传输对象 │ │ ├── entity/ # 实体类 │ │ ├── mapper/ # MyBatis映射器 │ │ ├── pojo/ # 普通Java对象 │ │ │ ├── Plan.java # 执行计划 │ │ │ └── ExecutionStep.java # 执行步骤 │ │ ├── prompt/ # 提示词管理 │ │ │ ├── PromptLoader.java # 提示词加载器 │ │ │ └── PromptHelper.java # 提示词辅助类 │ │ ├── util/ # 工具类 │ │ └── constant/ # 常量定义 │ └── src/main/resources/prompts/ # 提示词模板文件 │ ├── spring-ai-alibaba-data-agent-management/ # 管理端模块（可独立启动） │ ├── src/main/java/com/alibaba/cloud/ai/dataagent/ │ │ ├── DataAgentApplication.java # 主启动类 │ │ ├── controller/ # REST控制器 │ │ │ ├── ChatController.java # 聊天控制器 │ │ │ ├── AgentController.java # 智能体控制器 │ │ │ ├── DatasourceController.java # 数据源控制器 │ │ │ ├── GraphController.java # 图控制器 │ │ │ └── ... │ │ ├── service/ # 业务服务 │ │ │ ├── AgentService.java # 智能体服务 │ │ │ ├── ChatSessionService.java # 会话服务 │ │ │ └── ... │ │ └── entity/ # 实体类 │ │ ├── Agent.java # 智能体实体 │ │ ├── ChatSession.java # 会话实体 │ │ └── ChatMessage.java # 消息实体 │ └── src/main/resources/ │ ├── application.yml # 应用配置 │ └── sql/ # SQL初始化脚本 │ ├── spring-ai-alibaba-data-agent-common/ # 公共模块 │ └── src/main/java/com/alibaba/cloud/ai/dataagent/common/ │ ├── connector/ # 数据库连接器 │ │ ├── accessor/ # 数据访问器 │ │ │ ├── Accessor.java # 访问器接口 │ │ │ └── impls/ # 各数据库实现 │ │ │ ├── mysql/MySQLDBAccessor.java │ │ │ ├── postgre/PostgreDBAccessor.java │ │ │ └── ... │ │ ├── pool/ # 连接池 │ │ └── ddl/ # DDL操作 │ ├── enums/ # 枚举类 │ ├── request/ # 请求对象 │ └── util/ # 工具类 │ ├── spring-ai-alibaba-data-agent-frontend/ # 前端模块 │ ├── src/ │ │ ├── views/ # 视图组件 │ │ │ ├── AgentList.vue # 智能体列表 │ │ │ ├── AgentCreate.vue # 智能体创建 │ │ │ ├── AgentDetail.vue # 智能体详情 │ │ │ └── AgentRun.vue # 智能体运行 │ │ ├── components/ # 组件 │ │ ├── services/ # API服务 │ │ └── router/ # 路由配置 │ └── package.json │ ├── docker-file/ # Docker部署文件 │ ├── docker-compose.yml # Docker Compose配置 │ ├── Dockerfile-backend # 后端镜像 │ └── Dockerfile-frontend # 前端镜像 │ ├── tools/ # 工具脚本 │ ├── linter/ # 代码检查工具 │ └── scripts/ # 脚本文件 │ ├── pom.xml # 根POM文件 └── README.md # 项目说明文档

3.1 模块职责说明

• spring-ai-alibaba-data-agent-chat：核心业务逻辑模块，包含所有状态图节点、服务层实现，不可独立运行，供其他模块依赖
• spring-ai-alibaba-data-agent-management：Web应用管理端，提供REST API和Web界面，可独立启动
• spring-ai-alibaba-data-agent-common：公共代码模块，包含数据库连接器、工具类等，被其他模块共享
• spring-ai-alibaba-data-agent-frontend：Vue.js前端应用，提供用户交互界面

4. 关键文件清单

4.1 核心配置文件

4.2 核心节点文件