Spring AI 入门（持续更新）

发布于：2025-05-09 ⋅ 阅读:(20) ⋅ 点赞:(0)

介绍

Spring AI 是 Spring 项目中一个面向 AI 应用的模块，旨在通过集成开源框架、提供标准化的工具和便捷的开发体验，加速 AI 应用程序的构建和部署。

依赖

<!-- 基于 WebFlux 的响应式 SSE 传输 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
</dependency>
<!-- mcp -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
</dependency>
<!-- spring-ai -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
<!-- spring-web -->
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
</dependency>

配置文件

配置大模型的 API Key 和模型类型：

spring:
  ai:
    openai:
      base-url: ${AI_BASE_URL}
      api-key: ${AI_API_KEY} # 通过环境变量文件 .env 获取
      chat:
        options:
          model: ${AI_MODEL}
          temperature: 0.8

我这里使用的是 DeepSeek 的 API，可以去官网查看：https://platform.deepseek.com/

# AI URL
AI_BASE_URL=https://api.deepseek.com
# AI 密钥
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxx
# AI 模型
AI_MODEL=deepseek-chat

配置类

概念

首先，简单介绍一些概念

  1. ChatClient

ChatClient 提供了与 AI 模型通信的 Fluent API，它支持同步和反应式（Reactive）编程模型。

ChatClient 类似于应用程序开发中的服务层，它为应用程序直接提供 AI 服务，开发者可以使用 ChatClient Fluent API 快速完成一整套 AI 交互流程的组装

  1. ChatModel

ChatModel 即对话模型，它接收一系列消息（Message）作为输入，与模型 LLM 服务进行交互，并接收返回的聊天消息（ChatMessage）作为输出。目前，它有 3 种类型：

  • ChatModel：文本聊天交互模型，支持纯文本格式作为输入，并将模型的输出以格式化文本形式返回

  • ImageModel：接收用户文本输入，并将模型生成的图片作为输出返回（文生图）

  • AudioModel：接收用户文本输入，并将模型合成的语音作为输出返回

    ChatModel 的工作原理是接收 Prompt 或部分对话作为输入，将输入发送给后端大模型，模型根据其训练数据和对自然语言的理解生成对话响应，应用程序可以将响应呈现给用户或用于进一步处理。

问题

一个项目中可能会存在多个大模型的调用实例，例如 ZhiPuAiChatModel（智谱）、OllamaChatModel（Ollama本地模型）、OpenAiChatModel（OpenAi），这些实例都实现了ChatModel 接口，当然，我们可以直接使用这些模型实例来实现需求，但我们通常通过 ChatModel 来构建 ChatClient，因为这更通用。

可以通过在 yml 配置文件中设置 spring.ai.chat.client.enabled=false 来禁用 ChatClient bean 的自动配置，然后为每个聊天模型 build 出一个 ChatClient。

spring:
  ai:
    chat:
      client:
        enabled: false

配置类

package cn.onism.mcp.config;

import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.ollama.OllamaChatModel;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.zhipuai.ZhiPuAiChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * ChatClient 配置
 *
 * @author wxw
 * @date 2025-03-25
 */
@Configuration
public class ChatClientConfig {

    @Resource
    private OpenAiChatModel openAiChatModel;

    @Resource
    private ZhiPuAiChatModel zhiPuAiChatModel;

    @Resource
    private OllamaChatModel ollamaChatModel;

    @Resource
    private ToolCallbackProvider toolCallbackProvider;

    @Bean("openAiChatClient")
    public ChatClient openAiChatClient() {
        return ChatClient.builder(openAiChatModel)
                // 默认加载所有的工具，避免重复 new
                .defaultTools(toolCallbackProvider.getToolCallbacks())
                .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
                .build();
    }

    @Bean("zhiPuAiChatClient")
    public ChatClient zhiPuAiChatClient() {
        return ChatClient.builder(zhiPuAiChatModel)
                // 默认加载所有的工具，避免重复 new
                .defaultTools(toolCallbackProvider.getToolCallbacks())
                .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
                .build();
    }

    @Bean("ollamaChatClient")
    public ChatClient ollamaChatClient() {
        return ChatClient.builder(ollamaChatModel)
                // 默认加载所有的工具，避免重复 new
                .defaultTools(toolCallbackProvider.getToolCallbacks())
                .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
                .build();
    }
}

使用 ChatClient 的时候，@Resource 注解会按 Bean 的名称注入

@Resource
private ChatClient openAiChatClient;

