# SuperBizAgent

> 基于 Spring Boot + AI Agent 的智能问答与运维系统

## 📖 项目简介

企业级智能业务代理系统，包含两大核心模块：

### 1. RAG 智能问答
集成 Milvus 向量数据库和阿里云 DashScope，提供基于检索增强生成的智能问答能力，支持多轮对话和流式输出。

### 2. AIOps 智能运维
基于 AI Agent 的自动化运维系统，采用 Planner-Executor-Replanner 架构，实现告警分析、日志查询、智能诊断和报告生成。

## 🚀 核心特性

- ✅ **RAG 问答**: 向量检索 + 多轮对话 + 流式输出
- ✅ **AIOps 运维**: 智能诊断 + 多 Agent 协作 + 自动报告
- ✅ **工具集成**: 文档检索、告警查询、日志分析、时间工具
- ✅ **会话管理**: 上下文维护、历史管理、自动清理
- ✅ **Web 界面**: 提供测试界面和 RESTful API


## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 17 | 开发语言 |
| Spring Boot | 3.2.0 | 应用框架 |
| Spring AI | - | AI Agent 框架 |
| DashScope | 2.17.0 | 阿里云 AI 服务 |
| Milvus | 2.6.10 | 向量数据库 |

## 📦 核心模块

```
SuperBizAgent/
├── src/main/java/org/example/
│   ├── controller/
│   │   └── ChatController.java        # 统一接口控制器 ⭐
│   ├── service/
│   │   ├── ChatService.java           # 对话服务 ⭐
│   │   ├── AiOpsService.java          # AIOps 服务 ⭐
│   │   ├── RagService.java            # RAG 服务
│   │   └── Vector*.java               # 向量服务
│   ├── agent/tool/                    # Agent 工具集
│   │   ├── DateTimeTools.java         # 时间工具
│   │   ├── InternalDocsTools.java     # 文档检索
│   │   ├── QueryMetricsTools.java     # 告警查询
│   │   └── QueryLogsTools.java        # 日志查询
│   └── config/                        # 配置类
├── src/main/resources/
│   ├── static/                        # Web 界面
│   └── application.yml                # 应用配置
└── aiops-docs/                        # 运维文档库
```


## 📡 核心接口

### 1. 智能问答接口

**流式对话（推荐）**
```bash
POST /api/chat_stream
Content-Type: application/json

{
  "Id": "session-123",
  "Question": "什么是向量数据库？"
}
```
支持 SSE 流式输出、自动工具调用、多轮对话。

**普通对话**
```bash
POST /api/chat
Content-Type: application/json

{
  "Id": "session-123",
  "Question": "什么是向量数据库？"
}
```
一次性返回完整结果，支持工具调用和多轮对话。

### 2. AIOps 智能运维接口

```bash
POST /api/ai_ops
```
自动执行告警分析流程，生成运维报告（SSE 流式输出）。

### 3. 会话管理

- `POST /api/chat/clear` - 清空会话历史
- `GET /api/chat/session/{sessionId}` - 获取会话信息

### 4. 文件管理

- `POST /api/upload` - 上传文件并自动向量化
- `GET /milvus/health` - Milvus 健康检查


## ⚙️ 核心配置

### application.yml

```yaml
server:
  port: 9900

# Milvus 向量数据库
milvus:
  host: localhost
  port: 19530

# 阿里云 DashScope
spring:
  ai:
    dashscope:
      api-key: "${DASHSCOPE_API_KEY}" // 环境变量

# RAG 配置
rag:
  top-k: 3
  model: "qwen3-max"

# 文档分片
document:
  chunk:
    max-size: 800
    overlap: 100
```

### 环境变量

```bash
export DASHSCOPE_API_KEY=your-api-key
```


## 🚀 快速开始

### 1. 环境准备

```bash
# 设置 API Key
export DASHSCOPE_API_KEY=your-api-key
```

### 2. 启动应用

方法一： 手动启动
```bash
1.先启动向量数据库
docker compose up -d -f vector-database.yml

2.启动服务
mvn clean install
mvn spring-boot:run
```

方法二：一键启动
```bash
make init  # 会自动启动向量数据库并上传运维文档到向量库
```


### 3. 使用示例

