Spring AI Function Calling实战：让大模型从“聊天”到“办事”

大家有没有遇到过这种尴尬：AI助手聊得头头是道，但一问"帮我查一下这个订单的物流"，它只能回一句"我暂时无法访问实时数据"。模型的知识再大，也拿不到你系统里的真实数据，更不会替你去调接口、改状态、下单付款。

Spring AI的Function Calling机制解决的就是这个断层。它让大模型不再停留于"生成文字"，而是能在对话中判断"这里该调用一个函数"，然后以结构化参数的方式要求你的应用去执行真实操作，再把结果回填到对话里。整个链路打通之后，AI才真正从"聊天机器人"变成了"能办事的助手"。

这篇文章我会从零开始，完整拆解Spring AI里Function Calling的原理和实战路径。内容包括：它背后的交互协议是怎么回事、项目怎么搭、模型怎么选、单函数和多函数场景分别怎么写、实测中会遇到哪些边界问题、以及几个我用下来觉得值得单独拎出来讲的坑。适合正在用Spring Boot做AI应用、想把Agent能力落到真实业务的Java开发者。即使你对Function Calling零基础，按着文章走一遍也能跑通。

1. 为什么你的AI应用需要Function Calling

1.1 大模型的能力边界：只会"说"不会"做"

先想清楚一个本质问题：大模型本质上是一个基于概率的文本生成器。你给它一句问题，它给你一段回答。这个回答可以引经据典、逻辑严密，但它没有一个"执行环境"——没有你的订单数据库，没有你的业务接口，没有文件系统权限。

这就导致两个痛点：

• 拿不到实时数据。你和模型说"帮我看看深圳明天天气"，它可以凭记忆告诉你一个大概，但那是训练集中某个时间点的数据，可能早就过时了。
• 做不了实际操作。你让它"帮我给这个用户发一条优惠券短信"，模型只能告诉你一段文案，真正发的动作它做不了。

很多团队早期解决这些问题的方式，是在Prompt里让模型输出特定的JSON，再由后端代码去解析这个JSON、执行对应操作。听起来可行，但实现起来非常痛苦——模型经常输出不合法JSON、字段名自己编、参数类型搞错，解析逻辑越写越复杂，一场对话里只要涉及多个接口就乱成一团。

1.2 Function Calling是什么

Function Calling做的事情，是把"怎么调用函数"这件事从Prompt里的人工约定，变成了模型的原生能力。

具体来说，你在请求里以JSON Schema的形式声明一批函数，每个函数告诉模型：我叫什么、我用一句话描述是干什么的、我接收哪些参数、每个参数是什么类型。模型在理解用户意图后，会主动判断"这个问题需要借助哪个外部函数"，然后不是在生成的文字里暗示你，而是直接输出一个结构化结果，里面带上了函数名和完整参数。

这里有个很多人第一次接触时容易误解的点：整个过程中，真正执行函数的一直是你的应用，不是模型。模型只负责"决定调用哪个函数、参数填什么"，执行完的结果再交给它，让它基于结果组织最终回答。

这个过程给两端都带来了明显的好处。对模型来说，它不需要绞尽脑汁编造没有见过的数据，只需要把手上的参数整理好递出去。对你来说，你不再需要把业务逻辑塞进Prompt里赌模型的稳定性，业务代码该怎么样还是怎么样，模型只是多了一个"指挥"你的能力。

1.3 我为什么在Spring AI里选择Function Calling

市面上具备Function Calling能力的框架不少，Python生态有LangChain、LlamaIndex，Java生态里Spring AI目前是把这件事做得最顺手的。

原因有三点。第一，它是Spring官方生态的一部分，自然承接Spring Boot的自动装配、配置管理、Bean生命周期，不需要引入一套割裂的新框架；第二，Function注册机制平滑，写一个普通的Java方法加上描述注解，就能被模型识别，不像很多框架需要单独维护一套JSON Schema文件；第三，接入国产大模型生态也方便，DeepSeek、通义千问、智谱、MiniMax这些厂商都兼容OpenAI的Function Calling协议，Spring AI统一做了适配，换模型基本不需要改业务代码。