@Resource
private ChatClient ollamaChatClient;

@Resource
private ChatClient zhiPuAiChatClient;

基础对话

普通响应

使用 call 方法来调用大模型

private ChatClient openAiChatModel;

@GetMapping("/chat")
public String chat(){
    Prompt prompt = new Prompt("你好，请介绍下你自己");
    String response = openAiChatModel.prompt(prompt)
                            .call()
                            .content();
    return response;
}

流式响应

call 方法修改为 stream，最终返回一个 Flux 对象

@GetMapping(value = "/chat/stream", produces = "text/html;charset=UTF-8")
public Flux<String> stream() {
    Prompt prompt = new Prompt("你好，请介绍下你自己");
    String response = openAiChatModel.prompt(prompt)
            .stream()
            .content();
    return response;
}

tips：我们可以通过缓存减少重复请求，提高性能。可以使用 Spring Cache 的 @Cacheable 注解实现：

@Cacheable("getChatResponse")
public String getChatResponse(String message){
    String response = openAiChatModel.prompt()
                            .user(message)
                            .call()
                            .content();
    return response;
}

tips： 适用于批量处理场景。可以使用 Spring 的 @Async 注解实现：

@Async
public CompletableFuture<String> getAsyncChatResponse(String message) {
    return CompletableFuture.supplyAsync(() -> openAiChatModel.prompt()
            .user(message)
            .call()
            .content());
}

3 种组织提示词的方式

Prompt

通过 Prompt 来封装提示词实体，适用于简单场景

Prompt prompt = new Prompt("介绍下你自己");
PromptTemplate

使用提示词模板 PromptTemplate 来复用提示词，即将提示词的大体框架构建好，用户仅输入关键信息完善提示词

其中，{ } 作为占位符，promptTemplate.render 方法来填充

@GetMapping("/chat/formatPrompt")
public String formatPrompt(
        @RequestParam(value = "money") String money,
        @RequestParam(value = "number") String number,
        @RequestParam(value = "brand") String brand
) {
    PromptTemplate promptTemplate = new PromptTemplate("""

    根据我目前的经济情况{money},只推荐{number}部{brand}品牌的手机。

                                                       """);

    Prompt prompt = new Prompt(promptTemplate.render(
        Map.of("money",money,"number", number, "brand", brand)));

    return openAiChatModel.prompt(prompt)
            .call()
            .content();
}
Message

使用 Message ，提前约定好大模型的功能或角色

消息类型：

系统消息（SystemMessage）：设定对话的背景、规则或指令，引导 AI 的行为
用户消息（UserMessage）：表示用户的输入，即用户向 AI 提出的问题或请求
助手消息（AssistantMessage）：表示 AI 的回复，即模型生成的回答
工具响应消息（ToolResponseMessage）：当 AI 调用外部工具（如 API）后，返回 工具的执行结果，供 AI 进一步处理

@GetMapping("/chat/messagePrompt")
public String messagePrompt(@RequestParam(value = "book", defaultValue = "《白夜行》") String book) {
    // 用户输入
    UserMessage userMessage = new UserMessage(book);
    log.info("userMessage: {}", userMessage);
    // 对系统的指令
    SystemMessage systemMessage = new SystemMessage("你是一个专业的评书人，给出你的评价吧！");
    log.info("systemMessage: {}", systemMessage);
    // 组合成完整的提示词,注意,只能是系统指令在前,用户消息在后,否则会报错
    Prompt prompt = new Prompt(List.of(systemMessage, userMessage));

    return openAiChatModel.prompt(prompt)
                 .call()
                 .content();
}
保存 prompt

prompt 不宜嵌入到代码中，可以将作为一个 .txt 文件 其保存到 src/main/resources/prompt 目录下，使用读取文件的工具类就可以读取到 prompt

package cn.onism.mcp.utils;

import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;

/**
 * @description: 读取文件内容的工具类
 * @date: 2025/5/8
 */
@Component
public class FileContentReader {
    public String readFileContent(String filePath) {
        StringBuilder content = new StringBuilder();
        try {
            // 创建 ClassPathResource 对象以获取类路径下的资源
            ClassPathResource resource = new ClassPathResource(filePath);
            // 打开文件输入流
            InputStream inputStream = resource.getInputStream();
            // 创建 BufferedReader 用于读取文件内容
            BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8));
            String line;
            // 逐行读取文件内容
            while ((line = reader.readLine()) != null) {
                content.append(line).append("\n");
            }
            // 关闭输入流
            reader.close();
        } catch (IOException e) {
            // 若读取文件时出现异常，打印异常信息
            e.printStackTrace();
        }
        return content.toString();
    }
}

