# DataAgent

**Repository Path**: fanyc-ai/DataAgent

## Basic Information

- **Project Name**: DataAgent
- **Description**: https://github.com/spring-ai-alibaba/DataAgent.git
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-25
- **Last Updated**: 2025-11-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Alibaba DataAgent

（ “DataAgent用户1群”群的钉钉群号： 154405001431）

## 项目简介

这是一个基于Spring AI Alibaba的自然语言转SQL项目，能让你用自然语言直接查询数据库，不需要写复杂的SQL。

> （提示：文档有点落后，请以仓库实际代码为准，开发者正在抽空完善文档中……）

### 替换chat-model、embedding-model和vector-store的实现类

本项目的`ChatModel`和`EmbeddingModel`默认使用`DashScope`的实现，`VectorStore`默认使用内存向量，你可以替换成其他模型实现。

在[根pom](./pom.xml)中的`dependencies`中可以替换`ChatModel`，`EmbeddingModel`和`VectorStore`的实现starter，以替换掉项目默认使用的实现：

```xml
    <dependencies>
        <!-- 在这里可以替换vector-store，chat-model和embedding-model的starter -->
        <!-- 如果不使用默认依赖的话，需要手动配置application.yml -->
    
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
            <version>${spring-ai-alibaba.version}</version>
        </dependency>
    
        <!--            milvus  -->
        <!--        <dependency>-->
        <!--            <groupId>org.springframework.ai</groupId>-->
        <!--            <artifactId>spring-ai-starter-vector-store-milvus</artifactId>-->
        <!--        </dependency>-->
    </dependencies>
```

注意修改`application.yml`，以符合这些starter的需求。

举个例子，如果你需要使用`Milvus`作为向量库，使用DeepSeek的`ChatModel`，使用硅基流动的`EmbeddingModel`，你可以导入以下依赖：

```xml
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-deepseek</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-vector-store-milvus</artifactId>
        </dependency>
    </dependencies>
```

然后这么写`application.yml`：

```yaml
spring:
  ai:
    model:
      chat: deepseek      # 一定要配置此字段，否则会报多个Bean实例的异常
      embedding: openai
    deepseek:
      chat:
        api-key: ${DEEPSEEK_API_KEY}
    openai:
      api-key: ${SILICONFLOW_API_KEY}
      embedding:
        api-key: ${SILICONFLOW_API_KEY}
        base-url: https://api.siliconflow.cn
        options:
          model: BAAI/bge-m3
    vectorstore:
      milvus:
        initialize-schema: true
        client:
          host: ${MILVUS_HOST:192.168.16.100}
          port: ${MILVUS_PORT:19530}
          username: ${MILVUS_USERNAME:root}
          password: ${MILVUS_PASSWORD}
        databaseName: ${MILVUS_DATABASE:default}
        collectionName: ${MILVUS_COLLECTION:vector_store}
        embeddingDimension: 1536
        indexType: IVF_FLAT
        metricType: COSINE
        id-field-name:
        content-field-name:
        metadata-field-name:
        embedding-field-name:
```

## 项目结构

这个项目分为三个部分：

```
spring-ai-alibaba-nl2sql/
├── spring-ai-alibaba-nl2sql-management    # 管理端（可直接启动的Web应用）
├── spring-ai-alibaba-nl2sql-chat         # 核心功能（不能独立启动，供集成使用）
└── spring-ai-alibaba-nl2sql-common       # 公共代码
```

## 快速启动

项目进行本地测试是在spring-ai-alibaba-nl2sql-management中进行

### 1. 业务数据库准备

可以在spring-ai-alibaba-example项目仓库获取测试表和数据：

- Schema：https://github.com/springaialibaba/spring-ai-alibaba-examples/blob/main/spring-ai-alibaba-nl2sql-example/chat/sql/schema.sql
- Data：https://github.com/springaialibaba/spring-ai-alibaba-examples/blob/main/spring-ai-alibaba-nl2sql-example/chat/sql/insert.sql

将表和数据导入到你的MySQL数据库中。



### 2. 配置

#### 2.1 配置management数据库



在`spring-ai-alibaba-nl2sql-management/src/main/resources/application.yml`中配置你的MySQL数据库连接信息。

> 初始化行为说明：默认开启自动创建表并插入示例数据（`spring.sql.init.mode: always`）。生产环境建议关闭，避免示例数据回填覆盖你的业务数据。

```yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/nl2sql?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true&allowMultiQueries=true&allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Shanghai
    username: ${MYSQL_USERNAME:root}
    password: ${MYSQL_PASSWORD:root}
    driver-class-name: com.mysql.cj.jdbc.Driver
    type: com.alibaba.druid.pool.DruidDataSource
```

#### 2.2 可选：启用/关闭自动初始化（schema.sql + data.sql）



- 默认配置：`application.yml` 中已设置为开启

```yaml
spring:
  sql:
    init:
      mode: always           # 默认：每次启动执行 schema.sql 与 data.sql
      schema-locations: classpath:sql/schema.sql
      data-locations: classpath:sql/data.sql
```

- 若不希望每次启动回填示例数据，可将 `mode` 改为 `never` 关闭：

```yaml
spring:
  sql:
    init:
      mode: never            # 关闭自动初始化
      schema-locations: classpath:sql/schema.sql
      data-locations: classpath:sql/data.sql
```

注意：默认开启时（`mode: always`），`data.sql` 会在每次启动回填示例数据（即使你手动删除了数据）。生产环境请改为 `mode: never`，避免覆盖/复原业务数据。