这篇文章后面所有例子都基于Spring AI，代码里会用到Spring AI的ChatModel、FunctionCallback等核心类型。接下来先搞清楚它的底层交互协议，再上手写代码，否则你调半天都不明白返回值为什么长那个样子。

2. 一个真实的Function Calling交互流程长什么样

2.1 三个角色拆解

表面上看，一次Function Calling调用只有你和模型两方参与。实际上，把它拆开看，这里面有三个角色：

• 模型：负责语义理解与决策，判断"现在该不该调外部函数"。
• 你的应用：负责收集函数定义并交给模型，接收模型返回的调用请求，执行对应的Java方法，再把执行结果送回模型。
• 函数本身：就是你的业务方法，比如查天气、查订单、计算价格，它是普通代码，和模型没有直接关联。

这三个角色的关系，可以类比成你和助理配合做事。助理（模型）不亲手干活，但会写一张条子告诉你：你需要去库房取A货架第三层的蓝色盒子，取来之后告诉我。你（应用）看到条子，取了货，回来把结果告诉他，他再基于这个结果给你最终答复。

2.2 一次完整调用的三次往返

很多初学者以为Function Calling是模型"直接调用"你的接口，这是错误的。真实过程是一轮对话里的多次请求往返，我拆成三步来看。

第一步，应用向模型发起带函数声明的请求。你在请求里除了发用户消息，还要带上一批函数定义，告诉模型"你有这些工具可用"。

第二步，模型返回函数调用请求。模型读完用户消息，判断应该调用哪个函数，然后返回一条特殊响应，里面有一个tool_calls字段，包含函数名和模型自己填充的参数。这个响应不是最终答案，而是"我需要你帮我执行这个"。

第三步，应用执行函数并把结果回传。你拿到函数名和参数，在自己的Java代码里找到对应方法执行，然后把执行结果作为一条"工具消息"塞进对话历史，再次发给模型。模型看到函数返回值后，组织出一段自然语言回答，这次才是最终回复。

我见过不少第一次调试的人，第二步返回一个tool_calls的时候就开始懵了：怎么结果没有content？其实这是正常的，你要做的是检查tool_calls里的内容，执行完函数再把这轮对话发给模型。

2.3 和硬编码调用的本质差异

有些人会说，这绕了一圈，不就是模型输出一个JSON、后端解析一下去调用对应接口吗？确实有点像，但底层逻辑完全不同。

硬编码方案里，模型输出什么靠的是Prompt约束，你告诉它"必须输出JSON，key是function_name，value是参数"。模型经常"不听话"，输出格式漂移、参数类型不对、甚至直接开始唠嗑。你需要在外面套一堆解析、校验、重试逻辑。

Function Calling方案里，函数名和参数格式是模型在训练阶段就被教会的能力，它知道tool_calls这个字段必须带上已有的函数名，参数必须符合你声明的JSON Schema。从底层把"格式化输出"这件事变成了模型的内置技能，可靠性比Prompt约束高一个量级。

所以，Spring AI里你不需要自己解析函数名和参数，SDK已经替你处理了，你的任务是：定义好函数、注册给模型、在第三轮把结果传回去。搞清楚这个流程，后面写代码就有底了。

3. 搭建项目与选中模型前必须想清楚的几件事

3.1 版本怎么选

Spring AI的版本演进很快，早期用的是1.0.0-M1这种里程碑版本，后来出了1.0.0正式版，现在又是2.0时代。选版本这件事，比你想的重要得多，因为不同版本的API差异很大，网上搜到的大多数案例可能都不能直接运行。

我当前推荐的组合是Spring Boot 3.4.x配合Spring AI 1.0.0正式版，或者直接上用2.0.x的新版本。如果你在主题是"Spring AI Alibaba"相关的项目里，还需要额外引入spring-ai-alibaba-starter。

有一点踩坑经验：别直接照抄GitHub最新示例。Spring AI的主仓库在快速迭代，API经常变动，我在升级时吃过不少亏。稳妥的做法是先看你选的版本对应的Release文档，尤其是FunctionCallback和ChatClient的用法，不同版本差异主要在它们身上。

