：当一行代码背后发生的故事

在Java开发者的世界里Spring AI 似乎正在成为通往大模型时代的“任意门”。我们习惯了在代码中轻描淡写地敲下 ChatClient.builder.build，然后kan着屏幕上流式吐出智Neng的回答。这种丝滑的体验hen容易让人产生一种错觉：AI开发不过就是调几个API的事。

然而作为技术人，我们骨子里dou有一种“死磕”的精神。知其然geng要知其所以然。当你按下回车键的那一瞬间，到底在框架的深渊里发生了什么？为什么加了一个 Advisor，原本无状态的AI突然就有了记忆？为什么把OpenAI换成通义千问，业务代码竟然连一行dou不用改？

今天我们就基于Zui新的 Spring AI 1.1.4 版本，拨开代码的迷雾，进行一次深度的底层原理解析。这不仅仅是一次代码阅读，geng是一场关于架构设计的思维体操。

宏观视角：模块化的艺术与门面模式

在深入细节之前，我们必须先站在高处俯瞰整个 Spring AI 的版图。Ru果你直接扎进源码的细节里hen容易迷失在类的海洋中。Spring AI 的架构之所以优雅，核心在于它极其严格的分层设计。

它并不是一个铁板一块的巨石应用，而是由多个职责单一的模块组合而成的有机体。我们Ke以kan到几个核心的模块划分：

spring-ai-model这是整个世界的基石，定义了 ChatModelEmbeddingModel 等核心抽象接口。

spring-ai-client-chat这是面向开发者的 fluent API，也就是我们常用的 ChatClient，以及 Advisor 的 SPI 机制。

spring-ai-vector-store负责向量数据库的交互，内置了强大的 ANTLR4 过滤表达式解析器。

spring-ai-rag检索增强生成的具体实现，包含了查询转换、文档检索等逻辑。

spring-ai-retry专门处理网络抖动和重试逻辑的通用模块。

依赖关系的解耦

这里有一个极其精妙的设计哲学：你的业务代码永远只依赖 spring-ai-model 和 spring-ai-client-chat。这就意味着，Ru果明天你想把底层模型从 OpenAI 换成智谱 AI 或者阿里通义千问，业务代码一行dou不用改！

这种“门面接口与底层仓储分离”的设计，让框架拥有了极强的 性。所有的实现类dou只是对核心接口的忠实履行。对于上层业务而言，底层是谁在干活，根本不重要。

核心引擎：ChatModel 与流式响应

ChatModel 是所有对话模型的鼻祖，Ke以说是万物起源。它的核心职责极其纯粹：接收提示词，返回响应。

在 Java 生态中，Spring AI Yi经成为开发者拥抱大模型时代的首选利器。hen多人用它写出了酷炫的对话机器人、智Neng客服，甚至成功接入了私有知识库。但这一切的起点，dou是这个接口。

public interface ChatModel extends Model, StreamingChatModel {
    // 核心同步方法
    ChatResponse call;
    // 便捷方法：字符串直接转 Prompt，这就是适配器模式的体现
    default String call {
        return this.call));
    }
}

亮点解析：在类定义中，它巧妙地使用了多继承，同时继承了 Model 泛型接口和 StreamingChatModel 流式接口，在高度抽象的同时保证了Neng力的完整性。

流式输出的实现细节

为了应对大模型打字机效果的流式输出，Spring AI 专门抽离了流式接口。这不仅仅是简单的返回一个 Flux，背后隐藏着对响应式编程模型的深刻理解。

@FunctionalInterface
public interface StreamingChatModel extends StreamingModel {
    // 便捷方法：自动包装 Prompt，并直接提取流式文本
    default Flux stream {
        return stream))
            .map.getOutput.getText);
    }
    // 核心流式方法
    Flux stream;
}

kan完了接口，我们来kankan真正干活的实现类。这里隐藏着重试机制与工具调用的核心奥秘。在 OpenAiChatModel 中，你会发现一个 internalCall 方法，它不仅负责发送请求，还通过 Spring RetryTemplate 包裹了网络请求，极大地提升了容错率。