PromptTemplate promptTemplate = new PromptTemplate(
    fileContentReader.readFileContent("prompt/formatPrompt.txt")
);

解析模型输出（结构化）

模型输出的格式是不固定的，无法直接解析或映射到 Java 对象，因此，Spring AI 通过在提示词中添加格式化指令要求大模型按特定格式返回内容，在拿到大模型输出数据后通过转换器做结构化输出。

实体类 Json 格式

首先我们定义一个实体类 ActorInfo

@Data
@Description("演员信息")
public class ActorInfo {

    @JsonPropertyDescription("演员姓名")
    private String name;
    @JsonPropertyDescription("演员年龄")
    private Integer age;
    @JsonPropertyDescription("演员性别")
    private String gender;
    @JsonPropertyDescription("演员出生日期")
    private String birthday;
    @JsonPropertyDescription("演员国籍")
    private String nationality;
}

在 call 方法后面调用 entity 方法，把对应实体类的 class 传递进去即能做到结构化输出

@GetMapping("/chat/actor")
public ActorInfo queryActorInfo(@RequestParam(value = "actorName") String actorName) {

    PromptTemplate promptTemplate = new PromptTemplate("查询{actorName}演员的详细信息");
    Prompt prompt = new Prompt(promptTemplate.render(Map.of("actorName", actorName)));

    ActorInfo response = openAiChatModel.prompt(prompt)
                               .call()
                               .entity(ActorInfo.class);

    return response;
}

结果符合要求

List 列表格式

在 entity 方法中传入 new ListOutputConverter(new DefaultConversionService())

@GetMapping("/chat/actorMovieList")
public List<String> queryActorMovieList(@RequestParam(value = "actorName") String actorName) {

    PromptTemplate promptTemplate = new PromptTemplate("查询{actorName}主演的电影");
    Prompt prompt = new Prompt(promptTemplate.render(Map.of("actorName", actorName)));

    List<String> response = openAiChatModel.prompt(prompt)
                    .call()
                    .entity(new ListOutputConverter(new DefaultConversionService()));

    return response;
}
Map 格式

tips: 目前在 Map 中暂不支持嵌套复杂类型，因此 Map 中不能返回实体类，而只能是 Object。

在 entity 方法中传入 new ParameterizedTypeReference<>() {}

@GetMapping("/chat/actor")
public Map<String, Object> queryActorInfo(@RequestParam(value = "actorName") String actorName) {

    PromptTemplate promptTemplate = new PromptTemplate("查询{actorName}演员及另外4名相关演员的详细信息");
    Prompt prompt = new Prompt(promptTemplate.render(Map.of("actorName", actorName)));

    Map<String, Object> response = openAiChatModel.prompt(prompt)
                        .call()
                        .entity(new ParameterizedTypeReference<>() {});

    return response;
}

多模态

deepseek 暂时不支持多模态，因此这里选用 智谱：https://bigmodel.cn/

依赖与配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-zhipuai</artifactId>
    <version>1.0.0-M6</version>
</dependency>

spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY}
      chat:
        options:
          model: ${ZHIPUAI_MODEL}
          temperature: 0.8

# api-key
ZHIPUAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxx
# 所选模型
ZHIPUAI_MODEL=glm-4v-plus-0111
理解图片

在 src/main/resources/images 目录下保存图片

创建一个 ZhiPuAiChatModel，将用户输入和图片封装成一个 UserMessage，然后使用 call 方法传入一个 prompt，最后获得输出

@Resource
private ZhiPuAiChatModel zhiPuAiChatModel;

@GetMapping("/chat/pic")
public String pic() {

    Resource imageResource = new ClassPathResource("images/mcp.png");

    // 构造用户消息
    var userMessage = new UserMessage("解释一下你在这幅图中看到了什么?",
                                      new Media(MimeTypeUtils.IMAGE_PNG, imageResource));

    ChatResponse chatResponse = zhiPuAiChatModel.call(new Prompt(userMessage));

    return chatResponse.getResult().getOutput().getText();
}

文生图

这里需要使用 zhiPuAiImageModel，我们调用它的 call 方法，传入一个 ImagePrompt，ImagePrompt 由**用户图片描述输入 ImageMessage **和 **图片描述信息 OpenAiImageOptions **所构成，

