Spring AI 项目中工具调用流式处理的技术解析与解决方案

背景介绍

在Spring AI项目中，开发者经常需要实现AI模型与外部工具集成的功能。这种集成通常涉及工具调用（Tool Calling）机制，允许AI模型在执行过程中动态调用预定义的工具函数。然而，当开发者尝试在流式（Stream）模式下使用工具调用功能时，可能会遇到"toolInput cannot be null or empty"的错误。

问题本质分析

这个问题的核心在于Spring AI在处理流式工具调用时，对于空参数的处理机制存在不足。具体表现为：

1. 参数格式差异：在非流式调用中，无参数的函数调用会返回"{}"作为默认参数；而在流式调用中，同样的无参数函数调用会返回空字符串""。

2. 参数验证严格：FunctionToolCallback.call()方法中设置了严格的参数验证，要求toolInput不能为空或null，这导致了流式调用失败。

3. 工具调用管理器限制：默认的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);
    }
}

技术启示

1. 流式处理的特殊性：流式API调用与常规调用在参数处理和响应解析上存在差异，开发者需要特别注意。

2. 参数验证的灵活性：在设计工具调用接口时，应考虑不同调用模式下参数传递的多样性，提供更灵活的验证机制。

3. 上下文完整性：在流式处理中维护完整的执行上下文比非流式场景更具挑战性，需要特别设计。

4. 兼容性设计：解决方案展示了如何在不破坏现有功能的前提下，通过扩展机制解决特定场景下的问题。

最佳实践建议

1. 工具函数设计：即使工具函数不需要参数，也建议显式处理空参数情况，返回合理的默认值。

2. 错误处理：在工具调用实现中加入健壮的错误处理逻辑，特别是对参数格式的验证和转换。

3. 测试覆盖：确保对工具调用的测试覆盖流式和非流式两种模式，验证参数传递的正确性。

4. 性能考量：流式处理中频繁的工具调用可能影响性能，需要合理设计工具执行逻辑。

通过这种自定义工具调用管理器的实现，开发者可以在Spring AI项目中实现稳定可靠的流式工具调用功能，解决参数传递和验证的问题，为构建复杂的AI应用提供更强大的支持。