* Spring AI 的Tool Calling 工具调用

Function Calling让大模型拥有“动手能力”https://blog.csdn.net/weixin_55772633/article/details/160636233?spm1011.2415.3001.5331官网地址https://docs.spring.io/spring-ai/reference/api/tools.html一、什么是 Tool CallingTool Calling工具调用早期称为 Function Calling是 AI 应用中的一种常见模式它允许大语言模型与一组外部 API 或工具进行交互从而突破模型自身的知识局限。工具主要用在两种场景中信息检索型模型无法实时获取当前日期、天气等动态信息通过工具可以从外部数据源获取实时数据弥补模型知识的不足。例如查询给定地点的当前天气。执行动作型在软件系统中执行实际操作如发送邮件、在数据库中创建新记录、提交表单、触发工作流等。⚠️重要安全认知工具调用的实际执行逻辑由客户端应用程序提供模型本身只能请求调用工具并提供输入参数永远无法真正访问工具的底层 API。这一点对于保障系统的安全性至关重要。二、工作原理四阶段流程Spring AI 的工具调用遵循以下标准流程将工具的定义名称、描述、输入参数的 JSON Schema加入聊天请求AI 模型分析用户输入自主判断是否需要调用某个工具如果模型决定调用工具它会返回一个包含工具名和输入参数的响应应用收到请求后在本地执行对应的 Java 方法将方法执行结果返回给模型模型基于工具返回的结果生成最终的自然语言回复三、快速入门动手写一个工具下面我们从一个简单的例子开始在 Spring AI 中实现并调用一个工具。3.1定义Tool返回结果类为了让大模型理解返回的字段也方便前端处理我们定义一个CourseInfo类并添加JsonPropertyDescription注解。package com.edu.tools; import com.fasterxml.jackson.annotation.JsonPropertyDescription; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; import lombok.NoArgsConstructor; Data Builder NoArgsConstructor AllArgsConstructor public class CourseInfo { JsonPropertyDescription(课程id) private Long id; JsonPropertyDescription(课程名称) private String name; JsonPropertyDescription(课程价格单位为元货币为人民币) private double price; JsonPropertyDescription(课程学习有效期单位月) private Integer validDuration; JsonPropertyDescription(适用人群例如初学者) private String usePeople; JsonPropertyDescription(课程详细介绍) private String detail; }3.1.1 JsonPropertyDescription在 Spring AI 内部的实际效果当你在Tool方法返回一个包含JsonPropertyDescription注解的类时Spring AI 在构建工具调用请求时会将该类的 JSON Schema 传递给 AI 模型。模型在解析工具返回值时这些描述信息可以帮助它理解每个字段的业务含义决定是否需要在最终回复中重新组织或转述这些字段3.1.2其他常用注解增强字段描述除了JsonPropertyDescription你还可以组合使用注解作用示例JsonProperty(access Access.READ_ONLY)标记字段只用于返回不接受模型传入自动生成的courseIdJsonFormat(pattern yyyy-MM-dd)指定日期字段的格式JsonFormat(pattern yyyy-MM-dd) private Date createDate;JsonProperty(required true)标记字段在返回时必定存在关键业务字段3.2用Tool注解定义工具package com.edu.tools; import cn.hutool.core.lang.UUID; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.stereotype.Component; import java.util.Random; Component Slf4j RequiredArgsConstructor public class CourseTools { Tool(description 根据课程名称查询课程详细信息) public CourseInfo queryCourseByName(ToolParam(description 课程名称) String courseName) { log.info(调用根据课程名称查询课程详细信息工具课程名称{}, courseName); //todo 实际从数据库查询这里直接模拟一个数据 CourseInfo courseInfo CourseInfo.builder() .id(1L) .name(courseName AI大模型应用开发 UUID.randomUUID()) .price(new Random(1000).nextDouble()) .validDuration(new Random(10).nextInt()) .usePeople(开发者) .detail(学好AI大模型应用开发月入百万) .build(); log.info(返回课程详细信息{}, courseInfo); return courseInfo; } }Tool注解提供了几个常用属性属性说明name工具名称不指定时默认为方法名。同一类中不能有同名工具description工具描述强烈建议提供详细描述这是模型理解工具用途的关键returnDirect是否直接将工具结果返回给客户端而不再经过模型处理resultConverter自定义工具调用结果的转换器ToolParam支持以下属性description参数的描述帮助模型理解参数的含义和格式要求required参数是否必需默认为true。如果参数被标注为Nullable默认会被视为可选除非明确指定requiredtrue3.3注册Tool到ChatClientAutowired private CourseTools courseTools; Override public FluxChatEventVO streamChatJson(String question, String sessionId) { // 大模型输出内容的缓存器用于在输出中断后的数据存储 var outputBuilder new StringBuilder(); return chatClient .prompt() .advisors(MessageChatMemoryAdvisor.builder(redisChatMemory) .conversationId(sessionId) .build()) .tools(courseTools) // 添加工具 .system(x-x.text(aiPromptResources.getSystemChatMessage()) .param(now, LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)))) .user(question) .stream() .chatResponse() .doFirst(() - GENERATE_STATUS.put(sessionId, true)) // 开始生成时置为 true .doOnError(throwable - GENERATE_STATUS.remove(sessionId)) .doOnComplete(() - GENERATE_STATUS.remove(sessionId)) .doOnCancel(() - { // 当输出被取消时保存输出的内容到历史记录中 redisChatMemory.add(sessionId, new AssistantMessage(outputBuilder.toString())); }) .takeWhile(response - GENERATE_STATUS.getOrDefault(sessionId, false)) // 关键控制流是否继续 .map(chatResponse - { var text chatResponse.getResult().getOutput().getText(); outputBuilder.append(text); // 累积文本 return ChatEventVO.builder() .eventType(ChatEventTypeEnum.DATA.getValue()) .eventData(text) .build(); }) .concatWith(Flux.just(ChatEventVO.builder() .eventType(ChatEventTypeEnum.STOP.getValue()) //结束标识 .build())); }3.4测试基础查询四、实现课程卡片展示4.1问题分析前端需要接收结构化的JSON数据才能渲染卡片。而大模型返回的只是自然语言文本。我们需要在流式输出的最后额外追加一段约定好的JSON数据格式如下{ eventType: 1003, eventData: { courseInfo_1589905661084430337: { id: 1589905661084430337, name: 可能是史上最全的微服务技术栈课程, price: 199.0, validDuration: 9999, usePeople: 有一定的Java开发基础..., detail: 可能是史上最全的微服务技术栈课程... } } }4.2解决方案ToolResultHolder requestId生成请求唯一标识每次对话请求生成一个requestId通过ToolContext传递给Tool。Tool执行后存储结果Tool执行完毕后将课程数据以requestId为key存放到全局容器ToolResultHolder中。流输出末尾读取并追加在Flux输出流的最后根据requestId从容器中取出数据如果存在则构造卡片事件追加到流中。4.3代码实现4.3.1. 定义ToolResultHolderpackage com.edu.holder; import java.util.HashMap; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; public class ToolResultHolder { private static final MapString, MapString, Object HANDLER_MAP new ConcurrentHashMap(); public static void put(String key, String field, Object result) { HANDLER_MAP.computeIfAbsent(key, k - new HashMap()).put(field, result); } public static MapString, Object get(String key) { return key null ? null : HANDLER_MAP.get(key); } public static void remove(String key) { HANDLER_MAP.remove(key); } }4.3.2在chatClient中传递requestId4.3.3 修改CourseTools接收ToolContext并存储结果4.3.4末尾追加卡片数据public FluxChatEventVO streamChatJson(String question, String sessionId) { // 大模型输出内容的缓存器用于在输出中断后的数据存储 var outputBuilder new StringBuilder(); // 生成唯一请求id var requestId IdUtil.fastSimpleUUID(); return chatClient .prompt() .advisors(MessageChatMemoryAdvisor.builder(redisChatMemory) .conversationId(sessionId) .build()) .tools(courseTools) // 添加工具 .toolContext(Map.of(requestId,requestId)) .system(x-x.text(aiPromptResources.getSystemChatMessage()) .param(now, LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)))) .user(question) .stream() .chatResponse() .doFirst(() - GENERATE_STATUS.put(sessionId, true)) // 开始生成时置为 true .doOnError(throwable - GENERATE_STATUS.remove(sessionId)) .doOnComplete(() - GENERATE_STATUS.remove(sessionId)) .doOnCancel(() - { // 当输出被取消时保存输出的内容到历史记录中 redisChatMemory.add(sessionId, new AssistantMessage(outputBuilder.toString())); }) .takeWhile(response - GENERATE_STATUS.getOrDefault(sessionId, false)) // 关键控制流是否继续 .map(chatResponse - { var text chatResponse.getResult().getOutput().getText(); outputBuilder.append(text); // 累积文本 return ChatEventVO.builder() .eventType(ChatEventTypeEnum.DATA.getValue()) .eventData(text) .build(); }) .concatWith(Flux.defer(() - { // 流结束后检查是否有工具结果 var map ToolResultHolder.get(requestId); if (CollUtil.isNotEmpty(map)) { ToolResultHolder.remove(requestId); // 清理 var cardEvent ChatEventVO.builder() .eventData(map) // 此处map结构为 { courseInfo_xxx: CourseInfo对象 } .eventType(ChatEventTypeEnum.PARAM.getValue()) // 约定事件类型1003 .build(); return Flux.just(cardEvent, ChatEventVO.builder() .eventType(ChatEventTypeEnum.STOP.getValue()) //结束标识 .build()); } return Flux.just(ChatEventVO.builder() .eventType(ChatEventTypeEnum.STOP.getValue()) //结束标识 .build()); })); }4.3.5测试五、Tool额外数据丢失问题修复实录课程查询和预下单功能给前端返回的数据中包含了eventType为1003的数据这个叫作额外数据给前端提供前端是不会显示到页面的正常对话是没问题的但是数据存储到Redis是没有保存进去的如下5.1问题分析数据流向回顾一次完整调用中数据流如下请求层生成requestId通过ToolContext传递给ToolTool层查询课程数据将结果存入ToolResultHolderkey为requestId输出层流结束时从ToolResultHolder.get(requestId)取出卡片数据构造eventType1003事件发送给前端存储层RedisChatMemoryRepository负责将对话消息保存到Redis问题出在第4步保存消息时只保存了UserMessage和AssistantMessage的文本内容、metadata、toolCalls等标准字段完全没有涉及ToolResultHolder中的卡片数据。5.2根本原因RedisChatMemoryRepository在序列化消息时并不知道ToolResultHolder中存了什么。它只能拿到Spring AI框架提供的Message对象而AssistantMessage中没有params字段来存放额外的结构化数据。我们需要做两件事在保存助手消息时将对应的卡片数据params也持久化到Redis在读取历史消息时能恢复这些params并返回给前端关键在于如何将ToolResultHolder中临时存储的数据绑定到具体的某条助手消息上5.3 Bug解决这个bug的解决思路就是在RedisChatMemoryRepository中保存数据时获取到ToolResultHolder中的数据将数据保存到params中即可。但是ToolResultHolder中的数据是与requestId关联的requestId是我们自己生成的在RedisChatMemory中是没有的所以这个问题的关键就是如何获取到requestId了只要有了requestId就可以获取到数据进行保存了。如何传递requestId其实同样也是可以借助于ToolResultHolder来完成我们可以把ToolResultHolder看作是一个通用的容器可以放Tool的结果也可以放其他的内容只要及时的删除即可。有了这个思路问题就好解决了解决代码如下5.3.1 映射消息id和请求idpublic FluxChatEventVO streamChatJson(String question, String sessionId) { // 大模型输出内容的缓存器用于在输出中断后的数据存储 var outputBuilder new StringBuilder(); // 生成唯一请求id var requestId IdUtil.fastSimpleUUID(); return chatClient .prompt() .advisors(MessageChatMemoryAdvisor.builder(redisChatMemory) .conversationId(sessionId) .build()) .tools(courseTools) // 添加工具 .toolContext(Map.of(requestId,requestId)) .system(x-x.text(aiPromptResources.getSystemChatMessage()) .param(now, LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)))) .user(question) .stream() .chatResponse() .doFirst(() - GENERATE_STATUS.put(sessionId, true)) // 开始生成时置为 true .doOnError(throwable - GENERATE_STATUS.remove(sessionId)) .doOnComplete(() - GENERATE_STATUS.remove(sessionId)) .doOnCancel(() - { // 当输出被取消时保存输出的内容到历史记录中 redisChatMemory.add(sessionId, new AssistantMessage(outputBuilder.toString())); }) .takeWhile(response - GENERATE_STATUS.getOrDefault(sessionId, false)) // 关键控制流是否继续 .map(chatResponse - { // 对于响应结果进行处理如果是最后一条数据就把此次消息id放到内存中 // 主要用于存储消息数据到 redis中可以根据消息di获取的请求id再通过请求id就可以获取到参数列表了 // 从而解决在历史聊天记录中没有外参数的问题 var finishReason chatResponse.getResult().getMetadata().getFinishReason(); if (StrUtil.equals(STOP, finishReason)) { var messageId chatResponse.getMetadata().getId(); ToolResultHolder.put(messageId, requestId, requestId); } var text chatResponse.getResult().getOutput().getText(); outputBuilder.append(text); // 累积文本 return ChatEventVO.builder() .eventType(ChatEventTypeEnum.DATA.getValue()) .eventData(text) .build(); }) .concatWith(Flux.defer(() - { // 流结束后检查是否有工具结果 var map ToolResultHolder.get(requestId); if (CollUtil.isNotEmpty(map)) { ToolResultHolder.remove(requestId); // 清理 var cardEvent ChatEventVO.builder() .eventData(map) // 此处map结构为 { courseInfo_xxx: CourseInfo对象 } .eventType(ChatEventTypeEnum.PARAM.getValue()) // 约定事件类型1003 .build(); return Flux.just(cardEvent, ChatEventVO.builder() .eventType(ChatEventTypeEnum.STOP.getValue()) //结束标识 .build()); } return Flux.just(ChatEventVO.builder() .eventType(ChatEventTypeEnum.STOP.getValue()) //结束标识 .build()); })); }5.3.2在MessageUtil中增加params参数的处理public static String toJson(Message message) { var myMessage BeanUtil.toBean(message, MyMessage.class); // 设置消息内容 myMessage.setTextContent(message.getText()); if (message instanceof AssistantMessage assistantMessage) { myMessage.setToolCalls(assistantMessage.getToolCalls()); // 通过 messageId 获取 requestId再通过 requestId 获取参数列表如果有就存储起来 // 最后删除 messageId 对应的数据 var messageId Convert.toStr(assistantMessage.getMetadata().get(id)); var requestId Convert.toStr(ToolResultHolder.get(messageId).get(requestId)); var params ToolResultHolder.get(requestId); if (ObjectUtil.isNotEmpty(params)) { myMessage.setParams(params); } ToolResultHolder.remove(messageId); } if (message instanceof ToolResponseMessage toolResponseMessage) { myMessage.setToolResponses(toolResponseMessage.getResponses()); } return JSONUtil.toJsonStr(myMessage); }5.3.3在反序列化Message对象时无法给AssistantMessage设置params属性所以需要继承AssistantMessage来扩展params属性package com.tianji.aigc.memory; import lombok.Getter; import lombok.Setter; import org.springframework.ai.chat.messages.AssistantMessage; import org.springframework.ai.content.Media; import java.util.List; import java.util.Map; Setter Getter public class MyAssistantMessage extends AssistantMessage { private MapString, Object params; public MyAssistantMessage(String content, MapString, Object properties, ListToolCall toolCalls, ListMedia media, MapString, Object params) { super(content, properties, toolCalls, media); this.params params; } }MessageUtil:package com.edu.memory; import cn.hutool.core.bean.BeanUtil; import cn.hutool.core.convert.Convert; import cn.hutool.core.util.ObjectUtil; import cn.hutool.json.JSONUtil; import com.edu.holder.ToolResultHolder; import org.springframework.ai.chat.messages.*; /** * 消息转换工具类提供消息对象与JSON字符串之间的转换功能主要用于Redis存储格式转换 */ public class MessageUtil { /** * 将Message对象转换为Redis存储格式的JSON字符串 * * param message 需要转换的原始消息对象 * return 符合Redis存储规范的JSON字符串 */ public static String toJson(Message message) { var myMessage BeanUtil.toBean(message, MyMessage.class); // 设置消息内容 myMessage.setTextContent(message.getText()); if (message instanceof AssistantMessage assistantMessage) { myMessage.setToolCalls(assistantMessage.getToolCalls()); // 通过 messageId 获取 requestId再通过 requestId 获取参数列表如果有就存储起来 // 最后删除 messageId 对应的数据 var messageId Convert.toStr(assistantMessage.getMetadata().get(id)); var requestId Convert.toStr(ToolResultHolder.get(messageId).get(requestId)); var params ToolResultHolder.get(requestId); if (ObjectUtil.isNotEmpty(params)) { myMessage.setParams(params); } ToolResultHolder.remove(messageId); } if (message instanceof ToolResponseMessage toolResponseMessage) { myMessage.setToolResponses(toolResponseMessage.getResponses()); } return JSONUtil.toJsonStr(myMessage); } /** * 将Redis存储的JSON字符串反序列化为对应的Message对象 * * param json Redis存储的JSON格式消息数据 * return 对应类型的Message对象 * throws RuntimeException 当无法识别的消息类型时抛出异常 */ public static Message toMessage(String json) { var myMessage JSONUtil.toBean(json, MyMessage.class); var messageType MessageType.valueOf(myMessage.getMessageType()); switch (messageType) { case SYSTEM - { //return new SystemMessage(myMessage.getTextContent()); return SystemMessage.builder() .text(myMessage.getTextContent()) .build(); } case USER - { return UserMessage.builder() .text(myMessage.getTextContent()) .metadata(myMessage.getMetadata()) .media(myMessage.getMedia()) .build(); } case ASSISTANT - { /*return AssistantMessage.builder() .content(myMessage.getTextContent()) .media(myMessage.getMedia()) .toolCalls(myMessage.getToolCalls()) .build();*/ return new MyAssistantMessage(myMessage.getTextContent(), myMessage.getMetadata(), myMessage.getToolCalls(), myMessage.getMedia(), myMessage.getParams()); } case TOOL - { return ToolResponseMessage.builder() .responses(myMessage.getToolResponses()) .metadata(myMessage.getMetadata()) .build(); } } throw new RuntimeException(Message data conversion failed.); } }5.3.4测试结果