## 项目概述

DataAgent 是一个基于 **Spring AI Alibaba Graph** 打造的企业级智能数据分析 Agent。它超越了传统的 Text-to-SQL 工具，进化为一个能够执行 **Python 深度分析**、生成 **多维度图表报告** 的 AI 智能数据分析师。

系统采用高度可扩展的架构设计，**全面兼容 OpenAI 接口规范**的对话模型与 Embedding 模型，并支持**灵活挂载任意向量数据库**。无论是私有化部署还是接入主流大模型服务（如 Qwen, Deepseek），都能轻松适配，为企业提供灵活、可控的数据洞察服务。

同时，本项目原生支持 **MCP (Model Context Protocol)**，可作为 MCP 服务器无缝集成到 Claude Desktop 等支持 MCP 的生态工具中。

## 核心功能

- **智能数据分析**：基于 StateGraph 的 Text-to-SQL 转换，支持复杂的多表查询和多轮对话意图理解。
- **Python 深度分析**：基于 Spring AI Alibaba Sandbox 在任务级容器中执行生成代码，支持 PEP 723 动态依赖、资源限制、失败重试与自动清理。
- **智能报告生成**：分析结果自动汇总为包含 ECharts 图表的 HTML/Markdown 报告，所见即所得。
- **人工反馈机制**：独创的 Human-in-the-loop 机制，支持用户在计划生成阶段进行干预和调整。
- **RAG 检索增强**：集成向量数据库，支持对业务元数据、术语库的语义检索，提升 SQL生成准确率。
- **多模型调度**：内置模型注册表，支持运行时动态切换不同的 LLM 和 Embedding 模型。
- **MCP 服务器**：遵循 MCP 协议，支持作为 Tool Server 对外提供 NL2SQL 和 智能体管理能力。
- **API Key 管理**：完善的 API Key 生命周期管理，支持细粒度的权限控制。

## 适用与不适用场景

- **适用场景**：企业级数据分析、自然语言查询数据库、自动化报告生成、需要结合业务知识进行数据洞察的场景。
- **不适用场景**：仓库资料未提供。

## 技术架构与依赖

- **编程语言**：Java 17+
- **框架**：Spring Boot 3.4.8+, Spring AI Alibaba 1.1.2.2
- **前端**：Node.js 22+, Nuxt
- **数据库**：MySQL 5.7+
- **容器化**：Docker（Python 工作流必需）
- **AI 模型**：兼容 OpenAI 接口规范的对话模型与 Embedding 模型（如 Qwen, Deepseek）
- **向量数据库**：支持内存向量库、Milvus、Elasticsearch 等
- **协议**：MCP (Model Context Protocol)

## 安装与快速开始

### 1. 准备环境
- JDK 17+
- MySQL 5.7+
- Node.js 22+
- pnpm 11+
- Docker（工作流需要执行 Python 步骤时必需）

### 2. 启动服务

```bash
# 1. 导入数据库
mysql -u root -p < data-agent-management/src/main/resources/sql/schema.sql

# 2. 启动后端
./mvnw -pl data-agent-management spring-boot:run

# 3. 在另一个终端启动前端
cd data-agent-frontend-nuxt
pnpm install && pnpm dev
```

### 3. 访问系统
打开浏览器访问 `http://localhost:3000`，开始创建您的第一个数据智能体！

## 典型使用方法

1. **创建智能体**：在 Web 界面创建并配置数据智能体。
2. **配置数据源**：连接业务数据库，选择数据表。
3. **配置知识**：设置语义模型、业务知识和智能体知识库，提升 NL2SQL 准确率。
4. **运行分析**：输入自然语言问题，系统自动生成 SQL、执行 Python 分析并输出报告。
5. **人工反馈**：在计划生成阶段进行干预和调整。
6. **MCP 集成**：作为 MCP 服务器集成到 Claude Desktop 等工具中。

## 配置与部署要点

- **模型配置**：支持通过 Web 界面添加和管理 LLM 及 Embedding 模型。
- **向量库配置**：默认使用内存向量库，可切换至 Milvus、Elasticsearch 等持久化向量库。
- **Python 沙盒配置**：需配置 Docker 环境，支持动态依赖安装。
- **API Key 管理**：支持生成、重置、删除与启用/禁用 API Key。
- **Langfuse 可观测性**：可选集成 Langfuse 进行 LLM 调用追踪和性能监控。

## 限制、风险与许可证

- **许可证**：Apache License 2.0
- **限制**：仓库资料未提供。
- **风险**：仓库资料未提供。

## 官方链接

- **GitHub 仓库**：https://github.com/spring-ai-alibaba/DataAgent
- **最新发布**：https://github.com/spring-ai-alibaba/DataAgent/releases/tag/1.0.0-rc7
- **Spring AI Alibaba**：https://github.com/alibaba/spring-ai-alibaba

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README 及文档
- **分析时间**：2026-08-03