Spring AI 进阶指南：Hooks、Interceptors 与 Advisors 的深度辨析-牧云

在构建基于大语言模型（LLM）的应用时，开发者经常面临一个困惑：我该如何控制模型的输入输出？又该如何管理智能体（Agent）的复杂执行流程？

在 Spring AI 生态系统中，你可能会遇到三个相似但截然不同的概念：

Spring AI Core 的 Advisors
Spring AI Alibaba Agent 的 Hooks
Spring AI Alibaba Agent 的 Interceptors

很多开发者容易将它们混为一谈。本文将通过通俗易懂的比喻、架构对比和实战代码，彻底厘清这三者的区别、联系以及最佳使用场景。

1. 核心概念速览

为了直观理解，我们先给它们贴上简单的标签：

Advisors (顾问)：专注于 “单次对话”。它是 LLM 调用层面的拦截器，负责优化 Prompt、管理记忆、解析输出。
Hooks (钩子)：专注于 “Agent 生命周期”。它是事件监听器，在 Agent 开始、结束或状态变更时触发，用于监控和状态管理。
Interceptors (拦截器)：专注于 “具体动作执行”。它是工具调用或模型请求的守门员，负责重试、熔断、权限校验等逻辑。

一句话总结：
Advisors 让模型聊得更好；Hooks/Interceptors 让 Agent 跑得更稳、更可控。

2. 形象比喻：餐厅运营体系

想象你正在经营一家高级餐厅：

LLM (大模型) 是厨师。
Agent (智能体) 是 餐厅经理，他负责接单、指挥厨师、安排服务员、处理突发状况。

组件	角色比喻	职责描述
Advisors	厨师的助手	在厨师做菜前帮他整理菜谱（Prompt Enhancement），或者在他做完菜后摆盘（Output Parsing）。他们只关心这一道菜怎么做，不关心餐厅的整体运营。
Hooks	经理的日志员/监督员	记录经理今天接了多少单（Monitoring），在经理决定开除员工前提醒他需要董事会批准（HumanInTheLoop），或者在账本太厚时帮经理总结上月财报（Summarization）。他们关心经理的决策流程。
Interceptors	采购员的过滤器	当经理派采购员去买菜（调用工具）时，如果菜市场关门了，采购员会自动换一家店重试（ToolRetry）。他们关心具体任务的执行可靠性。

3. 深度技术对比

3.1 作用层级不同

特性	Spring AI Advisors	Spring AI Alibaba Hooks/Interceptors
所属模块	`spring-ai-core`	`spring-ai-alibaba-agent`
作用对象	`ChatClient` / `ChatModel`	`ReactAgent` (ReAct 智能体)
拦截时机	LLM 请求发送前 / 响应接收后	Agent 循环开始前/后、工具调用前后
状态感知	弱（通常仅关注当前 Message）	强（可访问 `OverAllState` 全局状态）
核心能力	记忆注入、提示词增强、格式转换	流程控制、人机协同、工具重试、隐私脱敏

3.2 设计哲学不同

Advisors 是“无状态”或“浅状态”的：
它的设计初衷是增强单一的 Chat 交互。例如，MessageChatMemoryAdvisor 只是把历史记录塞进 Prompt 里，它并不关心这次对话之后 Agent 要去干什么。
Hooks/Interceptors 是“强状态”和“流程导向”的：
Agent 是一个循环过程（观察 -> 思考 -> 行动）。Hooks 可以读取 Agent 当前的所有变量，决定下一步是否继续；Interceptors 可以拦截具体的 Tool 执行，决定是重试还是报错。

4. 实战代码对比

场景 A：使用 Advisors 优化单次对话

假设你只需要一个简单的聊天机器人，带有记忆功能。

// Spring AI Core 风格
@Autowired
private ChatClient chatClient;

public String chat(String userMessage) {
    return chatClient.prompt()
        // 1. 注入历史记忆
        .advisors(new MessageChatMemoryAdvisor(chatMemory)) 
        // 2. 失败自动重试
        .advisors(new RetryAdvisor(3))                      
        .user(userMessage)
        .call()
        .content();
}

特点：简单直接，适用于非 Agent 场景或 Agent 内部的底层 LLM 调用优化。

场景 B：使用 Hooks/Interceptors 构建健壮 Agent

假设你要构建一个能调用外部 API、需要人工确认高风险操作、且具备容错能力的智能体。

// Spring AI Alibaba Agent 风格
ReactAgent agent = ReactAgent.builder()
    .name("customer_service_agent")
    .model(chatModel)
    .tools(refundTool, queryOrderTool)
    
    // --- Hooks: 控制流程与状态 ---
    // 1. 长对话自动压缩，防止 Token 溢出
    .hooks(SummarizationHook.builder().maxTokensBeforeSummary(4000).build())
    // 2. 高风险操作前暂停，等待人工审批
    .hooks(HumanInTheLoopHook.builder()
        .approvalOn("refundTool", ToolConfig.builder().description("请确认退款").build())
        .build())
        
    // --- Interceptors: 控制执行可靠性 ---
    // 3. 工具调用失败自动重试 2 次
    .interceptors(ToolRetryInterceptor.builder().maxRetries(2).build())
    // 4. 检测并脱敏用户输入中的手机号/邮箱
    .interceptors(PIIDetectionInterceptor.builder().build())
    
    .build();

