Spring Boot 快速构建基于 Spring AI 的智能助手

最后，引入 spring-ai-openai 的依赖。为了方便后续开发，建议手动指定 Lombok 版本以确保兼容性：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>${spring-ai.version}</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.22</version>
</dependency>

③ 配置模型信息

无论什么大模型网站我们都需要获取两个内容：API Key 和 模型请求地址。接下来，我们在配置文件中配置模型的参数信息。以 OpenAI 为例，我们将 application.properties 修改为 application.yaml，然后添加下面的内容：

spring:
  ai:
    openai:
      api-key: your-api-key-here # 替换为你的实际 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;

    /**
     * 配置 ChatClient - OpenAI 兼容的聊天客户端
     * @return ChatClient 实例
     */
    @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?prompt=你好

1.4 Spring AI 核心 API

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

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) {
    // 流式调用核心 API 链
    return chatClient
            .prompt(prompt)
            .stream()
            .content();
}

重启测试，再次访问，会一点点生成数据展示在页面上。

1.6 系统 (角色) 设置

如果我们希望 AI 按照新的设定工作，就需要给它设置 System 背景信息。在 Spring AI 中，设置 System 信息非常方便，不需要在每次发送时封装到 Message，而是创建 ChatClient 时指定即可。

创建 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();
}

测试多轮对话

• 第一次访问：http://localhost:8080/ai/chat?prompt=12 个苹果分给 2 个人，每人分几个？ 返回：6 个；
• 第二次访问：http://localhost:8080/ai/chat?prompt=分给 3 个人呢？ 返回：4 个（成功识别上下文'12 个苹果'）。

1.8 日志集成

默认情况下，应用于 AI 的交互时不记录日志的，我们无法得知 Spring AI 组织的提示词到底长什么样，有没有问题。这样不方便我们调试。

修改 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 工具调用

工具调用是 Spring 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 = "执行数学计算，参数：expression（数学表达式，如 10+20*3）", returnDirect = true)
    public String calculator_tool(@ToolParam(description = "执行数学计算，如 10+20*3 等") String expression) {
        System.out.println("------------------------------------------数学计算-----------------------------------------");
        return "自己拿计算器算去";
    }

    @Tool(name = "weather_tool", description = "查询指定城市的实时天气信息，入参：city（城市名称，如北京、上海）", returnDirect = true)
    public String weather_tool(@ToolParam(description = "搜索关键词，如'北京'、'上海'等") String city) {
        System.out.println("------------------------------------------天气查询-----------------------------------------");
        String weatherInfo = switch (city) {
            case "北京" -> "晴，气温 18~28℃，西南风 2 级";
            case "上海" -> "多云，气温 22~30℃，东南风 3 级";
            default -> "暂未查询到「" + city + "」的天气信息，请确认城市名称";
        };
        return weatherInfo;
    }
}

修改 AiChatConfig 类

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

为了提高工具调用的命中率，可以在 System 模板中明确告知 AI 可用工具。

1.10 前端集成

在浏览器通过地址访问非常麻烦，如果能有一个优美的前端页面就好了。前后端在不同域名存在跨域问题，因此我们需要在服务端解决 CORS 问题。

配置跨域 在 config 包中添加一个类：

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("*")
                .exposedHeaders("Content-Disposition");
    }
}

1.11 会话隔离

在实际项目中，不同用户会在不同会话进行提问，要实现会话级别的记忆需要为每一个会话都创建一个专属于会话的'记忆'。例如前台案例请求携带的 chatId，就是会话的标识。

修改 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 前端界面功能简单实现

多会话切换历史查询

页面在进行会话切换时，会将会话的 Id 发送给后台，获取信息，所以后台需要保存对话信息。

创建 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; // user-用户，assistant-AI 助手
    private String content;
    private LocalDateTime createTime;
}

创建 MessageData 类，模拟存储对话数据

import java.util.ArrayList;

public class MessageData {
    public static ArrayList<AiChatMessage> messages = new ArrayList<>();

    public static void addMessage(AiChatMessage message) {
        messages.add(message);
    }
}

修改 ChatController 类内容

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

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

因为只是一个案例，所以使用 session 存储会话 id，实际开发中创建会话可以存储到数据库中，然后通过数据库查询返回。

修改 ChatController 类内容

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

至此，一个基础的 AI 对话机器人原型已完成。