LangChain4j 的 Spring Boot 3.x 深度集成

概述

系列定位：本文是“AI 应用核心框架与协议”系列的第 3 篇。在拆解了 LangChain4j 的源码内核（本系列第 2 篇）之后，我们将其放入 Spring Boot 3.x 的自动配置框架中，展示如何用声明式、自动化的方式构建生产级 AI 应用。掌握 Spring Boot 的集成原理，是构建企业级 AI 应用基础设施的重要前提。

总结性引言：在系列一的 Hello World 中，你写了一堆 main 方法里的配置代码来组装一个 Agent。前两篇文章中，我们看清了 Python 与 Java 框架的宏观差异，并深入了 LangChain4j 的动态代理源码。现在是时候让 Spring Boot 接管一切了。如果你对 Spring Boot 的自动配置——@SpringBootApplication 扫描、@ConfigurationProperties 绑定、@ConditionalOnClass 条件装配——已经了然于胸，那么你会发现 LangChain4j 与 Spring Boot 的集成是那样自然，如同 Spring 生态原生模块一般。只需在 application.yml 中配置 langchain4j.openai.api-key，定义一个带 @AiService 注解的接口，你就可以在任何 Controller 中像注入普通 Service 一样注入一个能自主推理、调用工具、记住对话的 AI Agent。Spring Boot 替你处理了 ChatModel 的单例管理、ChatMemory 的会话隔离、@Tool 的依赖注入，甚至通过 GraalVM Native Image 的支持，将这个 Agent 编译成一个 20 MB 的二进制文件秒级启动。本文将从自动配置内核、@AiService 装配、多模型路由，到 Native Image 兼容和 Spring Cloud 集成，带你用 Spring Boot 的方式全面驾驭 AI 应用。

核心要点：

• 自动配置内核：LangChain4jAutoConfiguration 通过条件装配和属性绑定，将几行 YAML 配置转化为可用的 ChatModel Bean。
• 声明式 Agent：@AiService 注解配合 FactoryBean，让 Agent 的创建像声明一个 @Service 一样简单。
• 会话级记忆：ChatMemory 的 Session Scope 与 Redis ChatMemoryStore，实现多用户、跨服务的对话隔离与持久化。
• 生产级增强：GraalVM Native Image 支持（AOT）、Resilience4j 熔断保护、Micrometer 指标监控。
• 一句话总结：LangChain4j 在 Spring Boot 上的集成，将 AI Agent 开发从“手工装配时代”带入了“自动配置时代”。

文章组织架构图：

flowchart TD
    n1["1. 自动配置内核: 从YAML到Bean"] --> n2["2. 声明式Agent: @AiService的Spring装配"]
    n2 --> n3["3. 记忆的容器化管理"]
    n3 --> n4["4. 多模型与动态路由"]
    n4 --> n5["5. 生产级增强: GraalVM AOT与Spring Cloud"]
    n5 --> n6["6. 贯穿案例: 迁移Hello Agent"]
    n6 --> n7["7. 与前后系列的衔接"]
    n7 --> n8["8. 面试高频专题"]

    classDef nodeStyle fill:#f1f5f9,stroke:#334155,stroke-width:1.5px,color:#1e293b
    class n1,n2,n3,n4,n5,n6,n7,n8 nodeStyle

图表主旨概括：展示文章从自动配置原理出发，经过声明式编程、状态管理、路由策略，再到生产级部署与案例迁移的完整认知路径。 逐层分解：1 剖析启动器如何将 YAML 转化为模型 Bean；2 讲解 @AiService 代理的生成；3 阐述会话记忆的容器化存储；4 实现多模型动态路由；5 涵盖 AOT 编译、熔断和监控；6 用实际案例对比简化；7 关联系列前后篇章；8 提炼面试要点。 设计原理映射：遵循“自动配置 → 声明式代理 → 状态管理 → 弹性与可观测 → 实战”的工程化递进，符合 Spring 生态从简单到复杂的典型学习路径。 工程联系与关键结论：这张图是整个文章的骨架，每个模块都对应着将 AI 能力融入企业技术栈的一个关键步骤，理解它们的顺序与关联是掌握 LangChain4j Spring Boot 集成的核心。

---

1. 自动配置内核：从 YAML 到 Bean

Spring Boot 的哲学是“约定优于配置”，LangChain4j 的 Starter 完美地践行了这一理念。我们从 application.yml 开始，追踪一条从属性绑定到最终 ChatLanguageModel Bean 注册的完整链路。

1.1 属性源：LangChain4jProperties

@ConfigurationProperties(prefix = "langchain4j")
public class LangChain4jProperties {
    private OpenAi openAi = new OpenAi();
    private Ollama ollama = new Ollama();
    private Anthropic anthropic = new Anthropic();
    // 其他厂商...

