Spring AI中Tool调用与自定义返回值实践

1. Spring AI中Tool调用的核心机制解析

在Spring AI框架中，Tool调用是实现AI与外部系统交互的关键机制。当我们需要让AI模型执行特定任务（如查询天气、创建待办事项等）时，Tool提供了标准化的接入方式。其核心工作原理可以分解为以下几个层面：

Function Calling的底层实现
Spring AI通过OpenAI的function calling协议实现Tool调用。当用户输入包含明确意图时（如"提醒我明天上午开会"），AI模型会识别出需要调用哪个Tool，并以结构化JSON格式返回调用参数。例如对于TodoList场景，可能返回：

json复制{
  "tool": "addTodoItem",
  "args": {
    "content": "项目进度会议",
    "time": "2024-03-20 09:00"
  }
}

Spring AI的适配层
框架在接收到AI模型的function call请求后，会通过ToolFunctionCallback接口将调用路由到开发者注册的Tool实现类。这个过程涉及几个关键组件：

• ToolExecutor：负责参数反序列化和方法调用
• ToolResponseConverter：将Java方法返回值转换为AI模型可理解的格式
• ToolCallContext：保存本次调用的上下文信息

默认返回值处理的局限性
系统默认会将Java方法的返回值直接序列化为JSON返回给AI模型。这在简单场景下可行，但当我们需要：

• 控制返回给用户的最终表述
• 注入额外的上下文信息
• 处理敏感数据过滤时
  就需要自定义返回值处理逻辑。

2. TodoList场景下的自定义返回值需求

在实现智能待办事项管理时，标准的"创建提醒"Tool调用往往需要更丰富的交互。让我们通过一个典型场景来说明自定义返回值的必要性：

基础功能实现的问题
假设我们已经实现了一个基础的addTodoItem Tool：

java复制@Tool(name = "addTodoItem", description = "添加待办事项")
public TodoItem addTodoItem(
    @P("content") String content,
    @P("time") @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm") LocalDateTime time) {
    return todoService.save(new TodoItem(content, time));
}

当用户说"提醒我明天下午3点提交报告"时，AI会机械地回复："已创建待办事项：内容=提交报告，时间=2024-03-20 15:00"。这种响应存在三个问题：

1. 缺乏自然语言交互的友好性
2. 没有利用系统已有的用户偏好数据
3. 无法添加额外的操作建议

业务场景的深度需求
通过分析实际使用场景，我们发现需要注入以下信息到返回值中：

1. 个性化提醒：根据用户设置的偏好（如"我喜欢被称呼为张工"），将响应改为"好的张工，已为您设置提醒"
2. 冲突检测：当新建事项与已有事项时间重叠时，提示"检测到与'团队例会'时间冲突，需要调整吗？"
3. 智能建议：对于"提交报告"类事项，自动附加"需要我帮您设置提前30分钟的准备提醒吗？"

这些需求促使我们需要全面自定义Tool调用的返回值处理流程。

3. 实现自定义返回值的三种技术方案

Spring AI提供了灵活的扩展点来实现返回值定制。根据复杂度不同，我们可以选择以下三种方案：

3.1 方案一：直接包装返回值

最简单的做法是在Tool方法内部完成所有处理：

java复制@Tool
public Map<String, Object> addTodoItem(...) {
    TodoItem item = todoService.save(new TodoItem(content, time));
    
    return Map.of(
        "original", item,
        "message", generateFriendlyMessage(user, item),
        "suggestions", generateSuggestions(item)
    );
}

优点：

• 实现简单直接
• 所有逻辑集中在一处

缺点：

• 污染业务逻辑
• 难以复用通用处理逻辑

3.2 方案二：实现ResponsePostProcessor

更优雅的方式是实现ToolResponsePostProcessor接口：

java复制@Component
public class TodoResponseEnhancer implements ToolResponsePostProcessor {
    @Override
    public Object process(ToolCallContext context, Object rawResponse) {
        if (rawResponse instanceof TodoItem item) {
            return new EnhancedTodoResponse(
                item,
                generateMessage(context.getUser(), item),
                checkConflicts(item)
            );
        }
        return rawResponse;
    }
}

