# AI Agent智能应用平台 **Repository Path**: north-dream-testing/AI-Agent-Intelligent-Application-Platform ## Basic Information - **Project Name**: AI Agent智能应用平台 - **Description**: 基于 Spring AI 构建的企业级 AI 应用工程模板，覆盖通用对话、课程智能客服、互动游戏、PDF 文档 RAG 问答四大业务场景，完整实现大模型接入、工具调用、向量检索、对话记忆持久化全链路能力。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-09 - **Last Updated**: 2026-09-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AI 智能应用平台 > 基于 Spring AI 构建的企业级 AI 应用工程模板，覆盖通用对话、课程智能客服、互动游戏、PDF 文档 RAG 问答四大业务场景，完整实现大模型接入、工具调用、向量检索、对话记忆持久化全链路能力。 ------ ## 📌 项目简介 基于 **Spring AI 1.0.0-M6** 原生生态开发的 Java AI 应用项目，完整实现了大语言模型对话、智能体（Agent）工具调用、RAG 文档问答、多场景对话系统、对话记忆持久化等核心能力。项目采用标准分层架构设计，对接通义千问大模型，提供 RESTful 风格接口与流式输出，可直接作为 AI 业务落地的参考架构与开发底座。 ------ ## ✨ 核心功能 ### 1. 多场景智能对话系统 - **通用聊天**：基础大模型对话能力，支持多轮上下文记忆、流式打字机输出 - **智能客服**：课程咨询 + 试听预约全流程自动化客服，大模型自主调用业务工具完成查询与下单 - **互动游戏**：女友哄人互动游戏，内置原谅值数值系统、自动判定通关 / 失败 - **PDF 问答**：上传 PDF 文档后基于内容精准问答，支持向量相似度检索与答案溯源 ### 2. 智能体工具调用（Agent） 客服场景内置业务工具集，大模型可根据对话上下文自主选择调用： - 课程条件查询：按类型、学历筛选课程，支持多字段排序 - 校区列表查询：查询所有校区名称与城市信息 - 课程预约生成：收集用户信息后自动生成预约订单并返回单号 ### 3. RAG 文档检索问答 - 支持 PDF 文档上传、自动解析与按页分块 - 基于 Spring AI `SimpleVectorStore` 实现向量存储与 Top-K 相似度检索 - 检索结果自动注入大模型上下文，生成基于文档的精准回答 - 会话与文档绑定，支持历史问答与上下文关联 ### 4. 对话记忆与持久化 - 基于 `InMemoryChatMemory` 实现多会话隔离的对话上下文记忆 - 服务启动自动加载历史会话与消息记录 - 服务停止自动持久化到本地 JSON / Properties 文件 - 支持按业务类型区分会话（chat /service/pdf） ### 5. 自定义大模型适配 - 独立实现 `AlibabaOpenAiChatModel`，完整适配通义千问 OpenAI 兼容接口 - 支持同步对话、流式输出、工具调用、可观测性埋点 - 完全兼容 Spring AI `ChatClient` 标准接口，可无缝替换其他模型 ------ ## 🏗️ 系统架构 系统采用四层分层架构，职责清晰、解耦性强，易于扩展与维护。 | 层级 | 说明 | 核心组件 | | ------------- | ------------------------------- | ------------------------------------------------------------ | | **交互层** | 对外提供 REST 风格接口 | ChatController、CustomerServiceController、GameController、PdfController | | **业务层** | 业务逻辑封装与 AI 工具实现 | CourseTools、各业务 Service、Repository 仓储 | | **AI 智能层** | 大模型、Agent、向量检索核心能力 | ChatClient、AlibabaOpenAiChatModel、VectorStore、ChatMemory、Advisor 拦截器 | | **持久层** | 数据存储落地 | MySQL 业务库、本地文件持久化、内存向量库 | ------ ## 🛠️ 完整技术栈 ### 一、核心基础框架 | 技术 / 组件 | 版本 | 核心用途 | | ----------- | -------- | ------------------------------------------------------------ | | Spring Boot | 3.4.3 | 项目基础脚手架，提供自动配置、依赖注入、Web 容器等核心能力 | | Spring AI | 1.0.0-M6 | AI 应用开发核心框架，提供大模型抽象、工具调用、向量存储、文档解析等完整能力集 | | Java | 17 | 项目开发语言，支持虚拟线程、模式匹配等新特性 | | Maven | 4.0.0 | 项目构建与依赖管理 | ### 二、AI 大模型与智能体层 | 技术 / 组件 | 版本 / 类型 | 核心用途 | | ------------------------ | ------------ | ------------------------------------------------------------ | | 通义千问 Qwen-Omni-Turbo | 大语言模型 | 核心对话、推理、工具调用、内容生成能力，通过 OpenAI 兼容协议接入 | | AlibabaOpenAiChatModel | 自定义实现 | 通义千问 OpenAI 兼容模式的完整 ChatModel 实现，支持同步 / 流式对话、工具调用、可观测性 | | OpenAiEmbeddingModel | 嵌入模型 | 文本向量化，支撑向量相似度检索 | | Spring AI ChatClient | 客户端抽象 | 统一的大模型对话客户端，支持提示编排、Advisor 拦截、工具注入 | | Spring AI Tool Calling | 工具调用机制 | `@Tool` 注解式工具定义，大模型自主识别与调用业务工具 | | Spring AI ChatMemory | 对话记忆 | 多会话隔离的对话上下文记忆，支持多轮对话 | | Spring AI Advisor | 拦截器机制 | MessageChatMemoryAdvisor（记忆注入）、QuestionAnswerAdvisor（RAG 检索）、SimpleLoggerAdvisor（日志） | | Reactor | 响应式编程 | Flux 流式输出，实现打字机效果的 SSE 响应 | | Function Calling | 函数调用 | 大模型自主调度业务工具的核心机制 | ### 三、RAG 与向量检索层 | 技术 / 组件 | 版本 / 类型 | 核心用途 | | ---------------------- | -------------- | ----------------------------------------------------------- | | SimpleVectorStore | Spring AI 内置 | 轻量级内存向量数据库，支持 Top-K 相似度检索、本地文件持久化 | | PagePdfDocumentReader | Spring AI 内置 | PDF 文档解析器，按页拆分文档，支持自定义每页分块 | | ExtractedTextFormatter | Spring AI 内置 | PDF 提取文本格式化处理 | | 余弦相似度算法 | 自定义实现 | 向量相似度计算核心算法，包含零向量处理、浮点精度修正 | | 欧氏距离算法 | 自定义实现 | 向量空间距离计算，支持多维度向量参数校验 | ### 四、数据持久层 | 技术 / 组件 | 版本 | 核心用途 | | ------------------- | -------- | ------------------------------------------------------------ | | MyBatis-Plus | 3.5.10.1 | ORM 持久层框架，提供 BaseMapper、IService、QueryChainWrapper 条件构造器等能力 | | MySQL | 8.0+ | 关系型数据库，存储课程、校区、预约订单等业务数据 | | MySQL Connector/J | 运行时 | MySQL 数据库驱动 | | Jackson | 2.x | JSON 序列化与反序列化，实现对话记忆、向量库本地持久化 | | Properties 配置文件 | - | 会话 - 文件映射关系持久化存储 | | 本地文件持久化 | - | chat-history.json、chat-memory.json、chat-pdf.json 实现服务重启数据不丢失 | ### 五、Web 与接口层 | 技术 / 组件 | 版本 / 类型 | 核心用途 | | -------------- | ----------- | ------------------------------------------ | | Spring MVC | 内置 | Web 请求处理、RESTful 接口设计 | | CORS 跨域配置 | - | 全局跨域支持，支持前后端分离部署 | | MultipartFile | - | PDF 文件上传处理 | | SSE 流式响应 | - | 基于 Flux 的服务端推送，实现打字机对话效果 | | ResponseEntity | - | 统一响应封装，支持文件下载、状态码控制 | ### 六、工具与中间件 | 技术 / 组件 | 版本 | 核心用途 | | ---------------------- | ----------- | ---------------------------------------------------------- | | Lombok | 1.18.22 | 简化实体类代码，自动生成 Getter/Setter、构造器、链式调用等 | | SLF4J + Logback | 内置 | 分级日志系统，支持控制台与文件双输出 | | Micrometer Observation | 内置 | 可观测性埋点，大模型调用监控与指标采集 | | RetryTemplate | Spring 内置 | 大模型接口调用重试机制，提升接口稳定性 | | ResponseErrorHandler | Spring 内置 | HTTP 请求错误处理，统一异常拦截 | | VectorDistanceUtils | 自定义工具 | 欧氏距离、余弦距离的高精度实现，包含参数校验与边界处理 | ### 七、工程与设计规范 | 分类 | 说明 | | ------------ | --------------------------------------------------------- | | 架构模式 | 分层架构（控制层 / 业务层 / 数据层 / AI 层） | | 设计模式 | 建造者模式（Builder）、策略模式、单例模式、依赖注入 | | 代码规范 | 接口与实现分离、PO/VO/Query 分层实体设计 | | 会话管理 | 按 chatId 多会话隔离，按业务类型（chat /service/pdf）分类 | | 生命周期钩子 | @PostConstruct 初始化加载、@PreDestroy 持久化落盘 | | 反射机制 | 运行时读取内存对话数据，实现序列化持久化 | ------ ## 📁 项目结构 ```bash project-ai/ ├── src/main/java/com/itheima/ai/ │ ├── controller/ # 【控制层】对外 REST 接口 │ │ ├── ChatController.java # 通用聊天接口 │ │ ├── CustomerServiceController.java # 智能客服接口 │ │ ├── GameController.java # 互动游戏接口 │ │ ├── PdfController.java # PDF 问答接口 │ │ └── ChatHistoryController.java # 对话历史查询接口 │ ├── service/ # 【服务层】业务逻辑 │ │ ├── ICourseService.java │ │ ├── ICourseReservationService.java │ │ ├── ISchoolService.java │ │ └── impl/ # 服务实现类 │ ├── mapper/ # 【数据层】数据库 Mapper │ │ ├── CourseMapper.java │ │ ├── CourseReservationMapper.java │ │ └── SchoolMapper.java │ ├── entity/ # 【实体层】数据模型 │ │ ├── po/ # 数据库持久化对象 │ │ ├── vo/ # 前端视图对象 │ │ └── query/ # 查询参数对象 │ ├── tools/ # 【AI 工具】业务工具集 │ │ └── CourseTools.java # 课程查询、校区查询、预约生成工具 │ ├── model/ # 【自定义模型】大模型适配 │ │ └── AlibabaOpenAiChatModel.java # 通义千问 OpenAI 兼容模型实现 │ ├── repository/ # 【仓储层】数据存取 │ │ ├── ChatHistoryRepository.java │ │ ├── FileRepository.java │ │ └── impl/ │ ├── config/ # 【配置类】 │ │ ├── CommonConfiguration.java # AI Bean 与系统配置 │ │ └── MvcConfiguration.java # Web 跨域配置 │ ├── constants/ # 【常量】系统提示词与常量 │ │ └── SystemConstants.java # 游戏、客服系统提示词 │ ├── utils/ # 【工具类】 │ │ └── VectorDistanceUtils.java # 向量距离计算工具 │ └── HeimaAiApplication.java # 【启动类】Spring Boot 入口 ├── src/main/resources/ │ └── application.yml # 应用配置文件 └── pom.xml # Maven 依赖管理 ``` ------ ## 🤖 核心模块详解 ![1](https://bee-reg-ab.imagency.cn/mr/5626/26/b28f5383606f8763ebdd2c69671d2092.png) ### 1. 智能客服 Agent 客服场景基于 Spring AI Tool 机制实现了完整的工具调用能力，大模型可自主完成课程咨询与预约全流程。 **执行流程：** 1. 用户发起咨询，大模型先引导确认学习兴趣、学历背景 2. 大模型自主调用 `queryCourse` 工具查询匹配的课程列表 3. 向用户推荐课程，确认意向后引导选择试听校区 4. 调用 `querySchool` 工具获取校区列表供用户选择 5. 收集姓名、联系方式后调用 `createCourseReservation` 生成预约单 6. 返回预约成功信息、预约单号与注意事项 ![2](https://bee-reg-ab.imagency.cn/mr/5626/26/3b1208e7ace7e6a796ac5a868b7ce73c.png) ### 2. PDF RAG 问答 基于 Spring AI 向量存储能力实现的文档问答系统，支持上传即问。 **执行流程：** 1. 用户上传 PDF 文件，系统按页解析并分块 2. 文本块通过嵌入模型向量化后存入 `SimpleVectorStore` 3. 用户提问时，对问题向量化并进行相似度检索 Top-K 4. 检索到的文档片段与问题一起注入大模型上下文 5. 大模型基于文档内容生成精准、可溯源的回答 ![3](https://bee-reg-ab.imagency.cn/mr/5626/26/9cf19622ad156a71b676fda6a869927a.png) ### 3. 自定义大模型适配 `AlibabaOpenAiChatModel` 完全兼容 Spring AI `ChatModel` 标准接口，支持： - 同步对话与流式对话双模式 - 工具调用（Function Calling）完整支持 - 可观测性埋点与监控约定 - 重试模板与异常处理机制 - 多模态输入（图片、音频）扩展能力 ![4](https://bee-reg-ab.imagency.cn/mr/5626/26/68798329b15a38169633aa606f083be7.png) ### 4. 对话记忆管理 - 按 `chatId` 隔离多会话，支持并发访问 - 支持按业务类型（chat /service/pdf）分类管理 - 服务启动自动加载历史，停止自动持久化到本地 - 通过反射实现内存对话数据的序列化与反序列化 ![5](https://bee-reg-ab.imagency.cn/mr/5626/26/102f4f1d2647005ffeb548b5a267b0da.png) ------ ## 🚀 快速开始 ### 环境要求 - JDK 17 及以上 - Maven 3.6 及以上 - MySQL 8.0 及以上 - 有效通义千问 API Key ### 数据库准备 创建数据库并执行以下表结构： ```sql CREATE DATABASE heima_ai DEFAULT CHARACTER SET utf8mb4; USE heima_ai; -- 课程表 CREATE TABLE course ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) COMMENT '学科名称', edu INT COMMENT '学历要求：0-无，1-初中，2-高中，3-大专，4-本科以上', type VARCHAR(20) COMMENT '课程类型：编程、设计、自媒体、其它', price BIGINT COMMENT '课程价格', duration INT COMMENT '学习时长，单位天' ); -- 校区表 CREATE TABLE school ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) COMMENT '校区名称', city VARCHAR(50) COMMENT '校区所在城市' ); -- 课程预约表 CREATE TABLE course_reservation ( id INT PRIMARY KEY AUTO_INCREMENT, course VARCHAR(100) COMMENT '预约课程', student_name VARCHAR(50) COMMENT '学生姓名', contact_info VARCHAR(50) COMMENT '联系方式', school VARCHAR(100) COMMENT '预约校区', remark VARCHAR(255) COMMENT '备注' ); ``` ### 配置文件 在 `application.yml` 中添加配置： ```yaml server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/heima_ai?useUnicode=true&characterEncoding=utf8 username: root password: your_password ai: openai: base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: your_api_key options: model: qwen-omni-turbo temperature: 0.7 ``` ### 启动项目 1. Maven 构建 ```bash mvn clean install ``` 1. 运行启动类 ```bash com.itheima.ai.HeimaAiApplication ``` 1. 接口基地址：`http://localhost:8080/ai` ------ ## 🔌 接口说明 ### 通用聊天 ```bash GET /ai/chat?prompt=你好&chatId=123 ``` - 支持流式文本输出 - `chatId` 用于标识会话，保持多轮记忆 ### 智能客服 ```bash GET /ai/service?prompt=我想学编程&chatId=service001 ``` - 课程咨询与预约全流程对话 - 自动调用工具查询课程、生成预约单 ### 互动游戏 ```bash GET /ai/game?prompt=我错了&chatId=game001 ``` - 女友哄人互动游戏 - 内置原谅值数值系统与通关判定 ### PDF 问答 1. 上传文档 ```bash POST /ai/pdf/upload/{chatId} Content-Type: multipart/form-data form-data: file ``` 1. 文档问答 ```bash GET /ai/pdf/chat?prompt=总结文档核心内容&chatId=pdf001 ``` ### 对话历史 ```bash GET /ai/history/{type} # 获取指定类型的会话ID列表 GET /ai/history/{type}/{chatId} # 获取指定会话的消息列表 ``` ------ ## 🌟 项目亮点 1. **纯 Java 技术栈**：基于 Spring AI 原生生态，Java 开发者可快速上手与二次开发 2. **完整 Agent 能力**：实现了工具调用、RAG 检索、对话记忆完整智能体三要素 3. **多场景开箱即用**：通用聊天、智能客服、互动游戏、PDF 问答四大业务场景 4. **自定义模型参考**：提供通义千问完整适配实现，可作为对接其他模型的参考范本 5. **数据持久化**：对话记忆、向量库均支持本地文件持久化，重启不丢失 6. **标准接口设计**：RESTful 风格 + SSE 流式输出，易于前端集成 7. **技术栈全面**：覆盖大模型、向量检索、响应式编程、ORM、工程化全链路 ------ ## 📌 扩展方向 - 接入更多大模型（Ollama 本地模型、文心一言、星火等） - 向量库升级（Chroma、Milvus、PGVector 等专业向量数据库） - 增加用户体系与权限管理 - 配套前端页面实现 - 扩展更多业务工具，丰富 Agent 能力边界 - 增加对话审计日志与监控埋点 - 接入多模态（图片识别、语音对话）能力 ------ ## 📄 许可证 本项目仅供学习与技术交流使用。