以Spring AI 1.0.0为例，核心依赖长这样：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency>

如果要接通义千问，引入对应的starter：

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

版本冲突是这类项目最常见的启动失败原因。建议用spring-ai-bom统一管理版本，别手动指定各子模块版本号，否则Maven会给你上一课。

3.2 模型选型：兼容性比性能更关键

Function Calling依赖模型的原生能力，所以不是所有模型都能跑。GPT-4o、Claude 3.5、DeepSeek、通义千问、智谱GLM这些主流模型都支持，但不同模型对参数Schema的容忍度差异很大。

我的建议是：如果你只是学习和验证，优先选OpenAI接口兼容的云服务，配置最简单。如果你在国内环境，用通义千问或智谱的接入方式也不会比OpenAI复杂多少。Spring AI把所有兼容OpenAI协议的模型都封装在同一个ChatModel接口后面，换模型通常意味着换一个配置前缀。

spring: ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o temperature: 0.7

有一点要提醒：Function Calling场景下，temperature不建议设太高。它是采样随机性参数，太高会让函数调用选择变得不稳定，偶尔明明该调天气函数却去调了别的函数。实务中我一般设0.2到0.4，结构化场景会更可靠。

3.3 工程结构与配置清单

为了方便直接跑，我建议你建一个普通的Spring Boot工程，只要一个模块就够了。整个项目的结构如下：

• controller/：提供HTTP入口，接收用户输入，调用ChatClient
• service/：放业务函数本体，比如天气查询、订单查询
• config/：做Bean装配，注册函数
• resources/application.yml：配置api-key、模型、超时参数

你需要准备的东西也很少：一个支持Function Calling模型的API Key、一个Spring Boot 3.4+的空工程、以及一点耐心。整个项目跑通，不会超过两百行代码。

4. 第一阶段实战：手写一个天气查询函数

4.1 定义一个能被模型识别的函数

在Spring AI里，定义一个"能被模型识别的函数"非常简单：写一个普通Java方法，加上@Description注解，描述这个函数的用途和参数含义。

为什么这个注解这么重要？因为模型不具备读你代码的能力，它只能看到你在注解里写的描述和JSON Schema。描述写得越清楚，模型的调用准确率就越高。

下面这个例子模拟一个天气查询函数：

@Description("根据城市名查询实时天气，用于回答用户关于天气的提问") public record WeatherFunction() implements Function<WeatherFunction.Request, WeatherFunction.Response> { @Override public Response apply(Request request) { // 这里实际上是调用外部天气API，为了演示返回固定数据 return new Response(request.city(), "多云", 26, "东南风3级"); } public record Request( @JsonProperty(required = true, value = "city") String city, @JsonProperty(required = false, value = "unit") String unit) { } public record Response(String city, String condition, int temperature, String wind) { } }

注意这段代码的几处细节：Request里的@JsonProperty注解定义了参数的名称、是否必填，这是Spring AI生成JSON Schema的基础。所谓"工具定义"，其实主要就是把Request这个record转成JSON Schema传给模型，所以字段命名要直观，别用晦涩缩写。

4.2 注册函数：属性声明和编程式注册

函数定义好之后，需要把它"告诉"模型。Spring AI提供了两种方式，原理都一样，只是配置位置不同。

第一种，配置文件声明。在application.yml里指定函数名和对应的Bean名称：

spring: ai: chat: client: tool-callbacks: - name: weatherFunction bean-name: weatherFunction description: 根据城市名查询实时天气 input-type: cn.example.functions.WeatherFunction$Request output-type: cn.example.functions.WeatherFunction$Response

第二种，编程式注册。在Java配置类里直接构造FunctionCallback：

@Bean public FunctionCallback weatherFunction() { return FunctionCallback.builder() .description("根据城市名查询实时天气") .function("weatherFunction", new WeatherFunction()) .inputType(WeatherFunction.Request.class) .build(); }

两种方式我建议你用编程式，原因很明显：不用写一长串类名到YAML里，类型安全，重构的时候编译器能帮你发现问题。配置文件方式适合不想动代码的场景，但调试起来比较麻烦。

4.3 跑通第一轮完整对话

函数定义好、也注册了，接下来写一个HTTP接口，把对话流程串起来。

@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder .defaultFunctions("weatherFunction") .build(); } @PostMapping("/chat") public String chat(@RequestBody String userMessage) { return chatClient.prompt(userMessage) .call() .content(); } }