// 执行 Agent
agent.call("帮我查询订单并申请退款");

特点：控制了 Agent 的“大脑”如何思考、“手脚”如何行动，以及整个流程如何监控。

5. 常见误区与最佳实践

误区 1：“我用了 Advisor 做记忆，就不需要 Hook 了？”

纠正：Advisor 的记忆是面向 LLM 的（放入 Context Window），而 Hook 可以管理更复杂的业务状态（如存入数据库、Redis）。对于长运行时的 Agent，建议使用 SummarizationHook 来管理长期上下文，而用 MessageChatMemoryAdvisor 管理短期滑动窗口。

误区 2：“Interceptors 和 Advisors 都能做重试，选哪个？”

纠正：

如果是 LLM 本身 超时或报错，用 RetryAdvisor。
如果是 调用的工具（如 API 接口）报错，用 ToolRetryInterceptor。
最佳实践：两者可以共存。LLM 重试保证“大脑”在线，工具重试保证“手脚”灵活。

误区 3：“Hooks 可以修改 LLM 的输出吗？”

纠正：Hooks 主要修改的是 Agent 的状态（State） 或 消息列表（Messages），而不是直接修改 LLM 的原始文本输出。如果你想格式化 LLM 的输出为 JSON，应该在底层 ChatClient 中使用 BeanOutputAdvisor。

6. 架构融合：它们如何协同工作？

在一个生产级的 Spring AI Alibaba 应用中，这三者通常是分层协作的：

graph TD User[用户请求] --> Agent[ReactAgent] subgraph Agent Layer [Spring AI Alibaba Agent] HookStart[Hook: beforeAgent 记录开始时间/初始化状态] Loop{Agent Loop} HookEnd[Hook: afterAgent 记录结束时间/清理资源] Loop --> InterceptorTool[Interceptor: ToolExecution 权限校验/重试/缓存] InterceptorTool --> Tool[外部工具/API] Loop --> LLMCall[LLM Call] end subgraph ChatClient Layer [Spring AI Core] LLMCall --> AdvisorMem[Advisor: Memory 注入历史消息] AdvisorMem --> AdvisorPrompt[Advisor: Prompt Enhance 优化提示词] AdvisorPrompt --> Model[LLM Model] end Tool --> Loop Model --> Loop Loop --> HookEnd HookStart --> Loop

graph TD
    User[用户请求] --> Agent[ReactAgent]
    
    subgraph Agent Layer [Spring AI Alibaba Agent]
        HookStart[Hook: beforeAgent<br/>记录开始时间/初始化状态]
        Loop{Agent Loop}
        HookEnd[Hook: afterAgent<br/>记录结束时间/清理资源]
        
        Loop --> InterceptorTool[Interceptor: ToolExecution<br/>权限校验/重试/缓存]
        InterceptorTool --> Tool[外部工具/API]
        
        Loop --> LLMCall[LLM Call]
    end
    
    subgraph ChatClient Layer [Spring AI Core]
        LLMCall --> AdvisorMem[Advisor: Memory<br/>注入历史消息]
        AdvisorMem --> AdvisorPrompt[Advisor: Prompt Enhance<br/>优化提示词]
        AdvisorPrompt --> Model[LLM Model]
    end
    
    Tool --> Loop
    Model --> Loop
    Loop --> HookEnd
    HookStart --> Loop

外层 (Agent)：Hooks 监控整体流程，Interceptors 保障工具调用的稳定性。
内层 (ChatClient)：Advisors 优化每一次与 LLM 的交互质量。

7. 总结：什么时候用什么？

你的需求	推荐组件	示例
我要给聊天机器人加记忆	`Advisor`	`MessageChatMemoryAdvisor`
我要让 LLM 输出 JSON 对象	`Advisor`	`BeanOutputAdvisor`
我要防止 Agent 无限循环	`Hook`	`ModelCallLimitHook`
我要在删除数据前让人工确认	`Hook`	`HumanInTheLoopHook`
我要在对话太长时自动总结	`Hook`	`SummarizationHook`
我要在 API 调用失败时重试	`Interceptor`	`ToolRetryInterceptor`
我要过滤用户输入的敏感信息	`Interceptor`	`PIIDetectionInterceptor`

结论：
不要将它们是互斥的。Advisors 是微观的对话优化器，Hooks/Interceptors 是宏观的流程控制器。 在构建复杂的 Agent 应用时，组合使用这三者，才能打造出既聪明又稳健的智能体。

目录CONTENT

Spring AI 进阶指南：Hooks、Interceptors 与 Advisors 的深度辨析