# spring-ai

**Repository Path**: maclezhou/spring-ai

## Basic Information

- **Project Name**: spring-ai
- **Description**: 基于 Spring Boot 4 + Spring AI 2.0 + 阿里云 DashScope 构建的多场景 AI 对话服务，集成智能客服、PDF 文档问答、角色扮演游戏和通用对话四大功能模块，支持 Redis 持久化记忆与多模态交互
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 Spring AI 职业教育智能服务平台

> 基于 Spring Boot 4 + Spring AI 2.0 + 阿里云 DashScope 构建的多场景 AI 应用平台，集成高级 RAG 文档问答、多 Agent 智能助手、AI 推理解谜游戏、智能客服等功能模块，支持 Redis 持久化记忆与多模态交互。

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.6-6DB33F?logo=springboot)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-2.0.0--M6-6DB33F?logo=spring)](https://spring.io/projects/spring-ai)
[![Java](https://img.shields.io/badge/Java-17-ED8B00?logo=openjdk)](https://openjdk.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql)](https://www.mysql.com/)
[![Redis](https://img.shields.io/badge/Redis-7.0-DC382D?logo=redis)](https://redis.io/)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
[![Gitee](https://img.shields.io/badge/Gitee-⭐_Star_Me-C71D23?logo=gitee)](https://gitee.com)

---

## 📖 项目简介

本项目是一个面向职业教育场景的 AI 应用平台，基于 Spring AI 框架与阿里云 DashScope（通义千问/DeepSeek）大模型能力，实现六大核心功能：

| 功能模块 | 描述 | 核心技术 |
|----------|------|----------|
| 📄 **高级 RAG 文档问答** | 支持 PDF/Word/Markdown 多格式文档上传，混合检索（向量+BM25）、查询改写、LLM 重排序、引用溯源 | RetrievalAugmentationAdvisor、Hybrid Search、RRF |
| 🤖 **多 Agent 智能助手** | Router Agent 意图分发 + 4 个专业 Agent 协作（课程咨询、学习规划、文档问答、通用对话） | Multi-Agent、Tool Calling、Agent Handoff |
| 🔍 **AI 推理解谜** | AI 实时生成谋杀谜案，审问嫌疑人、搜查线索、推理真相，5 维度评分 | 多 NPC 记忆隔离、结构化输出、状态机 |
| 🎓 **智能客服** | 课程咨询 + 预约服务，集成 Function Calling 实现数据库实时查询与预约下单 | Tool Calling、MyBatis-Plus |
| 💬 **通用对话** | 具备会话记忆的流式 AI 对话，支持文本 + 多模态（图片/文件）输入 | SSE 流式输出、Redis 持久化记忆 |
| 📚 **基础 PDF 问答** | 上传 PDF → 自动向量化 → 基于 RAG 的智能问答 | RedisVectorStore、Qwen Embedding |

### ✨ 核心亮点

- **高级 RAG 管线**：混合检索（向量相似度 + BM25 关键词）+ Reciprocal Rank Fusion 融合 + LLM 重排序，回答带 [1][2] 引用溯源
- **多 Agent 协作**：Router Agent 通过 Tool Calling 实现意图分发，Agent 间支持 handoff，AgentRegistry 注册中心动态管理
- **AI 推理解谜**：AI 实时生成完整谋杀谜案，每个嫌疑人独立人设和记忆（conversationId 隔离），5 维度结构化评分（S/A/B/C/D）
- **Function Calling**：客服 AI 可自主调用数据库 API 完成课程查询与预约创建
- **流式输出（SSE）**：所有对话接口基于 `Flux<String>` 实时推流，打字机效果
- **Redis 全链路持久化**：聊天记忆、会话历史、向量存储、游戏状态全部基于 Redis
- **多格式文档解析**：支持 PDF、Word（.docx）、Markdown、纯文本，使用 Apache Tika + 专用 Reader
- **BM25 关键词检索**：纯 Java 实现，中文按字切分，与向量检索互补

---

## 🏗️ 技术栈

| 层次 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 基础框架 | Spring Boot | 4.0.6 | — |
| AI 框架 | Spring AI | 2.0.0-M6 | OpenAI 兼容协议 |
| 大语言模型 | DeepSeek-V4-Flash / Qwen | — | 阿里云 DashScope |
| Embedding 模型 | text-embedding-v3 | 1024 维 | 阿里云 DashScope |
| Web 框架 | Spring MVC (WebMvc) | — | 同步 Servlet 模型 |
| 响应式流 | Project Reactor (`Flux`) | — | SSE 流式推送 |
| ORM 框架 | MyBatis-Plus | 3.5.15 | Spring Boot 4 适配版 |
| 数据库 | MySQL | 8.0+ | 课程/校区/预约数据 |
| 缓存 & 向量库 | Redis | 7.0+ | 聊天记忆 + 向量存储 + 游戏状态 |
| 文档解析 | Apache Tika + Spring AI Readers | — | PDF/Word/Markdown/文本 |
| 代码简化 | Lombok | 1.18.22 | — |
| 构建工具 | Maven | 3.6+ | — |
| JDK | Java | 17 | — |

> 💡 **模型可替换**：本项目使用 OpenAI 兼容协议，只需修改 `application.yaml` 即可切换到 DeepSeek、OpenAI、智谱等任何兼容服务商。

---

## 📂 项目结构

```
spring-ai/
├── pom.xml
├── README.md
├── itstudy.sql                              # 数据库初始化脚本
├── spring-ai/                               # Spring Boot 后端
│   └── src/main/java/com/sziit/springai/
│       ├── SpringAiApplication.java         # 启动入口
│       ├── config/
│       │   ├── CommonConfiguration.java     # 基础 Bean（Redis、向量存储、4 个 ChatClient）
│       │   ├── AdvancedRagConfiguration.java # 高级 RAG 管线配置
│       │   ├── MultiAgentConfiguration.java  # 多 Agent 系统配置
│       │   └── MvcConfiguration.java        # CORS 跨域配置
│       ├── controller/
│       │   ├── ChatController.java          # 通用对话（含多模态）
│       │   ├── ChatHistoryController.java   # 会话历史查询
│       │   ├── CustomerServiceController.java # 智能客服
│       │   ├── PdfController.java           # 基础 PDF 问答
│       │   ├── DocumentController.java      # 高级文档问答（多格式 + RAG）
│       │   └── AgentController.java         # 多 Agent 智能助手入口
│       ├── detective/                       # AI 推理解谜游戏
│       │   ├── config/DetectiveGameConfiguration.java
│       │   ├── controller/DetectiveController.java
│       │   ├── entity/                      # CaseData、GameState、DeductionResult
│       │   ├── service/                     # GameStateManager、SuspectClientFactory、GameHistoryService
│       │   └── DetectivePrompts.java        # 游戏提示词
│       ├── rag/                             # 高级 RAG 管线组件
│       │   ├── reader/MultiFormatDocumentReader.java    # 多格式文档解析
│       │   ├── splitter/SemanticDocumentSplitter.java   # 语义分块
│       │   ├── retrieval/Bm25DocumentRetriever.java     # BM25 关键词检索
│       │   ├── retrieval/HybridDocumentRetriever.java   # 混合检索
│       │   ├── joiner/RrfDocumentJoiner.java            # RRF 融合
│       │   ├── postprocessor/LlmRerankingPostProcessor.java # LLM 重排序
│       │   └── augmenter/CitationQueryAugmenter.java    # 引用溯源
│       ├── agent/                           # 多 Agent 系统
│       │   ├── AgentType.java               # Agent 类型枚举
│       │   ├── AgentRegistry.java           # Agent 注册中心
│       │   └── AgentRouterTool.java         # 路由分发工具
│       ├── tools/
│       │   ├── CourseTools.java             # 课程查询/预约工具
│       │   └── LearningPathTools.java       # 学习路径规划工具
│       ├── repository/
│       │   ├── RedisChatHistory.java        # Redis 会话历史
│       │   ├── RedisChatMemory.java         # Redis AI 聊天记忆
│       │   └── FileServiceImpl.java         # 文件存储 + 向量化
│       ├── service/                         # 业务服务层
│       ├── mapper/                          # MyBatis-Plus Mapper
│       ├── entity/                          # PO / VO / Query
│       └── constants/SystemConstants.java   # 系统提示词
├── spring-ai-protal/                        # Vue 3 前端
│   └── src/
│       ├── views/
│       │   ├── Home.vue                     # 首页（6 张功能卡片）
│       │   ├── AIChat.vue                   # 多模态对话
│       │   ├── ChatPDF.vue                  # PDF 文档问答
│       │   ├── CustomerService.vue          # 智能客服
│       │   ├── DetectiveGame.vue            # AI 推理解谜游戏
│       │   └── AgentChat.vue                # 多 Agent 智能助手
│       ├── components/
│       │   ├── ChatMessage.vue              # 通用聊天消息组件
│       │   └── PDFViewer.vue                # PDF 查看器
│       ├── services/api.js                  # API 层（全部流式接口）
│       └── router/index.js                  # 路由配置
└── spring-ai-nginx/                         # Nginx 反向代理（可选）
```

---

## 🚀 快速开始

### 环境要求

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| JDK | 17+ | — |
| Maven | 3.6+ | — |
| MySQL | 8.0+ | 课程/校区/预约数据存储 |
| Redis | 7.0+ | 聊天记忆、向量存储、游戏状态 |
| DashScope API Key | — | [申请地址](https://dashscope.console.aliyun.com/) |

### 1. 克隆项目

```bash
git clone https://gitee.com/zou-zhenxing99/spring-ai.git
cd spring-ai
```

### 2. 初始化数据库

执行 `itstudy.sql` 初始化课程、校区、预约表和示例数据。

### 3. 配置环境变量

```bash
# Linux / macOS
export OPENAI_API_KEY=sk-your-dashscope-api-key
export QWEN_API_KEY=sk-your-dashscope-api-key

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-dashscope-api-key"
$env:QWEN_API_KEY = "sk-your-dashscope-api-key"
```

### 4. 启动后端

```bash
cd spring-ai
mvn spring-boot:run
```

### 5. 启动前端

```bash
cd spring-ai-protal
npm install
npm run dev
```

访问 `http://localhost:5173` 即可使用。

---

## 📡 API 参考

### 多 Agent 智能助手

```bash
# 统一入口，Router Agent 自动分发到专业 Agent
curl -N "http://localhost:8080/ai/agent/chat?prompt=有哪些编程课程？&chatId=agent-001"
```

### 高级文档问答（RAG）

```bash
# 上传文档（支持 PDF/Word/Markdown）
curl -X POST -F "file=@document.pdf" "http://localhost:8080/ai/doc/upload/doc-001"

# 基于文档问答（带引用溯源）
curl -N "http://localhost:8080/ai/doc/chat?prompt=文档讲了什么？&chatId=doc-001"
```

### AI 推理解谜

```bash
# 生成新案件
curl -X POST "http://localhost:8080/ai/detective/new?theme=校园"

# 审问嫌疑人（流式）
curl -N -X POST "http://localhost:8080/ai/detective/{gameId}/interrogate?suspectId=s1&prompt=你昨晚在哪？"

# 搜查地点（流式）
curl -N -X POST "http://localhost:8080/ai/detective/{gameId}/search?locationId=loc1"

# 提交推理
curl -X POST "http://localhost:8080/ai/detective/{gameId}/deduct?killer=s1&motive=...&method=..."

# 查看游戏历史
curl "http://localhost:8080/ai/detective/history"
curl "http://localhost:8080/ai/detective/{gameId}/history"
```

### 智能客服（Function Calling）

```bash
curl -N "http://localhost:8080/ai/service?prompt=我想学编程，高中学历&chatId=session-abc"
```

### 通用对话

```bash
curl -N "http://localhost:8080/ai/chat?prompt=你好&chatId=user-001"
```

### API 路径汇总

| 路径 | 方法 | 功能 | 流式 |
|------|------|------|:----:|
| `/ai/agent/chat` | GET | 多 Agent 智能助手 | ✅ |
| `/ai/doc/upload/{chatId}` | POST | 多格式文档上传 | ❌ |
| `/ai/doc/chat` | GET | 高级文档问答（RAG） | ✅ |
| `/ai/detective/new` | POST | 生成推理案件 | ❌ |
| `/ai/detective/{gameId}/interrogate` | POST | 审问嫌疑人 | ✅ |
| `/ai/detective/{gameId}/search` | POST | 搜查地点 | ✅ |
| `/ai/detective/{gameId}/deduct` | POST | 提交推理 | ❌ |
| `/ai/detective/{gameId}/reveal` | GET | 揭晓真相 | ❌ |
| `/ai/detective/history` | GET | 游戏历史列表 | ❌ |
| `/ai/chat` | ALL | 通用对话（多模态） | ✅ |
| `/ai/service` | ALL | 智能客服 | ✅ |
| `/ai/pdf/chat` | ALL | 基础 PDF 问答 | ✅ |
| `/ai/pdf/upload/{chatId}` | POST | PDF 上传 | ❌ |
| `/ai/history/{type}` | GET | 会话 ID 列表 | ❌ |
| `/ai/history/{type}/{chatId}` | GET | 会话聊天记录 | ❌ |

---

## 🏛️ 系统架构

```
┌──────────────────────────────────────────────────────────────┐
│                       Vue 3 前端                              │
│  AIChat │ ChatPDF │ CustomerService │ DetectiveGame │ Agent   │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────┴─────────────────────────────────────┐
│                    Spring MVC Controllers                      │
│  Chat │ Pdf │ Document │ CustomerService │ Detective │ Agent  │
└────┬──────────┬──────────────┬──────────────┬────────────────┘
     │          │              │              │
┌────▼────┐ ┌───▼──────┐ ┌────▼─────┐ ┌─────▼──────┐
│ Chat    │ │ Advanced │ │Multi-Agent│ │ Detective  │
│ Client  │ │ RAG      │ │ System   │ │ Game       │
│         │ │ Pipeline │ │          │ │            │
│ Memory  │ │ Hybrid   │ │ Router → │ │ CaseGen    │
│         │ │ Search   │ │ 4 Agents │ │ NPC Chat   │
│         │ │ Rerank   │ │ Handoff  │ │ Deduction  │
└────┬────┘ └───┬──────┘ └────┬─────┘ └─────┬──────┘
     │          │              │              │
┌────▼──────────▼──────────────▼──────────────▼────────────────┐
│                    OpenAiChatModel (DashScope)                 │
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────┴──────────────────────────────────┐
│                         Redis                                  │
│  ChatMemory │ VectorStore │ ChatHistory │ GameState │ BM25    │
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────┴──────────────────────────────────┐
│                         MySQL                                  │
│  course │ school │ course_reservation                          │
└──────────────────────────────────────────────────────────────┘
```

### 高级 RAG 管线流程

```
用户问题
  → [1] 查询改写 (RewriteQueryTransformer)
  → [2] 查询扩展 (MultiQueryExpander, 3 个变体)
  → [3] 混合检索 (向量 + BM25 并行)
  → [4] RRF 融合 (Reciprocal Rank Fusion)
  → [5] LLM 重排序 (top-10 → top-5)
  → [6] 引用增强 (CitationQueryAugmenter)
  → [7] 生成回答（带 [1][2] 引用标记）
```

### 多 Agent 系统架构

```
用户请求 → [Router Agent] (意图分类)
              ├── → [课程咨询 Agent]  (CourseTools: 查课程/校区/预约)
              ├── → [学习规划 Agent]  (LearningPathTools + CourseTools)
              ├── → [文档问答 Agent]  (Advanced RAG 管线)
              └── → [通用聊天 Agent]  (纯对话)
```

### AI 推理解谜流程

```
开始 → AI 生成案件（2 嫌疑人、3 证据、2 地点）
  → 案件概览（受害者信息 + 嫌疑人列表）
  → 调查阶段：
      - 审问嫌疑人（每个 NPC 独立人设和记忆）
      - 搜查地点发现线索
  → 提交推理（凶手、动机、手法、证据）
  → AI 评分（100 分制 + S/A/B/C/D 评级）
  → 真相揭晓（完整时间线 + 证据链）
```

---

## ⚙️ 配置说明

### 核心配置项

| 配置键 | 默认值 | 说明 |
|--------|--------|------|
| `spring.ai.openai.api-key` | `${OPENAI_API_KEY}` | Chat 模型 API Key |
| `spring.ai.openai.base-url` | DashScope 兼容端点 | 可替换为 DeepSeek/OpenAI 等 |
| `spring.ai.openai.chat.options.model` | `deepseek-v4-flash` | 对话模型名称 |
| `spring.ai.openai.chat.options.temperature` | `0.7` | 温度（0~1） |
| `spring.ai.openai.embedding.options.model` | `text-embedding-v3` | 向量嵌入模型 |
| `spring.ai.openai.embedding.options.dimensions` | `1024` | 向量维度 |

### 模型替换

```yaml
# 切换到 DeepSeek
spring.ai.openai.base-url: https://api.deepseek.com
spring.ai.openai.chat.options.model: deepseek-chat

# 切换到 OpenAI
spring.ai.openai.base-url: https://api.openai.com
spring.ai.openai.chat.options.model: gpt-4o
```

---

## 🧩 扩展开发

### 添加新的 Agent

1. 在 `AgentType` 枚举中添加新类型
2. 在 `MultiAgentConfiguration` 中注册新 ChatClient bean
3. 在 `AgentRegistry` 中注册
4. 更新 Router Agent 的 system prompt

### 添加新的 RAG 组件

RAG 管线组件基于 Spring AI 接口，可独立替换：

- `DocumentRetriever` — 自定义检索策略
- `DocumentJoiner` — 自定义融合算法
- `DocumentPostProcessor` — 自定义后处理（如重排序）
- `QueryAugmenter` — 自定义 prompt 增强

### 添加 Function Calling 工具

```java
@Tool(description = "根据城市查询可用校区")
public List<School> querySchoolsByCity(
        @ToolParam(description = "城市名称") String city) {
    return schoolService.query().eq("city", city).list();
}
```

---

## 🔧 已知问题

| 位置 | 问题 | 状态 |
|------|------|------|
| `application.yaml` | 数据库密码硬编码 | 🔒 生产环境请用环境变量 |
| PDF 向量存储 | 重复上传会追加写入 | ⚠️ 上传前需清理旧数据 |
| 模型依赖 | Spring AI 2.0.0-M6 为里程碑版本 | ⚠️ 升级需评估兼容性 |

---

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源。

---

## 🙏 致谢

- [Spring AI](https://spring.io/projects/spring-ai) — 优雅的 Java AI 开发框架
- [阿里云 DashScope](https://dashscope.aliyun.com/) — 通义千问/DeepSeek 大模型服务
- [MyBatis-Plus](https://baomidou.com/) — 强大的 ORM 增强框架
- [Redis](https://redis.io/) — 高性能内存数据库与向量存储