基于LangChain4j的多Provider切换与RAG、Agent架构实战

1. 为什么要在项目里做多 Provider 切换

做过 AI 应用的人大概都有过这种体验：项目刚起步时接了一家大模型，代码写得挺顺，结果业务方突然说“我们想试试另一家的效果”，或者某天接口开始限流、响应变慢，你才发现整个调用逻辑跟那家 SDK 绑得死死的，改起来牵一发动全身。这就是我在做这个 AI 模块架构时踩过的第一个坑，也是我把“多 Provider 切换”放在架构最底层的原因。

所谓多 Provider，说白了就是让系统能同时对接多家大模型服务，并且能在运行时按需切换。它解决的核心问题是解耦——业务代码不应该关心底层到底调的是哪家模型，只关心“我发一段话，拿回一个结果”。这个思路跟数据库连接池、消息队列抽象层是一个道理，只不过对象换成了大模型。

我见过太多项目把模型调用直接写死在 Service 里，new OpenAiClient()一挂，后面想换模型就得全局搜索替换。这种写法在 Demo 阶段没问题，一旦进入真实业务，尤其是需要做 A/B 测试、成本控制、故障降级的场景，就会非常痛苦。举个实际例子：我们有个功能对响应速度要求高，用某家模型延迟稳定在 800ms 左右，但另一家只要 400ms 却贵一倍。如果没有 Provider 抽象层，你只能二选一；有了抽象层，你可以让这个功能走快的、那个功能走便宜的，甚至高峰期自动降级到便宜的那家。

从技术选型上看，我最终选了LangChain4j作为基础框架。原因很直接：它原生支持多家模型 Provider，接口统一，而且对 RAG 和 Agent 的支持是内建的，不用自己从零搭轮子。LangChain4j 的ChatLanguageModel接口就是那个抽象层，OpenAI、通义千问、DeepSeek、Ollama 本地模型都实现了它，切换时只需要换一个实现类，业务代码一行不用动。

这里有个关键设计点值得展开说：Provider 的配置不能硬编码。我采用的是“配置驱动 + 工厂模式”的组合。配置文件里定义每个 Provider 的base_url、api_key、model_name、timeout等参数，启动时由工厂类读取配置并实例化对应的 Model 对象，注册到一个ProviderRegistry里。业务层通过ProviderRegistry.get("providerName")拿到模型实例。这样做的好处是，新增一家 Provider 只需要加一段配置，不用改代码、不用重新编译。

注意：base_url配置缺失是新手最容易犯的错。我见过好几次报错信息里写着“provider 缺少 base_url 配置”，排查半天发现是配置文件里漏了一行。建议在工厂类里做启动时校验，缺参数直接抛异常，别等到运行时才报错。

还有一个容易被忽略的点是超时和重试策略。不同 Provider 的响应特性差异很大，有的首包快但整体慢，有的首包慢但流式输出稳。我在每个 Provider 的配置里都单独设了connectTimeout、readTimeout和maxRetries，并且重试逻辑做了区分：网络类错误重试，参数类错误直接失败不重试。这个细节后面在问题排查章节还会细说。

2. RAG 知识库的架构设计与落地细节

RAG 这个词这两年已经被说烂了，但真正落地时你会发现，从“知道 RAG 是什么”到“RAG 命中率能看”之间隔着一条鸿沟。我在这个模块里把 RAG 拆成了四个独立环节：文档加载、切分、向量化、检索，每个环节都可以单独调优，这样出问题时能快速定位是哪一步拖了后腿。

先说文档加载。LangChain4j 提供了DocumentLoader接口，支持从文件系统、URL、数据库等多种来源加载。我实际项目里主要是 PDF、Word 和 Markdown 三种格式。PDF 解析用的是 Apache PDFBox，这里有个坑：扫描版 PDF 直接解析出来是空的，需要先做 OCR。我的处理方式是加载时先判断文本提取结果的长度，如果低于阈值就标记为“需 OCR”，走另一条处理链路。Word 文档相对简单，但要注意表格内容的提取，默认解析器会把表格拍平成纯文本，丢失结构信息，如果知识库里有大量表格，建议自定义解析逻辑保留行列关系。

