Java开发者的大模型应用开发指南：LangChain4j从入门到生产落地

1. 为什么 Java 开发者需要 LangChain4j

1.1 大模型应用开发不是 Python 的专利

过去一年多，大模型应用开发的教程、框架、示例代码几乎被 Python 生态垄断。LangChain、LlamaIndex、FastAPI 这一套组合拳打得风生水起，搞得很多 Java 后端开发者心里发慌——难道我们这些年积累的 Spring 生态、工程化能力、高并发经验，在大模型时代就一文不值了？

实际情况完全不是这样。企业级应用的主战场依然在 Java 这边。银行的核心交易系统、电商的订单中台、物流的调度引擎，这些跑着几十万行 Java 代码的系统，不可能因为要接一个大模型能力就整体重写。更现实的路径是：在现有 Java 服务里嵌入大模型调用能力，让老系统长出新的智能触手。LangChain4j 就是为这个场景而生的。

LangChain4j 是一个面向 Java 开发者的开源库，它的定位和 Python 版 LangChain 类似，但设计上更贴近 Java 生态的使用习惯。你可以把它理解成一套“大模型能力接入的标准件”：统一不同厂商模型的调用接口、封装提示词模板、管理对话记忆、编排工具调用、实现检索增强生成（RAG）。它不要求你切换语言栈，不要求你放弃 Spring Boot，你可以在熟悉的 Maven 工程里，用几行代码就把大模型接进来。

这篇文章面向的是有 Java 基础、但还没接触过大模型应用开发的读者。我会从零开始，把 LangChain4j 的核心概念、环境搭建、第一个可运行 Demo、常见坑点全部讲清楚。读完之后，你应该能独立完成一个带对话记忆和知识库检索的小型智能问答服务。

1.2 LangChain4j 到底解决了哪些实际问题

在没有 LangChain4j 之前，Java 开发者接大模型通常是这样干的：直接写 HTTP 请求调某家厂商的 REST API，自己拼 JSON、自己解析响应、自己处理超时重试。这种做法在只有一个模型、一个简单场景时还能忍，一旦需求变复杂，问题就集中爆发了。

第一个问题是模型切换成本高。不同厂商的接口协议、参数命名、返回结构都不一样，今天用 A 家的，明天想换 B 家的做对比测试，代码得大改。LangChain4j 通过统一的ChatLanguageModel接口把这层差异抹平了，切换模型往往只需要改一个配置项。

第二个问题是对话状态管理麻烦。大模型本身是无状态的，多轮对话需要你把历史消息按顺序拼进请求里。手动维护这个消息列表，还要考虑截断策略、token 预算，很容易写出一堆重复代码。LangChain4j 的ChatMemory组件把这件事标准化了。

第三个问题是 RAG 流程繁琐。要把企业文档变成模型能用的知识，涉及文档加载、切分、向量化、存储、检索、拼装提示词一整条链路。自己从零搭，光是选型和调试就能耗掉一两周。LangChain4j 提供了EmbeddingStore、DocumentSplitter、ContentRetriever等现成组件，把这条链路串起来了。

第四个问题是工具调用（Function Calling）的编排。让模型去调用你系统里的 Java 方法，涉及参数描述、结果回传、多轮决策，手写起来非常啰嗦。LangChain4j 的AiServices用注解加接口的方式，把这块也简化了。

提示：LangChain4j 不是银弹，它主要解决的是“集成层”的复杂度。模型本身的能力边界、提示词工程的质量、业务逻辑的正确性，这些还是得靠你自己把控。

2. 环境准备与第一个可运行 Demo

2.1 开发环境与依赖选型

动手之前先把环境理清楚。我实测下来比较稳的组合是 JDK 17 加 Maven 3.8 以上。LangChain4j 对 JDK 8 的支持在逐步弱化，新版本基本要求 11 起步，用 17 是当前最省心的选择，LTS 版本也方便长期维护。

依赖方面，LangChain4j 采用了模块化设计，核心包和各家模型的适配包是分开的。这样做的好处是按需引入，不会把一堆用不到的 SDK 拖进你的工程。以接入某主流云厂商的对话模型为例，你通常需要引入三个部分：核心库、对应模型的适配库、以及一个 HTTP 客户端实现。

<dependencies> <!-- LangChain4j 核心 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>0.35.0</version> </dependency> <!-- 某云厂商模型适配 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>0.35.0</version> </dependency> <!-- 日志，方便观察请求响应 --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.13</version> </dependency> </dependencies>

