Function Calling 这个词这两年在 AI 应用开发圈子里出现的频率越来越高，但真正动手把它跑通、跑稳的人其实没想象中那么多。我最初接触它的时候，脑子里想的是“不就是让大模型调个接口吗”，结果真上手才发现，从模型返回的 JSON 结构解析、参数校验、异常兜底，到多轮对话里上下文怎么维护，每一步都有坑。Spring AI 这套框架把很多脏活累活封装掉了，但封装得越深，出问题时越难排查，所以“吃透”比“会用”重要得多。
这篇内容面向的是有 Java 和 Spring Boot 基础、想在自己的项目里落地 Function Calling 的开发者。我会从最基础的概念讲起，一路走到一个能跑通的完整实战案例，中间穿插我自己踩过的坑和排查思路。读完之后你应该能独立完成一个“模型理解用户意图、自动调用后端 Java 方法、再把结果组织成自然语言返回”的闭环。关键词涉及 Function Calling、Spring AI、Spring Boot、Java、MySQL，这些都会在实战里真实出现，不是摆设。
1. 先把 Function Calling 这件事的本质想清楚
1.1 它到底解决了什么问题
很多人第一次听到 Function Calling，会误以为是大模型自己去执行代码。不是的。大模型从头到尾只做一件事：根据你的描述和用户的输入，判断“现在该不该调用某个工具”，如果要调用，就输出一个结构化的调用请求。真正执行这个工具的，永远是你自己的后端代码。
举个生活化的类比。你是一个公司的前台，用户打电话进来问“帮我查一下上个月的报销到账没有”。前台（大模型）本身查不了财务系统，但它知道“查报销”这件事应该找财务部（你的 Java 方法）。于是前台把用户的诉求整理成一张工单，写上“查询报销，员工张三，月份上月”，然后转给财务部。财务部查完把结果告诉前台，前台再用自然语言回复用户。
这个“整理成工单”的动作，就是 Function Calling 的核心。它把自然语言的模糊意图，转成了程序能精确处理的参数结构。没有它，你只能靠正则或者关键词匹配去猜用户想干嘛，稍微复杂一点就崩。
1.2 为什么是 Spring AI 而不是自己拼 HTTP
理论上你完全可以自己调模型的 HTTP 接口，手动拼 tools 参数、手动解析返回的 function call 字段。我早期就这么干过，代码大概长这样：构造一个巨大的 JSON，里面塞工具定义，发请求，拿到响应后判断 finish_reason 是不是 tool_calls，再手动反序列化。能跑，但问题很明显。
第一，不同模型厂商的工具定义格式不完全一样，OpenAI 一套、通义一套、其他家又一套，你要写适配层。第二，多轮对话里工具调用结果怎么回填、消息历史怎么组织，这些逻辑每次都要重写。第三，Spring 生态里你本来就有依赖注入、有 Bean 管理，工具方法天然就是一个个 Service，自己拼 HTTP 等于把这些优势全扔了。
Spring AI 的价值在于它把这些统一了。你只需要用@Tool注解标记一个方法，框架自动帮你生成工具描述、处理调用请求、把结果回填到对话上下文。切换模型时，大部分代码不用动。这就是“站在框架肩膀上”的意义。
1.3 一次完整的调用链路长什么样
在动手写代码前，脑子里要有一张清晰的流程图。虽然这里不能用图表，但我用文字把链路拆开：
用户发消息 → Spring AI 把消息和所有已注册的工具描述一起发给模型 → 模型判断需要调用工具，返回工具名和参数 → Spring AI 解析出工具名，找到对应的 Java 方法 → 通过反射调用该方法，传入参数 → 方法执行（可能查数据库、调外部接口）→ 返回结果 → Spring AI 把结果作为一条特殊消息追加到对话历史 → 再次发给模型 → 模型基于工具返回的数据生成自然语言回复 → 返回给用户。
注意这里有个关键点：模型可能被调用两次。第一次是为了决定调不调工具，第二次是拿到工具结果后生成最终回复。这个“两次调用”是很多新手困惑的地方，也是 token 消耗比预期高的原因。理解这一点，后面做成本优化时才有方向。
2. 环境搭建里那些文档不会告诉你的细节
2.1 版本选择：别一上来就追最新
Spring AI 的版本迭代速度相当快，1.0 之前 API 变动频繁，很多网上搜到的教程用的是老版本，你照着抄会发现类名都对不上。我的建议是：先确定你用的 Spring Boot 版本，再选对应的 Spring AI 版本。
截至我写这篇内容时，比较稳的组合是 Spring Boot 3.2.x 或 3.3.x 搭配 Spring AI 1.0.x 的正式版。如果你用的是 Spring Boot 3.4 以上，注意有些 starter 的坐标变了。用 Maven 的话，核心依赖大概是这样：
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency>这里有个坑要提醒：早期版本 artifactId 是spring-ai-openai-spring-boot-starter，后来改成了spring-ai-starter-model-openai。如果你从旧教程复制依赖，编译报“找不到 artifact”，八成就是这个原因。另外 Spring AI 的正式版依赖已经进了 Maven 中央仓库，但如果你用的是里程碑版本，需要在 pom 里额外配置 milestone 仓库，否则下载不下来。
2.2 配置文件里的几个关键项
application.yml 里至少要配三样东西：API 地址、API Key、模型名称。
spring: ai: openai: base-url: https://your-api-endpoint/v1 api-key: ${AI_API_KEY} chat: options: model: your-model-name temperature: 0.7base-url这一项很多人会忽略。如果你用的是兼容 OpenAI 协议的服务，地址一定要带对路径，通常结尾是/v1。少了这个后缀，请求会 404，而且报错信息不一定直观，可能只告诉你“连接失败”，让你以为是网络问题。
API Key 千万别硬编码在 yml 里然后提交到代码仓库。用环境变量${AI_API_KEY}引用，本地开发时在 IDE 的运行配置里设置环境变量。这个习惯看着小，但真出过事的人都知道疼。
temperature在 Function Calling 场景下建议调低一点，0.1 到 0.3 之间比较合适。因为工具调用需要的是“准确判断意图”，不是“发挥创造力”。温度太高，模型可能该调工具的时候不调，或者参数填得离谱。
2.3 依赖注入的坑：ChatClient 和 ChatModel 的区别
Spring AI 里有两个容易混淆的类：ChatModel和ChatClient。ChatModel是底层接口，直接调它你要自己处理消息列表；ChatClient是上层封装，提供了流式 API，写起来更顺手。
我的经验是：做 Function Calling，优先用 ChatClient。它对新手的友好度更高，链式调用清晰，而且对工具注册的支持更自然。注入方式：
@Service public class AiService { private final ChatClient chatClient; public AiService(ChatClient.Builder builder) { this.chatClient = builder.build(); } }注意这里注入的是ChatClient.Builder而不是ChatClient本身。Builder 是原型作用域的，每次注入都是新实例，这样你可以针对不同的场景构建不同的 Client（比如一个带工具、一个不带）。如果你直接注入 ChatClient，可能会遇到工具注册不生效的问题，因为单例的 Client 在构建时就固定了配置。
3. 用 @Tool 注解把 Java 方法变成模型能调用的工具
3.1 一个最小可用的工具方法
假设我们要做一个“查询订单状态”的功能。先定义一个普通的 Service：
@Service public class OrderService { @Tool(description = "根据订单号查询订单的当前状态，返回状态描述和预计送达时间") public String queryOrderStatus( @ToolParam(description = "订单号，通常是10位数字") String orderId) { // 实际业务里这里查数据库 if ("1234567890".equals(orderId)) { return "订单已发货，预计明天下午送达"; } return "未找到该订单"; } }就这么简单。@Tool的 description 是给模型看的，模型靠这段文字判断“什么时候该调用这个方法”。所以 description 写得好不好，直接决定调用准确率。
我见过有人把 description 写成“查询订单”，结果模型在用户问“我的快递到哪了”的时候不调用，因为“快递”和“订单”在语义上模型没关联起来。改成“根据订单号查询订单状态和物流信息”之后，命中率明显提升。description 要覆盖用户可能用的各种说法，这是经验之谈。
@ToolParam的 description 同样重要，它告诉模型这个参数是什么、什么格式。如果参数格式有要求（比如必须是数字、必须是特定前缀），一定要写清楚，否则模型可能传个“我的订单”这种自然语言进来，你的方法直接抛异常。
3.2 工具方法的返回值怎么设计
返回值的设计有个原则：返回给模型的内容要“可读且信息完整”，但不要塞太多无关数据。
我一开始图省事，直接把数据库查出来的整个实体对象toString()返回，结果里面几十个字段，模型被淹没了，生成的回复又长又乱。后来改成只返回关键字段的简短描述，回复质量立刻上来了。
另一个坑是返回 null。如果方法返回 null，某些版本的 Spring AI 处理时会有问题，模型收到的工具结果为空，可能反复调用同一个工具。所以永远返回一个非空的字符串，查不到就返回“未找到相关记录”，别返回 null。
如果工具执行过程中抛异常，Spring AI 默认会把异常信息传给模型。这有好有坏：好处是模型知道出错了，可以告诉用户；坏处是异常堆栈可能包含敏感信息。建议在工具方法内部自己 try-catch，把异常转成友好的提示文字返回。
3.3 把工具注册到 ChatClient
定义好工具方法后，要显式注册：
this.chatClient = builder .defaultTools(orderService) .build();defaultTools接收的是包含@Tool方法的对象。Spring AI 会扫描这个对象里所有带注解的方法，生成工具定义。
这里有个容易踩的坑：如果你注册的对象是通过代理增强过的（比如加了事务注解 @Transactional），@Tool 注解可能扫描不到。因为 Spring 的 AOP 代理会生成一个子类，注解在父类方法上，某些扫描逻辑会漏掉。解决办法是把工具方法单独抽到一个没有事务代理的类里，或者用接口方式暴露。这个问题排查起来很费劲，因为不报错，只是工具静默地不生效，模型永远说“我无法查询”。
4. 多轮对话与上下文管理：Function Calling 最容易翻车的地方
4.1 为什么单轮能跑通，多轮就乱套
单轮对话很简单：用户问一句，模型调工具，返回结果，结束。但真实场景往往是多轮的。用户先问“帮我查订单 1234567890”，模型调用工具返回“已发货”，用户接着问“那大概几点到”，这时候模型需要知道“那”指的是刚才那个订单。
如果你每轮都新建一个 ChatClient 调用，历史消息全丢了，模型根本不知道“那”是什么。所以必须维护对话上下文。
Spring AI 提供了ChatMemory接口，常用的实现是MessageWindowChatMemory，它保留最近 N 条消息。配置方式：
@Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.builder() .maxMessages(20) .build(); }然后在构建 ChatClient 时挂上：
this.chatClient = builder .defaultTools(orderService) .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()) .build();4.2 窗口大小设多少合适
maxMessages这个值不是越大越好。设太大，每次请求携带的历史消息多，token 消耗高、响应慢；设太小，模型记不住上下文。
我的经验值是 10 到 20 条。但要注意，工具调用的请求和结果也算消息。一次工具调用至少产生两条消息（模型的调用请求 + 工具的执行结果），所以如果你设 20，实际能记住的用户对话轮次可能只有五六轮。
还有个细节：窗口是按“消息条数”截断的，不是按“对话轮次”。如果某一轮里工具调用特别多，可能一下子就把窗口占满了，导致更早的对话被挤出去。做长对话应用时，这个要特别注意，必要时得自己实现更智能的记忆策略，比如按 token 数截断，或者对历史做摘要压缩。
4.3 会话隔离：多用户场景下的必答题
上面那个 ChatMemory 是单例 Bean，意味着所有用户共享同一份记忆。本地测试没问题，一上线就出大事：A 用户问的订单，B 用户接着问“那个订单到哪了”，模型会把 A 的订单信息告诉 B。这是严重的数据泄露。
正确做法是按会话 ID 隔离。Spring AI 的 Advisor 支持传入 conversationId：
chatClient.prompt() .user(message) .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId)) .call() .content();sessionId 可以从用户登录态里取，或者前端生成一个 UUID 传过来。每个 sessionId 对应一份独立的记忆。这个点我在项目里踩过，测试阶段两个人同时用，发现对话串了，排查了半天才定位到是记忆没隔离。
5. 一个完整的实战案例：智能订单助手
5.1 需求拆解与技术选型
我们来做一个稍微完整点的东西：一个智能订单助手，用户可以用自然语言查询订单、查询物流、申请退款。数据存在 MySQL 里，通过 Spring Boot 提供接口，Spring AI 负责理解意图和调用工具。
技术栈：Spring Boot 3.3.x + Spring AI 1.0.x + MySQL 8 + MyBatis-Plus（或者 Spring Data JPA，看个人习惯）。我选 MyBatis-Plus，因为国内项目用得多，写起来快。
数据库表设计简单点，一张订单表：
CREATE TABLE `orders` ( `id` BIGINT PRIMARY KEY AUTO_INCREMENT, `order_no` VARCHAR(32) NOT NULL UNIQUE, `user_id` BIGINT NOT NULL, `status` TINYINT NOT NULL COMMENT '1待付款 2已付款 3已发货 4已完成 5已退款', `amount` DECIMAL(10,2) NOT NULL, `create_time` DATETIME NOT NULL, `update_time` DATETIME NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;5.2 工具方法的具体实现
订单查询工具：
@Service public class OrderToolService { @Autowired private OrderMapper orderMapper; @Tool(description = "根据订单号查询订单详情，包括状态、金额和下单时间") public String queryOrder( @ToolParam(description = "订单号，32位以内的字符串") String orderNo) { try { Order order = orderMapper.selectByOrderNo(orderNo); if (order == null) { return "没有找到订单号为 " + orderNo + " 的订单，请确认订单号是否正确"; } String statusText = switch (order.getStatus()) { case 1 -> "待付款"; case 2 -> "已付款，等待发货"; case 3 -> "已发货"; case 4 -> "已完成"; case 5 -> "已退款"; default -> "未知状态"; }; return String.format("订单 %s 当前状态：%s，金额 %.2f 元，下单时间 %s", orderNo, statusText, order.getAmount(), order.getCreateTime()); } catch (Exception e) { return "查询订单时出现异常，请稍后重试"; } } }退款申请工具：
@Tool(description = "为指定订单申请退款，只有已付款且未发货的订单可以申请") public String applyRefund( @ToolParam(description = "订单号") String orderNo, @ToolParam(description = "退款原因，用户描述的原因") String reason) { Order order = orderMapper.selectByOrderNo(orderNo); if (order == null) { return "订单不存在，无法申请退款"; } if (order.getStatus() != 2) { return "当前订单状态不支持退款，只有已付款未发货的订单可以申请"; } // 执行退款逻辑 orderMapper.updateStatus(orderNo, 5); return "退款申请已提交，订单 " + orderNo + " 将在1-3个工作日内原路退回"; }注意退款工具里的状态校验。业务规则一定要在 Java 代码里兜底，不能指望模型判断。模型可能会在订单已发货的情况下也调用退款工具，因为用户说“我要退款”，模型觉得该调。但实际能不能退，得你的代码说了算。这是 Function Calling 的一个重要原则：模型负责理解意图，代码负责执行规则。
5.3 组装 ChatClient 与对外接口
@Configuration public class AiConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder, OrderToolService orderToolService, ChatMemory chatMemory) { return builder .defaultSystem("你是一个专业的订单助手，负责帮用户查询订单和处理退款。" + "回答要简洁友好，涉及金额和时间要准确。") .defaultTools(orderToolService) .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()) .build(); } }对外接口：
@RestController @RequestMapping("/api/assistant") public class AssistantController { @Autowired private ChatClient chatClient; @PostMapping("/chat") public String chat(@RequestBody ChatRequest request) { return chatClient.prompt() .user(request.getMessage()) .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, request.getSessionId())) .call() .content(); } }system prompt 里我特意强调了“涉及金额和时间要准确”。因为模型在组织语言时，有时候会把工具返回的“明天下午”改写成“大概这两天”，这种模糊化在订单场景里是灾难。通过 system prompt 约束，能减少这类问题。
5.4 实测效果与调优过程
第一版跑起来，查询订单没问题，但退款场景经常出岔子。用户说“这个订单我不要了”，模型有时候不调用退款工具，而是回复“好的，请问您要退哪个订单”。原因是“不要了”和“退款”在语义上模型没直接关联。
解决办法是在工具的 description 里补充同义表达：“为指定订单申请退款（用户说不要了、取消订单、退货时都应调用此工具）”。改完之后命中率大幅提升。这个技巧很实用：把用户可能用的口语化表达写进 description。
另一个问题是参数提取。用户说“帮我退一下 1234567890 这个单”，模型有时候会把“这个单”也当成订单号的一部分。后来在@ToolParam的 description 里明确“订单号是纯数字或字母组合，不包含中文”，问题基本解决。
6. 上线前必须处理的异常与边界情况
6.1 模型不调用工具怎么办
这是最常见的“不生效”问题。排查顺序建议这样：
先确认工具真的注册上了。可以在启动日志里找找有没有工具注册相关的输出，或者写个单元测试直接断言工具列表。如果工具没注册，检查@Tool注解的类是不是被 Spring 管理、有没有被 AOP 代理。
如果工具注册了但模型不调，八成是 description 写得不够清楚。把 description 改得更具体，覆盖更多用户表达方式。还可以在 system prompt 里加一句“当用户询问订单相关信息时，优先使用提供的工具查询，不要凭记忆回答”。
还有一种情况是模型能力问题。小参数量的模型在工具调用上的准确率确实不如大模型。如果业务对准确率要求高，别在这上面省钱。
6.2 工具调用死循环
我遇到过一次：工具返回“未找到订单”，模型不甘心，又调了一次同样的工具，还是没找到，再调……直到达到最大迭代次数。Spring AI 有默认的最大工具调用轮次限制，但触发限制后返回的是一句比较生硬的提示。
避免死循环的关键是让工具返回的信息足够明确，让模型知道“再试也没用”。比如返回“订单号 XXX 在系统中不存在，请让用户核对后重新提供”，比单纯返回“未找到”效果好得多。模型看到“请让用户核对”，就知道该转向问用户了，而不是自己重试。
6.3 敏感操作的人工确认
退款、删除、支付这类操作，直接让模型调用风险很大。用户可能只是随口一说“这单真烦”，模型理解成要退款就执行了。
稳妥的做法是加一层确认机制。工具方法不直接执行，而是返回一个“待确认”的状态，前端弹出确认框，用户点确认后再真正执行。或者用两阶段工具：第一个工具负责“准备退款”，返回确认信息；第二个工具负责“确认执行退款”，需要用户明确说“确认”才调用。
这个设计在 demo 里可以省，但真上线一定要有。我见过因为没做确认，用户测试时误触发退款流程的案例，虽然金额小，但流程上的漏洞很吓人。
6.4 超时与降级
模型接口调用是有网络延迟的，工具方法里如果再查数据库、调外部服务，整体响应时间可能到好几秒。用户等太久体验很差。
建议给工具方法设置超时，比如数据库查询超过 2 秒就返回“查询超时，请稍后重试”。同时整个对话接口也要有超时控制，超时后返回一个友好的降级提示，而不是让请求一直挂着。
另外，模型服务本身也可能不可用。做好熔断降级，模型挂了的时候，至少让用户能通过传统的方式（比如输入订单号查询）完成核心操作，而不是整个功能瘫痪。
7. 关于成本和性能的一些实在话
Function Calling 的 token 消耗比普通对话高不少，因为每次请求都要带上所有工具的定义。工具越多，这部分开销越大。我实测过一个场景，注册了 8 个工具，光工具定义就占了将近 1000 个 token，每轮对话都要重复发送。
优化方向有几个。一是按场景拆分工具集，不要把所有工具都注册到一个 Client 上。订单相关的对话只注册订单工具，售后相关的只注册售后工具。二是工具 description 别写太长，够用就行，精简的描述能省不少 token。三是合理设置记忆窗口，别让历史消息无限增长。
响应速度方面，工具调用意味着至少两次模型请求，延迟天然比普通对话高。如果对响应速度要求高，可以考虑流式输出，让用户先看到“正在查询”的反馈，减少等待焦虑。
8. 我踩过的几个印象深刻的坑
第一个坑是中文参数乱码。工具方法接收中文参数时，某些环境下会出现乱码。排查后发现是请求编码的问题，在配置文件里显式指定 UTF-8 后解决。这个问题不常见，但一旦遇到很迷惑，因为英文参数完全正常。
第二个坑是工具方法的事务问题。我在工具方法上加了@Transactional，结果发现工具调用后数据没更新。原因是 Spring AI 通过反射调用方法时，如果方法是被代理的，调用链路可能绕过了事务代理。后来把事务逻辑抽到单独的内部方法里，通过 self-injection 或者编程式事务解决。
第三个坑是模型返回的参数类型不匹配。工具方法参数是Long，模型传了个字符串"123"，反序列化直接失败。解决办法是把工具方法的参数类型都设成String，在方法内部自己做类型转换和校验。虽然不够优雅，但最稳。
第四个坑是并发下的记忆串扰。前面提过，这里再强调一次：ChatMemory 一定要按会话隔离，而且要注意并发场景下同一个 sessionId 的请求要串行处理，否则两个请求同时读写同一份记忆，可能互相覆盖。
9. 后续可以怎么扩展
跑通基础版本之后，有几个方向值得继续深入。一是接入更多数据源，比如把物流接口、库存接口都做成工具，让助手能力更完整。二是引入 RAG，把商品详情、售后政策这些文档向量化，让助手在回答时能引用准确的政策条款，而不是靠模型自己编。三是做工具调用的可观测性，记录每次调用了哪个工具、参数是什么、耗时多少、结果如何，这些数据对优化 description 和排查问题极有价值。
Spring AI 本身也在快速演进，工具调用的 API 可能会继续调整。建议关注官方文档的更新，但也不要盲目追新，生产项目还是以稳定为主。我个人的习惯是，新版本出来先在测试项目里跑一遍，确认核心功能没问题再升级。
最后分享一个小心得：调试 Function Calling 的时候，把每次请求和响应的完整消息列表打印出来，包括工具调用的中间过程。虽然日志会很长，但这是定位问题最快的方式。很多“模型不听话”的问题，看一眼完整的消息流就明白了。