文档切分是影响检索质量的关键一步。LangChain4j 内置了多种DocumentSplitter，我常用的是RecursiveCharacterTextSplitter，它按段落、句子、字符的优先级递归切分，尽量保持语义完整。参数上，chunkSize我一般设 500 到 800 个字符，chunkOverlap设 50 到 100。为什么是这个范围？因为太小了语义不完整，检索出来答非所问；太大了向量表示会被稀释，相似度计算不准。这个值没有标准答案，得根据你的文档类型调。技术文档可以小一点，叙述性内容可以大一点。

向量化环节，我选的是本地嵌入模型加远程嵌入模型双轨制。本地用 Ollama 跑一个轻量嵌入模型，适合开发调试和隐私敏感场景；生产环境用远程嵌入 API，效果好但要注意成本和限流。LangChain4j 的EmbeddingModel接口同样做了抽象，切换嵌入模型和切换对话模型一样简单。这里要提醒一句：嵌入模型换了，整个向量库必须重建，因为不同模型生成的向量空间不兼容，混用会导致检索结果完全错乱。

检索环节我做了两层优化。第一层是混合检索，把向量相似度检索和关键词检索的结果做融合。纯向量检索对语义匹配好，但对专有名词、型号、代码片段这类精确匹配弱；关键词检索正好互补。LangChain4j 支持通过EmbeddingStoreContentRetriever配置，我在此基础上加了一个基于 Lucene 的关键词检索器，两路结果用 RRF（倒数排名融合）算法合并。第二层是重排序，检索出 Top 20 后，用一个交叉编码器模型对每个候选做精排，取 Top 5 送给大模型。这一步能把命中率提升 15% 到 25%，代价是增加一点延迟，但非常值得。

实操心得：RAG 的瓶颈往往不在检索算法，而在文档质量。我花在清洗文档上的时间比调参多得多。建议在入库前做一轮预处理：去掉页眉页脚、合并断行、统一标点、剔除乱码。这些脏数据对检索的负面影响远超你的想象。

另外提一下 GraphRAG 和本体 RAG 这两个进阶方向。GraphRAG 是把文档里的实体和关系抽出来构建知识图谱，检索时同时走图查询和向量查询，适合关系密集型知识库，比如专利、法律、医疗领域。本体 RAG 则是预先定义好领域本体结构，让检索和生成都围绕本体展开。这两个方案效果确实好，但构建成本高，我一般建议先用基础 RAG 跑通，有明确瓶颈再上。

3. Agent 编排的核心机制与实现路径

Agent 是这个模块里最复杂也最有意思的部分。简单说，Agent 就是让大模型不只是“回答问题”，而是能“决定做什么、调用什么工具、按什么顺序做”。LangChain4j 对 Agent 的支持主要通过AiServices和工具调用机制实现，我在此基础上做了一层编排层。

先讲工具调用。LangChain4j 允许你用@Tool注解把一个 Java 方法暴露给大模型，模型在需要时会生成调用请求，框架负责执行并把结果回传。这个机制是 Agent 的基础能力。我项目里定义了几类工具：知识库检索工具、数据库查询工具、外部 API 调用工具、计算工具。每个工具都有清晰的描述和参数说明，因为模型是靠这些描述来决定用哪个工具的。描述写得含糊，模型就会乱调或者不调。

工具定义有个细节：参数类型要简单。我试过用复杂的嵌套对象做参数，模型经常生成不合法的 JSON。后来改成扁平的基本类型加字符串，成功率大幅提升。如果确实需要复杂结构，就让参数是 JSON 字符串，在工具方法内部自己解析，这样模型只需要保证 JSON 格式正确即可。