版本号这里要提醒一句：LangChain4j 迭代非常快，0.x 阶段小版本之间偶尔会有 API 变动。建议在项目里锁定一个确定版本，不要用动态版本号，否则某天重新构建突然编译不过会很抓狂。我一般会在父 pom 里用dependencyManagement统一管理版本。

2.2 最小可运行示例：三行代码调通模型

环境搭好后，先写一个最简单的例子，确认链路是通的。这个例子的目标是：给模型发一句话，把回复打印出来。

import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.chat.ChatLanguageModel; public class QuickStart { public static void main(String[] args) { ChatLanguageModel model = OpenAiChatModel.builder() .baseUrl("你的服务地址") .apiKey("你的密钥") .modelName("你的模型名称") .build(); String answer = model.generate("用一句话解释什么是向量数据库"); System.out.println(answer); } }

这段代码里有几个点值得展开说。baseUrl指向的是模型服务的接入点，很多云厂商都提供了兼容主流协议的服务端点，所以用langchain4j-open-ai这个适配包就能对接，不一定非得是原厂。apiKey是身份凭证，实际项目里绝对不能硬编码在代码里，后面我会讲怎么安全管理。

modelName决定了你调用的是哪个具体模型，不同模型的定价、上下文长度、能力侧重都不一样。generate方法是最简单的同步调用，传入字符串返回字符串。跑通这一步，说明你的网络、凭证、依赖都没问题，可以往下走了。

注意：密钥千万不要提交到代码仓库。我见过不止一个团队因为把密钥写死在代码里，被人扫到后产生高额账单。用环境变量或者配置中心是基本操作。

2.3 用 AiServices 声明式定义你的智能接口

直接调generate方法虽然简单，但真实业务里我们更希望像调用普通 Java 方法一样使用大模型。LangChain4j 的AiServices就是干这个的，它让你定义一个接口，用注解描述行为，框架自动生成实现。

import dev.langchain4j.service.AiServices; import dev.langchain4j.service.SystemMessage; import dev.langchain4j.service.UserMessage; interface Assistant { @SystemMessage("你是一个简洁的 Java 技术顾问，回答控制在三句话以内") String chat(@UserMessage String question); } public class AiServiceDemo { public static void main(String[] args) { ChatLanguageModel model = OpenAiChatModel.builder() .baseUrl("你的服务地址") .apiKey("你的密钥") .modelName("你的模型名称") .build(); Assistant assistant = AiServices.create(Assistant.class, model); System.out.println(assistant.chat("什么是依赖注入")); } }

这种写法的好处是把“提示词”和“业务代码”解耦了。@SystemMessage定义模型的角色设定，@UserMessage标记用户输入。你不需要手动拼字符串，也不需要关心底层怎么组装请求。接口方法名、参数名在框架内部也会作为上下文信息参与提示词构建，所以命名尽量语义化。

我个人的经验是，把系统提示词单独抽到一个常量类或者配置文件里维护，方便非开发人员（比如产品、运营）参与调优。提示词这东西，改一个字效果可能天差地别，让更多人能方便地迭代是值得的。

3. 对话记忆与多轮交互的实现细节

3.1 为什么模型需要“记忆”

大模型 API 本质上是无状态的。你第一次问“我叫什么”，它不知道；你告诉它“我叫张三”，再问“我叫什么”，如果第二次请求里没带上第一次的对话，它还是不知道。所谓“记忆”，其实是每次请求时把历史消息一起发过去，让模型在完整上下文里生成回复。

手动维护这个历史列表有几个坑。一是长度控制，模型的上下文窗口有限，历史太长会超限报错，或者被截断导致信息丢失。二是消息顺序，必须严格按照 user、assistant 交替的顺序排列，顺序错了模型会困惑。三是并发场景，多个用户同时对话，历史不能串。

LangChain4j 的ChatMemory把这些都封装好了。最常用的是MessageWindowChatMemory，它按消息条数保留最近 N 条，超出就丢弃最旧的。这个策略简单有效，适合大多数对话场景。

3.2 给 Assistant 加上记忆能力

改造前面的例子，让助手记住对话内容：

import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.service.AiServices; Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) .build(); assistant.chat("我叫张三，是一名后端工程师"); System.out.println(assistant.chat("我叫什么，做什么工作"));

withMaxMessages(10)表示保留最近 10 条消息。这个数字怎么定？我的经验是看你的业务场景。客服类对话通常 10 到 20 条够用，因为用户的问题大多独立。如果是需要长期跟踪的任务型对话，比如逐步完善一份需求文档，那可能需要更大的窗口，或者配合摘要机制。

这里有个容易忽略的点：MessageWindowChatMemory默认是基于内存的，进程重启就没了。生产环境如果要求对话持久化，需要自己实现ChatMemoryStore接口，把消息存到数据库或缓存里。LangChain4j 提供了接口，但具体存储介质要你自己接。