其中，

  • model 要选择适用于图像生成任务的模型，这里我们选择了 cogview-4-250304
  • quality 为图像生成图像的质量，默认为 standard
    • hd : 生成更精细、细节更丰富的图像，整体一致性更高，耗时约20 秒
    • standard :快速生成图像，适合对生成速度有较高要求的场景，耗时约 5-10 秒
@Autowired
ZhiPuAiImageModel ziPuAiImageModel;

@Autowired
private FileUtils fileUtils;

@GetMapping("/outputImg")
public void outputImg() throws IOException {
    ImageMessage userMessage = new ImageMessage("一个仙人掌大象");

    OpenAiImageOptions chatOptions = OpenAiImageOptions.builder()
            .model("cogview-4-250304").quality("hd").N(1).height(1024).width(1024).build();

    ImagePrompt prompt = new ImagePrompt(userMessage, chatOptions);
    // 调用
    ImageResponse imageResponse = ziPuAiImageModel.call(prompt);
    // 输出的图片
    Image image = imageResponse.getResult().getOutput();

    // 保存到本地
    InputStream in = new URL(image.getUrl()).openStream();
    fileUtils.saveStreamToFile(in,
                               "src/main/resources/images", 
                               "pic"+RandomUtils.insecure().randomInt(0, 100)+".png"
                              );
}

@Component
public class FileUtils {

    public String saveStreamToFile(InputStream inputStream, String filePath, String fileName) throws IOException {

        // 创建目录（如果不存在）
        Path dirPath = Paths.get(filePath);
        if (!Files.exists(dirPath)) {
            Files.createDirectories(dirPath);
        }

        // 构建完整路径
        Path targetPath = dirPath.resolve(fileName);

        // 使用 try-with-resources 确保流关闭
        try (inputStream) {
            Files.copy(inputStream, targetPath, StandardCopyOption.REPLACE_EXISTING);
        }

        return targetPath.toAbsolutePath().toString();
    }
}

调用本地模型

_**tips: **_若想零成本调用大模型，并且保障隐私，可以阅读本章节

下载安装 Ollama

下载安装 Ollama：https://ollama.com/ [Ollama 是一个开源的大型语言模型服务工具，旨在帮助用户快速在本地运行大模型。通过简单的安装指令，用户可以通过一条命令轻松启动和运行开源的大型语言模型。Ollama 是 LLM 领域的 Docker]，安装完成后执行 ollama 得到如下输出则表明安装成功

选择一个模型下载到本地：https://ollama.com/search，我这里选择了 qwen3:8b

引入 ollama 依赖

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

配置

spring:
  ai:
    ollama:
      chat:
        model: ${OLLAMA_MODEL}
      base-url: ${OLLAMA_BASE_URL}

# 本地模型
OLLAMA_MODEL=qwen3:8b
# URL
OLLAMA_BASE_URL=http://localhost:11434

实际调用

/**
 * ollama本地模型测试
 * @param input
 * @return
 */
@GetMapping("/ollama/chat")
public String ollamaChat(@RequestParam(value = "input") String input) {

    Prompt prompt = new Prompt(input);

    return ollamaChatModel.call(prompt).getResult().getOutput().getText();
}

结果

对话记忆

内存记忆（短期）

MessageChatMemoryAdvisor 可以用来提供聊天记忆功能，这需要传递一个基于内存记忆的 ChatMemory

/**
 * 内存记忆/短期记忆
 * @param input
 * @return
 */
@GetMapping("/memory/chat")
public String chat(@RequestParam(value = "input") String input) {
    Prompt prompt = new Prompt(input);
    // 内存记忆的 ChatMemory
    InMemoryChatMemory inMemoryChatMemory = new InMemoryChatMemory();

    return openAiChatClient.prompt(prompt)
    .advisors(new MessageChatMemoryAdvisor(inMemoryChatMemory))
    .call()
    .content();
}

测试

隔离

多用户参与 AI 对话，每个用户的对话记录要做到互不干扰，因此要对不同用户的记忆按一定规则做好隔离。

由于在配置类中已经设置好了默认的 Advisors 为基于内存的聊天记忆 InMemoryChatMemory，因此，我们只需调用 openAiChatClient 的 advisors 方法，并设置好相应的参数即可

其中，

chat_memory_conversation_id 表示 会话 ID，用于区分不同用户的对话历史
chat_memory_response_size 表示每次最多检索 x 条对话历史