Agent 编排的核心是执行循环。一个典型的 Agent 执行流程是这样的：接收用户输入，模型判断是否需要调用工具，如果需要就生成工具调用请求，框架执行工具并把结果追加到对话历史，模型基于新上下文继续判断，直到模型认为可以给出最终答案。这个循环要有最大轮次限制，否则模型可能陷入死循环。我设的是 10 轮，超过就强制终止并返回当前结果。

LangChain4j 的AiServices提供了声明式的 Agent 定义方式，你定义一个接口，用注解标注哪些方法需要工具支持，框架自动生成实现。这种方式适合简单场景。复杂场景我建议自己写编排逻辑，因为你需要控制每一步的异常处理、超时、日志和状态管理。我的做法是定义一个AgentExecutor，内部维护对话状态、工具注册表和执行策略，每一步都有明确的输入输出和错误处理。

多 Agent 协作是另一个层次。我项目里有一个“研究 Agent”负责检索和整理资料，一个“写作 Agent”负责生成内容，一个“审核 Agent”负责检查事实和格式。它们之间通过消息传递协作，由一个协调器决定任务分配和流转。这种架构适合复杂任务，但调试难度也大。我的经验是：先从单 Agent 加多工具开始，确实需要分工再拆多 Agent，否则你会花大量时间在 Agent 之间的通信和状态同步上。

注意：Agent 执行中最常见的错误是“工具调用参数不合法”和“模型不按预期调用工具”。前者靠简化参数类型解决，后者靠优化工具描述和给模型提供 few-shot 示例解决。我在系统提示词里会放两三个工具调用的正确示例，效果立竿见影。

还有一个实际问题是执行终止条件。除了最大轮次，我还加了“连续两次调用同一工具且参数相同”就终止的逻辑，防止模型卡在某个工具上反复调用。另外，如果工具执行抛异常，我会把异常信息作为工具结果返回给模型，让它自己决定是重试还是换方案，而不是直接中断整个流程。这个设计让 Agent 的鲁棒性好了很多。

4. 多 Provider 切换的实操配置与代码落地

理论说完了，这一节直接上可复制的配置和代码。我用的是 Spring Boot 加 LangChain4j 的组合，配置走application.yml，工厂类负责实例化。

先看配置文件结构。我为每个 Provider 定义一组参数，用前缀区分：

ai: providers: openai: base-url: https://api.openai.com/v1 api-key: ${OPENAI_API_KEY} model-name: gpt-4o timeout: 30s max-retries: 2 deepseek: base-url: https://api.deepseek.com/v1 api-key: ${DEEPSEEK_API_KEY} model-name: deepseek-chat timeout: 60s max-retries: 1 ollama: base-url: http://localhost:11434 model-name: qwen2.5:7b timeout: 120s max-retries: 0 default-provider: openai

工厂类的核心逻辑是读取配置、校验必填项、创建对应的ChatLanguageModel实例并注册。LangChain4j 对不同 Provider 有不同的构建器，OpenAI 兼容的用OpenAiChatModel，Ollama 用OllamaChatModel。我写了一个ProviderFactory，根据配置里的类型字段决定用哪个构建器。

@Component public class ProviderFactory { private final Map<String, ChatLanguageModel> registry = new ConcurrentHashMap<>(); public void register(String name, ProviderConfig config) { if (config.getBaseUrl() == null || config.getBaseUrl().isBlank()) { throw new IllegalStateException("Provider [" + name + "] 缺少 base_url 配置"); } ChatLanguageModel model = switch (config.getType()) { case OPENAI_COMPATIBLE -> OpenAiChatModel.builder() .baseUrl(config.getBaseUrl()) .apiKey(config.getApiKey()) .modelName(config.getModelName()) .timeout(config.getTimeout()) .maxRetries(config.getMaxRetries()) .build(); case OLLAMA -> OllamaChatModel.builder() .baseUrl(config.getBaseUrl()) .modelName(config.getModelName()) .timeout(config.getTimeout()) .build(); }; registry.put(name, model); } public ChatLanguageModel get(String name) { ChatLanguageModel model = registry.get(name); if (model == null) { throw new IllegalArgumentException("未注册的 Provider: " + name); } return model; } }