3.3 多用户隔离的正确姿势

单用户 Demo 跑通后，马上会遇到多用户的问题。如果所有用户共用一个ChatMemory实例，张三的对话历史会污染李四的上下文，这是严重的事故。

正确的做法是给每个会话分配独立的记忆实例，用会话 ID 做隔离。常见实现是维护一个Map<String, ChatMemory>，key 是会话 ID。但要注意并发安全和内存回收，长期不活跃的会话要及时清理，否则内存会持续增长。

import java.util.concurrent.ConcurrentHashMap; public class MemoryManager { private final ConcurrentHashMap<String, ChatMemory> memories = new ConcurrentHashMap<>(); public ChatMemory getOrCreate(String sessionId) { return memories.computeIfAbsent(sessionId, id -> MessageWindowChatMemory.withMaxMessages(15)); } public void clear(String sessionId) { memories.remove(sessionId); } }

用ConcurrentHashMap保证并发安全，computeIfAbsent保证同一会话只创建一次。清理策略可以配合定时任务，把超过一定时间没活动的会话移除。如果会话量很大，建议直接用 Redis 这类外部存储，避免单机内存成为瓶颈。

提示：会话 ID 的生成要保证全局唯一且不可预测，用 UUID 是比较稳妥的选择。不要用自增数字，容易被遍历。

4. 检索增强生成（RAG）实战拆解

4.1 RAG 要解决的核心问题

大模型有两个硬伤：一是知识有截止日期，训练之后发生的事情它不知道；二是它不了解你企业的私有数据，比如内部文档、产品手册、历史工单。RAG 的思路是：在提问时，先从你的知识库里检索出相关内容，把这些内容作为上下文一起发给模型，让它基于这些材料回答。

这样做的好处很明显。模型不需要重新训练，知识更新只需要更新知识库。回答有据可查，可以附上引用来源，降低胡编乱造的概率。对于企业内部知识问答、产品客服、文档助手这类场景，RAG 是目前最实用的方案。

LangChain4j 把 RAG 的链路拆成了几个清晰的组件：DocumentLoader负责加载文档，DocumentSplitter负责切分，EmbeddingModel负责把文本转成向量，EmbeddingStore负责存储和检索，ContentRetriever负责把检索结果喂给模型。理解这条链路，是做好 RAG 的关键。

4.2 文档加载与切分的关键参数

文档切分是 RAG 里最容易被低估的环节。切得太碎，语义不完整，检索出来的片段答非所问；切得太大，噪声多，浪费上下文窗口还稀释了关键信息。

LangChain4j 提供了DocumentSplitters.recursive方法，它按段落、句子、词的优先级递归切分，尽量保持语义完整。关键参数有两个：maxSegmentSizeInChars和maxOverlapSizeInChars。

import dev.langchain4j.data.document.splitter.DocumentSplitters; import dev.langchain4j.data.document.DocumentSplitter; DocumentSplitter splitter = DocumentSplitters.recursive( 500, // 每段最大字符数 50 // 相邻段重叠字符数 );

500 字符大约对应 200 到 300 个中文字，这个粒度对大多数技术文档比较合适。重叠 50 字符是为了防止关键信息正好被切在边界上，导致两边都不完整。重叠比例一般控制在 10% 左右。

我的实操心得是：不同类型的文档要用不同的切分策略。结构化的 FAQ 可以按问答对切，每个问答作为一个独立单元。技术手册按章节切，保留标题层级信息。代码文档按函数或类切。一刀切的效果往往不理想，值得花时间针对你的语料调优。

4.3 向量化与检索的完整链路

把文档切好之后，下一步是向量化。EmbeddingModel把每段文本转成一个高维向量，语义相近的文本在向量空间里距离更近。检索时，把用户问题也转成向量，找出距离最近的若干段文本。

import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.data.segment.TextSegment; EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); EmbeddingModel embeddingModel = /* 初始化你的向量模型 */; // 向量化并存储 for (TextSegment segment : segments) { Embedding embedding = embeddingModel.embed(segment).content(); store.add(embedding, segment); } // 检索 Embedding queryEmbedding = embeddingModel.embed("你的问题").content(); List<EmbeddingMatch<TextSegment>> matches = store.findRelevant(queryEmbedding, 5);

findRelevant的第二个参数是返回的匹配数量，通常取 3 到 5。取太少可能漏掉关键信息，取太多会引入噪声。这个值需要根据你的知识库规模和问题复杂度来调。

