1. 为什么 Java 开发者现在该认真看看 LangChain4j

这两年大模型应用开发的热度基本被 Python 生态吃掉了，LangChain、LlamaIndex 这些框架一个比一个火，搞得很多写 Java 的同学心里发慌：难道做 AI 应用就得转语言？我一开始也这么想，直到实际在几个后端项目里试了 LangChain4j，才发现事情没那么绝对。LangChain4j 这个库的定位很明确，就是把大模型调用、提示词编排、对话记忆、工具调用、检索增强这些能力，用 Java 开发者熟悉的方式封装起来，让你在现有的 Spring Boot 项目里就能把 AI 功能接进去，不用另起一套 Python 服务再搞跨语言通信。

它解决的核心问题其实就一个：让 Java 后端工程师用自己熟悉的类型系统、依赖管理和工程结构，去构建基于大模型的应用。你不需要懂 Python 的异步生态，不需要折腾虚拟环境，Maven 里加几个依赖，写几个接口，就能跑起来一个能对话、能查资料、能调用你现有业务方法的智能体。适合谁看？我觉得有三类人最该上手：一是手里有成熟 Java 后端系统、想加 AI 能力但不想重构技术栈的工程师；二是做企业级应用、对稳定性和可维护性要求高的团队；三是想理解大模型应用底层编排逻辑、不想只停留在调 API 层面的开发者。

这篇文章我不打算写成官方文档的翻译，而是按我自己踩坑的顺序，从环境搭建、核心概念、实操代码到问题排查，把 LangChain4j 入门这条路上真正会卡住人的地方讲清楚。你跟着走一遍，基本能独立搭出一个带记忆、带工具调用、带知识库检索的小型 AI 服务。下面进入正题。

2. 动手之前先把这几个核心概念捋顺

2.1 LangChain4j 到底封装了什么

很多人第一次看 LangChain4j 的文档会懵，类名一大堆，不知道从哪下手。我的建议是先建立一张心智地图：这个库本质上在帮你做四件事——和大模型通信、管理对话状态、编排多步骤流程、连接外部数据和工具。围绕这四件事，它提供了对应的抽象接口。

最核心的接口是ChatLanguageModel，你可以把它理解成"一个能对话的模型对象"。它屏蔽了不同厂商 API 的差异，OpenAI、通义千问、本地部署的模型，只要对应的集成包引入了，用法基本一致。再往上是AiServices，这是我觉得 LangChain4j 最舒服的设计，它允许你用声明式接口的方式定义 AI 服务，就像写 MyBatis 的 Mapper 一样，定义一个接口，加几个注解，框架帮你生成实现。这个设计对 Java 开发者极其友好，后面实操会重点讲。

再往上是记忆（Memory）和检索（Retrieval）。记忆解决的是"模型记不住上一轮说了什么"的问题，检索解决的是"模型不知道你私有数据"的问题。这两个是实际项目里绕不开的，光会调 API 只能做玩具，加上这两个才能做产品。

2.2 模型、提示词、记忆三者的关系

我用一个生活化的类比帮你理清：把大模型想象成一个知识渊博但记性极差的顾问。你每次找他咨询，他都不记得你上次来过。提示词（Prompt）就是你这次递给他的问题纸条，记忆（Memory）就是你随身带的一个笔记本，每次咨询前把之前的对话记录一起递给他，他看完才知道上下文。而 LangChain4j 就是你的助理，帮你管理这个笔记本、帮你把纸条递过去、帮你把顾问的回答整理好。

理解这个类比，你就能明白为什么记忆模块那么重要，也能明白为什么提示词工程本质上是在"设计递给顾问的那张纸条"。很多新手一上来就纠结模型选哪个，其实在入门阶段，提示词和记忆的设计对最终效果的影响，往往比换个模型大得多。我见过太多人花时间对比模型跑分，结果提示词写得含糊不清，效果自然差。

2.3 版本选择和依赖管理的关键决策

LangChain4j 迭代很快，不同版本 API 有差异，这是新手最容易踩的坑。我的建议是：入门阶段锁定一个稳定版本，不要追最新。截至我写这篇内容时，1.x 系列已经比较成熟，社区文档也跟得上。你在pom.xml里明确写死版本号，别用范围依赖，否则某天构建突然失败你会很懵。

依赖拆分也是它的一大特点，它把不同厂商的集成做成了独立模块。核心包是langchain4j，OpenAI 集成是langchain4j-openai，其他厂商各有各的包。这样做的好处是按需引入，不会把一堆用不到的 SDK 塞进你的项目。坏处是新手容易漏引依赖，报错时找不到类。我的经验是：先把核心包和你要用的模型集成包引上，跑通最小对话，再逐步加记忆、检索这些模块，一次全引上反而容易乱。

