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

递归顾问

什么是递归顾问？

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

`0` 方法是实现递归顾问模式的关键工具。它可以根据原始链中的指定顾问创建一个新的顾问链，仅包含该指定顾问之后的所有顾问，并允许递归顾问在需要时调用这个子链。 这种做法确保了：spring-doc.cadn.net.cn

内置递归顾问

Spring AI 提供了两个内置递归顾问，展示了这一模式：spring-doc.cadn.net.cn

ToolCallAdvisor

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

关键功能：<br/>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. 检测ToolExecutionResult中的returnDirect标志spring-doc.cadn.net.cn

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

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

StructuredOutputValidationAdvisor

StructuredOutputValidationAdvisor 根据生成的JSON模式验证结构化的JSON输出，并在验证失败时重新尝试调用，最多尝试指定次数。spring-doc.cadn.net.cn

关键功能：<br/>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();