InMemoryEmbeddingStore适合开发和测试，数据量大了之后检索会变慢，而且重启就丢。生产环境建议换成专门的向量数据库，LangChain4j 支持多种主流向量库的适配，切换时只需要换EmbeddingStore的实现类，上层代码基本不用动。

4.4 把检索结果接入对话流程

最后一步是把检索到的内容和用户问题一起组装成提示词，发给模型。LangChain4j 的RetrievalAugmentor可以自动完成这个拼装过程。

import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; import dev.langchain4j.rag.content.retriever.ContentRetriever; ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.7) .build(); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();

minScore是相似度阈值，低于这个分数的检索结果会被丢弃。这个参数很重要，它能过滤掉那些“看起来相关其实没用”的片段。设得太低，噪声进来干扰模型；设得太高，可能什么都检索不到。0.7 是个常见的起点，具体值要结合你的向量模型和语料实测调整。

注意：RAG 的效果高度依赖检索质量。如果模型回答不准，先别急着换模型，回头看看检索出来的片段是不是真的相关。十有八九问题出在切分或检索环节。

5. 工具调用与常见问题排查

5.1 让模型调用你的 Java 方法

工具调用（也叫 Function Calling）是让大模型从“聊天”走向“干活”的关键能力。比如用户问“帮我查一下订单 12345 的状态”，模型本身不知道订单数据，但它可以决定调用你提供的查询方法，拿到结果后再组织语言回复。

LangChain4j 用注解来声明工具。你只需要在方法上标注@Tool，框架会自动把方法名、参数、描述信息告诉模型。