    public static class OpenAi {
        private String apiKey;
        private String modelName = "gpt-3.5-turbo";
        private Double temperature = 0.7;
        private Double topP = 1.0;
        private Integer maxTokens = 2048;
        // getters and setters
    }
    // ...
}

解读：@ConfigurationProperties(prefix = "langchain4j") 将 YAML 中 langchain4j 下的所有配置自动绑定到这个属性类上。嵌套静态类对应不同模型厂商，每个厂商的内部属性直接映射到其 ChatLanguageModel 的 Builder 参数。属性绑定依赖 Spring Boot 的 ConfigurationPropertiesBindingPostProcessor，它会在 Bean 初始化后根据 prefix 将环境中的值注入。这为后续的条件装配提供了类型安全的配置源。

1.2 条件装配：LangChain4jAutoConfiguration

@AutoConfiguration
@EnableConfigurationProperties(LangChain4jProperties.class)
@ConditionalOnClass(ChatLanguageModel.class)
public class LangChain4jAutoConfiguration {

    @Bean
    @ConditionalOnProperty(name = "langchain4j.openai.api-key")
    @ConditionalOnMissingBean
    public OpenAiChatModel openAiChatModel(LangChain4jProperties props) {
        LangChain4jProperties.OpenAi config = props.getOpenAi();
        return OpenAiChatModel.builder()
                .apiKey(config.getApiKey())
                .modelName(config.getModelName())
                .temperature(config.getTemperature())
                .topP(config.getTopP())
                .maxTokens(config.getMaxTokens())
                .build();
    }

    // Anthropic、Ollama 等 Bean 的定义...
}

解读：这个配置类是整个 Starter 的核心。@AutoConfiguration（Spring Boot 2.7+ 的特定注解）告诉框架这是一个自动配置候选，会被 spring.factories 或 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 注册。@ConditionalOnClass(ChatLanguageModel.class) 确保只有当 LangChain4j 的核心库在 classpath 下时才加载此配置，避免误引入 Starter 但缺少实现库的问题。@EnableConfigurationProperties 激活 LangChain4jProperties 使其成为容器中的 Bean，以便在方法参数中直接注入。

每个模型 Bean 的创建方法上都标有 @ConditionalOnProperty(name = "langchain4j.openai.api-key")，这意味着只有在配置了 API Key 时，对应的模型 Bean 才会创建。这个细节非常重要：它避免了因为缺少配置而导致 Bean 创建失败进而引发启动异常。若未配置任何模型，启动依然正常，只是容器中没有 ChatLanguageModel 类型的 Bean，后续的 @AiService 也会因为缺少必需依赖而不会被创建。

1.3 多厂商共存与优先级

如果 classpath 下同时存在 langchain4j-openai 和 langchain4j-ollama 的 jar，且都配置了相应的属性，那么两个模型 Bean 都会被注册。此时，若某个 @AiService 需要注入一个 ChatLanguageModel，Spring 会发现两个类型匹配的 Bean，从而抛出 NoUniqueBeanDefinitionException。解决方式是配合 @Qualifier（见第4节）显式指定，或者使用 @ConditionalOnMissingBean 定义默认首选。

@Bean
@ConditionalOnMissingBean(ChatLanguageModel.class)
public OpenAiChatModel defaultChatModel(LangChain4jProperties props) { ... }

这样，除非用户自定义了同类型的 Bean 或明确禁用了默认行为，OpenAI 模型会作为默认的 ChatLanguageModel。这种策略体现了“约定优于配置”：提供一个开箱即用的默认模型，同时允许全量覆盖。

1.4 自动配置全景图

flowchart TD
    classDef nodeStyle fill:#f1f5f9,stroke:#334155,stroke-width:1.5px,color:#1e293b
    classDef decisionStyle fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#92400e

    A["application.yml"] -->|"@ConfigurationProperties绑定"| B["LangChain4jProperties"]
    B -->|"提供配置值"| C{"LangChain4jAutoConfiguration"}
    C -->|"@ConditionalOnClass"| D["检查类路径"]
    D -->|"ChatLanguageModel.class存在"| E["条件装配模型Bean"]
    E -->|"@ConditionalOnProperty api-key"| F["OpenAiChatModel Bean"]
    E -->|"@ConditionalOnProperty ..."| G["OllamaChatModel Bean"]
    F -->|"注册到"| H["Spring容器"]
    G --> H
    H -->|"@ConditionalOnMissingBean默认"| I["确定唯一的ChatLanguageModel"]

    class A,B,D,E,F,G,H,I nodeStyle
    class C decisionStyle