@Bean("openAiChatClient")
public ChatClient openAiChatClient() {
    return ChatClient.builder(openAiChatModel)
    // 默认加载所有的工具，避免重复 new
    .defaultTools(toolCallbackProvider.getToolCallbacks())
    // 设置记忆
    .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
    .build();
}

/**
* 短期记忆,按用户 ID 隔离
* @param input 
* @param userId
* @return
*/
@GetMapping("/memory/chat/user")
public String chatByUser(@RequestParam(value = "input") String input, 
                         @RequestParam(value = "userId") String userId) {
    Prompt prompt = new Prompt(input);

    return openAiChatClient.prompt(prompt)
    // 设置记忆的参数
    .advisors(advisor -> advisor.param("chat_memory_conversation_id", userId)
              .param("chat_memory_response_size", 100))
    .call()
    .content();
}

测试

集成 Redis

基于内存的聊天记忆可能无法满足开发者的需求，因此，我们可以构建一个基于 Redis 的长期记忆 RedisChatMemory

引入 Redis 依赖
<!-- redis -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
yml 配置
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: xxxxx
Redis 配置类

创建了一个 RedisTemplate 实例

package cn.onism.mcp.config;

import org.springframework.context.annotation.Bean;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.serializer.Jackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.StringRedisSerializer;

/**
 * @description: Redis配置类
 * @date: 2025/5/9
 */
public class RedisConfig {

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<String, Object> redisTemplate = new RedisTemplate<>();
        redisTemplate.setConnectionFactory(factory);
        redisTemplate.setKeySerializer(new StringRedisSerializer());
        redisTemplate.setValueSerializer(new Jackson2JsonRedisSerializer<>(Object.class));
        redisTemplate.setHashKeySerializer(new StringRedisSerializer());
        redisTemplate.setHashValueSerializer(new Jackson2JsonRedisSerializer<>(Object.class));
        redisTemplate.afterPropertiesSet();
        return redisTemplate;
    }
}
定义消息实体类

用于存储对话的 ID、类型和内容，同时实现了序列化接口以便在 Redis 中存储

/**
 * @description: 聊天消息实体类
 * @date: 2025/5/9
 */
@NoArgsConstructor
@AllArgsConstructor
@Data
public class ChatEntity implements Serializable {
    private static final long serialVersionUID = 1555L;
    /**
     * 聊天ID
     */
    private String chatId;
    /**
     * 聊天类型
     */
    private String type;
    /**
     * 聊天内容
     */
    private String content;
}
构造 RedisChatMemory

创建一个 RedisChatMemory 并实现 ChatMemory 接口，重写该接口的 3 个方法

其中，

add表示添加聊天记录，conversationId 为会话 ID，messages 为消息列表
get表示获取聊天记录，lastN 表示获取最后 lastN 条聊天记录
clear表示清除聊天记录

package cn.onism.mcp.memory;

import cn.onism.mcp.model.entity.ChatEntity;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.messages.*;
import org.springframework.data.redis.core.RedisTemplate;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.concurrent.TimeUnit;

/**
 * @description: 基于Redis的聊天记忆
 * @date: 2025/5/9
 */
public class ChatRedisMemory implements ChatMemory {

    /**
     * 聊天记录的Redis key前缀
     */
    private static final String KEY_PREFIX = "chat:history:";

    private final RedisTemplate<String, Object> redisTemplate;

