zhuyongxin
26aaf149d8
Task 6.1: 统一异常处理
- 创建 GlobalExceptionHandler：Spring 全局异常拦截器
- SessionNotFoundException: 404 会话未找到
- DocumentProcessException: 400 文档处理异常
- MaxUploadSizeExceededException: 400 文件大小超限
- IllegalArgumentException: 400 参数错误
- Exception: 500 系统异常兜底
- 统一响应格式：Result<T> + HTTP 状态码
Task 6.2: Docker Compose 配置
- 创建 docker-compose.yml：本地开发环境一键启动
- MySQL 8.0: 数据持久化，端口 3306
- Redis 7: 会话缓存，端口 6379
- Milvus Standalone: 向量索引，端口 19530
- etcd: 元数据存储
- MinIO: 对象存储
- 数据卷持久化：mysql-data, redis-data, milvus-data
- 健康检查：自动重启机制
Task 6.3: 更新 README.md
- 新增 Phase 1 专属章节：
- 架构概览（已完成功能清单）
- 本地开发环境（前置要求、快速开始）
- 数据库迁移（Flyway 脚本说明）
- API 文档（文档管理接口示例）
- 项目结构（分层架构说明）
- 待办事项（向量化索引、混合检索）
- 技术决策（包名重构、文本格式、分块策略）
编译验证：BUILD SUCCESS
Progress: 31/33 tasks completed (94%)
353 lines
7.8 KiB
Markdown
353 lines
7.8 KiB
Markdown
# 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
|