核心就是defaultFunctions(...)，它告诉这个ChatClient实例：模型可用的工具里有weatherFunction。当你发送"深圳今天天气怎么样"，Spring AI会自动完成我之前讲的两次请求往返，最终返回的是一句自然语言。

一个典型的输出如下：

深圳今天多云，气温26度，东南风3级。

如果你打开日志，会看到第二次请求里有一个tool_calls字段，内容是：

{ "name": "weatherFunction", "arguments": { "city": "深圳" } }

看到这个结构，说明你的Function Calling已经完全打通了。剩下的事情都是在这个基础上做扩展。

5. 第二阶段进阶：让AI自主决策的多函数路由

5.1 多函数注册：模型如何自己选

真实业务里一个函数通常不够用。典型场景是：用户问"深圳天气怎么样，顺便把明天北京到上海的机票价格也算一下"，这时候需要两个函数配合，一个是天气查询，一个是机票比价。

在Spring AI里注册多函数非常直接，defaultFunctions接收一个可变参数：

this.chatClient = builder .defaultFunctions("weatherFunction", "airfareFunction", "hotelFunction") .build();

模型会读取所有函数的定义，根据用户问题的语义自行判断调用哪个，必要时还会并行调用多个。比如上面的问题，模型可能同时返回两个tool_calls，一个查天气，一个算机票。这就是多函数路由最省心的地方——你不用写任何路由逻辑。

但"自由选择"也意味着"可能选错"。这个问题的根源通常在函数描述写得有歧义。举个例子，如果你的天气函数描述里写了"支持查询气温、降雨、风力"，用户问"深圳明天要不要带伞"，模型可能优先调用降雨相关描述的函数，而不是天气总查询函数。所以函数描述要写得边界清晰，必要时用标点突出擅长范围。

5.2 参数Schema：类型、枚举、必填，一点也不能含糊

多函数场景下，参数定义直接决定了调用的成败。我见过一个翻车案例：一个电商客服的Agent，商品查询函数的category参数定义为String，模型自由发挥填了"男装夹克"、"春季外套"这类五花八门的写法，后端精确匹配完全对不上。

解决这个问题的最好办法，是给参数加上枚举约束。Spring AI支持用@JsonClassDescription配合Java的枚举类型来生成枚举Schema：

public record ProductQuery( @JsonProperty(required = true, value = "category") Category category, @JsonProperty(required = true, value = "keyword") String keyword) { public enum Category { 上衣, 裤装, 鞋靴, 配饰 } }

一旦声明了枚举，模型在生成参数时就会尽量从枚举值里选，不会自由发挥。同理，对于数值参数，能用@JsonProperty定义取值范围最好，比如价格区间可以定义为int，在描述里写明"单位：元"，避免模型给出一堆带小数点的价格。

参数Schema的规则总结起来就几条：

• 必填参数务必标required = true
• 能用枚举的地方别用String
• 单位、格式写在描述里，比如"日期格式YYYY-MM-DD"
• 参数数量控制在5个以内，太多模型容易填写混乱

5.3 多轮上下文与函数结果回填

多函数场景还有个常见问题：函数调用不止一轮。比如用户先说"帮我对比上海和杭州的天气"，模型调用两个天气函数，给出对比结论；用户接着说"那哪个城市更适合明天出行"，这句话表面上不涉及任何函数，但如果你不带上前面的上下文，模型根本无法作答。

Spring AI的ChatClient在这里帮了大忙。ChatClient内部维护着对话记忆，你只需要确保函数执行结果作为消息被放进了历史即可。实际使用中，如果你用ChatClient的prompt()方式，它会自动帮你把工具调用和工具结果拼进消息列表。

