此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！spring-doc.cadn.net.cn

递归顾问

什么是递归顾问？

Advisors Recursive 递归顾问是一种特殊类型的顾问，可以多次遍历下游顾问链。 当需要重复调用LLM直到满足特定条件时，此模式非常有用，例如：spring-doc.cadn.net.cn

CallAdvisorChain.copy(CallAdvisor after) 方法是实现递归通知器模式的关键工具。 它创建了一个新的通知器链，该链仅包含原始链中指定通知器之后的通知器， 并允许递归通知器根据需要调用此子链。 这种方法确保了：spring-doc.cadn.net.cn

内置递归顾问

Spring AI 提供了两个内置的递归顾问（recursive advisors），用于演示此模式：spring-doc.cadn.net.cn

工具调用顾问

ToolCallAdvisor 将工具调用循环作为顾问链的一部分来实现，而不是依赖模型的内部工具执行。这使得链中的其他顾问能够拦截并观察工具调用过程。spring-doc.cadn.net.cn

主要特性：spring-doc.cadn.net.cn

  • 通过设置 setInternalToolExecutionEnabled(false) 来禁用模型的内部工具执行spring-doc.cadn.net.cn

  • 遍历顾问链，直到不再存在工具调用为止spring-doc.cadn.net.cn

  • 支持“直接返回”功能 - 当工具执行的返回值为 returnDirect=true 时，将中断工具调用循环，并将工具执行结果直接返回给客户端应用，而不是将其发送回大语言模型（LLM）spring-doc.cadn.net.cn

  • 使用 callAdvisorChain.copy(this) 为递归调用创建子链spring-doc.cadn.net.cn

  • 包含空安全性检查，以处理聊天响应可能为 null 的情况spring-doc.cadn.net.cn

  • 通过 conversationHistoryEnabled 支持可配置的对话历史管理spring-doc.cadn.net.cn

示例用法：spring-doc.cadn.net.cn

var toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(toolCallAdvisor)
    .build();

会话历史管理

ToolCallAdvisor 包含一个 conversationHistoryEnabled 配置选项，用于控制在工具调用迭代过程中对话历史的管理方式。spring-doc.cadn.net.cn

默认情况下（conversationHistoryEnabled=true），顾问会在工具调用迭代期间在内部维护完整的对话历史。这意味着在工具调用循环中的每次后续LLM调用都会包含所有之前的消息（用户消息、助手回复、工具回复）。spring-doc.cadn.net.cn

使用 .disableInternalConversationHistory() 方法可禁用内部对话历史管理。禁用后，仅将上一次工具响应消息传递给下一次迭代。这在以下情况下很有用：spring-doc.cadn.net.cn

对话历史禁用的示例：spring-doc.cadn.net.cn

var toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .disableInternalConversationHistory()  // Disable internal history - let ChatMemory handle it
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();

var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 200)  // Positioned before ToolCallAdvisor
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(chatMemoryAdvisor, toolCallAdvisor)
    .build();

返回直接功能

“直接返回”功能允许工具绕过大语言模型（LLM），将其结果直接返回给客户端应用程序。当满足以下情况时，该功能非常有用：spring-doc.cadn.net.cn

当工具执行结果为 returnDirect=true 时，ToolCallAdvisor 将：spring-doc.cadn.net.cn

  1. 正常执行工具调用spring-doc.cadn.net.cn

  2. 检测 returnDirect 标志的 ToolExecutionResultspring-doc.cadn.net.cn

  3. 跳出工具调用循环spring-doc.cadn.net.cn

  4. 直接将工具执行结果以 ChatResponse 的形式返回给客户端应用程序，工具的输出作为生成内容spring-doc.cadn.net.cn

结构化输出验证顾问

StructuredOutputValidationAdvisor 会将结构化的 JSON 输出与生成的 JSON 模式进行验证，如果验证失败，则最多重试指定次数。spring-doc.cadn.net.cn

主要特性：spring-doc.cadn.net.cn

示例用法：spring-doc.cadn.net.cn

var validationAdvisor = StructuredOutputValidationAdvisor.builder()
    .outputType(MyResponseType.class)
    .maxRepeatAttempts(3)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 1000)
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(validationAdvisor)
    .build();