![Snipaste_2025-09-18_14-35-29.jpg](img/Snipaste_2025-09-18_14-35-29.jpg)


#### 2.3 配置 API Key

```yaml
spring:
  ai:
    openai:
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      api-key: ${AI_DASHSCOPE_API_KEY}
      model: qwen-max
      embedding:
        model: text-embedding-v4
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
```



#### 2.4 嵌入模型批处理策略配置



| 属性                                                        | 说明                                                         | 默认值      |
| ----------------------------------------------------------- | ------------------------------------------------------------ | ----------- |
| spring.ai.alibaba.nl2sql.embedding-batch.encoding-type      | 文本编码类型，可参考com.knuddels.jtokkit.api.EncodingType    | cl100k_base |
| spring.ai.alibaba.nl2sql.embedding-batch.max-token-count    | 每批次最大令牌数 值越小，每批次文档越少，但更安全 值越大，处理效率越高，但可能超出API限制 建议值：2000-8000，根据实际API限制调整 | 2000        |
| spring.ai.alibaba.nl2sql.embedding-batch.reserve-percentage | 预留百分比 用于预留缓冲空间，避免超出限制 建议值：0.1-0.2（10%-20%） | 0.2         |
| spring.ai.alibaba.nl2sql.embedding-batch.max-text-count     | 每批次最大文本数量 适用于DashScope等有文本数量限制的API DashScope限制为10 | 10          |



#### 2.5 向量库配置



| 属性                                                         | 说明                                                         | 默认值    |
| ------------------------------------------------------------ | ------------------------------------------------------------ | --------- |
| spring.ai.alibaba.nl2sql.vector-store.similarity-threshold   | 相似度阈值配置，用于过滤相似度分数大于等于此阈值的文档       | 0.2       |
| spring.ai.alibaba.nl2sql.vector-store.batch-del-topk-limit   | 一次删除操作中，最多删除的文档数量                           | 5000      |
| spring.ai.alibaba.nl2sql.vector-store.topk-limit             | 查询返回最大文档数                                           | 30        |
| **spring.ai.alibaba.nl2sql.vector-store.enable-hybrid-search** | 是否启用混合搜索。**注意**：**项目目前默认只提供ES的混合检索能力，<br />如需要扩展其他向量库可自行继承重写 com.alibaba.cloud.ai.service.hybrid.retrieval<br />.AbstractHybridRetrievalStrategy#retrieve 该方法**<br />**并且修改com.alibaba.cloud.ai.service.hybrid.<br />factory.HybridRetrievalStrategyFactory#getObject<br />注册相应的bean** | **false** |
| spring.ai.alibaba.nl2sql.vector-store.elasticsearch-min-score | Elasticsearch最小分数阈值，用于es执行关键词搜索时过滤相关性较低的文档。<br />**开发时使用的es服务端版本 8.15.0** | 0.5       |



#### 2.6 检索融合策略

| 属性                                     | 说明                 | 默认值 |
| ---------------------------------------- | -------------------- | ------ |
| spring.ai.alibaba.nl2sql.fusion-strategy | 多路召回结果融合策略 | rrf    |
|                                          |                      |        |



### 3. 启动管理端

在`spring-ai-alibaba-nl2sql-management`目录下，运行 `spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-management/src/main/java/com/alibaba/cloud/ai/DataAgentApplication.java` 类。

### 4. 启动WEB页面

进入 `spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-web-ui` 目录

#### 4.1 安装依赖


```bash
# 使用 npm
npm install

# 或使用 yarn
yarn install
```

#### 4.2 启动服务

```bash
# 使用 npm
npm run dev

# 或使用 yarn
yarn dev
```

启动成功后，访问地址 http://localhost:3000

## 系统体验

访问 http://localhost:3000 ，可以看到有四个智能体（目前这四个只是占位显示，并没有对接数据）

![homepage-agents.png](img/homepage-agents.png)


点击右上角“创建智能体” ，这里只需要输入智能体名称，其他配置都选默认。

创建成功后，可以看到智能体配置页面。

![agent-config.png](img/agent-config.png)

进入数据源配置页面，配置业务数据库（我们在环境初始化时第一步提供的业务数据库）。

![datasource-config.png](img/datasource-config.png)

添加完成后，可以在列表页面验证数据源连接是否正常。

![datasource-validation.png](img/datasource-validation.png)

预设问题管理，可以为智能体设置预设问题

![preset-questions.png](img/preset-questions.png)

智能体调试页面可以定制化配置数据源，然后初始化数据源到向量库，进行效果调试。

![agent-debug.png](img/agent-debug.png)

![vector-initialization.png](img/vector-initialization.png)

成功后可以在智能体调试页面输入自然语言进行查询。

![natural-language-query.png](img/natural-language-query.png)

![query-results.png](img/query-results.png)

> 调试和发布的智能体数据是分离的，调试时的数据不会影响发布后的智能体。

调试没问题后，可以发布智能体。

![publish-agent.png](img/publish-agent.png)

> 目前“嵌入网站”和“访问API”当前版本暂未实现。

点击发布后会更新元数据到发布后的智能体。

![metadata-update.png](img/metadata-update.png)

![publish-complete.png](img/publish-complete.png)

分析问题

![analyze-question.png](img/analyze-question.png)

分析结果

![analyze-result.png](img/analyze-result.png)

> 如果你没有环境执行Python节点，临时解决方法：在提问的问题中，添加“请不要通过Python分析”。