图表主旨概括：梳理从外部化配置到最终容器中 ChatLanguageModel Bean 的关键步骤与条件决策点。 逐层分解：application.yml 通过 @ConfigurationProperties 绑定到强类型属性对象；自动配置类检查 ChatLanguageModel 核心类是否存在；再依据厂商特定的 @ConditionalOnProperty 逐个判断是否创建对应的模型 Bean；最后通过 @ConditionalOnMissingBean 等机制确定唯一的主模型。 设计原理映射：这是 Spring Boot 条件装配在 AI 应用中的标准落地，利用配置门控和Bean竞争策略，实现了零硬编码的多模型管理。 工程联系与关键结论：掌握这条链路意味着你能通过修改几行 YAML 来切换不同的 LLM 提供商，而无需改动任何代码，这是将 AI 应用容器化的第一步。

---

2. 声明式 Agent：@AiService 的 Spring 装配

上一节解决了模型的来源，接下来要让 Agent 接口自动成为 Spring Bean，就像普通的 @Service 一样。

2.1 @AiService 注解与扫描

LangChain4j 定义了一个标记注解：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AiService {
}

在 Spring Boot 环境中，AiServicesAutoConfig（或类似配置）负责扫描标注了 @AiService 的接口。它可能通过 ClassPathScanningCandidateComponentProvider 来查找，或者更简单的，由 @Bean 方法显式声明。但为了体验友好，通常框架会提供一个 AiServiceScannerRegistrar 实现 ImportBeanDefinitionRegistrar，动态地向容器中注册 BeanDefinition。

实际上，langchain4j-spring-boot-starter 1.0.0-alpha1 的做法是提供了一个 AiServicesFactoryBean 和手动声明 bean 的方式，用户可以在配置类中这样写：

@Configuration
public class AiConfig {
    @Bean
    public Assistant assistant(ChatLanguageModel model, List<ToolProvider> tools) {
        return AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(tools)
                .build();
    }
}

但更高级的集成（在一些版本中）会自动处理 @AiService 注解，相当于将上述过程封装为 FactoryBean。

2.2 FactoryBean 模式：AiServicesFactoryBean

FactoryBean 是 Spring 中创建复杂 Bean 的利器，它能将 Bean 的构造逻辑完全控制在自己手中，同时又能享受到容器功能（如 AOP、依赖注入）。一个典型的 AiServicesFactoryBean 实现如下：

public class AiServicesFactoryBean<T> implements FactoryBean<T>, ApplicationContextAware {
    private Class<T> aiServiceInterface;
    private ApplicationContext applicationContext;

    @Override
    public T getObject() throws Exception {
        ChatLanguageModel chatModel = applicationContext.getBean(ChatLanguageModel.class);
        // 收集所有 @Tool 注解的方法所在的 Bean
        List<Object> toolBeans = new ArrayList<>();
        Map<String, Object> beans = applicationContext.getBeansWithAnnotation(Tool.class);
        toolBeans.addAll(beans.values());
        // 获取 ChatMemory（如果有会话作用域）
        ChatMemory chatMemory = null;
        try {
            chatMemory = applicationContext.getBean(ChatMemory.class);
        } catch (NoSuchBeanDefinitionException ignored) { }

        return AiServices.builder(aiServiceInterface)
                .chatLanguageModel(chatModel)
                .tools(toolBeans)
                .chatMemory(chatMemory)
                .build();
    }

    @Override
    public Class<?> getObjectType() { return aiServiceInterface; }

    @Override
    public void setApplicationContext(ApplicationContext context) {
        this.applicationContext = context;
    }
    public void setAiServiceInterface(Class<T> clazz) { this.aiServiceInterface = clazz; }
}

这个 FactoryBean 通过 getObject() 内部调用 AiServices.builder() 并返回动态代理。关键的依赖 ChatLanguageModel、工具 Bean 以及 ChatMemory 都从 ApplicationContext 中提取，确保了依赖注入的时序——当调用 getObject() 时，容器已经完全启动，所有依赖都已就绪。FactoryBean 返回的代理对象可以被 Spring 管理，能够被应用到事务、AOP 增强等。

2.3 代理 Bean 的调用：时序图

flowchart TD
    classDef nodeStyle fill:#f1f5f9,stroke:#334155,stroke-width:1.5px,color:#1e293b

    A["@AiService接口"] -->|"扫描/手动注册"| B["BeanDefinition"]
    B -->|"实例化"| C["AiServicesFactoryBean"]
    C -->|"调用 getObject"| D["ApplicationContext获取ChatModel/Tools"]
    D -->|"构造"| E["AiServices.builder.build"]
    E -->|"JDK动态代理"| F["返回代理对象"]
    F -->|"注入到Controller"| G["控制器使用"]

    class A,B,C,D,E,F,G nodeStyle

