# BoboCoding-SpringAI

**Repository Path**: Bowen-Lee/bobo-coding-spring-ai

## Basic Information

- **Project Name**: BoboCoding-SpringAI
- **Description**: AI学习资料
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BoboCoding Spring AI

一个基于 Spring Boot + Spring AI 的对话演示项目，包含：

1. Web 聊天页面（Thymeleaf）
2. 大模型对话能力（MiniMax 兼容 OpenAI 接口）
3. 递归顾问（Recursive Advisor）
4. 天气工具组（Open-Meteo，4 个技能）
5. 推理过程与最终回答分离展示（THINK/FINAL）

## 项目功能

1. 对话接口
	1. GET / 返回聊天页面
	2. POST /chat 返回 JSON（reply + think）
2. 递归顾问
	1. 在模型调用前增强系统提示
	2. 要求模型输出 THINK 与 FINAL 两段
3. 天气技能组（ToolGroup）
	1. 城市地理编码（城市名 -> 经纬度）
	2. 实时天气查询
	3. 未来预报查询
	4. 空气质量查询
4. 可观测性
	1. 天气工具会打印请求 URL
	2. 会打印响应预览和响应长度，便于排查

## 快速开始

1. 环境要求
	1. JDK 21
	2. Maven 3.8+
2. 配置环境变量
	1. MINIMAX_API_KEY=你的密钥
3. 启动项目

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

4. 访问页面
	1. http://localhost:8080/

## 核心依赖与作用

### Spring 相关核心包

1. spring-boot-starter
	1. 提供 Spring Boot 自动配置能力
	2. 负责应用启动、IOC 容器、基础日志等
2. spring-boot-starter-web
	1. 提供 Spring MVC、嵌入式 Tomcat、JSON 序列化
	2. 用于实现 Controller 和 REST 接口
3. spring-boot-starter-thymeleaf
	1. 提供服务端模板引擎
	2. 用于渲染 chat.html 首页
4. spring-boot-starter-test
	1. 提供测试基础设施（JUnit、Mock 等）

### Spring AI 核心包

1. spring-ai-starter-model-openai
	1. 提供 OpenAI 兼容协议的 ChatModel 集成
	2. 在本项目中对接 MiniMax 兼容接口
2. spring-ai-bom
	1. 统一 Spring AI 相关依赖版本
	2. 避免多模块版本冲突

## Spring AI 用到的核心功能

1. ChatClient
	1. 统一构建 prompt、system、user、tools、advisors
	2. 通过 call() 发起一次模型调用
2. Tool Calling
	1. 使用 @Tool + @ToolParam 把 Java 方法暴露为模型可调用工具
	2. 模型可在回答中自动触发工具，再基于工具结果生成答案
3. Advisor（顾问链）
	1. 使用 CallAdvisor 在请求前后插入增强逻辑
	2. 本项目的 RecursiveAdvisor 在调用前注入递归思考约束

## 原理说明

### 1. 对话主链路原理

1. 前端把 message + history 发送到 /chat
2. ChatService 组装上下文，创建 ChatClient 请求
3. RecursiveAdvisor 先改写系统提示，要求输出 THINK/FINAL
4. 模型按需调用天气工具（ToolGroup）
5. ChatService 解析模型输出标签
	1. <THINK> 进入 think 字段
	2. <FINAL> 进入 reply 字段
6. 前端将 think 与 reply 分开渲染

### 2. 天气技能原理

1. 用户只给城市名时
	1. 先调用 geocodeCity 拿经纬度
2. 根据意图调用
	1. 实时天气 -> getCurrentWeather
	2. 多天预报 -> getDailyForecast
	3. 空气质量 -> getAirQuality
3. 工具内部通过 RestClient 发起 HTTP GET
4. 工具日志会打印 URL 与响应预览，便于调试

### 3. 递归顾问原理

1. Advisor 本质是模型调用前后的可插拔拦截器
2. RecursiveAdvisor 在调用前向系统提示附加“递归检查规则”
3. 通过上下文维护递归深度（默认 3）
4. 目标是提升回答稳定性与完整性，同时把过程与结果分离

## 关键配置

1. server.port
	1. 服务端口，默认 8080
2. spring.ai.openai.api-key
	1. 模型密钥（本项目通过 MINIMAX_API_KEY 注入）
3. spring.ai.openai.base-url
	1. MiniMax 兼容 OpenAI 的基础地址
4. app.chat.recursive-advisor.max-depth
	1. 递归顾问深度，默认 3

## 后续可扩展方向

1. 增加 weather_code -> 中文天气文本映射工具
2. 为天气工具增加缓存与重试
3. 引入会话级记忆存储（数据库/Redis）
4. 增加单元测试和集成测试