    public ChatRedisMemory(RedisTemplate<String, Object> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    /**
     * 添加聊天记录
     * @param conversationId
     * @param messages
     */
    @Override
    public void add(String conversationId, List<Message> messages) {
        String key = KEY_PREFIX + conversationId;
        List<ChatEntity> chatEntityList = new ArrayList<>();
        for (Message message : messages) {
            // 解析消息内容
            String[] strings = message.getText().split("</think>");
            String text = strings.length == 2 ? strings[1] : strings[0];

            // 构造聊天记录实体
            ChatEntity chatEntity = new ChatEntity();
            chatEntity.setChatId(conversationId);
            chatEntity.setType(message.getMessageType().getValue());
            chatEntity.setContent(text);
            chatEntityList.add(chatEntity);
        }
        // 保存聊天记录到Redis, 并设置过期时间为60分钟
        redisTemplate.opsForList().rightPushAll(key, chatEntityList.toArray());
        redisTemplate.expire(key, 60, TimeUnit.MINUTES);
    }

    /**
     * 获取聊天记录
     * @param conversationId
     * @param lastN
     * @return List<Message>
     */
    @Override
    public List<Message> get(String conversationId, int lastN) {
        String key = KEY_PREFIX + conversationId;
        Long size = redisTemplate.opsForList().size(key);
        if (size == null || size == 0) {
            return Collections.emptyList();
        }

        // 取最后lastN条聊天记录,如果聊天记录数量少于lastN,则取全部
        int start = Math.max(0, size.intValue() - lastN);
        List<Object> objectList = redisTemplate.opsForList().range(key, start, -1);
        List<Message> outputList = new ArrayList<>();

        // 解析聊天记录实体,并构造消息对象
        ObjectMapper mapper = new ObjectMapper();
        for (Object object : objectList){
            ChatEntity chatEntity = mapper.convertValue(object, ChatEntity.class);
            if(MessageType.USER.getValue().equals(chatEntity.getType())){
                outputList.add(new UserMessage(chatEntity.getContent()));
            }else if (MessageType.SYSTEM.getValue().equals(chatEntity.getType())){
                outputList.add(new SystemMessage(chatEntity.getContent()));
            }else if (MessageType.ASSISTANT.getValue().equals(chatEntity.getType())){
                outputList.add(new AssistantMessage(chatEntity.getContent()));
            }
        }
        return outputList;
    }

    /**
     * 清除聊天记录
     * @param conversationId
     */
    @Override
    public void clear(String conversationId) {
        String key = KEY_PREFIX + conversationId;
        redisTemplate.delete(key);
    }
}
更改 ChatClient 配置

将 MessageChatMemoryAdvisor 中的参数替换为我们实现的 ChatRedisMemory

@Resource
private RedisTemplate<String, Object> redisTemplate;

@Bean("openAiChatClient")
public ChatClient openAiChatClient() {
    return ChatClient.builder(openAiChatModel)
    // 默认加载所有的工具，避免重复 new
    .defaultTools(toolCallbackProvider.getToolCallbacks())
    .defaultAdvisors(new MessageChatMemoryAdvisor(new ChatRedisMemory(redisTemplate)))
    .build();
}
测试
/**
 * RedisChatMemory
 * @param input
 * @param userId
 * @return String
 */
@GetMapping("/memory/chat/user")
public String chatByUser(@RequestParam(value = "input") String input, 
                         @RequestParam(value = "userId") String userId) {
    Prompt prompt = new Prompt(input);

    return openAiChatClient.prompt(prompt)
    .advisors(advisor -> advisor.param("chat_memory_conversation_id", userId)
              .param("chat_memory_response_size", 100))
    .call()
    .content();
}

执行结果

可以看到，Redis 中有对应的记录，我们可以通过 lrange key start end 命令获取列表中的数据，其中 content 为 UTF-8 编码

Tool/Function Calling

工具（Tool）或功能调用（Function Calling）允许大型语言模型在必要时调用一个或多个可用的工具，这些工具通常由开发者定义。工具可以是任何东西：网页搜索、对外部 API 的调用，或特定代码的执行等。

下面是工具调用的流程图：

更加简洁的流程图：

  1. 工具注册阶段，当需要为模型提供工具支持时，需在聊天请求中声明工具定义。每个工具定义包含三个核心要素：工具名称（唯一标识符）、功能描述（自然语言说明）、输入参数结构（JSON Schema格式）
  2. 模型决策阶段，模型分析请求后，若决定调用工具，将返回结构化响应，包含：目标工具名称、符合预定义Schema的格式化参数
  3. 工具执行阶段，客户端应用负责根据工具名称定位具体实现，使用验证后的参数执行目标工具
  4. 工具响应阶段，工具执行结果返回给应用程序
  5. 重新组装阶段，应用将标准化处理后的执行结果返回给模型再次处理
  6. 结果响应阶段，模型结合用户初始输入以及工具执行结果再次加工返回给用户

工具定义与使用

Methods as Tools
  1. 注解式定义

创建一个 DateTimeTool 工具类，在 getCurrentDateTime 方法上使用 @Tool 注解，表示将该方法标记为一个 Tool，description 表示对工具的描述，大模型会根据这个描述来理解该工具的作用

@Component
public class DateTimeTool {

    private static final Logger LOGGER = LoggerFactory.getLogger(DateTimeTool.class);

