Spring AI 项目中工具调用流式处理的技术解析与解决方案
项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai 背景介绍
在Spring AI项目中，开发者经常需要实现AI模型与外部工具集成的功能。这种集成通常涉及工具调用（Tool Calling）机制，允许AI模型在执行过程中动态调用预定义的工具函数。然而，当开发者尝试在流式（Stream）模式下使用工具调用功能时，可能会遇到"toolInput cannot be null or empty"的错误。
问题本质分析
这个问题的核心在于Spring AI在处理流式工具调用时，对于空参数的处理机制存在不足。具体表现为：
-
参数格式差异：在非流式调用中，无参数的函数调用会返回"{}"作为默认参数；而在流式调用中，同样的无参数函数调用会返回空字符串""。
-
参数验证严格：
FunctionToolCallback.call()方法中设置了严格的参数验证，要求toolInput不能为空或null，这导致了流式调用失败。 -
工具调用管理器限制：默认的
DefaultToolCallingManager对流式响应的处理不够完善，无法正确处理工具调用的参数聚合。
技术解决方案
针对这一问题，社区开发者提出了一个自定义的StreamingToolCallingManager实现方案，主要改进点包括：
1. 参数聚合处理
@Override
public ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse) {
Optional<Generation> first = chatResponse.getResults()
.stream()
.filter(g -> !CollectionUtils.isEmpty(g.getOutput().getToolCalls()))
.findFirst();
Generation generation = first.orElseThrow();
// 关键改进：聚合所有工具调用的参数
String args = generation.getOutput().getToolCalls().stream()
.map(AssistantMessage.ToolCall::arguments)
.reduce("", (s, s2) -> s + s2);
// 重构工具调用对象
AssistantMessage.ToolCall toolcall = generation.getOutput().getToolCalls().getFirst();
AssistantMessage.ToolCall newToolCall = new AssistantMessage.ToolCall(
toolcall.id(), toolcall.type(), toolcall.name(), args);
List<AssistantMessage.ToolCall> newToolCalls = List.of(newToolCall);
// 后续处理...
}
2. 工具执行上下文构建
解决方案中完善了工具执行的上下文构建过程，确保在流式调用和非流式调用中都能获得一致的上下文信息：
private static ToolContext buildToolContext(Prompt prompt, AssistantMessage assistantMessage) {
Map<String, Object> toolContextMap = Map.of();
if (prompt.getOptions() instanceof FunctionCallingOptions functionOptions
&& !CollectionUtils.isEmpty(functionOptions.getToolContext())) {
toolContextMap = new HashMap<>(functionOptions.getToolContext());
// 构建工具调用历史
toolContextMap.put(ToolContext.TOOL_CALL_HISTORY,
buildConversationHistoryBeforeToolExecution(prompt, assistantMessage));
}
return new ToolContext(toolContextMap);
}
3. 工具执行结果处理
改进后的方案提供了更灵活的工具执行结果处理机制，支持返回直接结果和构建对话历史：
private InternalToolExecutionResult executeToolCall(Prompt prompt,
AssistantMessage assistantMessage,
ToolContext toolContext) {
// 工具回调处理逻辑
List<ToolResponseMessage.ToolResponse> toolResponses = new ArrayList<>();
// 支持returnDirect标志
Boolean returnDirect = null;
// 遍历所有工具调用
for (AssistantMessage.ToolCall toolCall : assistantMessage.getToolCalls()) {
// 工具查找和调用逻辑
String toolResult = toolCallback.call(toolInputArguments, toolContext);
toolResponses.add(new ToolResponseMessage.ToolResponse(toolCall.id(), toolName, toolResult));
}
return new InternalToolExecutionResult(new ToolResponseMessage(toolResponses, Map.of()), returnDirect);
}
配置实现
要使上述解决方案生效，需要在Spring配置中声明自定义的ToolCallingManager：
@Configuration
public class ToolConfig {
@Bean
ToolCallingManager toolCallingManager(ToolCallbackResolver toolCallbackResolver,
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor,
ObjectProvider<ObservationRegistry> observationRegistry) {
return new StreamingToolCallingManager(
observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP),
toolCallbackResolver,
toolExecutionExceptionProcessor);
}
}
技术启示
-
流式处理的特殊性：流式API调用与常规调用在参数处理和响应解析上存在差异，开发者需要特别注意。
-
参数验证的灵活性：在设计工具调用接口时，应考虑不同调用模式下参数传递的多样性，提供更灵活的验证机制。
-
上下文完整性：在流式处理中维护完整的执行上下文比非流式场景更具挑战性，需要特别设计。
-
兼容性设计：解决方案展示了如何在不破坏现有功能的前提下，通过扩展机制解决特定场景下的问题。
最佳实践建议
-
工具函数设计：即使工具函数不需要参数，也建议显式处理空参数情况，返回合理的默认值。
-
错误处理：在工具调用实现中加入健壮的错误处理逻辑，特别是对参数格式的验证和转换。
-
测试覆盖：确保对工具调用的测试覆盖流式和非流式两种模式，验证参数传递的正确性。
-
性能考量：流式处理中频繁的工具调用可能影响性能，需要合理设计工具执行逻辑。
通过这种自定义工具调用管理器的实现，开发者可以在Spring AI项目中实现稳定可靠的流式工具调用功能，解决参数传递和验证的问题，为构建复杂的AI应用提供更强大的支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