优势：

• 业务逻辑与增强逻辑解耦
• 可以组合多个处理器
• 支持基于注解的过滤

3.3 方案三：自定义MessageConverter

对于需要深度控制序列化过程的场景，可以扩展AbstractMessageConverter：

java复制public class TodoMessageConverter extends AbstractMessageConverter {
    @Override
    protected boolean supports(Class<?> clazz) {
        return TodoItem.class.isAssignableFrom(clazz);
    }

    @Override
    protected Object convertToResponse(Object output) {
        TodoItem item = (TodoItem) output;
        // 自定义转换逻辑
    }
}

适用场景：

• 需要特殊序列化逻辑
• 响应结构需要兼容特定前端格式
• 涉及敏感数据过滤

4. TodoList提醒注入的完整实现

让我们实现一个包含完整增强功能的TodoList提醒系统。假设我们采用方案二（ResponsePostProcessor）作为核心架构。

4.1 基础环境配置

首先确保Spring AI依赖正确配置：

xml复制<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>0.8.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
    <version>0.8.0</version>
</dependency>

4.2 核心领域模型设计

定义增强版的返回值结构：

java复制public record EnhancedTodoResponse(
    TodoItem item,
    String userMessage,
    List<TimeConflict> conflicts,
    List<Suggestion> suggestions
) {}

public record TimeConflict(
    String existingTitle,
    LocalDateTime existingTime
) {}

public record Suggestion(
    String type, // "PREPARE"|"FOLLOWUP" 
    String description,
    String action
) {}

4.3 实现响应增强处理器

创建核心处理逻辑：

java复制@Component
@Order(Ordered.LOWEST_PRECEDENCE - 100) // 确保优先执行
public class TodoResponseEnhancer implements ToolResponsePostProcessor {
    
    @Autowired
    private UserPreferenceService prefService;
    
    @Autowired
    private ConflictDetector conflictDetector;
    
    @Autowired
    private SuggestionEngine suggestionEngine;

    @Override
    public Object process(ToolCallContext context, Object rawResponse) {
        if (!(rawResponse instanceof TodoItem item)) {
            return rawResponse;
        }
        
        User user = context.getUser();
        String message = generateMessage(user, item);
        List<TimeConflict> conflicts = detectConflicts(item);
        List<Suggestion> suggestions = generateSuggestions(item);
        
        return new EnhancedTodoResponse(item, message, conflicts, suggestions);
    }
    
    private String generateMessage(User user, TodoItem item) {
        String template = prefService.getMessageTemplate(user);
        return String.format(template, 
            user.getPreferredName(),
            item.getContent(),
            formatTime(item.getTime()));
    }
    
    // 其他辅助方法...
}

4.4 注册自定义Tool

配置Tool声明和响应处理器：

java复制@Configuration
public class TodoToolConfig {
    
    @Bean
    public ToolFunction todoAddFunction(TodoService service) {
        return ToolFunction.builder()
            .name("addTodoItem")
            .description("添加待办事项")
            .inputType(TodoItemRequest.class)
            .function(service::addItem)
            .build();
    }
    
    @Bean
    public ToolResponsePostProcessor todoEnhancer() {
        return new TodoResponseEnhancer();
    }
}

5. 高级功能与实战技巧

在实际应用中，我们还需要考虑一些增强场景和优化点。

5.1 动态建议生成策略

基于事项内容生成智能建议的算法示例：

java复制public List<Suggestion> generateSuggestions(TodoItem item) {
    List<Suggestion> suggestions = new ArrayList<>();
    
    // 基于NLP分析事项类型
    String content = item.getContent().toLowerCase();
    
    if (content.contains("报告") || content.contains("提交")) {
        suggestions.add(new Suggestion(
            "PREPARE",
            "通常需要提前准备材料",
            "ADD_PREP_TIME"
        ));
    }
    
    if (content.contains("会议")) {
        suggestions.add(new Suggestion(
            "FOLLOWUP",
            "需要安排会后跟进事项吗？",
            "ADD_FOLLOWUP"
        ));
    }
    
    return suggestions;
}

5.2 冲突检测优化方案

