SpringBoot 集成 Spring AI 实现简易智能助手

一、Spring AI 基础认知

1.1 主流大模型开发框架对比

Java 领域实现大模型（LLM）开发的两大核心框架，核心差异如下：

框架	最低 JDK 版本	核心优势
Spring AI	17	深度适配 SpringBoot 生态，自动装配，开发成本低
LangChain4J	8	兼容性强，支持低版本 JDK，生态插件丰富

1.2 Spring AI 核心特性

完全适配 SpringBoot 自动装配，提供各主流大模型的 starter 依赖，快速集成；
封装 ChatClient 统一对话 API，支持同步调用和流式调用两种交互方式；
基于 Advisor 切面机制实现功能增强，支持会话记忆、日志记录、RAG 等能力；
自动扫描 @Tool 注解实现工具调用，无需手动注册；
支持自定义 System 系统提示、对话上下文记忆，适配多轮对话场景。

1.3 快速开始

先带大家快速搭建一个基本功能项目，后面再依次拆分讲解。

环境要求
JDK：17 及以上版本（Spring AI 强制要求）；
SpringBoot：3.3.9 及以上（本文示例使用 3.3.9）；
构建工具：Maven；
大模型 URL&API：可通过相关大模型平台获取（支持 DeepSeek、OpenAI 等多模型，需实名认证并获取 API-Key）。

①创建 SpringBoot 项目

②引入依赖

首先，在项目 pom.xml 中添加 spring-ai 的版本信息：

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.0.0-SNAPSHOT</spring-ai.version>
</properties>

然后，添加 spring-ai 的依赖管理项：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

最后，引入 spring-ai-openai 的依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

为了方便后续开发，我们再手动引入一个 Lombok 依赖：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.22</version>
</dependency>

完整依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.9</version>
        <relativePath/>
    </parent>
    <groupId>com.ai</groupId>
    <artifactId>SpringAi</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>SpringAi</name>
    <description>SpringAi</description>
    <properties>
        <java.version>17
        1.0.0-SNAPSHOT
    
    
        
            
                org.springframework.ai
                spring-ai-bom
                ${spring-ai.version}
                pom
                import
            
        
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
        
            org.springframework.ai
            spring-ai-starter-model-openai
            ${spring-ai.version}
        
        
            org.projectlombok
            lombok
            1.18.22
        
    
    
        
            
                org.springframework.boot
                spring-boot-maven-plugin

③配置模型信息

首先需要获取对应模型的 API Key。可从相关大模型平台获取。无论什么大模型网站我们都需要获取两个内容：

API key
模型请求地址

接下来，我们在配置文件中配置模型的参数信息。以 openai 为例，我们将 application.properties 修改为 application.yaml，然后添加下面的内容：

spring:
  ai:
    openai:
      api-key: fghjklfghjklsahdjksadasdsadasd # 替换为你的 API-Key
      base-url: https://api.siliconflow.cn # 大模型接口地址
      chat:
        options:
          model: deepseek-ai/DeepSeek-V3 # 模型名称
          temperature: 0.7 # 随机性（0-1，值越大回答越灵活）
      completions-path: /v1/chat/completions # 对话接口路径

配置项说明：

api-key：大模型平台的访问密钥，需从平台获取；
base-url：大模型的接口根地址；
model：指定调用的大模型名称；
temperature：回答的随机性，推荐 0.5-0.7；
completions-path：对话接口的固定路径。

④创建 AiChatConfig 工具类

import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AiChatConfig {
    @Resource
    private OpenAiChatModel openAiChatModel;

    @Bean("open-ai")
    public ChatClient openAIChatClient() {
        return ChatClient.builder(openAiChatModel).build();
    }
}

⑤创建 AiChatController 控制类

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
@RequestMapping("/ai")
public class AiChatController {
    private final ChatClient chatClient;

    @RequestMapping("/chat")
    public String chat(@RequestParam(defaultValue = "介绍一下你自己") String prompt) {
        return chatClient.prompt(prompt).call().content();
    }
}

⑥测试

请求地址：http://localhost:8080/ai/chat

1.4 Spring AI 核心 API

Spring AI 围绕 ChatClient 构建统一对话入口，核心相关 API 及作用如下：

核心 API	所属包	核心作用
ChatClient	org.springframework.ai.chat.client	大模型对话统一入口，封装同步 / 流式调用
ChatClient.Builder	org.springframework.ai.chat.client	构建 ChatClient 实例，配置系统提示、增强器
OpenAiChatModel	org.springframework.ai.openai	OpenAI 兼容的模型实现，由 Spring 自动装配
ChatMemory	org.springframework.ai.chat.memory	对话记忆接口，存储多轮对话上下文
MessageWindowChatMemory	org.springframework.ai.chat.memory	ChatMemory 的实现类，基于消息窗口保留上下文
MessageChatMemoryAdvisor	org.springframework.ai.chat.client.advisor	会话记忆增强器，实现多轮对话上下文关联
SimpleLoggerAdvisor	org.springframework.ai.chat.client.advisor	日志增强器，打印 AI 交互全流程日志
Flux	reactor.core.publisher	流式返回结果类型，实现前端实时接收数据

1.5 流式结果

同步调用是指等待大模型完整返回结果后，再将数据返回给前端。核心 API 为 String ChatClient.prompt().call().content()。

流式调用是指大模型逐字 / 逐段返回结果，前端实时接收并展示。核心基于 WebFlux 实现，核心 API 为 Flux<String> ChatClient.prompt().stream().content()。

编写流式对话接口

在 Controller 中添加流式调用接口：