业务层调用时，通过一个ModelRouter决定用哪个 Provider。路由策略我实现了三种：固定路由（按配置指定）、权重路由（按比例分流做 A/B 测试）、降级路由（主 Provider 失败时切备用）。降级路由的实现是在调用外层包一个 try-catch，捕获超时和连接异常后切换到备用 Provider 重试一次。

public String chat(String providerName, String userMessage) { try { return providerFactory.get(providerName).generate(userMessage); } catch (Exception e) { log.warn("Provider [{}] 调用失败，尝试降级", providerName, e); String fallback = routingConfig.getFallback(providerName); if (fallback != null) { return providerFactory.get(fallback).generate(userMessage); } throw e; } }

这里有个实操细节：降级不能无脑切。如果失败原因是参数错误（比如消息格式不对），切到另一个 Provider 一样会失败，白白增加延迟。所以我在 catch 里判断异常类型，只对网络类、超时类、限流类异常做降级，参数类异常直接抛出。

提示：base_url末尾不要带斜杠，有些 SDK 会拼接出双斜杠导致 404。这个坑我踩过，排查了半小时才发现是配置里多了一个/。

流式输出也要考虑。LangChain4j 的StreamingChatLanguageModel接口支持流式返回，但不同 Provider 的流式实现细节有差异。我在路由层统一做了适配，对外暴露的接口是Flux<String>，内部把各家的流式回调转成响应式流。这样前端只需要处理一种数据格式。

5. RAG 知识库从零搭建的完整流程

这一节我把 RAG 的搭建过程拆成可执行的步骤，你照着做就能跑起来。我用 Ollama 加本地嵌入模型做演示，因为零成本、可离线、适合入门。

第一步是环境准备。装好 Ollama 后拉两个模型：一个对话模型，一个嵌入模型。对话模型我选qwen2.5:7b，中文效果好且体积适中；嵌入模型选nomic-embed-text，维度 768，够用且快。命令很简单，ollama pull qwen2.5:7b和ollama pull nomic-embed-text，等下载完就行。

第二步是引入 LangChain4j 依赖。Maven 里加langchain4j、langchain4j-ollama、langchain4j-easy-rag三个包。easy-rag是 LangChain4j 提供的一站式 RAG 组件，适合快速验证，但生产环境我建议自己组装各环节，可控性更强。

第三步是文档入库。核心代码逻辑是：加载文档、切分、向量化、存入向量库。向量库我用的是内存版InMemoryEmbeddingStore，适合小规模知识库；数据量大就换 Milvus 或 PgVector。入库代码大概长这样：

EmbeddingModel embeddingModel = OllamaEmbeddingModel.builder() .baseUrl("http://localhost:11434") .modelName("nomic-embed-text") .build(); EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); DocumentSplitter splitter = new RecursiveCharacterTextSplitter(600, 80); List<Document> documents = FileSystemDocumentLoader.loadDocuments("/path/to/docs"); List<TextSegment> segments = splitter.splitAll(documents); List<Embedding> embeddings = embeddingModel.embedAll(segments).content(); store.addAll(embeddings, segments);

第四步是检索配置。我配了向量检索加关键词检索的混合模式，检索 Top 10，再用重排序取 Top 3。重排序模型可以用bge-reranker系列，Ollama 也支持。如果不想加重排序，至少把 TopK 设大一点，比如 8 到 10，让大模型自己从更多上下文里挑。

第五步是接入对话。把检索到的内容拼进提示词，让模型基于上下文回答。提示词模板很关键，我用的结构是：系统指令说明“只基于提供的上下文回答，上下文没有的信息不要编造”，然后是上下文内容，最后是用户问题。这个模板能显著降低幻觉。

