Spring AI 2.0的Tool Calling功能详解与应用实践

1. Spring AI 2.0的Tool/Function Calling核心概念在AI应用开发中Tool Calling也称为Function Calling是一种常见模式它允许AI模型与一组API或工具进行交互。Spring AI 2.0对这一功能进行了全面升级提供了更强大、更灵活的集成方式。1.1 什么是Tool CallingTool Calling本质上是一种让AI模型能够调用外部功能的机制。想象一下你有一个非常聪明的助手但它只能回答问题而不能实际操作任何工具。Tool Calling就像是给这个助手配了一整套工具箱让它不仅能告诉你如何钉钉子还能实际拿起锤子帮你把钉子钉好。在Spring AI中Tool Calling通过ToolCallback接口实现主要包含三个核心部分工具定义ToolDefinition告诉模型这个工具是什么、能做什么工具元数据ToolMetadata定义工具的行为方式工具执行逻辑实际执行工具调用的代码1.2 方法型工具与函数型工具Spring AI支持两种主要的工具定义方式方法型工具Method Tools通过Java方法定义工具适合传统的面向对象编程风格。例如class DateTimeTools { Tool(description 获取当前日期时间) static String getCurrentDateTime() { return LocalDateTime.now().toString(); } }函数型工具Function Tools通过函数式接口定义工具更符合现代Java编程趋势。例如public class WeatherService implements FunctionWeatherRequest, WeatherResponse { public WeatherResponse apply(WeatherRequest request) { // 调用天气API获取数据 return new WeatherResponse(25.0, C); } }这两种方式各有优势方法型工具更适合与现有Spring Bean集成而函数型工具则更灵活适合简单的单一功能场景。2. 工具定义与配置详解2.1 工具元数据配置每个工具都可以通过ToolMetadata进行精细控制其中最重要的两个配置是returnDirect是否直接将工具结果返回给客户端而不是送回AI模型处理resultConverter如何将工具返回的对象转换为字符串ToolMetadata metadata ToolMetadata.builder() .returnDirect(true) .resultConverter(new CustomResultConverter()) .build();2.2 参数定义与JSON SchemaSpring AI会自动为工具参数生成JSON Schema但我们可以通过注解进行定制class AlarmService { Tool(description 设置闹钟) void setAlarm( ToolParam(description ISO-8601格式时间, required true) String time, ToolParam(description 闹钟名称, required false) String name ) { // 实现逻辑 } }支持的参数注解包括ToolParamSpring AI原生注解SchemaSwagger注解JsonPropertyJackson注解2.3 工具注册方式Spring AI提供了多种工具注册方式适应不同场景单次请求工具ChatClient.create(chatModel) .prompt(明天天气如何) .tools(weatherTool) .call();默认工具全局可用ChatClient.builder(chatModel) .defaultTools(weatherTool, dateTool) .build();Spring Bean工具Configuration class ToolConfig { Bean ToolCallback weatherTool() { return FunctionToolCallback.builder(...).build(); } }3. 高级特性与实战技巧3.1 工具上下文ToolContext有时工具执行需要额外的上下文信息而这些信息不适合作为工具参数暴露给AI模型。这时可以使用ToolContextclass CustomerService { Tool Customer getCustomer(Long id, ToolContext context) { String tenantId (String) context.get(tenantId); // 根据租户ID获取客户 } } // 使用方式 ChatClient.create(chatModel) .prompt(获取ID为42的客户信息) .tools(customerTool) .toolContext(Map.of(tenantId, acme)) .call();3.2 结果直接返回Return Direct某些工具的结果可能不需要AI模型进一步处理可以直接返回给客户端Tool(description 获取原始数据, returnDirect true) String getRawData(String query) { // 返回未经处理的原始数据 }这在构建RAG检索增强生成应用时特别有用可以避免不必要的模型后处理。3.3 工具执行生命周期管理Spring AI支持三种工具执行管理模式框架控制推荐通过ChatClient自动管理// 最简单的使用方式 String result ChatClient.create(chatModel) .tools(myTools) .prompt(问题) .call() .content();顾问控制通过ToolCallingAdvisor精细控制ToolCallingAdvisor advisor ToolCallingAdvisor.builder() .toolCallingManager(toolCallingManager) .build(); ChatClient.builder(chatModel) .defaultAdvisors(advisor) .build();用户完全控制手动处理每个工具调用ChatResponse response chatModel.call(prompt); while (response.hasToolCalls()) { // 手动执行工具 response chatModel.call(newPrompt); }3.4 工具组合与依赖管理在实际项目中工具之间可能存在依赖关系。Spring AI允许通过DependsOn注解管理工具加载顺序Configuration class ToolConfig { Bean DependsOn(databaseInitializer) ToolCallback customerTool() { // 确保数据库初始化后再加载此工具 } }4. 性能优化与最佳实践4.1 工具预热与缓存对于耗时工具可以考虑实现预热机制PostConstruct public void warmUpTools() { // 预先加载常用工具 }4.2 工具权限控制通过自定义ToolExecutionEligibilityChecker实现权限控制ToolCallingAdvisor.builder() .toolExecutionEligibilityChecker(response - { // 检查用户权限 return hasPermission; }) .build();4.3 监控与日志添加工具调用监控Aspect Component class ToolMonitoringAspect { Around(execution(* org.springframework.ai.tool..*.*(..))) public Object monitorTool(ProceedingJoinPoint pjp) throws Throwable { long start System.currentTimeMillis(); try { return pjp.proceed(); } finally { long duration System.currentTimeMillis() - start; // 记录监控数据 } } }5. 常见问题排查5.1 工具未被调用检查清单工具描述是否清晰明确工具名称是否唯一JSON Schema是否正确生成工具是否已正确注册5.2 参数类型不匹配典型错误Tool void processData(MapString, Object data) { // 复杂Map结构可能导致schema生成问题 }解决方案使用明确的DTO类代替Map或自定义JSON Schema5.3 性能问题优化建议为耗时工具添加Async支持实现批处理工具接口考虑工具结果的缓存策略6. 实战案例构建天气预报助手让我们通过一个完整示例展示如何构建一个实用的天气查询工具6.1 定义天气DTOpublic record WeatherRequest(String location, Unit unit) {} public record WeatherResponse(double temperature, Unit unit, String condition) {} public enum Unit { C, F }6.2 实现天气工具Component public class WeatherService { Tool(name getCurrentWeather, description 获取指定地点的当前天气需要location和unit(C/F)参数) public WeatherResponse getWeather( ToolParam(description 城市名称) String location, ToolParam(description 温度单位) Unit unit) { // 实际调用天气API return new WeatherResponse(22.5, unit, Sunny); } }6.3 配置ChatClientBean public ChatClient chatClient(ChatModel chatModel, WeatherService weatherService) { return ChatClient.builder(chatModel) .defaultTools(MethodToolCallback.from(weatherService)) .build(); }6.4 使用示例String result chatClient.prompt() .user(今天北京天气如何用摄氏度表示) .call() .content();这个简单的工具现在可以无缝集成到你的AI应用中让模型能够查询实时天气信息。