3. 环境搭建与最小可运行示例

3.1 Maven 依赖配置实操

先给一份我实测能跑通的最小依赖配置。这里以 OpenAI 兼容接口为例，因为很多国内厂商也提供兼容接口，换 baseUrl 就能用，灵活性高。

<properties> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <langchain4j.version>1.0.0</langchain4j.version> </properties> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>${langchain4j.version}</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>${langchain4j.version}</version> </dependency> </dependencies>

JDK 版本我建议至少 17，LangChain4j 用到了不少新特性，用 8 会各种别扭。如果你项目还锁在 8，要么升级，要么做好心理准备处理兼容问题。这一点没有捷径，我试过在 JDK 8 上硬跑，最后放弃升级了。

3.2 第一个对话程序：从零到跑通

依赖配好后，写一个最简单的对话程序。注意 API Key 千万别硬编码在代码里，用环境变量或者配置中心，这是基本的安全习惯。

import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.chat.ChatLanguageModel; public class FirstChat { public static void main(String[] args) { ChatLanguageModel model = OpenAiChatModel.builder() .apiKey(System.getenv("API_KEY")) .baseUrl("https://api.example.com/v1") .modelName("your-model-name") .temperature(0.7) .build(); String answer = model.chat("用一句话解释什么是依赖注入"); System.out.println(answer); } }

这段代码里几个参数值得说清楚。baseUrl指向服务地址，如果你用兼容接口，换成对应地址即可。modelName填你实际要用的模型标识。temperature控制输出的随机性，0 到 1 之间，值越低越确定、越保守，值越高越发散、越有创意。做事实性问答建议 0.2 到 0.3，做创意文案可以到 0.8 以上。这个参数我调过很多次，新手最容易忽略它，结果抱怨模型"胡说八道"，其实往往是温度设太高了。

3.3 用 AiServices 声明式定义你的 AI 服务

上面那种直接调model.chat()的方式适合测试，但真实项目里更推荐用AiServices。它的写法像这样：

interface Assistant { String chat(String userMessage); } Assistant assistant = AiServices.create(Assistant.class, model); String reply = assistant.chat("帮我写一个 Java 单例模式的例子");

看起来简单，但威力在于你可以往接口里加注解、加记忆、加工具。比如加个系统提示词：

interface Assistant { @SystemMessage("你是一个严谨的 Java 技术顾问，回答要简洁，代码要能直接运行") String chat(String userMessage); }

@SystemMessage定义的是模型的"人设"和全局约束，它比你在每条用户消息里重复写要求要优雅得多。我个人的经验是，把角色设定、输出格式要求、禁止事项都放在系统消息里，用户消息只放具体任务，这样提示词结构清晰，也方便统一维护。

4. 对话记忆与多轮上下文实战

4.1 为什么裸模型记不住上下文

大模型的 API 本质上是无状态的，你每次调用都是一次独立的请求，模型不会自动记住上一轮。这不是 LangChain4j 的问题，是所有大模型 API 的共性。所以"记忆"这件事必须由应用层来做，也就是每次请求时把历史对话一起带上。

LangChain4j 提供了ChatMemory抽象，最常用的是MessageWindowChatMemory，它维护一个固定大小的消息窗口，超出就丢弃最老的。为什么要有窗口？因为模型的上下文长度有限，而且历史越长 token 消耗越大、成本越高、响应越慢。窗口大小就是在这几者之间做权衡。

4.2 给 AI 服务加上记忆的完整代码

ChatMemory memory = MessageWindowChatMemory.withMaxMessages(20); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .build(); assistant.chat("我叫小明，正在学 Java"); assistant.chat("我叫什么名字？"); // 能正确回答"小明"

withMaxMessages(20)表示保留最近 20 条消息。这个数字怎么定？我的经验是：普通客服类场景 10 到 20 条够用，长文档分析类场景可能需要更大，但要配合 token 预算来算。一条中文消息大概 1 到 2 个 token 每字，20 条消息如果每条平均 50 字，大概 1000 到 2000 token，加上系统提示词和模型输出，单次请求 token 量可控。如果你设成 200 条，成本会飙升，而且模型对超长上下文的注意力也会下降。

4.3 记忆持久化：别让对话一重启就丢

MessageWindowChatMemory默认存在内存里，服务一重启就没了。生产环境肯定不行，用户会骂人。LangChain4j 允许你自定义ChatMemoryStore，把消息存到数据库或 Redis。