高效检测时间冲突的实现：

java复制public List<TimeConflict> detectConflicts(TodoItem newItem) {
    return todoRepository.findByTimeBetween(
            newItem.getTime().minusHours(1),
            newItem.getTime().plusHours(1))
        .stream()
        .filter(existing -> isOverlap(newItem, existing))
        .map(existing -> new TimeConflict(
            existing.getContent(),
            existing.getTime()))
        .toList();
}

private boolean isOverlap(TodoItem a, TodoItem b) {
    // 简化的重叠检测逻辑
    return !a.getTime().isAfter(b.getEndTime()) 
        && !b.getTime().isAfter(a.getEndTime());
}

5.3 性能优化技巧

1. 缓存用户偏好：避免每次调用都查询数据库

   java复制@Cacheable(value = "userPrefs", key = "#userId")
   public UserPreference getPreferences(String userId) {
       // ...
   }
   

2. 批量冲突检测：对于高频使用场景，可以考虑使用时间区间索引

   java复制@Document
   public class TodoItem {
       @Indexed
       private LocalDateTime time;
       
       @Indexed 
       private LocalDateTime endTime;
   }
   

3. 异步处理非关键路径：如建议生成可以异步执行

   java复制@Async
   public CompletableFuture<List<Suggestion>> generateSuggestionsAsync(TodoItem item) {
       // ...
   }
   

6. 常见问题与调试技巧

在实际开发中，我们可能会遇到以下典型问题：

6.1 Tool调用未触发

症状：AI模型没有识别出应该调用Tool
排查步骤：

1. 检查Tool的description是否准确描述了功能
2. 验证用户输入是否包含足够明确的意图
3. 在application.properties中增加调试日志：

   properties复制logging.level.org.springframework.ai=DEBUG
   

6.2 返回值序列化异常

错误现象：收到500错误或序列化失败日志
解决方案：

1. 确保自定义返回值类型有无参构造器
2. 检查字段的getter方法是否正确定义
3. 对于复杂类型，考虑实现Serializable接口

6.3 处理器执行顺序问题

场景：多个PostProcessor存在依赖关系
控制方法：

java复制@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // 最高优先级
public class ValidationProcessor implements ToolResponsePostProcessor {
    // ...
}

@Component 
@Order(Ordered.LOWEST_PRECEDENCE) // 最低优先级
public class LoggingProcessor implements ToolResponsePostProcessor {
    // ...
}

6.4 生产环境监控建议

建议添加以下监控指标：

1. Tool调用成功率
2. 平均响应时间
3. 冲突检测准确率
4. 建议采纳率

可以通过Spring Actuator暴露这些指标：

java复制@Bean
public MeterRegistryCustomizer<MeterRegistry> metrics() {
    return registry -> {
        registry.config().commonTags("application", "todo-ai");
        // 注册自定义指标
    };
}

7. 架构演进与扩展思路

随着业务发展，我们可以考虑以下方向扩展系统能力：

7.1 多步骤Tool调用

实现跨Tool的上下文保持，例如：

1. 用户："提醒我明天买生日礼物"
2. AI："好的，需要我推荐礼物吗？"
3. 用户："要，预算500元左右"
4. AI："根据您的喜好，推荐..."

这需要维护跨请求的对话状态：

java复制public class GiftSuggestionState {
    private String occasion;
    private int budget;
    private List<String> preferences;
    
    // 保存在分布式缓存中
}

7.2 与知识库集成

将公司内部知识库接入建议系统：

java复制public List<Suggestion> generateKnowledgeBasedSuggestions(TodoItem item) {
    List<Document> docs = vectorStore.similaritySearch(item.getContent());
    return docs.stream()
        .map(doc -> new Suggestion(
            "KNOWLEDGE",
            "相关文档：" + doc.getMetadata().get("title"),
            "VIEW_DOC_" + doc.getId()
        ))
        .toList();
}

7.3 移动端适配优化

针对移动端特点优化返回值结构：

java复制public class MobileTodoResponse {
    private String shortMessage;
    private List<QuickAction> quickActions;
    private String notificationSound;
    
    // 特殊字段处理...
}