Spring AI 学习项目 (SpringAI_Learn)

📖 项目简介

SpringAI_Learn 是一个基于 Spring Boot 3.4.5 和 Spring AI 框架构建的现代化AI应用学习项目。该项目展示了如何使用Spring AI框架集成各种AI模型和功能，包括大语言模型聊天、RAG（检索增强生成）、AI工具调用、向量存储等核心功能。

🚀 技术栈

核心框架

Spring Boot: 3.4.5
Spring AI: 1.0.0-M6
Java: 21

AI 集成

阿里云通义千问: Spring AI Alibaba Starter 1.0.0-M6.1
LangChain4j: DashScope社区版 1.0.0-beta2
MCP客户端: Spring AI MCP Client

数据存储

PostgreSQL: 用于向量存储 (PgVector)
Spring JDBC: 数据库操作

文档处理

iText: PDF生成和处理
JSoup: HTML解析和网页抓取
Markdown: 文档读取器

工具库

Hutool: 5.8.37 (Java工具库)
Knife4j: 4.4.0 (API文档增强)
Lombok: 1.18.30 (代码简化)

其他功能

邮件发送: Spring Boot Mail
Kryo: 5.6.2 (序列化)

🌟 核心功能

1. AI聊天系统

Love App聊天: 基于SSE的实时聊天应用
Manus AI代理: 智能对话代理系统
流式响应: 支持SSE (Server-Sent Events) 实时流式输出

2. AI 代理系统

基础代理 (BaseAgent): 提供代理的基础功能和生命周期管理
工具调用代理 (ToolCallAgent): 支持函数调用的智能代理
ReAct代理 (ReActAgent): 推理-行动循环代理
KkomaManus: 专用AI助手代理

3. AI 工具集

邮件发送工具 (EmailSendTool): 智能邮件发送功能
网络搜索工具 (WebSearchTool): 集成搜索API
网页抓取工具 (WebScrapingTool): 网页内容提取
文件操作工具 (FileOperationTool): 文件处理功能
PDF生成工具 (PDFGenerationTool): 动态PDF文档生成
终端操作工具 (TerminalOperationTool): 系统命令执行
资源下载工具 (ResourceDownloadTool): 资源下载管理
终止工具 (TerminateTool): 流程控制

4. RAG (检索增强生成)

向量存储: 基于PgVector的向量数据库
文档加载器: 支持多种文档格式加载
查询重写: 智能查询优化
自定义顾问: 个性化RAG策略

5. 聊天记忆管理

对话上下文: 维护聊天历史和上下文
记忆持久化: 对话记忆的存储和恢复

📁 项目结构

src/main/java/org/example/springai_learn/
├── SpringAiLearnApplication.java          # 应用启动类
├── controller/                            # 控制器层
│   ├── AiController.java                 # AI相关API接口
│   └── HealthController.java             # 健康检查接口
├── agent/                                # AI代理模块
│   ├── BaseAgent.java                    # 基础代理类
│   ├── ToolCallAgent.java               # 工具调用代理
│   ├── ReActAgent.java                  # ReAct代理
│   ├── KkomaManus.java                  # Manus代理
│   └── model/                           # 代理数据模型
├── app/                                  # 应用层
│   └── LoveApp.java                     # Love App聊天应用
├── tools/                               # AI工具集
│   ├── EmailSendTool.java               # 邮件发送工具
│   ├── WebSearchTool.java               # 网络搜索工具
│   ├── WebScrapingTool.java             # 网页抓取工具
│   ├── FileOperationTool.java           # 文件操作工具
│   ├── PDFGenerationTool.java           # PDF生成工具
│   ├── TerminalOperationTool.java       # 终端操作工具
│   ├── ResourceDownloadTool.java        # 资源下载工具
│   ├── TerminateTool.java               # 终止工具
│   └── ToolRegistration.java            # 工具注册管理
├── rag/                                 # RAG检索增强生成
│   ├── QueryRewriter.java               # 查询重写器
│   ├── PgVectorVectorStoreConfig.java   # PgVector配置
│   ├── LoveAppVectorStoreConfig.java    # Love App向量存储配置
│   ├── LoveAppRagCustomAdvisorFactory.java  # 自定义RAG顾问工厂
│   ├── LoveAppRagCloudAdvisorConfig.java    # 云端RAG顾问配置
│   └── LoveAppDocumentLoader.java       # 文档加载器
├── config/                              # 配置类
├── constant/                            # 常量定义
├── ChatMemory/                          # 聊天记忆管理
├── advisor/                             # 顾问模式实现
└── demo/                               # 演示示例