**Web 界面**
```
http://localhost:9900
```

**命令行**
```bash
# 上传文档
curl -X POST http://localhost:9900/api/upload \
  -F "file=@document.txt"

# 智能问答
curl -X POST http://localhost:9900/api/chat \
  -H "Content-Type: application/json" \
  -d '{"Id":"test","Question":"什么是向量数据库？"}'

# 健康检查
curl http://localhost:9900/milvus/health
```


---

## 🏗️ Phase 1: 基础设施搭建（已完成）

### 架构概览

Phase 1 完成了项目的基础设施搭建，包括：
- ✅ 数据持久化层（MySQL + JPA + Flyway）
- ✅ 会话管理（Redis）
- ✅ 向量索引（Milvus 集成）
- ✅ 文档管理服务（上传/查询/删除）
- ✅ 统一异常处理
- ✅ RESTful API 接口

### 本地开发环境

#### 前置要求

- Java 17+
- Maven 3.8+
- Docker & Docker Compose（用于本地数据库）

#### 快速开始

**1. 启动依赖服务**

```bash
# 启动 MySQL + Redis + Milvus（本地开发）
docker-compose up -d

# 查看服务状态
docker-compose ps
```

**2. 配置应用**

复制 `src/main/resources/application.yml` 并根据需要修改：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/super_biz_agent
    username: superbiz
    password: superbiz123
  
  data:
    redis:
      host: localhost
      port: 6379
      password: redis123

milvus:
  host: localhost
  port: 19530
```

**3. 运行应用**

```bash
# 编译
mvn clean compile

# 运行测试
mvn test

# 启动应用
mvn spring-boot:run
```

应用将在 `http://localhost:9900` 启动。

#### 数据库迁移

Flyway 会自动执行数据库迁移：

```
src/main/resources/db/migration/
├── V001__create_diagnosis_record.sql
├── V002__create_case_library.sql
└── V003__create_api_document.sql
```

#### API 文档

**文档管理接口**：

```bash
# 上传文档（仅支持 .md 和 .txt）
POST /api/documents/upload
Content-Type: multipart/form-data

# 查询文档
GET /api/documents/{docId}
GET /api/documents/status/{status}?page=0&size=20
GET /api/documents/faultSource/{faultSource}

# 删除文档
DELETE /api/documents/{docId}
```

**健康检查**：

```bash
# Milvus 连接测试
mvn test -Dtest=SimpleMilvusTest

# MySQL 连接测试
mvn test -Dtest=MySQLConnectionTest

# Redis 连接测试
mvn test -Dtest=RedisConnectionTest
```

### 项目结构

```
com.superbiz.agent/
├── controller/          # REST 控制器
│   ├── ChatController.java
│   ├── DocumentController.java
│   └── FileUploadController.java
├── service/             # 业务逻辑层
│   ├── DocumentManagementService.java
│   ├── TextExtractorService.java
│   ├── session/         # 会话管理
│   └── ...
├── repository/          # 数据访问层
│   ├── ApiDocumentRepository.java
│   ├── CaseLibraryRepository.java
│   └── DiagnosisRecordRepository.java
├── domain/              # 领域模型
│   ├── entity/          # JPA 实体
│   ├── model/           # 数据模型
│   └── enums/           # 枚举类
├── dto/                 # 数据传输对象
├── exception/           # 异常处理
│   ├── GlobalExceptionHandler.java
│   ├── SessionNotFoundException.java
│   └── DocumentProcessException.java
└── config/              # 配置类
```

### 待办事项

- [ ] 向量化索引实现（VectorIndexService.indexDocumentChunks）
- [ ] 混合检索工具（精确匹配 + 语义检索 + RRF 融合）
- [ ] 文档管理集成测试

### 技术决策

- **包名重构**：`org.example` → `com.superbiz.agent`
- **文本格式**：仅支持 Markdown (.md) 和纯文本 (.txt)，其他格式需外部转换服务
- **分块策略**：使用 DocumentChunkService 的智能分块（按标题、段落边界）
- **向量数据库**：生产环境推荐 Zilliz Cloud，本地开发可用 Docker Milvus

---

**版本**: v1.0.0  
**作者**: chief  
**许可证**: MIT