# SeedlingAI

**Repository Path**: DaLangYangFan_admin/seedling-ai

## Basic Information

- **Project Name**: SeedlingAI
- **Description**: Seedling AI (Vulnerability Management System with Retrieval-Augmented Generation) 是一个基于Spring Boot和Spring AI框架构建的智能问答系统，专门用于处理脆弱性扫描相关的文档查询和页面交互操作。该系统采用RAG（检索增强生成）技术，结合阿里云百炼大模型和Chroma向量数据库，为用户提供基于文档内容的
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-01-13
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Seedling AI - 智能助手系统

## 项目概述

Seedling AI 是一个基于Spring Boot和Spring AI框架构建的智能助手系统，专门用于处理文档查询和页面交互操作。
该系统采用RAG（检索增强生成）技术，结合多种大模型服务和Chroma向量数据库，为用户提供基于文档内容的精准问答服务，并支持页面元素分析和智能交互操作。

## 特别注意：
基于若依开源项目开发了一套页面对话&操控组件，需要页面对话框和页面操作的功能需要额外启动这个项目。
https://gitee.com/tianchaixiaoniuniu/RuoYi-Vue/tree/springboot3/

## 技术架构

### 核心技术栈
- **后端框架**: Spring Boot 3.5.7
- **Java版本**: JDK 17
- **AI框架**: Spring AI 1.1.0
- **大模型服务**: 阿里云百炼 (DashScope)、Ollama本地模型
- **向量数据库**: Chroma (部署在 http://localhost:8000)
- **关系数据库**: MySQL (用于对话记忆存储)
- **文档处理**: Spring AI PDF/Tika Document Reader
- **前端技术**: HTML5, CSS3, JavaScript, Bootstrap 5

### 系统架构
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面      │    │   Spring Boot   │    │   AI服务层      │
│                 │    │   应用层        │    │                 │
│ - Web界面       │◄──►│ - REST API      │◄──►│ - 多模型支持    │
│ - 流式响应      │    │ - 业务逻辑      │    │ - 文本嵌入      │
│ - 页面交互      │    │ - 页面分析      │    │ - 操作执行      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   数据访问层    │    │   向量数据库    │
                       │                 │    │                 │
                       │ - JDBC存储      │    │ - Chroma        │
                       │ - 对话记忆      │    │ - 文档向量      │
                       └─────────────────┘    └─────────────────┘
```

## 主要功能

### 1. 多格式文档处理与向量化
- 支持多种文档格式：PDF、JSON、CSV、Excel、Word、Markdown、TXT、XML、HTML、RTF、PPT
- 使用策略模式管理不同格式的处理器，易于扩展
- 支持文件路径和文件流两种输入方式
- 智能文档分割，支持自定义分割参数
- 使用阿里云文本嵌入模型(text-embedding-v4)将文档内容转换为向量表示
- 将向量存储到Chroma向量数据库中，集合名称为"vms_business"

### 2. 多模型智能问答
- 支持多种模型路由：默认模型(qwen-plus)、经济模型(qwen3:4b)、高质量模型(qwen3-8b)、多模态模型(qwen3-vl-plus)
- 基于用户问题从向量数据库中检索相关文档片段
- 将检索到的内容作为上下文提供给大模型
- 生成基于文档内容的精准回答
- 支持流式输出，提供更好的用户体验
- 当参考文档没有相关信息时，会提示"这个问题触及到我的知识盲区了"

### 3. 对话记忆
- 维护对话历史，保持上下文连贯性
- 使用MySQL数据库存储对话记录
- 每次进入页面生成新的chatId，确保每次会话独立
- 支持持久化存储，确保对话状态不丢失

### 4. 工具系统
- 基于Spring AI 1.1的@Tool注解规范实现的模块化工具管理系统
- 支持动态加载工具、参数校验、权限控制
- 预置工具包括字符串处理工具和计算器工具
- 支持基于配置文件的工具管理和用户组权限控制

### 5. 页面元素分析
- 支持上传页面元素信息进行分析
- 自动识别页面类型和关键元素
- 提供可能的操作建议
- 支持多种元素类型：button、input、link、form等

### 6. 智能交互操作
- 基于页面元素分析和用户需求，生成操作建议
- 支持多种操作类型：navigate、click、input、scan
- 提供操作执行接口，支持异步任务处理
- 支持操作结果查询和状态跟踪

## 项目结构

### 后端核心组件
1. **SeeglingAiApplication**: 应用程序入口点
2. **控制器层**:
   - **ChatController**: 处理聊天请求的控制器，提供多个主要接口：
     - `/chat`: 基础智能问答接口
     - `/chatTool`: 支持工具调用的智能问答接口
     - `/chatMcp`: 支持MCP工具调用的智能问答接口
     - `/embedding`: 文档向量化接口
   - **AiAssistantController**: AI助手控制器，提供以下接口：
     - `/api/ai/chat`: 发送消息到AI平台
     - `/api/ai/page-elements`: 上传页面元素信息（页面扫描功能）
     - `/api/ai/chatControl`: 基于页面元素的智能问答与页面操控命令
     - `/api/ai/isNeedAssistanceWithOperations`: 判断是否需要操作协助
   - **DocumentProcessingController**: 文档处理控制器，提供以下接口：
     - `/api/documents/process`: 处理单个文档文件
     - `/api/documents/process-pdf`: 处理PDF文档
     - `/api/documents/process-json`: 处理JSON文档
     - `/api/documents/split`: 分割文档
     - `/api/documents/formats`: 获取支持的文档格式
   - **IndexController**: 首页控制器

3. **服务层**:
   - **AiAssistantService**: AI助手服务，处理业务逻辑
   - **DocumentProcessingService**: 文档处理服务，负责多格式文档的处理
   - **RAGService**: RAG检索增强生成服务
   - **ETLUtils**: 文档处理工具类，支持多格式文档的解析、分割和向量化

4. **工具层**:
   - **ToolManager**: 工具管理器，负责工具的注册、查找和执行
   - **ScanTools**: 扫描工具实现
   - **工具实现**: 各种具体工具的实现

5. **配置层**:
   - **ChatMemoryConfig**: 聊天记忆配置，管理对话上下文
   - **ModelRouterConfig**: 模型路由配置，支持多模型切换
   - **SecurityConfig**: 安全配置，管理认证和授权
   - **WebConfig**: Web配置类

6. **路由层**:
   - **ModelRouter**: 模型路由器，根据需求选择合适的模型

### 前端组件
1. **index.html**: 主页面，提供聊天界面
2. **app.js**: 前端逻辑，处理用户交互和API调用
3. **style.css**: 样式文件，定义界面外观

### 数据库结构
- **MySQL表**: `SPRING_AI_CHAT_MEMORY`，存储对话历史
- **Chroma集合**: `vms_business`，存储文档向量

## 部署与运行

### 环境要求
- JDK 17 或更高版本
- Maven 3.6 或更高版本
- MySQL 8.0 或更高版本
- Chroma 向量数据库服务
- 阿里云百炼API访问权限(可选)
- Ollama服务(可选，用于本地模型)

### 启动方式
1. 配置环境变量：
   复制`.env.example`为`.env`，并填入正确的配置值：
   ```bash
   # API配置
   DASHSCOPE_API_KEY=your_dashscope_api_key
   
   # 数据库配置
   DB_PASSWORD=your_database_password
   
   # Chroma向量数据库配置
   CHROMA_HOST=your_chroma_host_address
   ```

2. 使用Maven构建项目：
   ```bash
   mvn clean install
   ```

3. 运行应用：
   ```bash
   mvn spring-boot:run
   ```


## 配置说明

### application.yml 关键配置
```yaml
# 服务器端口
server:
  port: 8081

# Spring AI模型配置
spring:
  ai:
    model:
      default-model: qwen-plus
      cost-effective-model: qwen3:4b
      high-quality-model: qwen3-8b
      multimodal-model: qwen3-vl-plus
      embedding: openai
    openai:
      api-key: ${DASHSCOPE_API_KEY}
      base-url: https://dashscope.aliyuncs.com/compatible-mode/v1/
      embedding:
        options:
          model: text-embedding-v4
    ollama:
      base-url: http://localhost:11434
      embedding:
        model: text-embedding-v4
    vectorstore:
      chroma:
        collection-name: vms_business
        initialize-schema: true
        client:
          host: ${CHROMA_HOST}
          port: 8000
    chat:
      memory:
        max-messages: 8
        repository:
          jdbc:
            initialize-schema: always
  datasource:
    url: jdbc:mysql://localhost:3306/springai?characterEncoding=utf8&useSSL=false&serverTimezone=UTC&
    username: root
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver

# 工具配置
tool-config: tools/defaultTools.json
```

## API接口说明

### 认证方式

系统支持三种认证方式：

1. **Bearer Token认证**
   ```
   Authorization: Bearer seedling-ai-2024-token
   ```

2. **API Key认证**
   ```
   X-API-Key: seedling-ai-2024-key
   ```

3. **基本认证**
   ```
   用户名: ai-assistant
   密码: seedling-2024
   ```

### 主要API接口

#### 1. 聊天相关接口

1. **基础智能问答**
   - 路径: `GET /chat`
   - 参数: value(问题内容), chatId(会话ID)
   - 功能: 基于文档内容回答用户问题，支持流式输出

2. **工具调用问答**
   - 路径: `GET /chatTool`
   - 参数: value(问题内容), chatId(会话ID)
   - 功能: 支持工具调用的智能问答

3. **MCP工具调用问答**
   - 路径: `GET /chatMcp`
   - 参数: value(问题内容), chatId(会话ID)
   - 功能: 支持MCP工具调用的智能问答

4. **文档向量化**
   - 路径: `GET /embedding`
   - 功能: 将预置PDF文档向量化存储到向量数据库

#### 2. AI助手接口

1. **发送消息到AI平台**
   - 路径: `POST /api/ai/chat`
   - 功能: 处理用户消息，返回AI回复和操作建议

2. **上传页面元素信息**
   - 路径: `POST /api/ai/page-elements`
   - 功能: 分析页面元素，返回页面分析结果，（页面扫描功能）

3. **基于页面元素的智能问答**
   - 路径: `POST /api/ai/chatControl`
   - 功能: 基于页面元素内容回答用户问题与下发操作命令

4. **判断是否需要操作协助**
   - 路径: `POST /api/ai/isNeedAssistanceWithOperations`
   - 功能: 判断用户是否需要执行操作协助

#### 3. 文档处理接口

1. **处理单个文档文件**
   - 路径: `POST /api/documents/process`
   - 功能: 处理单个文档文件，支持多种格式

2. **处理PDF文档**
   - 路径: `POST /api/documents/process-pdf`
   - 功能: 处理PDF文档，支持页面模式和段落模式

3. **处理JSON文档**
   - 路径: `POST /api/documents/process-json`
   - 功能: 处理JSON文档，可指定要提取的键

4. **分割文档**
   - 路径: `POST /api/documents/split`
   - 功能: 分割文档，可自定义分割参数

5. **获取支持的文档格式**
   - 路径: `GET /api/documents/formats`
   - 功能: 获取系统支持的所有文档格式

## 使用流程

### 1. 文档问答流程

1. **文档向量化**：首次使用时，系统会自动调用`/embedding`接口，将PDF文档内容向量化存储到Chroma数据库。
   - 也可以通过`/api/documents/process`接口处理其他格式的文档

2. **用户提问**：用户在前端界面输入问题，系统生成唯一的chatId标识本次会话。

3. **智能回答**：
   - 系统从向量数据库中检索与问题相关的文档片段
   - 将检索结果作为上下文提供给选定的AI模型
   - AI模型基于上下文生成回答，并通过流式响应返回给前端

### 2. 工具调用流程

1. **用户请求**：用户提出需要工具协助的问题，通过`/chatTool`接口发送请求。

2. **工具识别**：系统根据问题内容识别需要的工具类型。

3. **工具执行**：
   - 系统调用相应的工具执行请求
   - 工具执行完成后返回结果

4. **结果整合**：AI模型将工具执行结果整合到回答中，返回给用户。

### 3. 页面交互流程

1. **页面元素上传**：通过`/api/ai/page-elements`接口上传当前页面元素信息。

2. **页面分析**：AI分析页面元素，识别页面类型和关键元素。

3. **智能交互**：
   - 用户可以通过`/api/ai/chatControl`接口基于页面内容提问
   - 系统提供基于当前页面内容的智能回答和操作建议
   - 用户可以选择执行建议的操作

### 4. 多模型切换流程

1. **模型选择**：系统根据请求类型和复杂度自动选择合适的模型：
   - 默认模型(qwen-plus)：用于一般问答
   - 经济模型(qwen3:4b)：用于简单任务，响应速度快
   - 高质量模型(qwen3-8b)：用于复杂任务，提供高质量回答
   - 多模态模型(qwen3-vl-plus)：用于处理多种类型输入

2. **动态切换**：系统可以在同一会话中根据需要动态切换模型，提供最佳用户体验。

## 扩展功能

### 1. 工具系统扩展

系统基于Spring AI 1.1的@Tool注解规范实现了模块化的工具管理系统，支持：

- **动态工具加载**：通过配置文件动态加载工具类
- **权限控制**：基于用户组的工具访问权限控制
- **参数校验**：自动校验工具调用参数
- **扩展性**：轻松添加新的工具类型

添加新工具的步骤：
1. 创建实现`ToolFunction`接口的工具类
2. 使用`@Tool`注解标记工具方法
3. 在配置文件中添加工具定义
4. 重启应用或热加载配置

### 2. 向量数据库扩展

系统设计了多向量数据库支持的架构，当前已实现Chroma向量数据库适配器，并为其他向量数据库预留了配置结构。未来可支持：
- Pinecone
- Weaviate
- Milvus
- Qdrant

### 3. MCP服务集成

系统预留了MCP(Model Context Protocol)服务集成能力，可以方便地集成各种MCP服务，扩展系统的功能边界。

## 常见问题

### 1. 如何添加新文档？

可以通过以下接口添加新文档：
- 文件上传：`POST /api/documents/process`
- PDF文档：`POST /api/documents/process-pdf`
- JSON文档：`POST /api/documents/process-json`

### 2. 如何切换AI模型？

系统支持多模型路由，可以通过修改`application.yml`中的配置来更改默认模型：
```yaml
spring:
  ai:
    model:
      default-model: qwen-plus  # 更改此处可切换默认模型
```

### 3. 如何配置向量数据库？

向量数据库配置在`application.yml`中：
```yaml
spring:
  ai:
    vectorstore:
      chroma:
        client:
          host: ${CHROMA_HOST}  # 修改此处更改向量数据库地址
          port: 8000
```

### 4. 如何添加新工具？

参考`ETL-工具类使用指南.md`和`resources/docs/Tool使用指南.md`文档，按照以下步骤添加新工具：
1. 创建工具实现类
2. 使用`@Tool`注解标记方法
3. 在配置文件中添加工具定义
4. 重启应用

## 开发指南

### 1. 环境搭建

1. 安装JDK 17+
2. 安装Maven 3.6+
3. 安装MySQL 8.0+
4. 安装Chroma向量数据库
5. 克隆项目并导入IDE

### 2. 本地开发

1. 配置环境变量（参考`.env.example`）
2. 启动MySQL和Chroma服务
3. 运行`mvn spring-boot:run`启动应用
4. 访问`http://localhost:8081`进行测试

### 3. 代码规范

1. 遵循Java编码规范
2. 使用Lombok简化代码
3. 为新增功能编写单元测试
4. 更新相关文档

### 4. 调试技巧

1. 使用`logging.level.com.tcxnn.*=DEBUG`开启调试日志
2. 使用Swagger UI(`http://localhost:8081/swagger-ui.html`)测试API
3. 使用数据库客户端查看对话历史和向量数据

## 贡献指南

欢迎社区贡献！请遵循以下步骤：

1. Fork项目
2. 创建特性分支
3. 提交代码
4. 创建Pull Request

## 许可证

本项目采用Apache 2.0开源许可证，详情请参考`LICENSE`文件。
   - 前端实时显示回答内容，保留换行和缩进格式

4. **对话记忆**：整个对话过程会被记录到MySQL数据库中，保持上下文连贯性。

### 2. 页面交互流程

1. **页面扫描**：用户上传页面元素信息到`/api/ai/page-elements`接口。

2. **页面分析**：系统分析页面类型、关键元素和可能操作。

3. **交互对话**：用户通过`/api/ai/chat`接口描述需求，AI识别用户意图，返回具体操作建议。

4. **执行操作**：前端根据建议调用`/api/ai/execute-action`接口执行操作。

5. **结果获取**：通过`/api/ai/action-result/{taskId}`获取操作结果和状态。

## 项目特点

1. **智能检索**：基于向量相似度的文档检索，确保回答的相关性
2. **流式响应**：支持实时流式输出，提升用户体验
3. **对话记忆**：维护对话历史，支持多轮对话
4. **知识边界**：当超出文档范围时，会明确告知用户
5. **用户友好**：简洁美观的界面设计，支持移动设备
6. **页面交互**：支持页面元素分析和智能操作指导
7. **多认证支持**：提供多种认证方式，适应不同部署场景


## 总结

Seedling AI是一个完整的RAG系统实现，特别适合于需要基于特定文档提供智能问答服务和页面交互的场景，如技术支持、知识库查询、操作指导等。通过结合向量检索和大语言模型，系统能够提供准确、相关的回答，同时保持对话的上下文连贯性，并提供智能的页面操作指导，大大提升了用户体验和工作效率。