Spring AI 中 ChatClient 工具调用功能失效问题解析

问题现象

在使用 Spring AI 框架的 ChatClient 时，开发者发现当配置了 defaultOptions 后，工具调用（Tool Calling）功能会失效。具体表现为：

1. 当使用 ChatOptions.builder() 创建默认配置时，工具回调无法触发
2. 移除 defaultOptions 配置后，工具调用功能恢复正常
3. 该问题在 Spring AI 1.0.0 与 Spring Boot 3.5.0 环境下出现

问题根源

经过分析，这个问题源于 ChatClient 的内部实现机制：

1. 选项类型不匹配：当使用 ChatOptions.builder() 创建配置时，生成的是 DefaultChatOptions 实例，这种类型的选项不支持工具调用功能

2. 工具信息丢失：在构建 ChatClientRequest 时，系统没有正确处理 DefaultChatOptions 与工具调用信息共存的情况，导致工具配置被丢弃

3. 模型差异：该问题在切换不同 AI 模型（如 DEEPSEEK_CHAT 和 DEEPSEEK_REASONER）时表现一致，说明是框架层面的通用问题

解决方案

目前有两种可行的解决方案：

方案一：使用专用选项类

.defaultOptions(ToolCallingChatOptions.builder()
        .model(DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue())
        .temperature(0.7)
        .build())

方案二：使用模型特定选项

DeepSeekChatOptions options = deepSeekChatProperties.getOptions().copy();
options.setModel(DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue());
return chatClientBuilder
        .defaultOptions(options)
        // 其他配置...
        .build();

最佳实践建议

1. 明确工具调用需求：如果需要使用工具调用功能，应该始终使用 ToolCallingChatOptions 或其子类

2. 配置复用：对于多模型场景，可以创建基础配置然后复制修改，如示例中的 deepSeekChatProperties.getOptions().copy()

3. 版本适配：注意不同 Spring AI 版本对此问题的处理可能不同，1.0.0 之后版本可能会有官方修复

4. 调试技巧：当工具调用失效时，可以检查生成的请求中是否包含 tools 字段，这是快速诊断问题的方法

技术原理深入

工具调用是大型语言模型(LLM)的重要功能，允许AI主动调用开发者定义的方法。在Spring AI中，这一功能的实现涉及多个组件协作：

1. 工具注册：通过@Tool注解声明工具方法，MethodToolCallbackProvider收集这些方法

2. 选项配置：ToolCallingChatOptions会在生成的请求中包含工具描述信息

3. 请求构建：ChatClient将工具信息转换为模型能理解的格式

4. 响应处理：解析模型的工具调用请求，执行对应方法并返回结果

理解这一流程有助于开发者更好地使用和调试工具调用功能。

总结

Spring AI 提供了强大的工具调用能力，但需要注意选项配置的细节。开发者应该根据实际需求选择合适的选项类型，并在多模型场景中保持配置的一致性。随着框架的发展，这类问题可能会得到更优雅的解决方案，但当前理解其原理仍对开发有重要价值。