不过要注意，ChatClient默认不持久化上下文。如果你的应用是无状态接口，每次请求都是全新对话，用户连续追问就会失忆。要解决这个问题，可以在Starter里开启ChatMemory的持久化，或者自己引入Redis做会话消息存储。这个设计要提前想清楚，我遇到过很多团队在功能联调通过后，才回头补上下文存储，改起来很别扭。

6. 实测中的边界问题与性能优化

6.1 函数返回结果太长的风险

进入实测阶段，头号遭遇战往往不是"模型不调用函数"，而是"函数返回了巨大数据，模型不知道该怎么办"。

假设你做了一个订单查询函数，返回结构里带上了订单明细、商品快照、物流轨迹、售后记录。这个结果会被完整塞进对话历史发给模型。结果就是：token消耗暴涨、响应变慢、甚至因为超出上下文窗口直接报错。

我的处理经验是：函数返回给模型的数据，只保留模型需要用来组织回答的摘要字段，而不是完整业务对象。比如订单查询函数，返回前先把数据裁剪成：

• 订单状态
• 商品名称
• 下单时间
• 金额

至于订单内部冗长的明细列表，别一股脑丢给模型。模型不需要知道每件商品的内部编码，它只需要信息足以生成"您的订单已发货，包含3件商品，预计后天送达"这句话就好。

Spring AI里做这个很自然，你只需要让函数返回一个精简DTO对象：

public record OrderSummary(String orderNo, String itemBrief, String status, String eta) { }

6.2 无限函数调用Loop的防护

另一个奇怪的问题是死循环。某些情况下，模型拿到函数返回结果后，可能觉得结果不理想，又去调用同一个函数，如此反复。每次调用都产生token费用，接口迟迟不返回。

这听起来像极端情况，但多函数场景下确实发生过。比如你有一个"查询库存"的函数，用户问的是"这个库存数据哪里来的？"，模型可能理解为需要调用库存查询函数，拿到结果后又开始解释，解释过程中再次调用，陷入循环。

防止这个问题有几招：

1. 给函数执行总次数设置上限。Spring AI底层提供拦截机制，可以自己计数，达到5次直接终止循环。
2. 限制函数返回内容的表达精度。很多循环调用是因为函数返回的字段语义模糊，模型反复确认，尽量让返回数据"结论化"，而不是"数据化"。
3. 把不合适的意图通过描述排除掉。对非业务类元问题，比如"你从哪获知的数据"，明确描述"此函数仅用于XX，不做数据分析"。

.overrideToolCallbacksAfterCompletion(5) // 最多允许5次工具调用

实测下来这个参数非常有用，建议直接加上。

6.3 Token与延迟：怎么省

Function Calling会显著增加token消耗，它与普通对话的区别就是两次请求都携带大量函数定义和工具消息。有个简单的实测数据：注册5个函数、每个函数带3个参数，每次对话光函数定义就要消耗几百token。

优化手段有三个方向。

方向一，缩小函数定义体。Spring AI生成的FunctionCalling定义里包含你定义的DTO的结构描述，字段注释和描述都会转成Schema。如果描述很长，每次调用都带着这些文本。在保证模型能理解的前提下，描述写得精简一点，长期使用能省不少token。

方向二，缓存函数定义。函数Schema在业务运行期间基本不变，没必要每次请求都重新生成一遍。Spring AI本身有缓存，但你如果每次动态注册函数，就享受不到。尽量把函数定义为固定Bean，别在请求里临时创建。

方向三，按需注入函数。不需要把全部函数一古脑注册给模型。比如用户进入售后页面时，只注入售后相关函数，减少无关函数的干扰，也减少token开销。Spring AI可以在运行时通过runtimeFunctions动态指定函数集合，这就够用了。

延迟这块，最大瓶颈往往不在模型，而在你的函数执行速度。一个例子：查天气的函数如果调用外部天气API要3秒，用户体感上就是"回答问题前卡了3秒"。建议把高频外部查询函数做成缓存优先，或把执行步骤放到后台，返回即时状态给模型组织话术。

7. 几个容易被忽视但影响巨大的细节坑

7.1 一次事故：并发与本地变量状态