图表主旨概括：展示从 @AiService 接口定义到最终可调用的 Spring 代理 Bean 的完整创建时序。 逐层分解：接口通过扫描（或手动注册）形成 BeanDefinition；Spring 发现它是一个 FactoryBean，于是调用 getObject() 方法；在该方法内，从容器中收集必需的依赖（ChatLanguageModel、Tool Beans、ChatMemory）；然后将这些依赖传递给 AiServices.builder()，生成 JDK 动态代理；最后代理对象被注册为真正的 Bean，可注入到任何 Spring 组件中。 设计原理映射：FactoryBean 模式将复杂的构建过程封装在 Spring 的生命周期内，让 AI Agent 像其他 Bean 一样享受全栈的服务治理。这本质上是建造者模式在 Spring 容器中的实现。 工程联系与关键结论：AiServicesFactoryBean 是连接 Spring IOC 容器与 AI 代理对象的关键桥梁，它让 AI 能力无缝融入 Spring 的依赖注入体系，开发者不再需要手动管理模型和工具的组装。

---

3. 记忆的容器化管理

对话记忆是多轮交互的基础。在 Spring 环境中，需要保证每个用户的对话是隔离的，且能在分布式场景下持久化。

3.1 会话作用域（Session Scope）原理

在 Spring Boot Web 应用中，可以声明一个 ChatMemory 的会话作用域 Bean：

@Bean
@Scope(value = WebApplicationContext.SCOPE_SESSION, proxyMode = ScopedProxyMode.INTERFACES)
public ChatMemory chatMemory() {
    return MessageWindowChatMemory.builder()
            .maxMessages(10)
            .build();
}

proxyMode = ScopedProxyMode.INTERFACES 指示 Spring 创建一个 JDK 动态代理，该代理会从当前 HTTP Session 中获取真实的 ChatMemory 实例。每个用户的 Session 中会缓存一个独立的 ChatMemory 实例，从而实现了多用户对话隔离。LangChain4j 默认的 ChatMemory 实现内部使用一个 ChatMemoryStore 来实际存取消息列表。默认的 InMemoryChatMemoryStore 是单例的、进程内的，不适合分布式和多实例部署。

3.2 Redis 持久化的 ChatMemoryStore

通过自定义 ChatMemoryStore，可将消息存储到 Redis，实现跨服务实例的会话共享：

@Component
public class RedisChatMemoryStore implements ChatMemoryStore {
    private final RedisTemplate<String, List<ChatMessage>> redisTemplate;

    public RedisChatMemoryStore(RedisTemplate<String, List<ChatMessage>> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    @Override
    public List<ChatMessage> getMessages(Object memoryId) {
        String key = "chat:memory:" + memoryId;
        List<ChatMessage> messages = redisTemplate.opsForValue().get(key);
        return messages != null ? messages : new ArrayList<>();
    }

    @Override
    public void updateMessages(Object memoryId, List<ChatMessage> messages) {
        String key = "chat:memory:" + memoryId;
        redisTemplate.opsForValue().set(key, messages, Duration.ofMinutes(30));
    }

    @Override
    public void deleteMessages(Object memoryId) {
        redisTemplate.delete("chat:memory:" + memoryId);
    }
}

然后，ChatMemory Bean 需要使用这个 Store：

@Bean
@Scope(value = "session", proxyMode = ScopedProxyMode.INTERFACES)
public ChatMemory chatMemory(ChatMemoryStore store) {
    return MessageWindowChatMemory.builder()
            .chatMemoryStore(store)
            .maxMessages(10)
            .build();
}

这里的 ChatMemory 实例仍然是会话作用域，但其背后的 Store 是共享的 Redis 实例。每个用户的消息通过 memoryId 隔离，memoryId 可以取自当前登录用户的 ID 或 Session ID。这样的架构既保证了会话级隔离，又实现了状态的集中管理和持久化。

3.3 会话架构图

flowchart TD
    subgraph UserA_Session [User A Session]
        A1[HTTP Request] --> A2[ChatMemory Proxy]
        A2 --> A3[MessageWindowChatMemory]
        A3 --> A4[RedisChatMemoryStore]
    end
    subgraph UserB_Session [User B Session]
        B1[HTTP Request] --> B2[ChatMemory Proxy]
        B2 --> B3[MessageWindowChatMemory]
        B3 --> B4[RedisChatMemoryStore]
    end
    A4 -->|key=chat:memory:A| Redis[(Redis)]
    B4 -->|key=chat:memory:B| Redis

图表主旨概括：说明利用 Spring Session 作用域代理和 Redis Store 实现多用户对话记忆隔离与共享的架构。 逐层分解：每个用户 Session 内存在一个 ChatMemory 代理，代理背后是一个绑定该 Session 的 MessageWindowChatMemory 实例；当需要存取消息时，实例调用 ChatMemoryStore 接口，而 Redis 实现按照 memoryId 将数据写入 Redis；两个用户拥有不同的 memoryId，从而实现了逻辑隔离。 设计原理映射：使用代理模式处理 Session 作用域 Bean，再结合策略模式替换 Store 实现，将关注点分离为“生命周期管理”和“存储介质”。 工程联系与关键结论：这种设计使得 AI 应用的对话状态不再受限于服务器内存，可以轻松地在 Kubernetes 中水平扩展，而用户无感知。

---

4. 多模型与动态路由

生产环境中经常需要根据任务复杂度或成本选择不同的 LLM，LangChain4j 与 Spring 的结合可以优雅实现。

4.1 多模型 Bean 注册与 @Qualifier

假定我们同时配置了 GPT-4 和 Ollama 的本地模型：

@Bean
@Qualifier("gpt4o")
public ChatLanguageModel gpt4o(LangChain4jProperties props) {
    return OpenAiChatModel.builder()
        .apiKey(props.getOpenAi().getApiKey())
        .modelName("gpt-4o")
        .build();
}

@Bean
@Qualifier("claude3")
public ChatLanguageModel claude(LangChain4jProperties props) {
    // ... 返回 AnthropicChatModel
}

@Bean
@Qualifier("local-llama")
public ChatLanguageModel localLlama() {
    return OllamaChatModel.builder()
        .baseUrl("http://localhost:11434")
        .modelName("llama3")
        .build();
}

定义两个 AI Service 接口，分别绑定不同模型：

public interface GptAssistant {
    String chat(String userMessage);
}

public interface LocalAssistant {
    String chat(String userMessage);
}

@Configuration
public class AiServicesConfig {
    @Bean
    public GptAssistant gptAssistant(@Qualifier("gpt4o") ChatLanguageModel model, ChatMemory memory) {
        return AiServices.builder(GptAssistant.class)
                .chatLanguageModel(model)
                .chatMemory(memory)
                .build();
    }