    @Tool(description = "获取当前用户的日期和时间")
    public String getCurrentDateTime() {
        LOGGER.info("---------- getCurrentDateTime 工具被调用 ----------");

        return LocalDateTime.now()
        .atZone(LocaleContextHolder.getTimeZone().toZoneId())
        .toString();
    }
}

在使用时，可以在 ChatClient 配置类中将所有工具都提前加载到 ChatClient 中

@Configuration
public class ChatClientConfig {

    @Resource
    private OpenAiChatModel openAiChatModel;

    @Resource
    private ToolCallbackProvider toolCallbackProvider;

    @Resource
    private RedisTemplate<String, Object> redisTemplate;

    @Bean("openAiChatClient")
    public ChatClient openAiChatClient() {
        return ChatClient.builder(openAiChatModel)
        // 默认加载所有的工具，避免重复 new
        .defaultTools(toolCallbackProvider.getToolCallbacks())
        .defaultAdvisors(new MessageChatMemoryAdvisor(new ChatRedisMemory(redisTemplate)))
        .build();
    }
}

或者是不在配置类中加载所有工具，而是在调用 ChatClient 时将需要用到的工具传递进去，即使用 tools 方法，传入工具类

@GetMapping("/tool/chat")
public String toolChat(@RequestParam(value = "input") String input) {
    Prompt prompt = new Prompt(input);

    return openAiChatClient.prompt(prompt)
    .tools(new DateTimeTool())
    .call()
    .content();
}

测试后发现大模型的确调用了 DateTimeTool

  1. 编程式定义

我们可以不使用 @Tool 注解，而是采用编程式的方式构造一个 Tool

@Component
public class DateTimeTool {

    private static final Logger LOGGER = LoggerFactory.getLogger(DateTimeTool.class);

    // no annotation
    public String getCurrentDateTime() {
        LOGGER.info("---------- getCurrentDateTime 工具被调用 ----------");

        return LocalDateTime.now()
        .atZone(LocaleContextHolder.getTimeZone().toZoneId())
        .toString();
    }
}

首先通过反射获取方法，然后定义一个 ToolDefinition，最后创建一个 MethodToolCallback，将其传入到 tools 方法中即可

@GetMapping("/tool/chat")
public String toolChat(@RequestParam(value = "input") String input) {
    Prompt prompt = new Prompt(input);
    
    // 通过反射获取方法
    Method method = ReflectionUtils.findMethod(DateTimeTool.class, "getCurrentDateTime");
    
    // 工具定义
    ToolDefinition toolDefinition = ToolDefinition.builder(method)
    .description("获取当前用户的日期和时间")
    .build();
    
    // 创建一个 MethodToolCallback
    MethodToolCallback methodToolCallback = MethodToolCallback.builder()
    .toolDefinition(toolDefinition)
    .toolMethod(method)
    .toolObject(new DateTimeTool())
    .build();

    return openAiChatClient.prompt(prompt)
    .tools(methodToolCallback)
    .call()
    .content();
}
Fuctions as Tools

除方法外，Function、Supplier、Consumer 等函数式接口也可以定义为 Tool

下面**模拟一个查询天气的服务，首先定义 WeatherRequest 和 WeatherResponse**

其中，@ToolParam 注解用于定义工具所需参数， description 为工具参数的描述，模型通过描述可以更好的理解参数的作用

/**
 * 天气查询请求参数
 */
@Data
public class WeatherRequest {
    /**
     * 坐标
     */
    @ToolParam(description = "经纬度，精确到小数点后4位，格式为：经度,纬度")
    String location;

}

@Data
@AllArgsConstructor
@NoArgsConstructor
public class WeatherResponse {
    /**
     * 温度
     */
    private double temp;
    /**
     * 单位
     */
    private Unit unit;
}

/**
 * 温度单位
 */
public enum Unit {
    C, F
}

接下来创建一个 WeatherService，实现 Function 接口，编写具体逻辑。这里获取天气使用的是彩云科技开放平台提供的免费的 API 接口：https://docs.caiyunapp.com/weather-api/，构造好请求后使用 HttpURLConnection 发送请求，读取响应后使用 Jackson 解析 JSON，获取天气数据。

package cn.onism.mcp.tool.service;

import cn.onism.mcp.tool.Unit;
import cn.onism.mcp.tool.WeatherRequest;
import cn.onism.mcp.tool.WeatherResponse;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.function.Function;

/**
 * @description: 天气服务
 * @date: 2025/5/9
 */
@Slf4j
@Component
public class WeatherService implements Function<WeatherRequest, WeatherResponse> {

    private static final Logger LOGGER = LoggerFactory.getLogger(WeatherService.class);