public class RedisChatMemoryStore implements ChatMemoryStore { @Override public List<ChatMessage> getMessages(Object memoryId) { // 从 Redis 读取并反序列化 } @Override public void updateMessages(Object memoryId, List<ChatMessage> messages) { // 序列化写入 Redis } @Override public void deleteMessages(Object memoryId) { // 删除 } }

这里有个坑我要提醒：消息对象的序列化要处理好，不同版本的消息类结构可能变。我建议用 JSON 存，并且给存储结构加个版本字段，将来升级时能做兼容。另外memoryId通常用用户 ID 或会话 ID，一定要保证隔离，别让 A 用户的对话串到 B 用户那里，这是严重的安全问题。

5. 工具调用与检索增强的落地

5.1 让模型调用你的 Java 方法

工具调用（Tool Calling）是让 AI 从"聊天"变成"干活"的关键。原理是：你把一些 Java 方法暴露给模型，模型在需要时返回一个"我要调用某方法、参数是什么"的指令，LangChain4j 帮你执行方法并把结果回传给模型，模型再基于结果生成最终回答。

class WeatherTools { @Tool("查询指定城市的天气") String getWeather(@P("城市名称") String city) { // 实际调用你的天气服务 return city + "今天晴，25度"; } } Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build();

@Tool的说明文字很关键，模型靠它判断什么时候该调用这个工具。说明要写得像给同事解释这个方法是干嘛的，别写得太技术化。我见过有人写"invoke weather api"，模型根本不知道啥时候用，改成"查询指定城市的实时天气情况"就正常了。

5.2 检索增强：让模型读懂你的私有文档

检索增强（RAG）解决的是模型不知道你内部资料的问题。流程是：把文档切块、向量化、存进向量库；用户提问时，先把问题向量化，检索出最相关的几块，拼进提示词一起发给模型。

EmbeddingModel embeddingModel = ...; EmbeddingStore<TextSegment> store = ...; // 入库 Document doc = Document.from("你的文档内容"); List<TextSegment> segments = new DocumentSplitter(500, 50).split(doc); store.addAll(embeddingModel.embedAll(segments).content(), segments); // 检索 ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) .build(); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();

切块大小 500、重叠 50 是我常用的起点。切太大，检索精度下降；切太小，语义不完整。重叠是为了避免关键信息正好被切在边界上。这个参数没有万能值，要拿你的真实文档测，我一般会准备十几个典型问题，调参数时看召回的相关块是否真的相关。

6. 常见问题排查与避坑经验

6.1 高频报错速查表

6.2 几个我踩过的坑

第一个坑是流式输出和记忆混用时的顺序问题。流式返回时，如果你在流结束前就把消息写进记忆，可能写入不完整。正确做法是等流式响应完全结束后再更新记忆。

第二个坑是提示词里塞了太多无关内容。新手容易把一堆背景资料全塞进系统提示词，结果模型注意力被稀释，回答质量反而下降。我的做法是系统提示词只放角色和规则，具体资料通过检索动态注入。

第三个坑是忽视 token 成本。上线前一定要估算：单次请求平均 token 数乘以日调用量，再乘以单价。我见过一个项目没算这笔账，上线一周账单吓人。控制手段包括压缩历史、精简提示词、对简单问题用小模型。

6.3 性能与成本优化的实操建议

模型分级是个好策略：简单意图识别、分类任务用便宜的小模型，复杂推理用大模型。LangChain4j 支持配置多个模型实例，按场景切换。另外，对高频且答案固定的问题做缓存，能省下大量调用。缓存 key 可以用问题文本的哈希，注意设置合理的过期时间，避免答案过时。

还有一点，异步调用能显著提升吞吐。LangChain4j 提供了异步的模型接口，配合 Java 的 CompletableFuture 使用，在 IO 等待期间不阻塞线程。但要注意线程池配置，别把连接池打满。

7. 从入门到能用的进阶路线

跑通上面这些，你已经能做出一个像样的 AI 服务了。接下来往哪走？我的建议是先别急着上多智能体、复杂工作流这些花哨的东西，而是把可观测性做好。记录每次请求的输入、输出、token 消耗、耗时，这些数据是你后续优化的依据。没有数据，调优就是瞎猜。

然后是评测体系。准备一批标准问题和期望答案，每次改提示词或换模型都跑一遍，看效果是变好还是变差。这个习惯能帮你避免"感觉好像变好了"这种主观判断带来的反复横跳。

最后是错误处理和降级。模型服务会抖动，会限流，会超时。你的代码要有重试、有超时、有降级方案，比如模型不可用时返回兜底话术。这些工程细节，才是把 demo 变成产品的分水岭。

我个人在实际项目里的体会是，LangChain4j 最大的价值不是它封装了多少功能，而是它让 Java 团队能用自己熟悉的工程方式去构建 AI 应用，不用为了 AI 而割裂技术栈。入门门槛确实不高，但要做好，功夫还是在提示词设计、数据质量和工程细节上，这些是任何框架都替不了的。