实操心得：文档入库时一定要打印每个环节的中间结果。我习惯在切分后打印前三个 segment 的内容，向量化后打印向量维度，检索后打印命中的文本片段。这样出问题时一眼就能看出是哪一步不对。很多人跳过这步，结果检索效果差却不知道差在哪。

关于 RAG 命中率，我再补充一个技巧：给文档加元数据。每个 segment 除了文本内容，还存来源文件名、章节标题、页码等信息。检索时可以按元数据过滤，比如只在某个章节里搜，或者把来源信息一起送给模型帮助它判断可信度。LangChain4j 的TextSegment支持Metadata，用起来很方便。

6. Agent 编排的实操与工具定义

Agent 的落地我分三块讲：工具定义、执行器实现、多 Agent 协作。

工具定义用@Tool注解，方法描述要写清楚“这个工具做什么、什么时候用、参数是什么”。我举个例子：

public class KnowledgeTools { @Tool("根据关键词检索内部知识库，返回相关文档片段。当用户问题涉及公司内部资料时使用。") public String searchKnowledge( @P("检索关键词，多个关键词用空格分隔") String query) { List<TextSegment> results = retriever.retrieve(query); return results.stream() .map(TextSegment::text) .collect(Collectors.joining("\n---\n")); } }

描述里的“当用户问题涉及公司内部资料时使用”这句话很重要，它告诉模型触发条件。我试过不写触发条件，模型要么不用工具，要么滥用工具。加上之后准确率明显提升。

执行器我手写了一个，核心是一个 while 循环加状态机。每轮把当前对话历史发给模型，解析返回结果是文本还是工具调用请求。如果是工具调用，执行工具、把结果追加到历史、继续循环；如果是文本，返回给用户并结束。循环上限 10 轮，同时记录每轮的 token 消耗和耗时，方便后续优化。

public AgentResult execute(String userInput) { List<ChatMessage> history = new ArrayList<>(); history.add(SystemMessage.from(SYSTEM_PROMPT)); history.add(UserMessage.from(userInput)); for (int round = 0; round < MAX_ROUNDS; round++) { ChatResponse response = model.generate(history); AiMessage aiMessage = response.content(); history.add(aiMessage); if (!aiMessage.hasToolExecutionRequests()) { return AgentResult.success(aiMessage.text()); } for (ToolExecutionRequest request : aiMessage.toolExecutionRequests()) { String result = toolExecutor.execute(request); history.add(ToolExecutionResultMessage.from(request, result)); } } return AgentResult.maxRoundsExceeded(history); }

多 Agent 协作我用的是“协调器 + 消息总线”模式。协调器持有多个 Agent 的引用，根据任务类型决定调用哪个。Agent 之间不直接通信，都通过协调器转发消息。这样做的好处是解耦，每个 Agent 只关心自己的输入输出，不关心上下游是谁。缺点是协调器逻辑会变复杂，需要仔细设计任务路由规则。

注意：多 Agent 场景下，每个 Agent 的提示词要明确边界。我见过“研究 Agent”和“写作 Agent”职责重叠，结果两个都在检索资料，浪费资源还互相干扰。解决办法是在系统提示词里写清楚“你只负责 X，不要做 Y”，并且协调器在分配任务时明确告诉 Agent 当前阶段的目标。

工具执行的安全问题也要考虑。Agent 能调用的工具必须做权限控制，尤其是涉及写操作、外部 API 调用的工具。我的做法是给工具加一个@RequiresPermission注解，执行前检查当前会话的权限，没权限直接返回错误信息给模型。另外，所有工具调用都记审计日志，包括入参、出参、耗时、调用者，方便追溯。

7. 常见问题与排查技巧实录

这一节是我踩坑最多的地方，整理成速查表，你遇到问题时可以直接对照。