    private static final String TOEKN = "xxxxxxxxxxxxxxxxxx";
    /**
    * 实时天气接口
    */
    private static final String API_URL = "https://api.caiyunapp.com/v2.6/%s/%s/realtime";

    private double temp;

    private String skycon;

    @Override
    public WeatherResponse apply(WeatherRequest weatherRequest) {
        LOGGER.info("Using caiyun api, getting weather information...");

        try {
            // 构造API请求
            String location = weatherRequest.getLocation();
            String encodedLocation = URLEncoder.encode(location, StandardCharsets.UTF_8);
            String apiUrl = String.format(
                    API_URL,
                    TOEKN,
                    encodedLocation
            );
            URL url = new URL(apiUrl);

            // 发送请求
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");

            // 读取响应
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
                String inputLine;
                StringBuilder response = new StringBuilder();
                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();
                // 使用Jackson解析JSON
                ObjectMapper objectMapper = new ObjectMapper();
                JsonNode rootNode = objectMapper.readTree(response.toString());

                // 获取天气数据
                JsonNode resultNode = rootNode.get("result");
                LOGGER.info("获取到天气信息: " + resultNode.toString());
                temp = resultNode.get("realtime").get("temperature").asDouble();
                skycon = resultNode.get("realtime").get("skycon").asText();
            } else {
                System.out.println("请求失败，响应码为: " + responseCode);
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
        return new WeatherResponse(temp, skycon, Unit.C);
    }
}

创建一个 WeatherTool 工具类，定义一个 Bean，Bean 名称为工具名称，@Description 中描述工具作用，该 Bean 调用了 WeatherService 中的方法

package cn.onism.mcp.tool;

import cn.onism.mcp.tool.service.WeatherService;
import lombok.extern.slf4j.Slf4j;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Description;
import org.springframework.stereotype.Component;

import java.util.function.Function;

/**
 * @description: 天气工具类
 * @date: 2025/5/9
 */

@Slf4j
@Component
public class WeatherTool {

    private final WeatherService weatherService = new WeatherService();

    @Bean(name = "currentWeather")
    @Description("依据位置获取天气信息")
    public Function<WeatherRequest, WeatherResponse> currentWeather() {
        return weatherService::apply;
    }
}

将天气工具和日期工具传入 tools 方法中

@GetMapping("/tool/weather")
public String toolFunctionAnnotation(@RequestParam(value = "input") String input) {
    Prompt prompt = new Prompt(input);

    return openAiChatClient.prompt(prompt)
    .tools("currentWeather","getCurrentDateTime")
    .call()
    .content();
}

测试

可以看到，大模型首先会调用日期工具获取时间，同时，我们向大模型询问的地点会被自动解析为 location 经纬度参数，接着调用天气工具获取天气信息

在之前的流程图中，工具的调用会与大模型进行 2 次交互，第一次为发起请求，第二次在工具执行完成后带着工具执行的结果再次调用大模型，而某些情况下，我们想在工具执行完成后直接返回，而不去调用大模型。在 @Tool 注解中令 returnDirect = true 即可

MCP

首先来看这张经典的图，MCP（Model Context Protocol 模型上下文协议）可以被视为 AI 应用的 USB-C 端口，它为 AI 模型/应用与不同数据源/工具建立了统一对接规范，旨在标准化应用程序向大语言模型提供上下文的交互方式。

MCP 采用客户端-服务器架构，

其中，

- **<font style="color:rgb(25, 27, 31);">MCP Hosts（宿主程序）：</font>**<font style="color:rgb(25, 27, 31);">如 Claude Desktop、IDE 等，通过 MCP 访问数据</font>
- **<font style="color:rgb(25, 27, 31);">MCP Clients（客户端）：</font>**<font style="color:rgb(25, 27, 31);">与服务器建立 1:1 连接，处理通信</font>
- **<font style="color:rgb(25, 27, 31);">MCP Servers（服务端）：</font>**<font style="color:rgb(25, 27, 31);">轻量级程序，提供标准化的数据或工具访问能力</font>
- **<font style="color:rgb(25, 27, 31);">Local Data Sources（本地数据源）：</font>**<font style="color:rgb(25, 27, 31);">如文件、数据库等，由 MCP 服务端安全访问</font>
- **<font style="color:rgb(25, 27, 31);">Remote Services（远程服务）：</font>**<font style="color:rgb(25, 27, 31);">如 API、云服务等，MCP 服务端可代理访问</font>

RAG

Aegnt

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布