    @Bean
    public LocalAssistant localAssistant(@Qualifier("local-llama") ChatLanguageModel model) {
        return AiServices.builder(LocalAssistant.class)
                .chatLanguageModel(model)
                .build();
    }
}

4.2 运行时动态路由

可创建路由决策组件，根据提示词复杂度或成本预算选择 Agent：

@Service
public class AgentRouter {
    private final GptAssistant gptAssistant;
    private final LocalAssistant localAssistant;

    public AgentRouter(GptAssistant gptAssistant, LocalAssistant localAssistant) {
        this.gptAssistant = gptAssistant;
        this.localAssistant = localAssistant;
    }

    public String route(String prompt, Complexity complexity) {
        if (complexity == Complexity.HIGH) {
            return gptAssistant.chat(prompt);
        } else {
            return localAssistant.chat(prompt);
        }
    }
}

还可以结合 Resilience4j 实现自动降级路由：当高级模型不可用或超过熔断阈值时，自动切换到本地模型。

4.3 多模型路由与熔断集成架构图

flowchart TD
    R[请求进入] --> Router{路由决策}
    Router -->|复杂/高优先级| G[AiService-GPT4o]
    Router -->|简单/低优先级| L[AiService-LocalLlama]
    G --> CB1{CircuitBreaker GPT}
    CB1 -->|闭合| GPT[OpenAI GPT-4o API]
    CB1 -->|打开/降级| L
    L --> CB2{CircuitBreaker Local}
    CB2 -->|闭合| Llama[Ollama Local Model]
    CB2 -->|打开| Fallback[返回固定回答/缓存]

图表主旨概括：展示多模型路由策略与 Resilience4j 熔断结合的保护性调用流程。 逐层分解：请求经过复杂度判定选择对应的 AiService；每个 AiService 调用前包裹有熔断器；若主模型服务不可用，熔断器打开，流量降级到备选模型或最终兜底逻辑。 设计原理映射：这里应用了策略模式（路由选择）和断路器模式，确保高可用。Spring 的 @Qualifier 提供了依赖选择的类型安全方式。 工程联系与关键结论：将业务路由与熔断降级结合，可以在保证用户体验的前提下大幅降低推理成本，是企业 AI 应用必备的弹性设计。

---

5. 生产级增强：GraalVM AOT 与 Spring Cloud

5.1 GraalVM Native Image 的 AOT 兼容

LangChain4j 大量使用 JDK 动态代理 (java.lang.reflect.Proxy)，这在 GraalVM 原生镜像中是不允许的，因为运行时无法动态生成类。Spring Boot 3.x 引入了 AOT (Ahead-of-Time) 处理机制，通过 RuntimeHints 提前注册需要反射、代理和资源的信息。

挑战：在编译为原生镜像时，AiServices 的代理接口、LLM 交互的 DTO 类（ChatMessage、UserMessage 等）若未注册，会出现 ClassNotFoundException 或 MissingReflectionMetadataException。

解决方案：langchain4j-spring-boot-starter 内置了 LangChain4jRuntimeHints：

public class LangChain4jRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // 注册所有消息类的反射
        hints.reflection().registerType(ChatMessage.class, MemberCategory.values());
        hints.reflection().registerType(UserMessage.class, MemberCategory.values());
        hints.reflection().registerType(SystemMessage.class, MemberCategory.values());
        // 注册动态代理接口
        // 实际上需要向 ProxyHints 注册 @AiService 的接口
        // 但 AiService 接口往往由用户定义，框架无法预知
    }
}

