FDE W7D2 学习手册 · Spring AI Tool Calling 与 Chat Memory

W7 周级拆解 Day2 · A 级（必须掌握，面试核心）· 约 4h · 学完能讲清"Java 侧如何让模型调本地方法、以及如何管理多轮会话记忆"

一、Tool Calling 概览：让模型调你的 Java 方法

1.1 是什么

Tool Calling（工具调用）让 LLM 在对话中"决定调用哪个本地函数、填什么参数"，Spring AI 负责把你的 Java 方法暴露成工具描述（JSON Schema）发给模型，模型返回调用请求后，框架本地执行并把结果回灌模型。

1.2 在 Java 企业平台的典型用途

• 查保单系统（调 Java 服务查数据库）。
• 调用特药目录 API 校验药品是否在目录。
• 触发理赔工单创建（副作用操作需谨慎）。

二、@Tool 注解定义工具

2.1 定义方式

@Service
public class PolicyTools {

    @Tool(description = "根据保单号查询保单基本信息：投保人、险种、生效日、状态")
    public String queryPolicy(@ToolParam(description = "保单号，如 PA2024XXXX") String policyNo) {
        return policyService.getPolicy(policyNo).toJson();
    }

    @Tool(description = "校验某药品是否在特药目录，返回是否覆盖及自付比例")
    public String checkSpecialDrug(@ToolParam(description = "药品通用名") String drugName) {
        return drugCatalogService.check(drugName).toJson();
    }
}

2.2 关键注解

三、ToolCallback 与自动注册到 ChatClient

3.1 ToolCallback

每个 @Tool 方法会被扫描成一个 ToolCallback（含工具名、schema、可执行引用）。Spring AI 提供 MethodToolCallback.builder() 或自动扫描 @Bean 工具类。

3.2 注册方式

// 方式A：自动扫描（@Tool 的 Spring Bean 自动注册）
ChatClient client = ChatClient.builder(chatModel)
        .defaultTools(policyTools, drugTools)  // 直接传工具对象
        .build();

// 方式B：显式 ToolCallback
ToolCallback[] callbacks = ToolCallbacks.from(policyTools, drugTools);
ChatClient client2 = ChatClient.builder(chatModel).defaultTools(callbacks).build();

// 调用时也可临时指定
String r = client.prompt().user("查一下保单 PA2024XXXX").tools(policyTools).call().content();

四、工具调用完整执行流程

1. 注入：ChatClient 携带工具 schema 请求模型。
2. 决策：模型返回 tool_calls（工具名 + 参数 JSON），不生成最终文本。
3. 执行：Spring AI 按名字找到 ToolCallback，本地反射执行 Java 方法。
4. 回灌：把执行结果作为 tool 角色消息追加进对话历史。
5. 续生成：模型拿到结果继续生成，直到不再请求工具、输出最终答案。

五、ChatMemory：会话记忆抽象

5.1 是什么

ChatMemory 是 Spring AI 对"多轮对话历史存储"的抽象接口，负责按 conversationId 存取 Message 列表。模型本身无状态，记忆靠外部存储维持。

5.2 核心方法

• add(conversationId, message)：追加消息。
• get(conversationId, n)：取最近 n 条。
• clear(conversationId)：清空会话。

六、ChatMemory 多种实现（InMemory / Redis / JDBC）

6.1 代码示例

// Redis 实现（生产推荐）
ChatMemory redisMem = RedisChatMemory.builder(redisConnectionFactory).build();
ChatClient client = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(redisMem).build())
    .build();
// 调用时带 conversationId
client.prompt().advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "user-7788"))
       .user("我上次问的特药能报多少？").call().content();

七、与 W2 Tool Calling、W4 Agent 的关系

八、Advisor 与 Memory 配合（MessageChatMemoryAdvisor）

8.1 如何接

MessageChatMemoryAdvisor 在调用前从 ChatMemory 取出历史注入 prompt，调用后把本轮消息写回。它是 s4 讲过的 Advisor 链的一员。

ChatClient client = ChatClient.builder(chatModel)
    .defaultAdvisors(
        MessageChatMemoryAdvisor.builder(redisMem).build(),  // 记忆注入
        new AuditAdvisor(meterRegistry)                      // Trace 埋点
    ).build();

8.2 顺序

• 记忆 Advisor 应在"改写/RAG"之前，保证注入的是完整历史。
• Trace/日志 Advisor 可在最外层，包裹整个调用。

九、生产注意事项（状态隔离 / 过期 / 成本）

• 状态隔离：conversationId 必须来自可信会话标识（登录态 user_id + session_id），不能由模型/用户乱传，防串号。
• 过期策略：Redis 记忆设 TTL（如 30 分钟无活动过期），Jdbc 定时清理。
• 窗口裁剪：get(id, n) 只取最近 n 条；超长会话用摘要压缩（另一轮 LLM 把历史压成小结）。
• 成本：每轮都把历史重发给模型，长会话 token 成本线性增长，要监控（呼应 W4 cost 字段）。
• 合规：记忆里可能含用户隐私（保单号、身份证），存储要加密、访问要审计。

十、与 W3 会话状态的关系

十一、学习资源（中文 / 官方）

• Spring AI Tool Calling 文档（docs.spring.io/spring-ai/reference/api/tools.html）——@Tool、ToolCallback、注册方式精读。
• Spring AI Chat Memory 文档（docs.spring.io/spring-ai/reference/api/chat-memory.html）——InMemory/Redis/JDBC 实现对照。
• B站：Spring AI 全套 84 集（BV1GfyGBqEm6）——重点看"工具调用""会话记忆"相关集。
• Spring AI GitHub samples——spring-ai-examples/tool、chat-memory 可运行示例。

十二、面试达标线①：Spring AI Tool Calling 怎么定义和注册

十三、面试达标线②：Chat Memory 接不同存储、与 W3 会话状态的关系

1. 接不同存储：ChatMemory 是接口，InMemory（单机 demo）、Redis（分布式生产）、Jdbc（审计持久化）都是实现；通过 MessageChatMemoryAdvisor 接进 Advisor 链；调用时用 conversationId 关联。选型看是否跨实例、是否需持久化、成本。
2. 与 W3 会话状态关系：W3 讲会话状态的"外置/隔离/持久化/过期"设计原则，W7D2 的 ChatMemory 是这些原则的 Java 落地——ChatMemory 接口 = W3 的抽象，Redis/JDBC 实现 = W3 的持久化方案。一脉相承。
3. 生产要点：conversationId 强隔离防串号、设过期 TTL、窗口裁剪控成本、敏感数据加密存储。

十四、W7D2 自测清单

十五、高频面试题速记卡