Spring AI与LangChain4j深度对比：Java AI框架选型与迁移实战

1. 为什么我要做这个对比测试做Java后端的人最近一两年应该都有同感AI能力集成这件事从“要不要做”变成了“怎么做”。尤其是大模型调用、RAG检索增强、工具函数编排这几块摆在面前的选择其实不多——要么用Spring AI要么用LangChain4j偶尔也有人自己裸写HTTP客户端调API。我所在的项目组之前一直用自己封装的HTTP工具类调模型接口简单场景够用但一旦涉及多轮对话记忆、向量检索、函数调用编排代码就开始失控。于是团队决定引入一个成熟的AI框架。问题来了选哪个网上关于这两个框架的对比文章不少但大多数停留在“Spring AI有什么特性”“LangChain4j支持哪些模型”这种罗列层面。真正让我下决心做这个测试的是一个很实际的问题如果我用同一套业务逻辑分别用两个框架实现代码差异到底有多大迁移成本有多高运行时的表现有没有本质区别这个测试我前前后后花了大概两周的业余时间中间踩了不少坑也推翻了自己一开始的一些判断。下面把整个过程和结论完整记录下来包括代码结构、配置细节、性能数据、以及那些文档里不会写的坑。注意本文涉及的所有模型服务均通过标准API接口调用测试环境为本地开发机不涉及任何特定网络环境配置。2. 测试方案设计与核心思路拆解2.1 为什么选“同一套业务代码”作为测试基准很多对比文章喜欢用“Hello World”级别的示例来展示两个框架的用法差异比如调一次模型返回一句话。这种测试有意义但意义有限——它只能告诉你API长什么样不能告诉你真实项目里哪个更顺手。我设计的测试基准是一个模拟的智能客服工单处理系统核心业务逻辑包括接收用户自然语言描述的问题调用大模型进行意图分类比如“退款”“咨询”“投诉”根据意图决定是否需要查询知识库RAG如果需要从向量库检索相关文档片段将检索结果和用户问题一起交给模型生成最终回复记录对话历史支持多轮追问这套逻辑覆盖了AI应用开发中最常见的几个能力点对话管理、结构化输出、向量检索、提示词模板、多轮上下文。用同一套业务需求分别用两个框架实现才能看出真正的差异。2.2 两个框架的定位差异以及为什么这很重要在动手之前有必要先理清两个框架的设计哲学因为这直接决定了后续代码的组织方式。Spring AI的定位很明确它是Spring生态的一部分。如果你用过Spring Data、Spring Security你会发现Spring AI的API设计风格一脉相承——大量使用注解、自动配置、依赖注入。它的核心抽象是ChatClient围绕它构建了Advisor、VectorStore、FunctionCallback等组件。优势是跟Spring Boot项目集成极其顺滑劣势是如果你不用Spring或者项目结构比较特殊会感觉被框架“绑架”。LangChain4j的定位是“Java版的LangChain”。它的设计更偏向于链式调用和显式编排。核心抽象是AiServices接口和ChatLanguageModel通过建造者模式组装各种组件。优势是灵活不依赖特定容器可以按需组合劣势是配置相对繁琐跟Spring Boot集成需要额外写配置类。我一开始的判断是如果项目本来就是Spring BootSpring AI应该更省事如果项目结构复杂或者需要精细控制LangChain4j更合适。但实际跑下来这个判断需要修正。2.3 测试环境与依赖版本说明为了让测试结果有参考价值我把环境信息列清楚项目版本/配置JDK21 (LTS)Spring Boot3.3.xSpring AI1.0.0-M6LangChain4j0.35.0模型服务兼容OpenAI接口的通用模型服务向量库内存向量库测试用构建工具Maven 3.9.x操作系统Linux (开发机)提示Spring AI在1.0.0-M6版本中API变动较大如果你用的是更早的版本部分代码可能需要调整。LangChain4j 0.35.0的API相对稳定但不同小版本之间也有细微差异。两个框架都通过标准的模型服务接口调用配置项包括API地址、密钥、模型名称等这些在两个框架中都是通过配置文件或建造者参数传入的。3. 核心细节解析与实操要点3.1 对话客户端初始化注解驱动 vs 建造者模式先看最基础的模型调用初始化。Spring AI的做法在application.yml中配置spring: ai: openai: api-key: ${API_KEY} base-url: ${BASE_URL} chat: options: model: gpt-4o-mini temperature: 0.7然后直接注入ChatClientService public class IntentService { private final ChatClient chatClient; public IntentService(ChatClient.Builder builder) { this.chatClient builder.build(); } }LangChain4j的做法需要手动构建模型对象Configuration public class LangChainConfig { Bean public ChatLanguageModel chatModel() { return OpenAiChatModel.builder() .apiKey(System.getenv(API_KEY)) .baseUrl(System.getenv(BASE_URL)) .modelName(gpt-4o-mini) .temperature(0.7) .build(); } }然后注入使用Service public class IntentService { private final ChatLanguageModel model; public IntentService(ChatLanguageModel model) { this.model model; } }差异分析Spring AI的自动配置确实省事配置文件一写就能用。LangChain4j需要显式构建但好处是你可以精确控制每个参数而且不依赖Spring的自动配置机制。如果你的项目有多个不同配置的模型实例比如一个用于意图分类用低温度一个用于生成回复用高温度LangChain4j的建造者模式反而更清晰。实操心得Spring AI也可以通过ChatClient.Builder的defaultOptions()方法覆盖配置但多个实例的管理不如LangChain4j直观。我在测试中需要两个不同温度的模型实例Spring AI那边折腾了一会儿才搞定。3.2 提示词模板字符串拼接 vs 结构化模板意图分类需要把用户输入嵌入到提示词中。Spring AI提供了PromptTemplatePromptTemplate template new PromptTemplate( 你是一个客服意图分类器。请将以下用户问题分类为 退款、咨询、投诉、其他。 只返回分类结果不要解释。 用户问题{question} ); Prompt prompt template.create(Map.of(question, userInput)); String result chatClient.call(prompt).getResult().getOutput().getContent();LangChain4j的做法类似但更灵活PromptTemplate template PromptTemplate.from( 你是一个客服意图分类器。请将以下用户问题分类为 退款、咨询、投诉、其他。 只返回分类结果不要解释。 用户问题{{question}} ); String result model.generate(template.apply(Map.of(question, userInput)).text());差异分析两者都支持模板变量替换但LangChain4j的模板语法更接近Mustache风格Spring AI用的是{}占位符。功能上差别不大但LangChain4j的PromptTemplate可以更方便地跟其他组件组合。注意Spring AI的PromptTemplate在M6版本中对特殊字符的处理有一些边界问题比如用户输入中包含{}时可能导致模板解析异常。LangChain4j在这方面更稳健一些。我在测试中特意用包含花括号的用户输入做了验证。3.3 结构化输出类型安全转换的两种路径意图分类的结果需要映射为Java枚举。这是两个框架差异比较大的地方。Spring AI提供了.entity()方法public enum Intent { REFUND, CONSULT, COMPLAINT, OTHER } Intent intent chatClient.call(prompt) .entity(Intent.class);看起来很简单但实际用的时候发现模型返回的文本如果跟枚举值不完全匹配比如返回“退款”而不是“REFUND”转换就会失败。需要额外配置BeanOutputConverter或者自定义转换器。LangChain4j的做法是通过AiServices接口interface IntentClassifier { UserMessage( 你是一个客服意图分类器。请将以下用户问题分类为 退款、咨询、投诉、其他。 用户问题{{it}} ) Intent classify(String userInput); } IntentClassifier classifier AiServices.create(IntentClassifier.class, model); Intent intent classifier.classify(userInput);差异分析LangChain4j的AiServices方式更声明式接口定义即契约代码更干净。Spring AI的.entity()方式更直接但需要处理转换失败的边界情况。实测下来LangChain4j在结构化输出这块的体验明显更好尤其是当输出结构比较复杂比如嵌套对象时。实操心得无论用哪个框架都建议在提示词中明确要求模型返回JSON格式并且在代码中做好异常兜底。模型不按格式返回是常态不是异常。3.4 向量检索与RAG集成RAG是这次测试的重点也是两个框架差异最大的地方。Spring AI的RAG集成围绕Advisor构建Bean public ChatClient chatClient(ChatClient.Builder builder, VectorStore vectorStore) { return builder .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build(); }然后调用时自动触发检索String response chatClient.prompt() .user(question) .call() .content();LangChain4j需要显式编排检索链Retriever retriever EmbeddingStoreRetriever.from(embeddingStore, embeddingModel, 5); String response ConversationalRetrievalChain.builder() .chatLanguageModel(model) .retriever(retriever) .build() .execute(question);差异分析Spring AI的Advisor机制确实优雅检索逻辑对业务代码透明。但问题在于当检索策略需要动态调整时比如根据意图决定是否检索、检索多少个文档Advisor的灵活性就不够了。LangChain4j的显式编排虽然代码多一些但控制力更强。我在测试中需要实现“只有咨询类问题才触发检索”的逻辑。Spring AI那边需要自定义Advisor写了不少代码LangChain4j那边就是一个简单的if判断。提示Spring AI也支持通过QuestionAnswerAdvisor的参数动态控制检索行为但文档不够详细我是翻源码才找到的。4. 实操过程与核心环节实现4.1 项目结构搭建与依赖引入先看两个框架在Maven项目中的依赖引入方式。Spring AIdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId version1.0.0-M6/version /dependencyLangChain4jdependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependencySpring AI的starter会自动配置大量BeanLangChain4j需要手动配置。这一点在项目启动阶段就能感受到差异Spring AI的项目启动后日志里会多出一堆自动配置相关的输出LangChain4j则干净很多。4.2 完整业务逻辑实现对比我把智能客服的核心流程完整实现了一遍下面是关键代码的对比。意图分类环节Spring AI版本public Intent classifyIntent(String userInput) { PromptTemplate template new PromptTemplate(INTENT_PROMPT); Prompt prompt template.create(Map.of(question, userInput)); try { return chatClient.call(prompt).entity(Intent.class); } catch (Exception e) { log.warn(意图分类失败降级为OTHER, e); return Intent.OTHER; } }LangChain4j版本public Intent classifyIntent(String userInput) { try { return intentClassifier.classify(userInput); } catch (Exception e) { log.warn(意图分类失败降级为OTHER, e); return Intent.OTHER; } }RAG检索环节Spring AI版本需要自定义Advisorpublic class ConditionalRagAdvisor implements CallAroundAdvisor { private final VectorStore vectorStore; private final Intent currentIntent; Override public AdvisedResponse aroundCall(AdvisedRequest request, CallAroundAdvisorChain chain) { if (currentIntent Intent.CONSULT) { ListDocument docs vectorStore.similaritySearch( SearchRequest.query(request.userText()).withTopK(5)); String context docs.stream() .map(Document::getContent) .collect(Collectors.joining(\n)); request AdvisedRequest.from(request) .withUserText(context \n\n request.userText()) .build(); } return chain.nextAroundCall(request); } }LangChain4j版本public String generateResponse(String userInput, Intent intent) { String context ; if (intent Intent.CONSULT) { ListTextSegment segments retriever.retrieve(userInput); context segments.stream() .map(TextSegment::text) .collect(Collectors.joining(\n)); } String prompt buildPrompt(userInput, context); return model.generate(prompt); }差异分析Spring AI的Advisor机制在简单场景下很优雅但一旦需要条件逻辑代码复杂度急剧上升。LangChain4j的显式编排虽然看起来“笨”但逻辑清晰调试也方便。4.3 多轮对话记忆的实现多轮对话是客服系统的刚需。Spring AI通过ChatMemory实现Bean public ChatMemory chatMemory() { return new InMemoryChatMemory(); } Bean public ChatClient chatClient(ChatClient.Builder builder, ChatMemory memory) { return builder .defaultAdvisors(new MessageChatMemoryAdvisor(memory)) .build(); }LangChain4j通过ChatMemory和AiServices结合interface Assistant { String chat(MemoryId String sessionId, UserMessage String message); } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemoryProvider(sessionId - MessageWindowChatMemory.withMaxMessages(20)) .build();差异分析两者都提供了开箱即用的内存记忆实现。Spring AI的记忆管理跟Advisor机制绑定LangChain4j的记忆管理跟AiServices绑定。实测下来LangChain4j的MemoryId注解方式在多会话场景下更直观。实操心得内存记忆在生产环境不可靠重启就丢。两个框架都支持接入外部存储比如Redis但LangChain4j的扩展点更清晰。我后来把记忆存储换成了基于文件的实现LangChain4j那边只改了一个ProviderSpring AI那边需要自定义ChatMemory实现类。4.4 性能实测数据我在本地环境跑了100次完整的客服对话流程意图分类条件检索生成回复记录平均耗时环节Spring AILangChain4j意图分类820ms810ms向量检索45ms42ms回复生成1500ms1480ms框架开销约120ms约35ms总耗时约2485ms约2367ms框架开销的差异主要来自Spring AI的Advisor链式调用和自动配置带来的额外代理层。LangChain4j的调用链更短开销更小。不过这个差异在模型调用耗时面前占比不大实际体感差异不明显。注意这个数据是在本地开发环境测的没有做JVM预热和GC调优。生产环境的表现可能不同建议在自己的环境里实测。5. 常见问题与排查技巧实录5.1 依赖冲突与版本兼容问题Spring AI因为跟Spring Boot深度集成版本兼容性需要特别注意。我遇到的一个典型问题是Spring AI 1.0.0-M6要求Spring Boot 3.3.x以上但项目里其他依赖锁定了3.2.x导致启动时报NoSuchMethodError。排查思路先看mvn dependency:tree找到冲突的Spring核心包用exclusions排除旧版本。LangChain4j的依赖相对独立跟Spring Boot版本耦合度低这方面问题少一些。5.2 模型返回格式不符合预期这是最常见的坑。无论用哪个框架模型都可能返回意料之外的格式。比如要求返回JSON结果返回了带Markdown代码块的JSON。解决方案在提示词中明确要求“只返回JSON不要包含任何其他文字”代码中做容错处理比如用正则提取JSON部分设置合理的重试机制Spring AI的.entity()方法在格式不匹配时会抛异常需要捕获处理。LangChain4j的AiServices同样会抛异常但异常信息更详细便于定位问题。5.3 向量检索结果不相关RAG效果不好很多时候不是框架的问题而是检索策略的问题。排查清单问题现象可能原因排查方法检索结果完全不相关嵌入模型不匹配检查嵌入模型和向量库的维度是否一致检索结果部分相关分块策略不合理调整文档分块大小和重叠度检索结果重复相似度阈值过低提高相似度阈值或减少TopK检索不到任何结果向量库为空确认文档已正确写入向量库实操心得Spring AI的VectorStore默认相似度阈值比较宽松容易召回不相关文档。LangChain4j的EmbeddingStoreRetriever可以更精细地控制检索参数。建议在测试阶段把TopK设大一些观察召回情况后再调整。5.4 多轮对话上下文丢失多轮对话中模型“忘记”之前说过的话通常是因为记忆窗口设置太小或者记忆没有正确关联到会话ID。Spring AI的MessageChatMemoryAdvisor默认使用ChatMemory.DEFAULT_CONVERSATION_ID如果多会话场景下没有显式传递会话ID所有对话会混在一起。LangChain4j的MemoryId注解强制要求指定会话ID反而避免了这个问题。5.5 常见问题速查表问题Spring AI排查方向LangChain4j排查方向启动报Bean冲突检查自动配置排除项检查手动配置的Bean模型调用超时检查spring.ai.openai配置检查OpenAiChatModel超时参数结构化输出失败检查BeanOutputConverter配置检查接口方法的返回类型检索无结果检查VectorStore写入检查EmbeddingStore内容记忆不生效检查Advisor顺序检查ChatMemoryProvider6. 我的最终选择与迁移建议两周测试跑下来我最初的判断被推翻了。原本以为Spring AI会因为Spring Boot的加持而全面胜出但实际结果是在业务逻辑复杂度较高的场景下LangChain4j的显式编排反而更省心。Spring AI的优势在于简单场景的快速集成——如果你只是调个模型、做个简单的RAGSpring AI的自动配置确实快。但一旦业务逻辑涉及条件分支、动态检索策略、多模型实例管理Spring AI的Advisor机制就开始显得笨重。LangChain4j的优势在于控制力和灵活性。它的API设计更接近“工具库”而非“框架”你可以按需组合组件不被框架的约定绑架。代价是需要写更多的配置代码但换来的是更清晰的调用链和更低的调试成本。如果你正在做技术选型我的建议是项目是标准Spring Boot应用AI功能只是辅助比如智能客服的意图分类选Spring AI项目以AI能力为核心业务逻辑复杂需要精细控制检索和编排选LangChain4j团队对Spring生态非常熟悉选Spring AI团队更倾向于显式编程风格选LangChain4j迁移成本方面如果从Spring AI迁移到LangChain4j核心业务逻辑提示词、检索策略、记忆管理基本可以复用主要改动在框架API的适配层。反过来迁移也类似。所以选型时不用太纠结“选错了怎么办”两者的核心概念是相通的。最后分享一个我在测试中总结的小技巧无论用哪个框架都建议把模型调用、检索、记忆管理封装成独立的Service层框架相关的代码只出现在这一层。这样即使将来换框架业务代码几乎不用动。我在测试中就是这么做的两套实现共用同一套业务逻辑接口切换框架只需要换实现类。