用户自定义的 @AiService 接口以及 @Tool 方法的参数类型，需要在编译时手动注册。常用的手段是使用 @RegisterReflectionForBinding 注解：

@RegisterReflectionForBinding({MyAiService.class, MyToolParam.class})
@SpringBootApplication
public class Application { ... }

或者实现自己的 RuntimeHintsRegistrar：

public class MyHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.proxies().registerJdkProxy(MyAiService.class);
        hints.reflection().registerType(MyToolInput.class, MemberCategory.INVOKE_PUBLIC_METHODS);
    }
}

并在 META-INF/spring/aot.factories 中注册该实现。在 AOT 编译阶段，Spring 会收集这些 hints 并生成 reflect-config.json 等配置文件给 GraalVM 编译器。

实际错误案例：编译时若缺少反射配置，原生镜像启动时会报：

com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfaces [com.example.MyAiService] not found.

解决方案就是在 runtime hints 中注册该代理接口。

AOT 元数据注册流程图：

flowchart TD
    classDef nodeStyle fill:#f1f5f9,stroke:#334155,stroke-width:1.5px,color:#1e293b

    A["@AiService接口/Tool参数类型"] -->|"标注@RegisterReflectionForBinding"| B["Spring AOT引擎"]
    B -->|"生成"| C["RuntimeHintsRegistrar"]
    C -->|"输出"| D["生成reflect-config.json/proxy-config.json"]
    D -->|"用于"| E["native-image编译"]
    E -->|"产出"| F["原生二进制"]

    class A,B,C,D,E,F nodeStyle

图表主旨概括：从源码注解到最终原生二进制中元数据注册的编译期处理流程。 逐层分解：开发者在接口或 DTO 上添加提示注解；Spring AOT 编译阶段调用所有 RuntimeHintsRegistrar 收集反射和代理信息；生成 GraalVM 所需的配置文件；native-image 使用这些配置生成可执行文件。 设计原理映射：这是将 Java 动态特性向“提前编译”世界迁移的元数据驱动方案，体现了 Spring 一贯的抽象与自动化的理念。 工程联系与关键结论：如果不处理好 AOT 元数据，AI 应用无法在云原生 Serverless 环境（如 AWS Lambda）中以毫秒级启动，因此 Native Image 兼容是生产级 AI 微服务的必修课。

5.2 Resilience4j 熔断保护 LLM 调用

LLM 服务是外部依赖，不稳定是常态。使用 Resilience4j 可以为 AiService 调用添加熔断和重试。

@Bean
public GptAssistant gptAssistant(ChatLanguageModel model) {
    GptAssistant raw = AiServices.builder(GptAssistant.class)
            .chatLanguageModel(model)
            .build();
    // 创建CircuitBreaker
    CircuitBreakerConfig config = CircuitBreakerConfig.custom()
            .failureRateThreshold(50)
            .waitDurationInOpenState(Duration.ofSeconds(10))
            .build();
    CircuitBreakerRegistry registry = CircuitBreakerRegistry.of(config);
    CircuitBreaker circuitBreaker = registry.circuitBreaker("gpt");
    // 使用装饰器包装接口
    return CircuitBreaker.decorate(raw, circuitBreaker)::chat;
}

更优雅的是在调用方使用 @CircuitBreaker 注解（需引入 AOP 支持）：

@CircuitBreaker(name = "gpt", fallbackMethod = "fallbackChat")
public String chatWithGpt(String prompt) {
    return gptAssistant.chat(prompt);
}
public String fallbackChat(String prompt, Throwable t) {
    return "抱歉，高级模型暂时不可用，请稍后重试。";
}

结合第4节的动态路由，可在降级方法中调用 localAssistant.chat(prompt)。

5.3 Micrometer 监控指标

通过实现 ChatModelListener 收集指标：

@Component
public class MetricsChatModelListener implements ChatModelListener {
    private final MeterRegistry meterRegistry;

    public MetricsChatModelListener(MeterRegistry registry) {
        this.meterRegistry = registry;
    }

    @Override
    public void onRequest(ChatModelRequestContext context) {
        // 记录请求计数
    }

