commit
This commit is contained in:
zhuyongxin
@@ -0,0 +1,352 @@
|
||||
# Explore Report: SuperBizAgent-java
|
||||
|
||||
> 生成时间: 2026-04-30
|
||||
> Project type: **code repository**
|
||||
> Phases completed: 4/4
|
||||
> Diagram included: yes
|
||||
> Core designs: 3
|
||||
> Status: complete
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Positioning & Structure
|
||||
|
||||
### 这是什么项目
|
||||
|
||||
SuperBizAgent-java 是一个基于 **Spring AI + Alibaba DashScope (Qwen)** 的智能运维 AI Agent 平台。它将大语言模型、向量检索增强生成（RAG）和多智能体协作（Planner-Executor-Replanner）整合为一体，面向企业 IT 运维场景提供：
|
||||
|
||||
- **智能文档问答**：上传运维知识库文档（Markdown/TXT），通过 RAG 管道实现向量化检索 + LLM 流式生成回答
|
||||
- **告警分析自动化**：多 Agent 协作分析 Prometheus 告警，结合日志查询（腾讯云 CLS）和内部知识库，生成结构化的告警分析报告
|
||||
- **MCP 协议集成**：通过 Spring AI MCP Client 连接外部工具服务，扩展 Agent 能力边界
|
||||
|
||||
### 为什么值得研究
|
||||
|
||||
| 维度 | 价值 |
|
||||
|------|------|
|
||||
| **AI 框架落地** | Spring AI Alibaba 生态的完整实践——ReactAgent、SupervisorAgent、Tool 注册、流式对话 |
|
||||
| **多 Agent 协作** | 非玩具级的 Planner-Executor-Replanner 监督循环，实际解决告警分析这种开放性问题 |
|
||||
| **RAG 工程化** | 完整的文档分块→向量化→Milvus 存储→语义检索→流式生成的端到端管道 |
|
||||
| **MCP 协议** | 业界较早将 MCP (Model Context Protocol) 用于生产场景的 Java 案例 |
|
||||
|
||||
### 适合谁
|
||||
|
||||
- Spring Boot / Java 开发者学习 AI Agent 框架的落地模式
|
||||
- AIOps / SRE 工程师了解智能运维 Agent 的架构设计
|
||||
- 对 Spring AI Alibaba 生态感兴趣的技术决策者
|
||||
|
||||
### 项目规模
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| Java 源文件 | ~25 个 |
|
||||
| 代码行数 | ~2500 行 |
|
||||
| API 端点 | 7 个 |
|
||||
| Agent 工具 | 4 个 |
|
||||
| 知识库文档 | 5 篇 |
|
||||
|
||||
### 技术栈
|
||||
|
||||
```
|
||||
应用层 Spring Boot 3.2 / Java 17
|
||||
AI 层 Spring AI Alibaba 1.1.0 / Qwen3-Max / text-embedding-v4
|
||||
存储层 Milvus 2.5 (向量库) / MinIO (对象存储)
|
||||
集成层 MCP Client (WebFlux SSE) / Prometheus
|
||||
部署 Docker Compose (Milvus + etcd + MinIO + Attu)
|
||||
```
|
||||
|
||||
### 与替代方案的对比
|
||||
|
||||
| 方案 | 优势 | 劣势 |
|
||||
|------|------|------|
|
||||
| 本项目 (Spring AI Alibaba) | 完整生态、国产模型、Java 原生 | 社区相对年轻 |
|
||||
| LangChain4j | 社区活跃、模型支持广 | 多 Agent 模式需自行构建 |
|
||||
| Python LangChain | 生态最丰富 | 非 Java 技术栈 |
|
||||
| 纯 DashScope API | 简单直接 | 缺乏 Agent 编排、工具调用框架 |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Flow
|
||||
|
||||
### 架构总览
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph 前端
|
||||
WEB[Web UI<br/>index.html + app.js]
|
||||
end
|
||||
|
||||
subgraph 控制层
|
||||
CC[ChatController<br/>/api/chat /api/chat_stream]
|
||||
AO[AIOpsController<br/>/api/ai_ops]
|
||||
UP[FileUploadController<br/>/api/upload]
|
||||
HC[MilvusCheckController<br/>/milvus/health]
|
||||
end
|
||||
|
||||
subgraph 服务层
|
||||
CS[ChatService<br/>ReactAgent 编排]
|
||||
AIS[AiOpsService<br/>多Agent 协作]
|
||||
RS[RagService<br/>RAG 流式问答]
|
||||
VIS[VectorIndexService<br/>文件索引管道]
|
||||
VSS[VectorSearchService<br/>向量相似搜索]
|
||||
VES[VectorEmbeddingService<br/>文本向量化]
|
||||
DCS[DocumentChunkService<br/>智能文档分块]
|
||||
end
|
||||
|
||||
subgraph Agent工具
|
||||
DT[DateTimeTools]
|
||||
IDT[InternalDocsTools]
|
||||
QMT[QueryMetricsTools]
|
||||
QLT[QueryLogsTools]
|
||||
end
|
||||
|
||||
subgraph 外部服务
|
||||
DS[DashScope API<br/>Qwen3-Max / Embedding]
|
||||
MV[Milvus<br/>向量数据库]
|
||||
PM[Prometheus<br/>监控告警]
|
||||
CLS[腾讯云CLS<br/>MCP SSE]
|
||||
end
|
||||
|
||||
WEB --> CC
|
||||
WEB --> AO
|
||||
WEB --> UP
|
||||
WEB --> HC
|
||||
|
||||
CC --> CS
|
||||
CC --> RS
|
||||
AO --> AIS
|
||||
UP --> VIS
|
||||
|
||||
CS --> DT & IDT & QMT & QLT
|
||||
AIS --> DT & IDT & QMT & QLT
|
||||
|
||||
CS --> DS
|
||||
RS --> DS
|
||||
RS --> VSS
|
||||
VIS --> DCS --> VES --> MV
|
||||
VSS --> MV
|
||||
QMT --> PM
|
||||
QLT --> CLS
|
||||
|
||||
VES --> DS
|
||||
```
|
||||
|
||||
### 主要运行时流程
|
||||
|
||||
#### 流程 A：RAG 智能问答（文档→检索→生成）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Ctrl as FileUploadController
|
||||
participant VIS as VectorIndexService
|
||||
participant DCS as DocumentChunkService
|
||||
participant VES as VectorEmbeddingService
|
||||
participant MV as Milvus
|
||||
participant RS as RagService
|
||||
participant DS as DashScope
|
||||
|
||||
Note over User,DS: === 索引阶段 ===
|
||||
User->>Ctrl: POST /api/upload (file.md)
|
||||
Ctrl->>VIS: indexSingleFile(file)
|
||||
VIS->>VIS: 删除旧向量(按source路径匹配)
|
||||
VIS->>DCS: chunkDocument(content)
|
||||
DCS-->>VIS: List<DocumentChunk>
|
||||
loop 每个分块
|
||||
VIS->>VES: generateEmbedding(chunk)
|
||||
VES->>DS: text-embedding-v4 API
|
||||
DS-->>VES: float[1024]
|
||||
VES-->>VIS: 向量
|
||||
end
|
||||
VIS->>MV: insert(向量 + 原文 + metadata)
|
||||
MV-->>VIS: OK
|
||||
|
||||
Note over User,DS: === 问答阶段 ===
|
||||
User->>Ctrl: POST /api/chat (question)
|
||||
Ctrl->>RS: generateAnswerStream(question)
|
||||
RS->>VES: 向量化问题
|
||||
VES->>DS: text-embedding-v4
|
||||
DS-->>RS: query_vector[1024]
|
||||
RS->>MV: search(query_vector, topK=3)
|
||||
MV-->>RS: 3条最相似文档片段
|
||||
RS->>DS: Generation API (提示词 + 上下文 + 问题)
|
||||
DS-->>User: SSE 流式生成回答
|
||||
```
|
||||
|
||||
#### 流程 B：AIOps 多 Agent 告警分析
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Ctrl as ChatController
|
||||
participant AIS as AiOpsService
|
||||
participant Sup as SupervisorAgent
|
||||
participant P as PlannerAgent
|
||||
participant E as ExecutorAgent
|
||||
participant Tools as Agent Tools
|
||||
participant DS as DashScope
|
||||
|
||||
User->>Ctrl: POST /api/ai_ops (告警信息)
|
||||
Ctrl->>AIS: executeAiOpsAnalysis(request)
|
||||
|
||||
Note over AIS, DS: 启动监督循环
|
||||
AIS->>Sup: 启动，传入 Planner + Executor
|
||||
|
||||
loop Planner-Executor-Replanner
|
||||
Sup->>P: 分析当前状态，决定下一步
|
||||
alt 需要制定/修订计划
|
||||
P-->>User: SSE: 📋 分析计划...
|
||||
else 需要执行步骤
|
||||
P-->>Sup: EXECUTE
|
||||
Sup->>E: 执行计划第一步
|
||||
E->>Tools: 调用工具收集证据
|
||||
Tools-->>E: 日志/告警/文档信息
|
||||
E-->>User: SSE: 🔍 执行结果...
|
||||
E-->>Sup: 反馈 + 证据
|
||||
Note over Sup: 将执行结果反馈给Planner
|
||||
else 分析完成
|
||||
P-->>Sup: FINISH
|
||||
end
|
||||
end
|
||||
|
||||
Sup-->>User: SSE: ✅ Markdown 告警分析报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Start Path
|
||||
|
||||
### 最小启动步骤
|
||||
|
||||
```bash
|
||||
# 1. 启动基础设施（Milvus + etcd + MinIO）
|
||||
cd D:\zhu\project\SuperBizAgent-java
|
||||
docker compose -f vector-database.yml up -d
|
||||
|
||||
# 2. 设置 API Key 环境变量
|
||||
export DASHSCOPE_API_KEY="your-dashscope-api-key"
|
||||
|
||||
# 3. 启动应用
|
||||
mvn spring-boot:run
|
||||
# 应用启动在 http://localhost:9900
|
||||
|
||||
# 4. 打开 Web 测试页面
|
||||
# http://localhost:9900/index.html
|
||||
```
|
||||
|
||||
### 学习起点
|
||||
|
||||
1. **第一入口**：`src/main/java/org/example/Main.java` — Spring Boot 启动类，了解组件扫描范围
|
||||
2. **核心对话**：`src/main/java/org/example/controller/ChatController.java` — 所有 API 端点定义，理解请求路由
|
||||
3. **Agent 编排**：`src/main/java/org/example/service/ChatService.java` — ReactAgent 如何注册工具、处理对话
|
||||
4. **多 Agent 协作**：`src/main/java/org/example/service/AiOpsService.java` — Planner-Executor-Replanner 模式完整实现
|
||||
5. **RAG 管道**：按 `VectorIndexService → DocumentChunkService → VectorEmbeddingService → RagService` 顺序阅读
|
||||
|
||||
### 建议的第一个修改
|
||||
|
||||
在 `QueryMetricsTools.java` 的 `queryPrometheusAlerts()` 方法中添加一个 Mock 数据，观察 Agent 如何将新的工具输出整合到对话中。修改后重新提问相关问题即可看到效果。
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Core Designs
|
||||
|
||||
### 设计一：Planner-Executor-Replanner 监督循环
|
||||
|
||||
**位置**：`src/main/java/org/example/service/AiOpsService.java`
|
||||
|
||||
**是什么**：一个三层多 Agent 协作模式，用监督者控制循环来解决开放性的告警分析问题。
|
||||
|
||||
```
|
||||
SupervisorAgent (监督者)
|
||||
├── PlannerAgent (规划者)
|
||||
│ └── 决策三个状态: PLAN → 制定/修订计划
|
||||
│ EXECUTE → 交给执行者
|
||||
│ FINISH → 输出最终报告
|
||||
└── ExecutorAgent (执行者)
|
||||
└── 执行计划中的第一步
|
||||
└── 调用工具获取真实数据
|
||||
└── 返回反馈给 Planner 重新规划
|
||||
```
|
||||
|
||||
**为什么重要**：
|
||||
- 不是简单的单次 Agent 调用，而是通过**循环反馈**逐步逼近准确分析
|
||||
- Planner 根据 Executor 返回的证据**动态调整计划**（即 Replan 机制）
|
||||
- 通过 SSE 将每一步的中间结果实时推送给前端，用户体验好
|
||||
- 工具调用是**实际的**：Prometheus 查询、日志搜索、知识库检索，不是 mock 玩具
|
||||
|
||||
**关键实现细节**：
|
||||
```java
|
||||
// SupervisorAgent 创建并传入子 Agent
|
||||
SupervisorAgent supervisor = SupervisorAgent.builder()
|
||||
.supervisorAgent(supervisor)
|
||||
.subAgents(plannerAgent, executorAgent)
|
||||
.build();
|
||||
```
|
||||
|
||||
### 设计二：完整的 RAG 管道（5 级流水线）
|
||||
|
||||
**位置**：`VectorIndexService` → `DocumentChunkService` → `VectorEmbeddingService` → `VectorSearchService` → `RagService`
|
||||
|
||||
**是什么**：从原始文档到流式问答输出的完整 RAG 管道，涉及 5 个松耦合的服务组件。
|
||||
|
||||
| 阶段 | 组件 | 关键技术点 |
|
||||
|------|------|------------|
|
||||
| 1. 智能分块 | DocumentChunkService | 按 Markdown 标题层级 + 段落边界分割，800 字符/块，100 字符重叠 |
|
||||
| 2. 向量化 | VectorEmbeddingService | DashScope text-embedding-v4，1024 维，支持批量 |
|
||||
| 3. 向量存储 | MilvusClientFactory | IVF_FLAT 索引，L2 距离，自动去重（按 source 路径） |
|
||||
| 4. 语义检索 | VectorSearchService | Top-K 配置化（default 3），返回原文 + 相似度分数 |
|
||||
| 5. 流式生成 | RagService | DashScope Generation API，SSE 流式输出，支持 system prompt |
|
||||
|
||||
**为什么重要**：
|
||||
- 每个阶段**独立可替换**——可以换分块策略、换向量库、换 LLM
|
||||
- **幂等上传**：同一文件重新上传时，先删除旧向量再写入，保证数据一致性
|
||||
- 分块策略考虑了 Markdown 的文档结构（标题层级），而不是简单的固定长度切割
|
||||
|
||||
### 设计三：工具即插即用的 Agent 工具系统
|
||||
|
||||
**位置**：`src/main/java/org/example/agent/tool/*.java`
|
||||
|
||||
**是什么**：基于 Spring AI `@Tool` 注解的工具系统，Agent 自动发现并可调用。
|
||||
|
||||
```java
|
||||
// 工具定义示例
|
||||
@Component
|
||||
public class DateTimeTools {
|
||||
@Tool(description = "获取当前日期和时间")
|
||||
public String getCurrentDateTime() { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**核心设计决策**：
|
||||
|
||||
| 决策 | 做法 | 原因 |
|
||||
|------|------|------|
|
||||
| Mock 开关 | `QueryMetricsTools` 和 `QueryLogsTools` 都有 `mockEnabled` 配置 | 开发/演示时不需要真实 Prometheus/CLS 环境 |
|
||||
| MCP 优先 | 当 MCP Client 可用时，自动排除 `QueryLogsTools` | 避免工具重复，MCP 提供更丰富的日志能力 |
|
||||
| JSON Schema 生成 | 使用 `jsonschema-generator` 为工具参数生成 schema | 让 LLM 理解工具的参数类型和约束 |
|
||||
| 工具注册 | `ChatService` 和 `AiOpsService` 各自注册工具集 | Agent 只获得需要的能力，避免干扰 |
|
||||
|
||||
**ChatService 工具注册**：
|
||||
```java
|
||||
// 构建时注册所有可用工具
|
||||
ReactAgent agent = ReactAgent.builder()
|
||||
.tools(dateTimeTools, internalDocsTools,
|
||||
queryMetricsTools, queryLogsTools)
|
||||
.build();
|
||||
```
|
||||
|
||||
**为什么重要**：
|
||||
- Agent 工具系统是 AI Agent 的**能力边界**——定义了 Agent 能做什么
|
||||
- Mock/Real 模式切换体现了**开发友好性**
|
||||
- MCP 协议的集成展示了**可扩展性**——Agent 可以从外部获取新能力
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
SuperBizAgent-java 是一个小而完整的 AI Agent 实践项目。它的三个核心竞争力是：
|
||||
|
||||
1. **多 Agent 协作**（Planner-Executor-Replanner）——不是玩具，是真正解决问题的模式
|
||||
2. **工程化的 RAG 管道**——5 级流水线、幂等上传、智能分块
|
||||
3. **Spring AI 生态的完整实践**——从 @Tool 注解到 MCP 协议，展示了 Java 生态做 AI Agent 的成熟路径
|
||||
|
||||
对于想将 AI Agent 引入企业运维场景的 Java 团队，这是一个很好的学习起点和脚手架。
|
||||
Reference in New Issue
Block a user