zhuyongxin
a1876286fd
## 改动内容
### 增强 extractTextContent() 方法
支持 6 种提取方式，依次尝试：
```java
// 方法 1: 反射获取 text 字段
Field textField = message.getClass().getDeclaredField("text");
// 方法 2: 反射获取 content 字段
Field contentField = message.getClass().getDeclaredField("content");
// 方法 3: 调用 getText() 方法
Method getTextMethod = message.getClass().getMethod("getText");
// 方法 4: 调用 getContent() 方法
Method getContentMethod = message.getClass().getMethod("getContent");
// 方法 5: 打印类结构信息（帮助调试）
log.warn("字段列表: ...");
log.warn("方法列表: ...");
// 方法 6: toString() 兜底
return message.toString();
```
---
## 调试信息输出
### 当提取失败时
```
[WARN] 无法提取 AssistantMessage 文本内容，打印类信息:
[WARN] 类名: org.springframework.ai.chat.messages.AssistantMessage
[WARN] 字段列表:
[WARN] - text: String
[WARN] - toolCalls: List
[WARN] - metadata: Map
[WARN] 方法列表:
[WARN] - getText(): String
[WARN] - getToolCalls(): List
[WARN] - getMetadata(): Map
```
**用途**：
- 帮助快速定位正确的字段/方法名
- 不同 Spring AI 版本可能有不同实现
- 一次调试，永久修复
---
### 当提取成功时
```
[DEBUG] 通过 text 字段提取成功
[INFO] *** [Agent 思考] 模型返回文本: 我需要查询知识库...
```
---
## 适配不同 Spring AI 版本
| 版本 | 字段/方法 | 提取方式 |
|------|----------|---------|
| **Spring AI 0.x** | `text` 字段 | 方法 1 ✅ |
| **Spring AI 1.x** | `content` 字段 | 方法 2 ✅ |
| **阿里云版本** | `getText()` 方法 | 方法 3 ✅ |
| **自定义实现** | `getContent()` 方法 | 方法 4 ✅ |
| **未知版本** | 打印类信息 | 方法 5 → 手动适配 |
---
## 错误处理
### 提取失败但不中断
```java
catch (Exception e) {
log.error("提取 AssistantMessage 文本内容时出错", e);
return null;
}
// 调用处
String textContent = extractTextContent(lastAssistant);
if (textContent != null && !textContent.isEmpty()) {
log.info("*** [Agent 思考] 模型返回文本: {}", textContent);
} else {
// 跳过，不打印
}
```
**不会中断流程**：
- 提取失败 → 返回 null
- null 检查 → 跳过日志输出
- 继续执行后续逻辑
---
## 使用场景
### 场景 1：首次运行，不确定字段名
```bash
# 启动应用
mvn spring-boot:run
# 发起请求
curl -X POST http://localhost:9900/api/chat \
-d '{"id":"test","question":"测试"}'
# 查看日志
tail -f logs/application.log | grep "模型返回文本\|字段列表\|方法列表"
```
**如果看到**：
```
[WARN] 无法提取 AssistantMessage 文本内容，打印类信息:
[WARN] 方法列表:
[WARN] - getTextContent(): String ← 找到了！
```
**修复**：在 `extractTextContent()` 中添加方法 7：
```java
// 方法 7: 尝试 getTextContent()
Method method = message.getClass().getMethod("getTextContent");
Object value = method.invoke(message);
```
---
### 场景 2：提取成功
```
[DEBUG] 通过 text 字段提取成功
[INFO] *** [Agent 思考] 模型返回文本: 我需要查询知识库来了解支付失败的具体原因
```
正常使用，无需调整。
---
## 性能考虑
### 反射开销
- 反射调用比直接调用慢 ~10-100 倍
- 但只在日志输出时使用，不在热路径
- Agent 调用频率低（秒级），性能影响可忽略
### 优化建议（可选）
缓存反射结果：
```java
private static Field cachedTextField = null;
private String extractTextContent(AssistantMessage message) {
if (cachedTextField == null) {
cachedTextField = message.getClass().getDeclaredField("text");
cachedTextField.setAccessible(true);
}
return (String) cachedTextField.get(message);
}
```
**当前未实现**，因为：
- 日志场景无性能瓶颈
- 简单实现更易维护
- 如需优化再添加
---
## 提交历史
```
当前 fix(observability): 增强模型文本提取，支持多种方式并输出调试信息
934d8ee feat(observability): 在 Hook 中输出模型返回的文本内容
7c8758d refactor(observability): 简化 ChatService 日志，避免与 Hook 重复
```
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. 智能问答接口
流式对话（推荐）
POST /api/chat_stream
Content-Type: application/json
{
"Id": "session-123",
"Question": "什么是向量数据库？"
}
支持 SSE 流式输出、自动工具调用、多轮对话。
普通对话
POST /api/chat
Content-Type: application/json
{
"Id": "session-123",
"Question": "什么是向量数据库？"
}
一次性返回完整结果，支持工具调用和多轮对话。
2. AIOps 智能运维接口
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
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
环境变量
export DASHSCOPE_API_KEY=your-api-key
🚀 快速开始
1. 环境准备
# 设置 API Key
export DASHSCOPE_API_KEY=your-api-key
2. 启动应用
方法一： 手动启动
1.先启动向量数据库
docker compose up -d -f vector-database.yml
2.启动服务
mvn clean install
mvn spring-boot:run
方法二：一键启动
make init # 会自动启动向量数据库并上传运维文档到向量库
3. 使用示例
Web 界面
http://localhost:9900
命令行
# 上传文档
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. 启动依赖服务
# 启动 MySQL + Redis + Milvus（本地开发）
docker-compose up -d
# 查看服务状态
docker-compose ps
2. 配置应用
复制 src/main/resources/application.yml 并根据需要修改：
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. 运行应用
# 编译
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 文档
文档管理接口：
# 上传文档（仅支持 .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}
健康检查：
# 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