    @Override
    public void onResponse(ChatModelResponseContext context) {
        ChatResponse response = context.response();
        String model = context.modelName();
        // 记录 token 消耗
        TokenUsage usage = response.tokenUsage();
        meterRegistry.counter("langchain4j.llm.tokens", "model", model, "type", "input")
                .increment(usage.getInputTokenCount());
        meterRegistry.counter("langchain4j.llm.tokens", "model", model, "type", "output")
                .increment(usage.getOutputTokenCount());
        // 记录延迟
        Timer.Sample sample = Timer.start(meterRegistry);
        sample.stop(Timer.builder("langchain4j.llm.latency")
                .tag("model", model)
                .register(meterRegistry));
    }
}

通过 Spring Boot Actuator 暴露 /actuator/metrics，再对接 Prometheus + Grafana 实现可视化。

---

6. 贯穿案例：迁移 Hello Agent

在系列一第 8 篇中，我们曾编写 main 方法手工构建 Agent：

public static void main(String[] args) {
    ChatLanguageModel model = OpenAiChatModel.withApiKey("sk-xxx");
    Tool tool = new CalculatorTool();
    ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);
    Assistant agent = AiServices.builder(Assistant.class)
            .chatLanguageModel(model)
            .tools(tool)
            .chatMemory(memory)
            .build();
    String answer = agent.chat("计算 3*5");
}

迁移到 Spring Boot 自动配置后：

@AiService
public interface Assistant {
    String chat(String userMessage);
}

@SpringBootApplication
public class AgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(AgentApplication.class, args);
    }
}

@RestController
public class ChatController {
    private final Assistant assistant;
    public ChatController(Assistant assistant) {
        this.assistant = assistant;
    }
    @GetMapping("/chat")
    public String chat(@RequestParam String msg) {
        return assistant.chat(msg);
    }
}

只需提供 application.yml：

langchain4j:
  openai:
    api-key: ${OPENAI_API_KEY}

代码对比：main 方法 30 余行配置，被 Spring Boot 压缩至纯声明式的接口与 YAML。ChatMemory 由会话作用域自动管理，Tool 通过 @Component 注册后自动发现，整个 Agent 的生命周期完全由容器托管。代码量减少 70%，且获得了会话隔离、持久化、指标监控等高级特性。

---

7. 与前后系列的衔接

• 关联前文（本系列第 2 篇）：第 2 篇手工构建 AiServices 的方式，本篇将其自动化——FactoryBean、条件装配、Bean 生命周期管理全部由 Spring 容器接管。读者可以将本篇视为第 2 篇源码分析在生产环境中的落地。
• 关联前文（系列一第 8 篇）：Hello Agent 从 main 方法迁移到 Spring Boot，体现了从原型到工程的跃迁。
• 关联后续（本系列第 5-8 篇 MCP 协议）：MCP Client 可以通过类似的自动配置机制，在启动时自动连接 MCP Server 并注册其工具为 Spring Bean，供 @AiService 使用。
• 关联后续（系列五第 15 篇 AI 应用 FinOps）：本篇建立的多模型动态路由和 Micrometer 指标监控，是实施成本优化的基础设施，后续将在此基础上实现 token 计费、预算告警等。

---

8. 面试高频专题

1. Spring Boot Starter 如何自动配置一个 Bean？ 四段式：Spring Boot 通过 @AutoConfiguration 和条件注解决定是否加载配置；@ConfigurationProperties 将外部化配置绑定到属性类；@Bean 方法根据属性值构建实例；最终注册到容器。LangChain4j 中就是靠 langchain4j.openai.api-key 属性决定是否创建 OpenAiChatModel。

2. 解释 LangChain4j 中 @AiService 代理的创建流程。 扫描接口 → 注册 FactoryBean 定义 → 容器调用 FactoryBean.getObject() → 在其中收集 ChatModel、Tools、ChatMemory → 调用 AiServices.builder().build() 生成 JDK 动态代理 → 返回代理对象作为最终的 Bean。

3. 如何实现多用户的会话隔离？ 使用 @Scope("session") 并设置 proxyMode=INTERFACES，Spring 会为每个 HTTP Session 创建一个 ChatMemory 代理，背后使用 ChatMemoryStore（如 Redis）按 memoryId 存取消息。

4. 什么是 @Qualifier？在 LangChain4j 中怎么用？ @Qualifier 是 Spring 提供的限定符，用于区分同一类型的多个 Bean。在配置中给不同的模型 Bean 加上 @Qualifier("gpt4o") 等，注入时通过 @Qualifier("gpt4o") ChatLanguageModel 指定具体模型，从而实现多模型绑定。