@RequestMapping(value = "/chat2", produces = "text/html;charset=UTF-8")
public Flux<String> chat2(@RequestParam(defaultValue = "介绍一下你自己") String prompt) {
    return chatClient.prompt().stream().content();
}

1.6 系统 (角色) 设置

在 Spring AI 中，设置 System 信息非常方便，不需要在每次发送时封装到 Message，而是创建 ChatClient 时指定即可。用于定义 AI 的角色、回答风格、业务规则。

创建 SystemManage 系统设置管理类

public class SystemManage {
    public static final String DEMO_SYSTEM = """
        你是一个专业的 AI 智能助手，你的名字叫小艾同学，请以友好、乐于助人和愉快的方式解答各种问题。
        重要：当用户询问具体信息时，不要编造不存在的数据。
        """;
}

修改 AiChatConfig 类

@Bean("open-ai")
public ChatClient openAIChatClient() {
    return ChatClient.builder(openAiChatModel)
            .defaultSystem(SystemManage.DEMO_SYSTEM)
            .build();
}

1.7 多轮对话上下文

多轮对话的核心是上下文关联，即 AI 能识别上一轮的提问和回答。Spring AI 通过 ChatMemory + MessageChatMemoryAdvisor 实现该能力。

Advisor 核心概念
Advisor 是 Spring AI 基于 AOP 切面机制实现的功能增强接口，用于在大模型对话的请求前、响应后进行无侵入式处理。

修改 AiChatConfig 类

@Bean
public ChatMemory chatMemory() {
    return MessageWindowChatMemory.builder().maxMessages(30).build();
}

@Bean("open-ai")
public ChatClient openAIChatClient() {
    return ChatClient.builder(openAiChatModel)
            .defaultSystem(SystemManage.DEMO_SYSTEM)
            .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
            .build();
}

1.8 日志集成

Spring AI 基于 AOP 机制实现与大模型对话过程的增强、拦截、修改等功能。所有的增强通知都需要实现 Advisor 接口。

修改 AiChatConfig 类

@Bean("open-ai")
public ChatClient openAIChatClient() {
    return ChatClient.builder(openAiChatModel)
            .defaultSystem(SystemManage.DEMO_SYSTEM)
            .defaultAdvisors(
                    MessageChatMemoryAdvisor.builder(chatMemory).build(),
                    new SimpleLoggerAdvisor()
            )
            .build();
}

修改日志级别

在 application.yaml 中添加日志配置：

logging:
  level:
    org.springframework.ai: debug
    com.ruangong.springai: debug

1.9 工具调用

工具调用允许大模型根据用户提问自动判断并调用自定义工具。

工具调用常用注解

核心组件	所属包	注解位置	作用
@Tool	org.springframework.ai.tool.annotation	方法	标记方法为可被 AI 调用的工具
@ToolParam	org.springframework.ai.tool.annotation	参数	标记被 AI 调用的工具方法参数

定义可被 AI 调用的工具类

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class MyTool {
    @Tool(name = "calculator_tool", description = "执行数学计算", returnDirect = true)
    public String calculator_tool(@ToolParam(description = "数学表达式") String expression) {
        // 实际可使用安全的表达式解析库
        return "计算结果";
    }

    @Tool(name = "weather_tool", description = "查询指定城市的实时天气信息", returnDirect = true)
    public String weather_tool(@ToolParam(description = "城市名称") String city) {
        // 模拟天气查询
        return "天气信息";
    }
}

修改 AiChatConfig 类

@Bean("open-ai")
public ChatClient openAIChatClient() {
    return ChatClient.builder(openAiChatModel)
            .defaultSystem(SystemManage.DEMO_SYSTEM)
            .defaultTools(myTool)
            .build();
}

1.10 前端集成

前后端在不同域名存在跨域问题，需要在服务端解决 CORS 问题。

配置跨域

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class MvcConfiguration implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*");
    }
}

1.11 会话隔离

在实际项目中，不同用户会在不同会话进行提问。需要为每一个会话都创建一个专属于会话的记忆。

修改 ChatController 对应方法

@RequestMapping(value = "/chat2", produces = "text/html;charset=UTF-8")
public Flux<String> chat2(@RequestParam(defaultValue = "介绍一下你自己") String prompt, String chatId) {
    return chatClient.prompt(prompt)
            .advisors(advisorSpec -> advisorSpec.param(ChatMemory.CONVERSATION_ID, chatId))
            .stream()
            .content();
}

1.12 前端界面功能简单实现

多会话切换历史查询

创建 AiChatMessage 类

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDateTime;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class AiChatMessage {
    private Long id;
    private String sessionId;
    private String role;
    private String content;
    private LocalDateTime createTime;
}

修改 ChatController 类内容

// 存储用户信息
MessageData.addMessage(AiChatMessage.builder()
        .role(MessageType.USER.getValue())
        .content(prompt)
        .sessionId(chatId)
        .build());

// 存储 AI 回复
.doOnComplete(() -> {
    MessageData.addMessage(AiChatMessage.builder()
            .role(MessageType.ASSISTANT.getValue())
            .content(fullResponse.toString())
            .sessionId(chatId)
            .build());
});

@GetMapping("/history/chat/{chatId}")
public List<AiChatMessage> history(@PathVariable String chatId) {
    return MessageData.messages.stream()
            .filter(msg -> msg.getSessionId().equals(chatId))
            .toList();
}

获取当前网页会话下的多个聊天记录

@GetMapping("/history/chat")
public HashSet<String> history1(HttpSession session) {
    HashSet<String> sessionIds = (HashSet<String>) session.getAttribute("sessionIds");
    if (sessionIds == null) {
        sessionIds = new HashSet<>();
    }
    return sessionIds;
}

SpringBoot 集成 Spring AI 实现简易智能助手