记忆的奥秘：如何让 AI 拥有“海马体”

日常开发中，我们赋予大模型“记忆”的代码非常简单。但为什么加了一个 Advisor，无状态的 AI 就有了记忆？因为 Spring AI 设计了一套基于 Deque的弹出式拦截器链 。

前面我们在拦截器中kan到了 MessageChatMemoryAdvisor，那这些历史对话具体是存在哪里、又是如何管理的呢？这就不得不提 Spring AI 中极其优雅的记忆抽象设计。

门面接口：ChatMemory

这是面向业务开发者的顶层接口，相当于大模型的“海马体”。它只关心Zui核心的四个动作：增加、批量增加、查询、清空。

public interface ChatMemory {
    String DEFAULT_CONVERSATION_ID = "default";
    void add;
    void add;
    List get;
    void clear;
}

底层实现：ChatMemoryRepository

光有接口不行，记忆Zui终得落地。ChatMemoryRepository 负责实际的存储逻辑。框架内置了基于内存的 InMemoryChatMemory，同时也支持通过 接入 Redis、PostgreSQL 等持久化数据库，确保服务重启后 AI 不会“失忆”。

public interface ChatMemoryRepository {
    List findConversationIds;
    List findByConversationId;
    void saveAll;
    void deleteByConversationId;
}

窗口策略：为什么需要 MessageWindowChatMemory？

大模型的上下文窗口是极其宝贵且有上限的。Ru果不加节制地把几百轮历史对话全塞进 Prompt 里不仅每次调用的 API 费用会原地起飞，还极易触发“Token 爆栈”错误。

为此，Spring AI 提供了 MessageWindowChatMemory来精准控场。它的底层驱逐算法遵循着极其严密的逻辑，确保只保留Zui近Zui重要的 N 条消息，而将过期的信息无情地剔除。这种“遗忘”机制，恰恰是系统长期稳定运行的关键。

智Neng的双手：Function Calling 的递归之美

大模型本质上无法直接理解文字，它们只认识“向量”。但geng关键的是大模型本身不Neng查天气、不Neng查数据库，必须依赖本地代码。Spring AI 的 ToolCallAdvisor 实现了一个极其精妙的递归执行循环。

假设你注册了一个 @Bean 或者 java.util.function.Function 作为工具，框架是如何在 JSON 和 Java 方法之间搭建桥梁的呢？

在 OpenAiChatModel 的源码中，我们Ke以kan到一个 internalCall 方法，它处理了工具调用的核心逻辑：

private ChatResponse internalCall {
    // 1. 构建底层 API 请求
    ChatCompletionRequest request = createRequest;
    // ... 观察上下文 ...
    // 2. 执行重试和观察
    return ChatModelObservationDocumentation.CHAT_MODEL_OPERATION
        .observation.observe -> {
            // 使用 Spring RetryTemplate 包裹网络请求
            ResponseEntity completionEntity = 
                this.retryTemplate.execute(ctx -> 
                    this.openAiApi.chatCompletionEntity);
            // 3. 转换为 Spring AI 标准的 Generation 格式
            List generations = choices.stream
                .map)
                .toList;
            // 4. 处理工具执行
            if ) {
                // 内部执行本地 Java 方法
                ToolExecutionResult toolExecutionResult = 
                    this.toolCallingManager.executeToolCalls;
                // ⚠️ 隐式递归调用：将工具执行结果重新塞回 Prompt，
请求大模型
                return this.internalCall, response);
            }
            return response;
        });
}

对于流式响应，情况geng复杂，因为工具调用的 JSON 是一段段返回的。Spring AI 在底层的 OpenAiStreamFunctionCallingHelper 中实现了极其复杂的 merge逻辑，把散落的 chunks 拼成完整的工具调用参数。

上下文透传与 ToolContext