🛠️ 环境要求

Java: 21+
Maven: 3.6+
PostgreSQL: 12+ (如需使用向量存储功能)
Node.js: 16+ (如需运行前端)

⚙️ 配置说明

1. 数据库配置

在 application.yml 中配置PostgreSQL数据库：

spring:
  datasource:
    url: jdbc:postgresql://your-host:5432/your-database
    username: your-username
    password: your-password

2. AI模型配置

配置阿里云通义千问API密钥（在环境变量或配置文件中）：

spring:
  ai:
    alibaba:
      api-key: your-api-key

3. 邮件服务配置

spring:
  mail:
    host: smtp.qq.com
    port: 465
    username: your-email@qq.com
    password: your-auth-code  # QQ邮箱授权码

4. 搜索API配置

search-api:
  api-key: your-search-api-key

🚀 快速开始

1. 克隆项目

git clone <repository-url>
cd SpringAI_Learn

2. 配置环境

复制并编辑配置文件：

cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml

在 application-local.yml 中填入你的API密钥和数据库配置。

3. 启动应用

# 使用Maven启动
mvn spring-boot:run

# 或者编译后启动
mvn clean package
java -jar target/SpringAI_Learn-0.0.1-SNAPSHOT.jar

4. 访问应用

应用地址: http://localhost:8088/api
API文档: http://localhost:8088/api/swagger-ui.html
健康检查: http://localhost:8088/api/health

📚 API 文档

主要接口

1. Love App 聊天

GET /api/ai/love_app/chat/sse?message={message}&chatId={chatId}

说明: 启动Love App的SSE聊天流，支持实时流式响应。

参数:

message: 用户消息内容
chatId: 聊天会话ID

响应: SSE流式数据

2. Manus AI 聊天

GET /api/ai/manus/chat?message={message}

说明: 与Manus AI代理进行对话。

参数:

message: 用户消息内容

响应: SSE流式数据

3. 健康检查

GET /api/health

说明: 检查应用运行状态。

SSE 响应格式

所有SSE接口都遵循以下响应格式：

data: {"type":"message","content":"AI回复内容"}

data: [DONE]

🔧 开发指南

1. 添加新的AI工具

在 tools 包下创建新的工具类
实现工具的核心逻辑
在 ToolRegistration 中注册新工具
在代理中使用新工具

示例：

@Component
public class MyCustomTool {
    
    @Tool("工具描述")
    public String myToolFunction(String parameter) {
        // 工具逻辑实现
        return "工具执行结果";
    }
}

2. 创建新的AI代理

继承 BaseAgent 类
实现特定的代理逻辑
配置所需的工具和参数
在控制器中暴露代理接口

3. 扩展RAG功能

在 rag 包下添加新的文档加载器
配置向量存储策略
自定义查询重写逻辑
实现自定义顾问模式

🚨 注意事项

API密钥安全: 不要将API密钥提交到版本控制系统
数据库连接: 确保PostgreSQL服务正常运行
内存管理: AI模型可能消耗较多内存，建议分配足够的JVM堆内存
并发控制: SSE连接数量有限，注意连接池管理
日志监控: 开发环境下建议开启DEBUG日志以便调试

📝 开发计划

支持更多AI模型提供商
实现对话历史的持久化存储
添加用户认证和权限控制
优化向量存储性能
扩展更多实用AI工具
完善错误处理和重试机制

🤝 贡献指南

欢迎提交Issue和Pull Request来帮助改进项目！

📄 许可证

MIT License

📞 联系方式

如有问题，请提交Issue或联系项目维护者。

注意: 这是一个学习项目，主要用于探索和学习Spring AI框架的各种功能。在生产环境中使用前，请确保充分测试和安全评估。

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.mvn/wrapper		.mvn/wrapper
mcp-servers		mcp-servers
springAI-front		springAI-front
src/main		src/main
README.md		README.md
pom.xml		pom.xml
start.bat		start.bat
start.sh		start.sh

KkOma-value/SpringAI_Learn

Folders and files

Latest commit

History

Repository files navigation