import dev.langchain4j.agent.tool.Tool; import dev.langchain4j.agent.tool.P; public class OrderTools { @Tool("根据订单号查询订单状态") public String queryOrderStatus(@P("订单号") String orderId) { // 实际业务里这里查数据库 return "订单 " + orderId + " 已发货，预计明天送达"; } }

然后在构建 Assistant 时把工具类注册进去：

Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new OrderTools()) .build();

模型收到问题后，会判断是否需要调用工具。如果需要，它会返回一个调用请求，框架执行对应方法，把结果回传给模型，模型再生成最终回复。整个过程对调用方是透明的，你只管调assistant.chat(...)。

这里有个关键点：方法的描述和参数描述要写清楚。模型是根据这些文字描述来决定调不调、怎么调的。描述含糊，模型就可能该调不调，或者传错参数。把@Tool和@P里的文字当成给模型看的 API 文档来写，越明确越好。

5.2 常见问题速查表

实际开发中踩的坑，我整理成了一张表，方便对照排查。

5.3 超时与重试的工程化处理

大模型调用是典型的远程调用，网络抖动、服务端限流都是常态。生产环境必须配置合理的超时和重试策略。

超时时间怎么定？我的经验是分两段看。连接超时设短一点，5 秒左右，因为连不上就是连不上，等太久没意义。读取超时设长一点，30 到 60 秒，因为模型生成回复本身就需要时间，尤其是长文本。如果业务对响应时间敏感，可以考虑流式输出，边生成边返回，用户感知的等待时间会短很多。

重试要谨慎。不是所有失败都值得重试。网络超时、5xx 错误可以重试，但 4xx 错误（比如密钥错误、参数错误）重试多少次都没用，反而浪费配额。重试次数建议 2 到 3 次，并且要用指数退避，避免瞬间打爆服务端。

OpenAiChatModel model = OpenAiChatModel.builder() .baseUrl("你的服务地址") .apiKey("你的密钥") .modelName("你的模型名称") .timeout(Duration.ofSeconds(60)) .maxRetries(2) .logRequests(true) .logResponses(true) .build();

logRequests和logResponses在调试阶段非常有用，能看到实际发出的请求和收到的响应。但生产环境要关掉，一是日志量大，二是可能泄露敏感信息。

5.4 成本控制与提示词优化

大模型调用是按 token 计费的，用起来不心疼，月底账单会心疼。控制成本有几个实用手段。

第一，精简提示词。系统提示词里那些客套话、重复说明，能删就删。每减少 100 个 token，乘以调用量就是一笔钱。

第二，合理设置记忆窗口。不是所有对话都需要记住全部历史，很多场景保留最近几轮就够了。

第三，RAG 检索数量别贪多。检索 5 段和检索 10 段，成本差一倍，但效果未必提升。找到那个性价比拐点。

第四，缓存高频问题的答案。很多用户问的问题是重复的，把常见问题和答案缓存起来，命中缓存就不调模型，能省下大量费用。

第五，选对模型。简单任务用便宜的小模型，复杂任务才上大模型。LangChain4j 支持配置多个模型实例，根据场景路由。

我在实际项目里的体会是，成本优化不是一次性的工作，而是要持续观察调用日志，找出那些又贵又没必要的调用，逐个优化。上线第一个月，通常能通过优化把成本砍掉一半以上。

5.5 流式输出提升用户体验

同步调用要等模型把整段话生成完才返回，用户盯着空白屏幕等好几秒，体验很差。流式输出让模型边生成边推送，用户看到文字一个个蹦出来，感知上快很多。

LangChain4j 支持流式接口，返回一个TokenStream，你可以逐 token 处理。

import dev.langchain4j.model.StreamingResponseHandler; import dev.langchain4j.model.output.Response; model.generate("讲个笑话", new StreamingResponseHandler<>() { @Override public void onNext(String token) { System.out.print(token); } @Override public void onComplete(Response response) { System.out.println("\n--- 完成 ---"); } @Override public void onError(Throwable error) { error.printStackTrace(); } });

在 Web 服务里，通常配合 SSE（Server-Sent Events）把 token 推给前端。要注意的是，流式模式下错误处理更复杂，因为响应已经开始返回了才出错，没法简单地重试整个请求。我的做法是在流开始前做好参数校验，流过程中出错就推送一个错误标记，让前端提示用户重试。

6. 从 Demo 到生产的落地建议

6.1 配置管理与密钥安全

Demo 里把密钥写在代码里图方便，生产环境这么干就是事故隐患。正确的做法是把密钥放在环境变量或配置中心，代码里只读不写。

String apiKey = System.getenv("MODEL_API_KEY"); if (apiKey == null || apiKey.isBlank()) { throw new IllegalStateException("未配置模型密钥"); }

如果团队有配置中心，把密钥托管在那里更好，支持动态更新和权限管控。另外，密钥要定期轮换，不要一个密钥用到底。不同环境（开发、测试、生产）用不同的密钥，方便隔离和追踪。

6.2 可观测性建设

大模型应用上线后，你必须能回答这些问题：调用量多少？成功率多少？平均延迟多少？token 消耗多少？哪些问题回答得不好？没有这些数据，优化就是盲人摸象。

建议在调用层埋点，记录每次请求的模型名称、输入 token 数、输出 token 数、耗时、是否成功。这些指标汇总起来，能帮你发现很多问题。比如某个时段延迟飙升，可能是服务端限流；某类问题成功率低，可能是提示词需要优化。

LangChain4j 提供了监听器接口，可以在请求前后插入自定义逻辑。用它来采集指标是比较优雅的方式，不用侵入业务代码。

6.3 降级与兜底策略

大模型服务不是百分之百可用的，网络故障、服务端维护、配额耗尽都可能发生。生产系统必须有降级方案。

最简单的降级是返回预设的兜底话术，比如“当前咨询人数较多，请稍后再试”。好一点的方案是准备一个备用模型，主模型不可用时自动切换。再进一步，对于高频问题，直接用本地缓存的答案兜底，完全不依赖模型服务。

降级策略要提前设计好，并且定期演练。真出故障的时候才想起来没做降级，就来不及了。

6.4 提示词的版本管理

提示词是影响效果的关键因素，但很多团队把它散落在代码各处，改了就改了，没有记录，出了问题也不知道是哪个版本导致的。

我的建议是把提示词当成代码来管理。统一放在一个地方，每次修改都记录版本和修改原因。有条件的话，建立一套评测机制，每次改提示词都跑一遍测试集，看看效果是变好还是变差。这样迭代才有依据，而不是凭感觉。

LangChain4j 本身不强制你怎么管理提示词，但它的@SystemMessage支持从外部读取，你可以把提示词放在配置文件或数据库里，配合版本号管理。

6.5 安全与内容过滤

接入大模型后，输入输出的安全过滤不能少。用户可能输入恶意内容试图诱导模型，模型也可能生成不当内容。这两头都要防。

输入端，对用户输入做基本的校验和清洗，过滤明显的攻击模式。输出端，对模型生成的内容做审核，发现不当内容及时拦截。LangChain4j 的监听器机制可以在请求和响应环节插入过滤逻辑。

另外要注意数据隐私。发给模型的内容可能包含用户敏感信息，要评估是否合规。涉及个人隐私、商业机密的数据，要么脱敏后再发，要么用私有化部署的模型。

我在实际落地中最大的体会是：技术接入只是第一步，真正决定项目成败的是工程化程度。提示词管理、成本控制、可观测性、降级兜底，这些“脏活累活”做扎实了，系统才能稳定跑起来。LangChain4j 帮你省掉了集成层的重复劳动，但工程化的功夫还得自己下。