1. 为什么你的业务代码不该跟大模型“领证”我见过太多团队在接入大模型这件事上一开始就给自己挖了个深坑。项目立项老板说“我们要用AI”技术负责人一拍脑袋选了个当时最火的模型然后直接在业务代码里new一个客户端把 API Key、模型名称、请求地址硬编码进去。三个月后老板说“换个模型试试听说那个更便宜”或者“国产化要求得换成国内某个模型”这时候你打开代码一看模型调用散落在几十个 Service 里每个地方都写着具体的模型名和地址改起来跟拆炸弹一样。这就是典型的“把大模型焊死在业务里”。模型不是你的业务逻辑它只是一个外部依赖一个随时可能被替换的零件。今天 GPT-4 效果最好明天可能 Claude 更便宜后天国产模型追上来性价比更高。如果你的业务代码跟某一个具体模型深度耦合那每次换模型都是一次伤筋动骨的重构。模型中立这个概念说白了就是让你的业务代码只依赖一个抽象的“对话能力”接口而不是依赖某个具体厂商的 SDK。就像你家里装修插座用的是国标五孔不管你插的是小米电视还是格力空调插座本身不关心。模型中立要做的就是定义好这个“插座标准”然后让各个模型厂商的 SDK 去适配这个标准。这件事在 Java 生态里LangChain4j是目前最值得关注的方案之一。它提供了一套统一的 API让你可以用同样的代码调用 OpenAI、通义千问、DeepSeek、Ollama 本地模型等等。你只需要在配置文件里改一个baseUrl和模型名称业务代码一行不用动。这篇文章我就从实际项目经验出发把模型中立的落地思路、LangChain4j 的集成细节、踩过的坑和排查技巧完整地聊一遍。注意本文讨论的是架构设计层面的模型解耦不涉及任何网络访问工具或特殊渠道。所有模型调用均基于各厂商官方公开的 API 接口。2. 模型中立的整体架构设计思路2.1 核心原则业务层只认接口不认厂商模型中立的本质是依赖倒置。你的业务层应该依赖一个抽象的ChatLanguageModel接口而不是依赖OpenAiChatModel或者QwenChatModel这样的具体实现。这个接口定义的是“输入一组消息返回一个回复”这样的能力契约至于背后是哪个模型在干活业务层不关心。在 Spring 项目里这个思路落地下来就是定义一个AiService接口业务代码注入这个接口具体的模型实现通过配置文件和条件装配来决定。LangChain4j 已经帮你把ChatLanguageModel这个抽象定义好了你要做的是在 Spring 配置层把它组装起来。我试过几种不同的组织方式最后觉得最舒服的是三层结构接口层定义业务需要的 AI 能力比如ChatService、EmbeddingService、RagService这些接口只依赖 LangChain4j 的抽象类型。适配层针对每个模型厂商写一个配置类负责创建对应的ChatLanguageModelBean。这一层是唯一跟具体厂商 SDK 打交道的地方。配置层用application.yml控制激活哪个模型通过ConditionalOnProperty实现条件装配。这样做的直接好处是换模型的时候你只需要改配置文件重新启动业务代码零改动。间接好处是测试的时候可以轻松 mock 掉模型调用单元测试不用真的去请求外部 API。2.2 为什么选 LangChain4j 而不是 Spring AISpring AI 也是很好的方案但在我实际用下来LangChain4j 在模型支持的广度和 API 的稳定性上更胜一筹。LangChain4j 支持的模型列表非常长从 OpenAI、Anthropic 到通义千问、DeepSeek、智谱、Ollama、LocalAI基本上你听说过的它都有对应的ChatLanguageModel实现。而且它的 API 设计比较统一不同模型之间的切换成本很低。另一个关键点是LangChain4j 的baseUrl可配置性。很多国产模型和本地部署方案都兼容 OpenAI 的 API 格式你只需要把baseUrl指向对应的地址就能用同一套代码调用。这个特性在模型中立架构里非常关键因为它意味着你甚至不需要为每个模型写适配器只要它们兼容 OpenAI 协议一个OpenAiChatModel配上不同的baseUrl就能通吃。Spring AI 在这方面也在快速追赶但如果你现在就要做一个需要支持多种模型、包括本地模型的项目LangChain4j 的成熟度更高。当然如果你的项目已经深度使用 Spring 生态Spring AI 的集成度会更自然这个后面我会细说。2.3 配置驱动的模型切换机制模型中立的核心实现手段是配置驱动。在application.yml里定义一个ai.model.provider属性然后在配置类里根据这个属性决定创建哪个ChatLanguageModelBean。ai: model: provider: qwen qwen: api-key: ${QWEN_API_KEY} model-name: qwen-plus base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 openai: api-key: ${OPENAI_API_KEY} model-name: gpt-4o-mini base-url: https://api.openai.com/v1 ollama: base-url: http://localhost:11434/v1 model-name: qwen2.5:7b对应的 Java 配置类用ConditionalOnProperty来条件装配Configuration public class ModelConfig { Bean ConditionalOnProperty(name ai.model.provider, havingValue qwen) public ChatLanguageModel qwenChatModel( Value(${ai.model.qwen.api-key}) String apiKey, Value(${ai.model.qwen.model-name}) String modelName, Value(${ai.model.qwen.base-url}) String baseUrl) { return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue ollama) public ChatLanguageModel ollamaChatModel( Value(${ai.model.ollama.base-url}) String baseUrl, Value(${ai.model.ollama.model-name}) String modelName) { return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(modelName) .build(); } }这个模式的好处是新增一个模型只需要加一个配置类和一段 yml不需要动任何现有代码。而且因为ChatLanguageModel是同一个接口业务层注入的时候完全无感知。提示baseUrl的配置要特别注意结尾的/v1路径。不同厂商的兼容接口路径不一样有的需要/v1有的不需要配错了会直接 404。这个后面排查章节会细说。3. LangChain4j 核心细节与实操要点3.1 依赖引入与版本选择LangChain4j 的 Maven 依赖需要根据你用的模型来选。核心包是langchain4j-core但通常你不需要单独引它因为具体的模型包会传递依赖进来。properties langchain4j.version0.35.0/langchain4j.version /properties dependencies !-- 核心抽象通常被具体实现传递依赖 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- OpenAI 兼容协议实现通义、DeepSeek 等都用这个 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency !-- Ollama 本地模型 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version${langchain4j.version}/version /dependency !-- Spring Boot Starter简化集成 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency /dependencies版本选择上我建议用 0.35.0 或更新的稳定版。LangChain4j 迭代很快0.3x 系列在 API 稳定性上已经不错了。注意langchain4j-spring-boot-starter这个包它提供了一些自动配置但在模型中立场景下我建议还是自己写配置类因为 starter 的自动配置往往假设你只有一个模型不够灵活。3.2 ChatLanguageModel 的统一抽象ChatLanguageModel是 LangChain4j 最核心的接口它只有一个主要方法public interface ChatLanguageModel { String generate(String userMessage); ResponseAiMessage generate(ListChatMessage messages); // 还有其他重载 }所有模型实现都遵循这个接口。OpenAiChatModel、OllamaChatModel、QwenChatModel如果有的话都实现了它。这意味着你在业务代码里注入ChatLanguageModel调用generate方法完全不需要知道背后是谁。但这里有个细节要注意不同模型对消息角色的支持程度不一样。比如 system messageOpenAI 支持得很好但某些本地小模型可能对 system message 的处理比较弱。LangChain4j 在抽象层做了统一但实际效果还是取决于模型本身。所以在模型中立架构里你的 prompt 设计要尽量兼容性广一些不要过度依赖某个模型特有的能力。3.3 用 AiServices 进一步解耦LangChain4j 提供了一个更高级的抽象叫AiServices它允许你用接口 注解的方式定义 AI 服务框架自动生成实现。这个在模型中立架构里非常有用因为它把“调用模型”这件事完全声明式化了。public interface Assistant { SystemMessage(你是一个专业的客服助手回答要简洁准确。) String chat(UserMessage String userMessage); } // 在配置类里创建 Bean public Assistant assistant(ChatLanguageModel chatModel) { return AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .build(); }业务代码注入Assistant接口调用chat方法完全看不到模型的存在。换模型的时候ChatLanguageModelBean 变了Assistant自动跟着变业务代码纹丝不动。这是我认为模型中立架构里最优雅的落地方式。注意AiServices创建的代理对象是线程安全的可以放心注入到单例 Service 里。但如果你用了MemoryId做多轮对话记忆要注意记忆存储的并发问题。3.4 流式输出的统一处理流式输出是现在大模型应用的标配但不同模型的流式实现细节有差异。LangChain4j 提供了StreamingChatLanguageModel接口来统一流式调用public interface StreamingChatLanguageModel { void generate(ListChatMessage messages, StreamingResponseHandlerAiMessage handler); }在 Spring Boot 里通常配合 SSE 或者 WebSocket 把流式结果推给前端。这里有个实操要点不是所有模型都支持流式有些本地部署的小模型或者某些厂商的兼容接口可能不支持。所以在模型中立架构里你的ChatService接口最好同时定义流式和非流式方法然后根据当前激活的模型能力来决定用哪个。我一般的做法是在配置里加一个ai.model.streaming-enabled开关业务层根据这个开关决定调用哪个方法。这样即使换到一个不支持流式的模型业务也不会崩只是降级为非流式。4. 完整实操从零搭建模型中立的 Spring Boot 项目4.1 项目骨架与依赖配置先创建一个标准的 Spring Boot 项目用 Maven 管理依赖。除了 LangChain4j 相关的包还需要spring-boot-starter-web来提供 REST 接口。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version0.35.0/version /dependency /dependencies项目结构建议这样组织src/main/java/com/example/modelneutral/ ├── config/ │ ├── ModelConfig.java # 模型 Bean 配置 │ └── AiServiceConfig.java # AiServices 配置 ├── service/ │ ├── ChatService.java # 业务接口 │ └── impl/ │ └── ChatServiceImpl.java # 业务实现 ├── controller/ │ └── ChatController.java # REST 接口 └── ModelNeutralApplication.java4.2 多模型配置类的编写ModelConfig是整个架构的核心它负责根据配置创建对应的ChatLanguageModel。我把它写成条件装配的形式每个模型一个Bean方法。Configuration Slf4j public class ModelConfig { Bean ConditionalOnProperty(name ai.model.provider, havingValue openai) public ChatLanguageModel openAiChatModel( Value(${ai.model.openai.api-key}) String apiKey, Value(${ai.model.openai.model-name:gpt-4o-mini}) String modelName, Value(${ai.model.openai.base-url:https://api.openai.com/v1}) String baseUrl, Value(${ai.model.openai.timeout:60s}) Duration timeout) { log.info(初始化 OpenAI 模型: {}, baseUrl: {}, modelName, baseUrl); return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .timeout(timeout) .logRequests(true) .logResponses(true) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue qwen) public ChatLanguageModel qwenChatModel( Value(${ai.model.qwen.api-key}) String apiKey, Value(${ai.model.qwen.model-name:qwen-plus}) String modelName, Value(${ai.model.qwen.base-url}) String baseUrl) { log.info(初始化通义千问模型: {}, baseUrl: {}, modelName, baseUrl); return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue ollama) public ChatLanguageModel ollamaChatModel( Value(${ai.model.ollama.base-url:http://localhost:11434}) String baseUrl, Value(${ai.model.ollama.model-name:qwen2.5:7b}) String modelName) { log.info(初始化 Ollama 本地模型: {}, baseUrl: {}, modelName, baseUrl); return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(modelName) .build(); } }注意通义千问这里用的是OpenAiChatModel因为通义的兼容模式完全兼容 OpenAI 协议。baseUrl填https://dashscope.aliyuncs.com/compatible-mode/v1。DeepSeek 也是类似baseUrl填https://api.deepseek.com/v1用OpenAiChatModel就能调。提示logRequests(true)和logResponses(true)在开发阶段很有用能看到实际发送的请求体和返回内容。但生产环境建议关掉避免日志里出现敏感信息。4.3 业务层接口定义与实现业务层定义一个ChatService接口只依赖 LangChain4j 的抽象类型public interface ChatService { String chat(String userMessage); String chatWithSystem(String systemPrompt, String userMessage); }实现类注入ChatLanguageModelService public class ChatServiceImpl implements ChatService { private final ChatLanguageModel chatModel; public ChatServiceImpl(ChatLanguageModel chatModel) { this.chatModel chatModel; } Override public String chat(String userMessage) { return chatModel.generate(userMessage); } Override public String chatWithSystem(String systemPrompt, String userMessage) { ListChatMessage messages List.of( SystemMessage.from(systemPrompt), UserMessage.from(userMessage) ); return chatModel.generate(messages).content().text(); } }这里的关键是构造器注入ChatLanguageModelSpring 会根据当前激活的配置自动注入对应的实现。业务代码里没有任何if-else判断模型类型完全中立。4.4 Controller 层与接口测试Controller 层就是标准的 REST 接口RestController RequestMapping(/api/chat) public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService chatService; } PostMapping public ResponseEntityMapString, String chat(RequestBody MapString, String request) { String message request.get(message); String reply chatService.chat(message); return ResponseEntity.ok(Map.of(reply, reply)); } }启动项目后用 curl 测试curl -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d {message: 用一句话解释什么是模型中立}如果配置的是 Ollama 本地模型确保 Ollama 服务已经启动并且模型已经拉取ollama pull qwen2.5:7b ollama serve4.5 切换模型的完整验证流程切换模型只需要改application.yml里的ai.model.provider值然后重启应用。比如从qwen切到ollamaai: model: provider: ollama重启后同样的 curl 请求会打到本地 Ollama 模型上。业务代码、Controller、Service 全部不变。这就是模型中立的价值。我实测下来从通义千问切到 DeepSeek再切到本地 Ollama整个过程不超过两分钟主要时间花在重启应用上。如果配合 Spring Cloud Config 或者 Nacos 做动态配置刷新甚至可以不重启就切换模型。5. 常见问题与排查技巧实录5.1 baseUrl 配置错误的典型表现baseUrl配错是最高频的问题。不同厂商的兼容接口路径不一样我整理了一个对照表厂商baseUrl备注OpenAIhttps://api.openai.com/v1标准路径通义千问https://dashscope.aliyuncs.com/compatible-mode/v1必须带/compatible-mode/v1DeepSeekhttps://api.deepseek.com/v1标准兼容路径智谱https://open.bigmodel.cn/api/paas/v4路径不同注意版本号Ollamahttp://localhost:11434/v1本地默认端口带/v1LocalAIhttp://localhost:8080/v1取决于部署配置配错的典型报错是404 Not Found或者Connection refused。如果看到 404先检查baseUrl结尾是不是多了或少了/v1。如果看到Connection refused检查服务是否启动、端口是否正确。注意有些厂商的文档里给的 baseUrl 不带/v1但 LangChain4j 的OpenAiChatModel会自动拼接/chat/completions所以你需要确保 baseUrl 是完整的到版本号的路径。我踩过这个坑通义的 baseUrl 如果只写到https://dashscope.aliyuncs.com会直接 404。5.2 模型名称不匹配导致的 400 错误另一个常见问题是模型名称写错。每个厂商的模型名称格式不一样比如 OpenAI 是gpt-4o-mini通义是qwen-plus、qwen-turboDeepSeek 是deepseek-chat、deepseek-coder。写错了会返回 400 错误提示model not found或者invalid model。我的经验是在配置类里给模型名称设一个默认值同时在启动日志里打印出来。这样一旦报错看日志就能确认实际用的模型名是什么。log.info(初始化模型: provider{}, modelName{}, baseUrl{}, provider, modelName, baseUrl);5.3 超时与重试策略配置大模型调用有时候会比较慢特别是长文本生成或者本地小模型。默认超时可能不够需要根据实际情况调整。OpenAiChatModel的 builder 支持设置timeout.timeout(Duration.ofSeconds(120)) .maxRetries(3)maxRetries在遇到 429限流或者 5xx 错误时会自动重试。但要注意重试会增加费用如果按 token 计费所以生产环境要权衡。我一般设maxRetries(2)配合指数退避。对于流式调用超时设置要更宽松因为流式响应本身持续时间就长。LangChain4j 的流式接口没有直接暴露 timeout 配置需要通过底层的 HTTP 客户端来设置。5.4 本地模型与云端模型的差异处理本地模型比如 Ollama 跑的 Qwen2.5-7B和云端模型GPT-4o在能力上有明显差距。模型中立架构虽然让你能无缝切换但业务逻辑可能需要根据模型能力做降级。比如云端模型能很好地处理复杂的多轮对话和长上下文本地 7B 模型可能上下文窗口只有 8K超过就截断了。我的做法是在配置里加一个ai.model.capabilities配置声明当前模型的最大上下文长度、是否支持 function calling、是否支持流式等。业务层根据这些能力声明来决定是否走降级逻辑。ai: model: provider: ollama capabilities: max-context-length: 8192 streaming-enabled: true function-calling-enabled: false这样即使切换到能力较弱的本地模型业务也不会因为超出上下文而报错而是自动截断或者提示用户。5.5 常见问题速查表问题现象可能原因排查方向404 Not FoundbaseUrl 路径错误检查是否缺少/v1或版本路径401 UnauthorizedAPI Key 无效或未配置检查环境变量和 yml 配置400 Bad Request模型名称错误确认厂商文档中的模型名429 Too Many Requests触发限流降低并发或增加重试等待连接超时网络问题或服务未启动检查本地服务状态和网络连通性返回内容为空模型不支持该消息格式检查 system message 兼容性流式输出中断超时或模型不支持检查流式配置和模型能力6. 模型中立架构的扩展与进阶玩法6.1 多模型路由与 fallback 机制模型中立做到后面自然会想到多模型路由。比如主模型用 GPT-4o备用模型用通义千问当主模型限流或故障时自动切换到备用模型。这个在 LangChain4j 里可以通过自定义ChatLanguageModel实现来做。思路是写一个RoutingChatLanguageModel内部持有多个ChatLanguageModel根据配置的优先级和健康状态来决定用哪个。这个实现起来不复杂但要注意 fallback 的触发条件要明确不能主模型返回一个正常但质量不高的结果也触发 fallback。6.2 结合 RAG 的模型中立设计RAG检索增强生成是现在大模型应用的主流模式。在模型中立架构里RAG 的检索部分Embedding 向量库和生成部分ChatModel应该分开解耦。LangChain4j 提供了EmbeddingModel和EmbeddingStore的抽象同样可以用配置驱动的方式切换。比如 Embedding 用本地的bge-small-zhChatModel 用云端的 GPT-4o这种混合架构在成本和效果之间取得平衡。关键是每一层都通过接口解耦换任何一个组件都不影响其他部分。6.3 配置热更新与动态切换如果不想重启应用就切换模型可以结合 Spring Cloud Config 或者 Nacos 做配置热更新。核心思路是把ChatLanguageModel的创建逻辑放到一个RefreshScope的 Bean 里配置变更时重新创建 Bean。但这里有个坑ChatLanguageModel通常会被AiServices代理持有直接刷新ChatLanguageModelBean 可能不会让AiServices感知到。我的做法是用一个ModelHolder类持有当前模型业务层通过ModelHolder.get()获取配置刷新时更新ModelHolder内部的引用。这样虽然多了一层间接但热切换更可靠。6.4 模型调用的监控与成本统计模型中立之后监控和成本统计也需要统一。不同厂商的计费方式不一样但 token 消耗量是通用的指标。LangChain4j 的Response对象里包含了TokenUsage信息可以在业务层统一收集。我一般会在ChatService的实现里加一个拦截逻辑每次调用后记录 token 消耗、耗时、模型名称然后上报到监控系统。这样不管底层换什么模型成本数据都是连续的。ResponseAiMessage response chatModel.generate(messages); TokenUsage usage response.tokenUsage(); log.info(模型调用: model{}, inputTokens{}, outputTokens{}, costTime{}ms, currentModelName, usage.inputTokenCount(), usage.outputTokenCount(), costTime);这个数据积累下来对后续选择模型、优化 prompt、控制成本都非常有价值。6.5 团队协作中的模型中立规范最后聊一个容易被忽视的点团队规范。模型中立不只是技术架构更是一种协作约定。我在团队里推这个架构的时候定了几条规矩业务代码里禁止直接import任何厂商的 SDK 类只能import dev.langchain4j.model.chat.ChatLanguageModel。新增模型支持必须通过配置类不允许在业务代码里写if (provider.equals(xxx))。所有 prompt 模板集中管理不散落在各个 Service 里。模型切换必须经过测试环境验证确认输出质量可接受后再上生产。这些规矩看起来简单但执行下来能避免很多“临时改一下”导致的架构腐化。模型中立的价值在于长期可维护性如果因为赶进度就随便破坏约定那还不如一开始就焊死。我个人在实际操作中的体会是模型中立架构的初期投入大概多花两三天但第一次换模型的时候就能回本。后面每次换模型、加模型、做 A/B 测试都是配置级别的工作量。对于任何需要长期迭代的 AI 应用来说这笔投入都值得。 
长河君 · 2026/11/5 6:24:11 · 阅读 1.2k LangChain4j模型中立架构：业务代码解耦大模型实践
1. 为什么你的业务代码不该跟大模型“领证”我见过太多团队在接入大模型这件事上一开始就给自己挖了个深坑。项目立项老板说“我们要用AI”技术负责人一拍脑袋选了个当时最火的模型然后直接在业务代码里new一个客户端把 API Key、模型名称、请求地址硬编码进去。三个月后老板说“换个模型试试听说那个更便宜”或者“国产化要求得换成国内某个模型”这时候你打开代码一看模型调用散落在几十个 Service 里每个地方都写着具体的模型名和地址改起来跟拆炸弹一样。这就是典型的“把大模型焊死在业务里”。模型不是你的业务逻辑它只是一个外部依赖一个随时可能被替换的零件。今天 GPT-4 效果最好明天可能 Claude 更便宜后天国产模型追上来性价比更高。如果你的业务代码跟某一个具体模型深度耦合那每次换模型都是一次伤筋动骨的重构。模型中立这个概念说白了就是让你的业务代码只依赖一个抽象的“对话能力”接口而不是依赖某个具体厂商的 SDK。就像你家里装修插座用的是国标五孔不管你插的是小米电视还是格力空调插座本身不关心。模型中立要做的就是定义好这个“插座标准”然后让各个模型厂商的 SDK 去适配这个标准。这件事在 Java 生态里LangChain4j是目前最值得关注的方案之一。它提供了一套统一的 API让你可以用同样的代码调用 OpenAI、通义千问、DeepSeek、Ollama 本地模型等等。你只需要在配置文件里改一个baseUrl和模型名称业务代码一行不用动。这篇文章我就从实际项目经验出发把模型中立的落地思路、LangChain4j 的集成细节、踩过的坑和排查技巧完整地聊一遍。注意本文讨论的是架构设计层面的模型解耦不涉及任何网络访问工具或特殊渠道。所有模型调用均基于各厂商官方公开的 API 接口。2. 模型中立的整体架构设计思路2.1 核心原则业务层只认接口不认厂商模型中立的本质是依赖倒置。你的业务层应该依赖一个抽象的ChatLanguageModel接口而不是依赖OpenAiChatModel或者QwenChatModel这样的具体实现。这个接口定义的是“输入一组消息返回一个回复”这样的能力契约至于背后是哪个模型在干活业务层不关心。在 Spring 项目里这个思路落地下来就是定义一个AiService接口业务代码注入这个接口具体的模型实现通过配置文件和条件装配来决定。LangChain4j 已经帮你把ChatLanguageModel这个抽象定义好了你要做的是在 Spring 配置层把它组装起来。我试过几种不同的组织方式最后觉得最舒服的是三层结构接口层定义业务需要的 AI 能力比如ChatService、EmbeddingService、RagService这些接口只依赖 LangChain4j 的抽象类型。适配层针对每个模型厂商写一个配置类负责创建对应的ChatLanguageModelBean。这一层是唯一跟具体厂商 SDK 打交道的地方。配置层用application.yml控制激活哪个模型通过ConditionalOnProperty实现条件装配。这样做的直接好处是换模型的时候你只需要改配置文件重新启动业务代码零改动。间接好处是测试的时候可以轻松 mock 掉模型调用单元测试不用真的去请求外部 API。2.2 为什么选 LangChain4j 而不是 Spring AISpring AI 也是很好的方案但在我实际用下来LangChain4j 在模型支持的广度和 API 的稳定性上更胜一筹。LangChain4j 支持的模型列表非常长从 OpenAI、Anthropic 到通义千问、DeepSeek、智谱、Ollama、LocalAI基本上你听说过的它都有对应的ChatLanguageModel实现。而且它的 API 设计比较统一不同模型之间的切换成本很低。另一个关键点是LangChain4j 的baseUrl可配置性。很多国产模型和本地部署方案都兼容 OpenAI 的 API 格式你只需要把baseUrl指向对应的地址就能用同一套代码调用。这个特性在模型中立架构里非常关键因为它意味着你甚至不需要为每个模型写适配器只要它们兼容 OpenAI 协议一个OpenAiChatModel配上不同的baseUrl就能通吃。Spring AI 在这方面也在快速追赶但如果你现在就要做一个需要支持多种模型、包括本地模型的项目LangChain4j 的成熟度更高。当然如果你的项目已经深度使用 Spring 生态Spring AI 的集成度会更自然这个后面我会细说。2.3 配置驱动的模型切换机制模型中立的核心实现手段是配置驱动。在application.yml里定义一个ai.model.provider属性然后在配置类里根据这个属性决定创建哪个ChatLanguageModelBean。ai: model: provider: qwen qwen: api-key: ${QWEN_API_KEY} model-name: qwen-plus base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 openai: api-key: ${OPENAI_API_KEY} model-name: gpt-4o-mini base-url: https://api.openai.com/v1 ollama: base-url: http://localhost:11434/v1 model-name: qwen2.5:7b对应的 Java 配置类用ConditionalOnProperty来条件装配Configuration public class ModelConfig { Bean ConditionalOnProperty(name ai.model.provider, havingValue qwen) public ChatLanguageModel qwenChatModel( Value(${ai.model.qwen.api-key}) String apiKey, Value(${ai.model.qwen.model-name}) String modelName, Value(${ai.model.qwen.base-url}) String baseUrl) { return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue ollama) public ChatLanguageModel ollamaChatModel( Value(${ai.model.ollama.base-url}) String baseUrl, Value(${ai.model.ollama.model-name}) String modelName) { return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(modelName) .build(); } }这个模式的好处是新增一个模型只需要加一个配置类和一段 yml不需要动任何现有代码。而且因为ChatLanguageModel是同一个接口业务层注入的时候完全无感知。提示baseUrl的配置要特别注意结尾的/v1路径。不同厂商的兼容接口路径不一样有的需要/v1有的不需要配错了会直接 404。这个后面排查章节会细说。3. LangChain4j 核心细节与实操要点3.1 依赖引入与版本选择LangChain4j 的 Maven 依赖需要根据你用的模型来选。核心包是langchain4j-core但通常你不需要单独引它因为具体的模型包会传递依赖进来。properties langchain4j.version0.35.0/langchain4j.version /properties dependencies !-- 核心抽象通常被具体实现传递依赖 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- OpenAI 兼容协议实现通义、DeepSeek 等都用这个 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency !-- Ollama 本地模型 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version${langchain4j.version}/version /dependency !-- Spring Boot Starter简化集成 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency /dependencies版本选择上我建议用 0.35.0 或更新的稳定版。LangChain4j 迭代很快0.3x 系列在 API 稳定性上已经不错了。注意langchain4j-spring-boot-starter这个包它提供了一些自动配置但在模型中立场景下我建议还是自己写配置类因为 starter 的自动配置往往假设你只有一个模型不够灵活。3.2 ChatLanguageModel 的统一抽象ChatLanguageModel是 LangChain4j 最核心的接口它只有一个主要方法public interface ChatLanguageModel { String generate(String userMessage); ResponseAiMessage generate(ListChatMessage messages); // 还有其他重载 }所有模型实现都遵循这个接口。OpenAiChatModel、OllamaChatModel、QwenChatModel如果有的话都实现了它。这意味着你在业务代码里注入ChatLanguageModel调用generate方法完全不需要知道背后是谁。但这里有个细节要注意不同模型对消息角色的支持程度不一样。比如 system messageOpenAI 支持得很好但某些本地小模型可能对 system message 的处理比较弱。LangChain4j 在抽象层做了统一但实际效果还是取决于模型本身。所以在模型中立架构里你的 prompt 设计要尽量兼容性广一些不要过度依赖某个模型特有的能力。3.3 用 AiServices 进一步解耦LangChain4j 提供了一个更高级的抽象叫AiServices它允许你用接口 注解的方式定义 AI 服务框架自动生成实现。这个在模型中立架构里非常有用因为它把“调用模型”这件事完全声明式化了。public interface Assistant { SystemMessage(你是一个专业的客服助手回答要简洁准确。) String chat(UserMessage String userMessage); } // 在配置类里创建 Bean public Assistant assistant(ChatLanguageModel chatModel) { return AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .build(); }业务代码注入Assistant接口调用chat方法完全看不到模型的存在。换模型的时候ChatLanguageModelBean 变了Assistant自动跟着变业务代码纹丝不动。这是我认为模型中立架构里最优雅的落地方式。注意AiServices创建的代理对象是线程安全的可以放心注入到单例 Service 里。但如果你用了MemoryId做多轮对话记忆要注意记忆存储的并发问题。3.4 流式输出的统一处理流式输出是现在大模型应用的标配但不同模型的流式实现细节有差异。LangChain4j 提供了StreamingChatLanguageModel接口来统一流式调用public interface StreamingChatLanguageModel { void generate(ListChatMessage messages, StreamingResponseHandlerAiMessage handler); }在 Spring Boot 里通常配合 SSE 或者 WebSocket 把流式结果推给前端。这里有个实操要点不是所有模型都支持流式有些本地部署的小模型或者某些厂商的兼容接口可能不支持。所以在模型中立架构里你的ChatService接口最好同时定义流式和非流式方法然后根据当前激活的模型能力来决定用哪个。我一般的做法是在配置里加一个ai.model.streaming-enabled开关业务层根据这个开关决定调用哪个方法。这样即使换到一个不支持流式的模型业务也不会崩只是降级为非流式。4. 完整实操从零搭建模型中立的 Spring Boot 项目4.1 项目骨架与依赖配置先创建一个标准的 Spring Boot 项目用 Maven 管理依赖。除了 LangChain4j 相关的包还需要spring-boot-starter-web来提供 REST 接口。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version0.35.0/version /dependency /dependencies项目结构建议这样组织src/main/java/com/example/modelneutral/ ├── config/ │ ├── ModelConfig.java # 模型 Bean 配置 │ └── AiServiceConfig.java # AiServices 配置 ├── service/ │ ├── ChatService.java # 业务接口 │ └── impl/ │ └── ChatServiceImpl.java # 业务实现 ├── controller/ │ └── ChatController.java # REST 接口 └── ModelNeutralApplication.java4.2 多模型配置类的编写ModelConfig是整个架构的核心它负责根据配置创建对应的ChatLanguageModel。我把它写成条件装配的形式每个模型一个Bean方法。Configuration Slf4j public class ModelConfig { Bean ConditionalOnProperty(name ai.model.provider, havingValue openai) public ChatLanguageModel openAiChatModel( Value(${ai.model.openai.api-key}) String apiKey, Value(${ai.model.openai.model-name:gpt-4o-mini}) String modelName, Value(${ai.model.openai.base-url:https://api.openai.com/v1}) String baseUrl, Value(${ai.model.openai.timeout:60s}) Duration timeout) { log.info(初始化 OpenAI 模型: {}, baseUrl: {}, modelName, baseUrl); return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .timeout(timeout) .logRequests(true) .logResponses(true) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue qwen) public ChatLanguageModel qwenChatModel( Value(${ai.model.qwen.api-key}) String apiKey, Value(${ai.model.qwen.model-name:qwen-plus}) String modelName, Value(${ai.model.qwen.base-url}) String baseUrl) { log.info(初始化通义千问模型: {}, baseUrl: {}, modelName, baseUrl); return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .baseUrl(baseUrl) .build(); } Bean ConditionalOnProperty(name ai.model.provider, havingValue ollama) public ChatLanguageModel ollamaChatModel( Value(${ai.model.ollama.base-url:http://localhost:11434}) String baseUrl, Value(${ai.model.ollama.model-name:qwen2.5:7b}) String modelName) { log.info(初始化 Ollama 本地模型: {}, baseUrl: {}, modelName, baseUrl); return OllamaChatModel.builder() .baseUrl(baseUrl) .modelName(modelName) .build(); } }注意通义千问这里用的是OpenAiChatModel因为通义的兼容模式完全兼容 OpenAI 协议。baseUrl填https://dashscope.aliyuncs.com/compatible-mode/v1。DeepSeek 也是类似baseUrl填https://api.deepseek.com/v1用OpenAiChatModel就能调。提示logRequests(true)和logResponses(true)在开发阶段很有用能看到实际发送的请求体和返回内容。但生产环境建议关掉避免日志里出现敏感信息。4.3 业务层接口定义与实现业务层定义一个ChatService接口只依赖 LangChain4j 的抽象类型public interface ChatService { String chat(String userMessage); String chatWithSystem(String systemPrompt, String userMessage); }实现类注入ChatLanguageModelService public class ChatServiceImpl implements ChatService { private final ChatLanguageModel chatModel; public ChatServiceImpl(ChatLanguageModel chatModel) { this.chatModel chatModel; } Override public String chat(String userMessage) { return chatModel.generate(userMessage); } Override public String chatWithSystem(String systemPrompt, String userMessage) { ListChatMessage messages List.of( SystemMessage.from(systemPrompt), UserMessage.from(userMessage) ); return chatModel.generate(messages).content().text(); } }这里的关键是构造器注入ChatLanguageModelSpring 会根据当前激活的配置自动注入对应的实现。业务代码里没有任何if-else判断模型类型完全中立。4.4 Controller 层与接口测试Controller 层就是标准的 REST 接口RestController RequestMapping(/api/chat) public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService chatService; } PostMapping public ResponseEntityMapString, String chat(RequestBody MapString, String request) { String message request.get(message); String reply chatService.chat(message); return ResponseEntity.ok(Map.of(reply, reply)); } }启动项目后用 curl 测试curl -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d {message: 用一句话解释什么是模型中立}如果配置的是 Ollama 本地模型确保 Ollama 服务已经启动并且模型已经拉取ollama pull qwen2.5:7b ollama serve4.5 切换模型的完整验证流程切换模型只需要改application.yml里的ai.model.provider值然后重启应用。比如从qwen切到ollamaai: model: provider: ollama重启后同样的 curl 请求会打到本地 Ollama 模型上。业务代码、Controller、Service 全部不变。这就是模型中立的价值。我实测下来从通义千问切到 DeepSeek再切到本地 Ollama整个过程不超过两分钟主要时间花在重启应用上。如果配合 Spring Cloud Config 或者 Nacos 做动态配置刷新甚至可以不重启就切换模型。5. 常见问题与排查技巧实录5.1 baseUrl 配置错误的典型表现baseUrl配错是最高频的问题。不同厂商的兼容接口路径不一样我整理了一个对照表厂商baseUrl备注OpenAIhttps://api.openai.com/v1标准路径通义千问https://dashscope.aliyuncs.com/compatible-mode/v1必须带/compatible-mode/v1DeepSeekhttps://api.deepseek.com/v1标准兼容路径智谱https://open.bigmodel.cn/api/paas/v4路径不同注意版本号Ollamahttp://localhost:11434/v1本地默认端口带/v1LocalAIhttp://localhost:8080/v1取决于部署配置配错的典型报错是404 Not Found或者Connection refused。如果看到 404先检查baseUrl结尾是不是多了或少了/v1。如果看到Connection refused检查服务是否启动、端口是否正确。注意有些厂商的文档里给的 baseUrl 不带/v1但 LangChain4j 的OpenAiChatModel会自动拼接/chat/completions所以你需要确保 baseUrl 是完整的到版本号的路径。我踩过这个坑通义的 baseUrl 如果只写到https://dashscope.aliyuncs.com会直接 404。5.2 模型名称不匹配导致的 400 错误另一个常见问题是模型名称写错。每个厂商的模型名称格式不一样比如 OpenAI 是gpt-4o-mini通义是qwen-plus、qwen-turboDeepSeek 是deepseek-chat、deepseek-coder。写错了会返回 400 错误提示model not found或者invalid model。我的经验是在配置类里给模型名称设一个默认值同时在启动日志里打印出来。这样一旦报错看日志就能确认实际用的模型名是什么。log.info(初始化模型: provider{}, modelName{}, baseUrl{}, provider, modelName, baseUrl);5.3 超时与重试策略配置大模型调用有时候会比较慢特别是长文本生成或者本地小模型。默认超时可能不够需要根据实际情况调整。OpenAiChatModel的 builder 支持设置timeout.timeout(Duration.ofSeconds(120)) .maxRetries(3)maxRetries在遇到 429限流或者 5xx 错误时会自动重试。但要注意重试会增加费用如果按 token 计费所以生产环境要权衡。我一般设maxRetries(2)配合指数退避。对于流式调用超时设置要更宽松因为流式响应本身持续时间就长。LangChain4j 的流式接口没有直接暴露 timeout 配置需要通过底层的 HTTP 客户端来设置。5.4 本地模型与云端模型的差异处理本地模型比如 Ollama 跑的 Qwen2.5-7B和云端模型GPT-4o在能力上有明显差距。模型中立架构虽然让你能无缝切换但业务逻辑可能需要根据模型能力做降级。比如云端模型能很好地处理复杂的多轮对话和长上下文本地 7B 模型可能上下文窗口只有 8K超过就截断了。我的做法是在配置里加一个ai.model.capabilities配置声明当前模型的最大上下文长度、是否支持 function calling、是否支持流式等。业务层根据这些能力声明来决定是否走降级逻辑。ai: model: provider: ollama capabilities: max-context-length: 8192 streaming-enabled: true function-calling-enabled: false这样即使切换到能力较弱的本地模型业务也不会因为超出上下文而报错而是自动截断或者提示用户。5.5 常见问题速查表问题现象可能原因排查方向404 Not FoundbaseUrl 路径错误检查是否缺少/v1或版本路径401 UnauthorizedAPI Key 无效或未配置检查环境变量和 yml 配置400 Bad Request模型名称错误确认厂商文档中的模型名429 Too Many Requests触发限流降低并发或增加重试等待连接超时网络问题或服务未启动检查本地服务状态和网络连通性返回内容为空模型不支持该消息格式检查 system message 兼容性流式输出中断超时或模型不支持检查流式配置和模型能力6. 模型中立架构的扩展与进阶玩法6.1 多模型路由与 fallback 机制模型中立做到后面自然会想到多模型路由。比如主模型用 GPT-4o备用模型用通义千问当主模型限流或故障时自动切换到备用模型。这个在 LangChain4j 里可以通过自定义ChatLanguageModel实现来做。思路是写一个RoutingChatLanguageModel内部持有多个ChatLanguageModel根据配置的优先级和健康状态来决定用哪个。这个实现起来不复杂但要注意 fallback 的触发条件要明确不能主模型返回一个正常但质量不高的结果也触发 fallback。6.2 结合 RAG 的模型中立设计RAG检索增强生成是现在大模型应用的主流模式。在模型中立架构里RAG 的检索部分Embedding 向量库和生成部分ChatModel应该分开解耦。LangChain4j 提供了EmbeddingModel和EmbeddingStore的抽象同样可以用配置驱动的方式切换。比如 Embedding 用本地的bge-small-zhChatModel 用云端的 GPT-4o这种混合架构在成本和效果之间取得平衡。关键是每一层都通过接口解耦换任何一个组件都不影响其他部分。6.3 配置热更新与动态切换如果不想重启应用就切换模型可以结合 Spring Cloud Config 或者 Nacos 做配置热更新。核心思路是把ChatLanguageModel的创建逻辑放到一个RefreshScope的 Bean 里配置变更时重新创建 Bean。但这里有个坑ChatLanguageModel通常会被AiServices代理持有直接刷新ChatLanguageModelBean 可能不会让AiServices感知到。我的做法是用一个ModelHolder类持有当前模型业务层通过ModelHolder.get()获取配置刷新时更新ModelHolder内部的引用。这样虽然多了一层间接但热切换更可靠。6.4 模型调用的监控与成本统计模型中立之后监控和成本统计也需要统一。不同厂商的计费方式不一样但 token 消耗量是通用的指标。LangChain4j 的Response对象里包含了TokenUsage信息可以在业务层统一收集。我一般会在ChatService的实现里加一个拦截逻辑每次调用后记录 token 消耗、耗时、模型名称然后上报到监控系统。这样不管底层换什么模型成本数据都是连续的。ResponseAiMessage response chatModel.generate(messages); TokenUsage usage response.tokenUsage(); log.info(模型调用: model{}, inputTokens{}, outputTokens{}, costTime{}ms, currentModelName, usage.inputTokenCount(), usage.outputTokenCount(), costTime);这个数据积累下来对后续选择模型、优化 prompt、控制成本都非常有价值。6.5 团队协作中的模型中立规范最后聊一个容易被忽视的点团队规范。模型中立不只是技术架构更是一种协作约定。我在团队里推这个架构的时候定了几条规矩业务代码里禁止直接import任何厂商的 SDK 类只能import dev.langchain4j.model.chat.ChatLanguageModel。新增模型支持必须通过配置类不允许在业务代码里写if (provider.equals(xxx))。所有 prompt 模板集中管理不散落在各个 Service 里。模型切换必须经过测试环境验证确认输出质量可接受后再上生产。这些规矩看起来简单但执行下来能避免很多“临时改一下”导致的架构腐化。模型中立的价值在于长期可维护性如果因为赶进度就随便破坏约定那还不如一开始就焊死。我个人在实际操作中的体会是模型中立架构的初期投入大概多花两三天但第一次换模型的时候就能回本。后面每次换模型、加模型、做 A/B 测试都是配置级别的工作量。对于任何需要长期迭代的 AI 应用来说这笔投入都值得。