5. GraalVM Native Image 为什么不能运行动态代理？怎么解决？ 原生镜像在编译时封闭了世界，不允许运行时生成新类。Spring 通过 RuntimeHintsRegistrar 收集需要代理的接口，提前生成代理字节码或注册信息。LangChain4j 需要将 @AiService 接口和 Tool 参数类型在 hints 中注册反射和代理。

6. Resilience4j 如何保护 LLM 调用？ 使用 @CircuitBreaker 注解包裹 AiService 方法，配置失败阈值和半开状态；当外部 API 频繁超时，断路器打开，执行降级逻辑，如切换本地模型。

7. 怎么实现动态路由策略选择不同的 LLM？ 定义多个 AiService 代理分别绑定不同模型，编写路由 Service 根据复杂度、成本或可用性选择调用对应的代理。

8. 如何持久化对话记忆到 Redis？ 实现 ChatMemoryStore 接口，使用 RedisTemplate 以 chat:memory:{memoryId} 为 key 存储消息列表，设置 TTL。然后在 ChatMemory Bean 中注入该 Store。

9. 在 Spring Boot 中如何暴露 LLM 调用的指标？ 自定义 ChatModelListener，在 onResponse 中获取 TokenUsage 和耗时，通过 MeterRegistry 注册 Counter 和 Timer，最后通过 Actuator 端点暴露。

10. 如果同时存在多个模型 Bean，@AiService 如何选择？ 默认会因类型歧义抛出异常。需要显式指定 @Qualifier 限定，或者在 AiServices 构建时明确传入特定的 ChatLanguageModel。

11. 什么是 FactoryBean，与 @Bean 方法有何不同？ FactoryBean 是一个特殊的 Bean，其 getObject() 返回实际对象，Spring 会将其生成的实例注册到容器。适合复杂构建逻辑，且可以实现单例/原型控制，@Bean 方法相对轻量，但 FactoryBean 可以和 AOP 更好集成，且可以更早介入 Bean 生命周期。

12. 系统设计题：设计一个支持多模型动态切换和会话级记忆的 AI 应用后端架构。 要求给出 Spring Boot 集成架构图与模型路由策略的时序图。
架构图：

flowchart TD
    Client-->LB[负载均衡]
    LB-->GW[API Gateway]
    GW-->ChatService[ChatController]
    ChatService-->Router[AgentRouter]
    Router-->|简单任务| LocalAgent[AiService-Local]
    Router-->|复杂任务| GptAgent[AiService-GPT4]
    LocalAgent-->LModel[Ollama Llama3]
    GptAgent-->GModel[OpenAI]
    subgraph Session [会话管理]
        ChatService-->SessionScope[ChatMemory Session Scope]
        SessionScope-->RedisStore[RedisChatMemoryStore]
    end

路由策略时序图：

flowchart TD
    A[用户请求] --> B[Router评估复杂度]
    B -->|复杂度低| C[调用LocalAgent]
    C --> D{Ollama健康?}
    D -->|是| E[返回结果]
    D -->|否| F[降级到GptAgent]
    B -->|复杂度高| G[调用GptAgent]
    G --> H{GPT健康?}
    H -->|是| E
    H -->|否| F

图表主旨概括：展示网关、路由、模型服务与会话存储的完整分层架构。 逐层分解：客户端经网关访问 Chat 服务；Router 根据复杂度选模型；每个模型调用前有健康检查，异常时降级；会话记忆通过 Session 作用域存放在 Redis，所有服务实例共享。 设计原理映射：后端采用分层架构和微服务弹性模式，确保高可用和成本控制。 工程联系与关键结论：此架构适用于需要同时平衡响应质量和运营成本的企业级 AI 平台，通过 Spring Boot 的自动配置和生态组件可以快速落地。

---

附录：Spring Boot 集成关键点速查表

关键环节	Spring Boot 机制	LangChain4j 对应实现
外部配置绑定	@ConfigurationProperties	LangChain4jProperties
条件装配	@ConditionalOnClass、@ConditionalOnProperty	检查 ChatLanguageModel.class 及 api-key 属性
声明式 Agent	FactoryBean、@Bean	AiServicesFactoryBean 创建代理
会话隔离	@Scope("session") + 代理	ChatMemory 会话 Bean
存储持久化	策略模式替换实现	自定义 ChatMemoryStore → Redis
多模型注入	@Qualifier	为不同模型 Bean 添加限定符
弹性保护	Resilience4j @CircuitBreaker	装饰 AiService 接口调用
AOT 编译	RuntimeHintsRegistrar	注册代理接口和 DTO 反射
指标监控	Micrometer MeterRegistry	实现 ChatModelListener 收集 token 和延迟

延伸阅读：

• Spring Boot 3.4 官方文档 Auto-configuration
• LangChain4j 官方 Spring Boot Starter 指南 langchain4j-spring
• GraalVM Native Image Runtime Hints