从模型只会聊天到模型能帮你干活中间差的就是function-call这一步。Spring AI里的Tools机制正是把LLM从嘴炮选手变成行动派的关键桥梁。这篇文章我打算从最基础的用法讲起一路深入到源码层面把我自己在项目中接入Spring AI Toolsfunction-call时踩过的坑、理清的思路、总结出的最佳实践一次说清楚。不管你是刚接触Spring AI的初学者还是已经跑通Demo想优化细节的开发者这篇文章都应该能给你一些实在的参考。1. 先把共识拉齐function-call到底解决了什么问题很多人在看Spring AI文档时第一眼就被Tools这个词带偏了以为它只是给模型加点外部API调用能力。实际上function-call机制解决的是大模型天生的一个短板模型本身只会做文本生成它不具备执行动作、读取实时数据、访问外部系统的能力。1.1 模型的能力边界纯文本输入输出到底缺了什么你让GPT-4或通义千问帮你查询订单状态它会一本正经地编一个订单状态给你因为它没有查询数据库的渠道。你让它把这段文本翻译后存到文件它也只能给你翻译结果没法真正落盘。这就是纯文本生成模型的边界——它活在训练数据里活不到你的业务系统里。要让模型真正做事业界通用的解法是把动作执行权交还给代码模型只负责决定要调用哪个能力、并以结构化格式给出参数真正的执行由你的Java方法完成执行结果再回传给模型让它基于真实结果生成最终回复。这个决定调用给出参数的动作就是function-call在Spring AI中叫Tools。1.2 function-call与传统硬编码关键词匹配的本质区别可能有人会说这跟以前做聊天机器人时用关键词匹配、意图识别有啥区别区别非常大。传统做法是你在代码里写死当用户提到天气时调用天气API模型没有决策权所有路由逻辑都要人工维护。而function-call机制把理解用户意图并匹配合适工具这件事交给了模型本身。举个例子用户说上海明天适合穿短袖吗传统意图识别需要你预先维护天气穿衣建议这种复合意图规则而function-call机制下模型会自动识别出需要调用天气查询工具传入参数上海、明天拿到天气数据后再结合自身知识判断适不适合穿短袖。决策的泛化能力从规则库转移到了模型能力上这意味着你只需要注册工具不需要维护任何意图规则。1.3 Spring AI在这一环做了什么Spring AI做的不是从零发明function-call协议而是把这些能力抽象成了一组Java友好的API屏蔽了底层不同模型厂商OpenAI、通义、智谱等在function-call协议上的差异。你只需要在Spring Bean方法上标注注解框架自动帮你做工具描述生成、参数JSON Schema构建、模型请求封装和响应解析。对Java开发者来说这是最佳的接入姿势不需要手写Protocol Buffers描述文件不需要关心模型API里tools字段的格式细节更不需要自己维护对话上下文里的工具调用中间状态。Spring AI把这些都封装成了ToolCallback体系这也是后面我们看源码时的主线。2. 快速跑通在Spring AI里注册第一个Tool光讲概念没有用我们直接上手。如果你已经有一个Spring Boot 3.x项目引入Spring AI之后最快一分钟就能注册出第一个可用工具。2.1 工程准备与版本选择我建议当前阶段直接使用Spring AI 1.0.0及以上版本早期0.8.x版本的API在Tools这块变化较大网上很多教程用的还是0.8.x的快照版本照着抄很容易踩坑。以Maven为例核心依赖就两个dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId version1.0.0/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-tool/artifactId version1.0.0/version /dependency如果你用的是阿里云的通义千问或者Spring AI Alibaba把starter换成spring-ai-starter-model-tongyi或走spring-ai-alibaba的依赖管理Tools相关的核心API是通用的。这里我强烈建议不要直接用OpenAI官方key做试验国内模型厂商智谱、通义、DeepSeek都兼容OpenAI协议Spring AI也提供了对应的starter选一个网络链路稳定的就好。2.2 最简单形态Tool注解自动注册Spring AI最人性化的地方在于你只需要写一个普通的Spring组件并在方法上标注Tool注解剩下的交给框架Component public class WeatherTools { Tool(description 查询指定城市当前天气) public String getCurrentWeather(String city) { // 这里实际可以调用外部APIDemo里先返回写死数据 return city 晴25摄氏度微风; } }然后在构建ChatClient时把该Bean传进去ChatClient chatClient ChatClient.builder(chatModel) .defaultTools(new WeatherTools()) .build(); String response chatClient.prompt(北京天气怎么样) .call() .content();跑起来之后模型的调用链是它识别出用户想查天气→触发getCurrentWeather(北京)方法→拿到返回值北京晴25摄氏度微风→把这段结果包装成消息再发给模型→模型基于真实数据生成北京今天晴气温25度风力不大这样的最终回复。2.3 带复杂参数和返回值的工具实际业务里不可能只有String入参。Spring AI的Tool方法支持POJO参数并会自动生成JSON Schema描述。比如我们要实现一个查询订单状态的工具Component public class OrderTools { Tool(description 根据订单号查询订单当前状态与物流信息) public OrderInfo getOrderInfo(OrderQueryParam param) { return orderService.query(param.orderId()); } record OrderQueryParam(String orderId, String customerPhone) {} record OrderInfo(String orderId, String status, String logisticsCompany, String trackingNo) {} }这里有个很重要的点参数对象和返回值对象的字段名、层级结构都会直接影响模型能否正确生成参数。如果参数名称是orderId模型在看到用户说订单号12345时大概率会往orderId字段填但如果你的字段叫id、phone这类泛化名称模型就可能犹豫甚至填错。所以要给POJO字段起语义清晰的名字必要时用JsonProperty(description ...)补充说明相当于手把手教模型如何填参。2.4 多工具并存模型如何做路由选择当你注册了多个工具时模型会根据用户意图在多个工具之间做选择。Spring AI会把所有工具的描述、参数信息拼进系统提示词让模型知道有哪些工具可用。比如你同时注册了天气查询、订单查询、计算器三个工具用户说算一下明天北京和上海的温度差模型会先两次调用天气查询工具北京、上海再调用计算器工具算出差值最后汇总输出。不过这里要泼一盆冷水工具越多模型选错工具的概率就越高尤其是两个工具功能相似时。我做过的项目里同时挂了查订单和查物流两个工具模型经常混用。后来把两个工具合并成一个getOrderFullInfo描述里写清楚包含物流信息反而效果更稳定。工具设计上要遵循少而精语义边界清晰的原则而不是多多益善。3. 核心机制拆解模型与代码之间到底是怎么握手的跑通Demo只是第一步。如果不知道底层调用链后面碰到模型不调用工具、参数解析报错这些问题时你会一头雾水。我来完整拆一下一次带工具调用的请求要经历哪些环节。3.1 一次完整调用的内部时序整个流程可以分成三个阶段第一阶段工具描述注入。Spring AI扫描所有注册的ToolCallback将工具名称、描述、参数JSON Schema整理成模型协议文档要求的格式OpenAI格式/通义格式填入请求消息中。第二阶段模型决策与响应。模型读取当前用户消息以及可用工具列表输出两种结果之一要么直接生成文本回复要么生成一个工具调用请求包含工具名称和由JSON构成的参数。第三阶段执行与回填。Spring AI解析模型返回的ToolCall请求通过反射或直接调用注册的Java方法拿到执行结果后把结果作为一条tool角色消息追加到对话历史中再次发送给模型。模型基于工具返回的真实数据处理后给出最终自然语言回复。如果模型觉得需要多次调用才能完成任务比如上面说的温度差计算第三阶段的执行→回填→再请求会递归循环多次直到模型认为信息足够了、生成纯文本回复为止。3.2 工具描述是如何进入Prompt的这是function-call最容易被忽视、但影响最大的细节工具描述占用的token量是实打实的成本也是影响模型决策的重要因素。Spring AI在向模型发送请求时会在messages之外单独携带一个tools字段这个字段的内容结构大致如下[ { type: function, function: { name: getCurrentWeather, description: 查询指定城市当前天气, parameters: { type: object, properties: { city: {type: string} }, required: [city] } } } ]模型在生成回复时会同时参考用户消息和这个tools字段注各家模型对tools字段在上下文中的权重处理不同但语义上都遵循同一协议。所以工具描述写得越精确模型越容易做出正确的调用决策。描述里不要写废话比如这是一个很好用的天气查询工具这种内容纯粹浪费token要写查询指定城市当前天气输入城市名返回温度、天气现象、风力这种能帮助模型判断何时用、怎么用的信息。3.3 响应解析与循环终止条件模型返回的tool调用响应中每个调用都有一个id、name和arguments字段。Spring AI底层通过ToolCallingManager的resolveToolCall方法把arguments的JSON字符串反序列化成Java对象再通过反射匹配到对应方法并invoke。循环终止条件也很有意思模型只要还在tool调用模式里就会一直返回tool调用请求直到它认为Hmm我现在手里信息够了该写总结了。问题在于如果工具返回的数据始终不满足模型的判断预期它就可能反复调用同一个工具形成死循环。这是后面实战踩坑部分我要重点讲的。4. 源码视角Spring AI Tools模块的核心类与扩展点深入到源码层面Spring AI把Tools体系抽象得比较干净。理解清楚下面这几个核心接口和类你就掌握了这个模块的骨架。4.1 ToolCallingManager总调度入口ToolCallingManager是整个工具调用的核心门面。它的主要任务是接收模型的响应内容解析出其中的ToolCall列表逐个执行并返回结果列表。核心接口方法简化后大致长这样public interface ToolCallingManager { ToolCallingResponse resolveToolCalling(ToolCallingRequest request); }ToolCallingRequest里封装了对话消息列表和可用的ToolCallback列表ToolCallingResponse则封装了执行后需要追加回对话的记录。在Spring AI的默认实现里这部分逻辑会遍历模型返回的消息过滤出类型为ToolCall的消息交给ToolCallback执行。4.2 ToolCallback工具的运行时抽象所有工具最终都被统一包装成ToolCallback接口它有四个核心方法getToolName()工具名称getDescription()工具描述getToolDefinition()返回协议要求的工具定义内部包含name、description、parametersJSON Schemacall(String toolInput)执行工具入参是模型返回的参数JSON字符串返回执行结果字符串Spring AI提供了MethodToolCallback这个实现类它的作用就是把一个Java方法适配成ToolCallback。Tool注解就是通过MethodToolCallback的构建器builder().method(...)来桥接的。这里的反射调用发生在ToolCallingManager执行阶段参数绑定由ToolInputTypeResolver负责它会根据模型返回的JSON字符串和目标方法的参数类型做反序列化。看源码你会发现Spring AI对参数解析用了两层逻辑如果目标方法只有一个参数且该参数类型不是String就尝试把整个JSON反序列化成该类型如果方法有多个参数则会按参数名去JSON里匹配。这就是为什么我之前强调参数名要语义化——orderId这种名字能被自动绑定a、b这种名字就只能靠运气了。4.3 自定义ToolCallback接管参数解析的进阶姿势绝大多数场景用Tool注解就够了但如果你想精确控制参数的JSON Schema生成、想为同一个方法注册多个不同的工具描述、或者想彻底绕开反射用更快的路径执行可以手动实现ToolCallbackpublic class CustomCalculatorTool implements ToolCallback { Override public String getToolName() { return calculator; } Override public String getDescription() { return 执行四则运算输入格式{\expression\:\12\}; } Override public String getToolDefinition() { return { type: function, function: { name: calculator, description: 执行四则运算输入格式{expression:12}, parameters: { type: object, properties: { expression: {type: string} }, required: [expression] } } } ; } Override public String call(String toolInput) { // 此处省略JSON解析和运算逻辑 return 3; } }然后把自定义实现类作为Bean注册通过ChatClient.builder().defaultTools(new CustomCalculatorTool())接入。这种写法的好处是你可以精确控制getToolDefinition返回的内容——比如把工具的parameters字段从object改成string适配那些JSON Schema兼容性不佳的国产模型。4.4 Observer机制全链路可观测工具调用出问题时最难受的是不知道模型到底返回了什么原始内容。Spring AI提供了ToolCallingManager的观察者机制ToolCallingObserver你可以实现它来拿到每次工具调用的完整请求和响应ToolCallingManager.builder() .observers(List.of(new ToolCallingObserver() { Override public void onToolCallStart(ToolCallingRequest request) { log.info(开始执行工具调用{}, request); } Override public void onToolCallEnd(ToolCallingResponse response) { log.info(工具调用结束返回结果{}, response); } Override public void onToolCallError(ToolCallingException exception) { log.error(工具调用异常, exception); } })) .build();这个Observer在生产环境排查问题时价值极大。尤其是模型返回了你的Java方法根本无法解析的畸形JSON时你才能在原始日志里看到问题全貌而不是只看到一个JsonParseException。5. 实战踩坑记录我在接入过程中遇到的高频问题与排查链路这部分是干货密集区。以下问题全部来自我实际开发中遇到的场景每个我都给出了排查思路和最终解法希望能让你少走弯路。5.1 模型死活不调用工具先看工具描述和参数Schema现象用户明确说了帮我查天气但模型就是不触发工具调用而是直接编了一个答案。排查过程这类问题我一般的排查顺序是——先开Debug日志查看实际发给模型的请求中tools字段是否存在。这里有个容易被忽略的点Spring AI的ChatClient里如果defaultTools没有正确传入工具是不会注册进请求的。特别是当你用了chatModel直连而不是ChatClient时容易漏传。再检查工具描述质量。我遇到过描述写得过于模糊天气相关导致模型无法判断该在什么条件下使用。改成查询指定城市的实时天气情况入参为城市中文名称返回温度、天气现象、湿度后模型立刻就能正确触发了。最后检查参数Schema。有些模型对复杂嵌套的JSON Schema支持不好如果POJO里套了多层内部类模型可能生成不了合法参数就直接放弃调用。这种情况可以给工具换一个简单的参数类型或者用手写getToolDefinition的方式简化Schema。核心结论模型不调用工具80%以上是工具描述和参数Schema写得不够清晰而不是模型不行。先把描述写得像给同事的需求文档一样明确再考虑模型兼容性问题。5.2 工具循环调用模型钻进了死胡同现象用户问帮我对比一下北京和上海的温度模型不断调用天气工具十几次每次都只传一个城市名始终没有进入总结阶段最终token耗尽报错。排查过程我最初以为是没有设置循环限制后来发现核心原因是工具返回的结果里缺少模型判断任务是否完成的关键信息。我的天气工具只返回了晴25度模型总觉得数据不够。给工具返回值补充了数据查询时间、数据来源、该数据已包含温度/湿度/风力/降水概率等说明信息后模型很快就生成了对比结论。另一个有效做法是在ChatClient上设置最大工具调用次数限制ChatClient.builder(chatModel) .defaultTools(weatherTools) .defaultToolCallbacksResolvers(...) .build();不过更通用的是在应用层自己做次数控制用一个计数器记录本轮对话中工具调用的总次数超过阈值比如5次后强制终止循环并向模型注入一条已执行足够多次工具调用请基于现有信息回答的消息。这个兜底逻辑能有效避免生产环境烧钱。5.3 复杂参数反序列化失败模型生成了你方法不认识的JSON现象工具方法接收一个包含嵌套对象的POJO日志里报了JsonParseException或类型转换错误。排查过程看过原始请求后我发现问题出在模型给出的arguments里嵌套对象的字段名跟我定义的不一样。比如我定义的字段是phoneNumber模型给我填了phone。这说明模型的参数生成具有天然的灵活性它在尽力理解字段语义而不是死板照搬。解法给POJO字段加JsonProperty别名提示把可能出现的多种叫法都映射到同一个字段public record OrderQueryParam( JsonProperty(order_id) String orderId, JsonProperty(orderId) String orderIdAlias, JsonProperty(customerPhone) String customerPhone ) {}但这种做法维护成本高。更稳妥的方案是把工具方法入参设计成扁平化、语义简单的结构尽量用String和基本类型避免多层嵌套对象。如果业务上确实需要复杂结构就在Tool的description里把参数JSON的示例格式写清楚手把手教模型怎么填。5.4 Spring AI Alibaba生态整合时的小坑用Spring AI Alibaba的朋友要注意几个细节。第一不同AI厂商对tool调用的响应格式有个别差异Spring AI虽然做了兼容层但某些厂商的模型在parallel_tool_calls并行工具调用场景下会有兼容问题表现为连续调用多个工具时后面的工具参数解析失败。遇到这种情况可以在模型配置里关闭并行工具调用强制模型一次只调用一个工具spring: ai: tongyi: chat: options: parallel-tool-calls: false第二如果你在一个Spring Boot项目里同时引入了多个模型供应商的starterSpring AI的自动配置会创建多个ChatModelBean这时ChatClient.Builder需要显式指定用哪个模型ChatClient.builder(tongYiChatModel) .defaultTools(weatherTools) .build();这个坑早期版本几乎必踩报错信息还不直观建议从构建时就通过构造器把具体的ChatModel传进去不要依赖隐式注入。5.5 Token成本控制工具越多吃token越猛我们来粗略算一笔账一个工具的描述加参数Schema平均要消耗200~400个token如果你注册了10个工具固定成本就是2000~4000个token。每次对话即使不走工具调用这些token都要随请求发到模型侧。按用户量放大后这是一笔不小的开支。我现在的实践是把工具注册和实际会话解耦根据用户当前会话的主题动态决定启用哪些工具。比如用户进入的是订单咨询会话就只注册订单相关的3个工具而不是一股脑注册全部20个。Spring AI的ChatClient提供了动态工具配置的方式可以在每次请求时重新指定tools列表。这个改动的成本节省非常明显尤其是在工具数量超过10个的场景下。6. 最后的落地建议如果你只是想让项目里的大模型会调用接口干活用Tool注解就够了如果你想把工具调用做得稳定可控、能插桩排查、能动态启停建议直接深入ToolCallback这一层把Spring AI的Tools机制当成一个可扩展的框架来用而不是当成一个黑盒。我在实际项目中最后沉淀下来的用法是核心业务工具用Tool注解快速注册涉及复杂参数或需要精细控制Schema的工具用手写ToolCallback再通过ToolCallingObserver把每次工具调用的请求和响应落到日志里。这样既能保证开发效率又能在线上问题出现时快速定位到底是模型决策错了、参数解析错了、还是执行业务方法出错了。还有一个小提醒——function-call看起来是模型调用工具本质上依然是概率生成行为模型不会100%按你的预期执行。所以在关键业务链路上工具执行结果一定要做二次校验不要盲目相信模型的参数生成能力也不要让工具执行链上的异常静默吞掉。这个思维转变比学会任何API都重要。