第一个高频问题是配置错误。报错信息里经常出现“缺少 base_url 配置”或“缺少 api_key”，这类问题最好在启动时就暴露。我在工厂类的register方法里做了必填校验，缺任何一项直接抛异常，应用启动失败。这样比运行时才发现要好得多。另外，配置项建议用环境变量注入密钥，别写死在文件里。

第二个高频问题是模型不可用。原因可能是模型名写错、服务没启动、或者账号额度用完。排查时先确认服务端点能通，再确认模型名和文档一致，最后看账号状态。我习惯在启动时发一个简单的测试请求，验证每个 Provider 都可用，不可用的打警告日志但不阻塞启动，运行时再降级。

第三个问题是RAG 命中率低。这个最考验耐心。我的排查顺序是：先看切分结果是否合理，再看检索返回的片段是否相关，最后看提示词是否把上下文用好了。很多时候问题出在切分，比如把一句话切成两半，或者把不相关的内容切到一起。调整chunkSize和chunkOverlap通常能解决大部分问题。如果还不行，就上重排序。

第四个问题是Agent 行为不符合预期。表现是乱调工具、不调工具、或者调了工具不用结果。乱调工具通常是工具描述太模糊，模型分不清该用哪个；不调工具是描述里没写触发条件；调了不用结果是提示词没强调“必须基于工具结果回答”。这三个问题我都遇到过，解决办法分别是：细化描述、加触发条件、强化系统提示词。

实操心得：排查 Agent 问题时，把完整的对话历史和工具调用记录打出来看。我一般会记录每一轮的输入消息、模型输出、工具调用请求、工具执行结果。这样一眼就能看出模型在哪一步“想歪了”。光看最终结果很难定位问题。

还有一个隐蔽的问题是并发下的状态污染。Agent 执行器如果设计成有状态的单例，多个请求同时进来会互相干扰。我的做法是每次执行创建一个新的执行上下文，所有状态都存在上下文对象里，执行器本身无状态。这个设计在压测时验证过，并发 50 个请求没有出现串数据的情况。

最后说一个性能相关的坑：向量检索的延迟。数据量小的时候内存检索很快，上万条之后延迟明显上升。解决办法是换专业向量库，或者加缓存。我给检索结果加了基于查询文本的缓存，相同查询直接返回缓存结果，命中率在重复问题多的场景下能到 30% 以上，延迟降得很明显。

8. 架构扩展与后续优化方向

这套架构跑通之后，我陆续做了一些扩展，这里分享几个觉得有价值的方向。

第一个是成本追踪。每个 Provider 的计费方式不同，我在调用层记录了每次请求的输入输出 token 数，按 Provider 的单价算出成本，汇总到监控面板。这样能清楚看到哪个功能烧钱最多，有针对性地优化。比如发现某个功能用贵模型但效果提升有限，就切到便宜模型。

第二个是效果评估。我建了一个小规模的评测集，包含问题和标准答案，定期跑一遍看各 Provider 和 RAG 配置的准确率。这个评测集不用很大，几十条就够，关键是持续跑，能发现模型更新或配置调整带来的效果波动。

第三个是提示词版本管理。提示词改动对效果影响很大，我把提示词存在数据库里，带版本号，每次改动记录变更内容和评测结果。这样能回溯“哪个版本效果最好”，也方便 A/B 测试。

第四个是降级链路细化。除了 Provider 降级，我还加了 RAG 降级（检索失败时直接用模型知识回答）和 Agent 降级（工具调用失败时退化为普通对话）。每一层降级都有明确的触发条件和日志，保证系统在部分组件故障时仍能提供基本服务。

这套东西搭下来，最大的体会是：架构的价值在于应对变化。模型会换、需求会变、数据会增长，好的架构让你在这些变化面前只需要改配置或加模块，而不是推倒重来。多 Provider 切换、RAG、Agent 编排这三块，本质上都是在为“变化”留出空间。我一开始也觉得抽象层麻烦，但经历过几次紧急切换 Provider 之后，就再也不想回到硬编码的时代了。