大模型在调用本地工具时往往不Neng只传一个“订单号”，工具方法可Neng还需要知道“当前登录的用户是谁？”、“用户的鉴权 Token 是什么？”。这就需要一套机制来跨越层层拦截器，把业务上下文透传给底层工具。

这就是 ToolContext 的作用：

public final class ToolContext {
    public static final String TOOL_CALL_HISTORY = "TOOL_CALL_HISTORY";
    private final Map context;
    // 工具可访问的内容
    public Map getContext { return this.context; }
    // 获取工具执行前的对话历史
    public List getToolCallHistory { ... }
}

在构建上下文时框架会巧妙地将用户提供的参数与对话历史合并，生成一个不可变的 Map 传递给执行器。这种设计既保证了安全性，又提供了足够的灵活性。

知识的海洋：向量存储与过滤表达式

我们不仅要kan向量相似度，还要Zuo属性过滤。比如：只搜索“状态为活跃”且“年份大于 2020”的文档。Spring AI 提供了类似 MyBatis-Plus 的 DSL 语法，这背后其实隐藏着一个强大的编译器技术。

内置了一个 ANTLR4 语法分析器！你Ke以直接传字符串："country == 'UK' && year>= 2020"。底层通过 FilterExpressionTextParser 解析生成一棵抽象语法树。然后框架使用不同的 Converter，把这棵树翻译成各种向量数据库认识的。

var b = new FilterExpressionBuilder;
var exp = b.and, b.gte);

Embedding 维度的“探路”机制

大模型本质上无法直接理解文字，它们只认识“向量”。EmbeddingModel 的职责就是将文本转化为 float。在 AbstractEmbeddingModel 基类中，隐藏着一个极其巧妙的细节：

// 缓存维度数，避免每次请求dou调用 API 去计算
protected final AtomicInteger embeddingDimensions = new AtomicInteger;
public int dimensions {
    if  <0) {
        // Ru果不知道维度，先拿 "Test" 跑一次 API 探探路，然后缓存起来
        this.embeddingDimensions.set);
    }
    return this.embeddingDimensions.get;
}

通过这种“探路+缓存”机制，框架在处理复杂的向量库操作时避免了频繁的元数据查询，极大地节约了 Token 和网络请求时间。这种细节上的打磨，才是一个成熟框架该有的样子。

拦截器链：请求的“过五关斩六将”

当请求发出时犹如过五关斩六将。Spring AI 的 DefaultAroundAdvisorChain 负责协调各种 Advisor 的执行顺序。

public ChatClientResponse nextCall {
    if ) {
        throw new IllegalStateException;
    }
    // 弹出下一个 advisor 执行
    var advisor = this.callAdvisors.pop;
    return AdvisorObservationDocumentation.AI_ADVISOR
        .observation
        .observe -> {
            // 当前 advisor 调用链
            var response = advisor.adviseCall;
            return response;
        });
}

一个典型的执行流程如下：

Request Path - before methods

toolCallAdvisor.before --> 初始化工具调用循环

ragAdvisor.before --> 检索文档，增强查询

memoryAdvisor.before --> 添加对话历史

Terminal - 实际 AI 调用

ChatModelCallAdvisor.adviseCall --> 调用 chatModel.call

Response Path - after methods

memoryAdvisor.after --> 存储助手回复到记忆

ragAdvisor.after --> 添加文档到响应元数据

toolCallAdvisor.after --> 检测并执行工具调用，循环直到完成

Spring AI 1.1.4 不仅仅是一个简单的 SDK 封装，它是一套经过深思熟虑的企业级架构。从模块的解耦设计，到流式响应的细腻处理；从记忆管理的滑动窗口策略，到 Function Calling 的递归优雅，每一处细节dou体现了开发者对复杂度的极致控制。

理解了这些底层原理，当你 使用 ChatClient 时kan到的就不再是一个简单的 Builder 模式，而是一台精密运转的机器。希望这次深度的拆解，Neng帮助你在未来的 AI 开发之路上，走得geng稳、geng远。

---