Function Calling在Spring AI里的执行方式，并不是简单反射调用一个方法，而是要经过FunctionCallback的包装。默认情况下，Spring AI在每次调用时会复用你注册的Bean。

我自己踩过一个很深的坑：在函数Bean里加了一个private List<String> history字段，想记录该函数的所有调用历史。本意是方便追溯，结果在高并发测试时发现，多个用户的调用历史互相串了。因为Spring的Bean默认是单例的，所有请求共享同一个Bean实例，我的history是个共享状态。

这种问题的教训是：函数Bean设计时要无状态。所有临时数据都放在方法参数或函数内部创建，不要挂在成员变量上。如果确实要记录状态，请使用外部存储，比如Redis或数据库。

@Component public class OrderFunction implements Function<OrderQuery.Request, OrderQuery.Response> { // 禁止这样的写法 // private Map<String, Object> state = new ConcurrentHashMap<>(); @Override public Response apply(Request request) { // 业务逻辑 } }

7.2 金额与换算：不该用double

Function Calling是AI与业务系统之间的桥梁，这个"桥"最容易出现问题的地方之一是数值精度。一个订单金额，模型以为是99.99，但你的数据库存的是分：9999。模型直接传参可能会传成9999.0或10000，后端入库就错了。

我的建议是：所有金额类参数在函数DTO里用整数分或者BigDecimal定义，并且在描述里明确单位。比如：

public record RefundRequest( @JsonProperty(required = true, value = "orderId") String orderId, @JsonProperty(required = true, value = "amountFen") long amountFen) { }

这里amountFen是"分"，模型看到的Schema会明确这是一个整数，单位是分。即使模型从用户的"退款100元"里解析出10000，也正好是10000分，不会出现精度问题。千万别用double接金额，浮点误差一旦发生，审计都对不上账。

7.3 超时、重试与流式对话的坑

Function Calling天然比普通对话慢，因为多了一轮"模型返回工具调用→执行函数→再次请求模型"的往返。这意味着HTTP超时设置和流式输出需要特殊处理。

先说超时。如果你给接口设置的超时只有10秒，而函数本身要执行3秒，加上模型两轮生成时间，极容易超时。我通常在网关层对这类接口放宽到30秒以上，同时内部给模型调用设置合理超时，比如OpenAI的socketTimeout设为30秒。

再说流式。StreamingChatClient模式下，如果用户问了一个需要函数调用的问题，第一轮流式输出的内容往往是空的，因为模型没有直接生成回答，而是在生成tool_calls。这会让前端表现为"半天没反应"。处理办法有两种：一是前后端交互时，遇到空流式块展示"正在思考"状态；二是把Function Calling场景下流式输出阶段分清楚，工具执行完成后再做最终流式回答。

spring: ai: openai: client: connect-timeout: 10s read-timeout: 60s

7.4 权限思维：让函数最小化暴露业务能力

最后一个我要重点强调的：Function Calling是一个入口，模型选择什么函数去调用，那个函数就会真正执行。这等于把系统的部分操作能力暴露给了AI，那AI的入口层（也就是前端聊天框）就成了一个新的安全边界。

如果你把所有函数都注册给模型，用户说"给全体用户发优惠券"，模型真的会去执行对应函数。这听起来是科幻场景，但真实发生过。

我的做法是，给函数调用设计三层防线：

1. 函数权限等级。非敏感操作随意调用，涉及资金、用户资产、批量操作的函数必须加上二次确认步骤。
2. 参数校验前置。模型生成的参数不可信，函数入口处用Spring Validation或手动校验，比如金额不能为负、手机号格式必须正确。
3. 操作审计。每次函数调用记录用户标识、函数名、参数、结果，存日志或数据库，方便追踪。

一个Agent系统能不能安全落地，关键不在模型能力，而在这些外围防线。Function Calling本身是通道，通道打通了之后，业务安全规则一个都不能省。

我自己的经验是，功能上线前后，拿出半天时间专门做函数调用的权限梳理，把"模型可以做"的清单和"模型绝对不可以做"的清单分开，比后续补救省心得多。