Java后端必学：LangChain4j从入门到RAG实战指南

1. 为什么 Java 后端值得花时间学 LangChain4j

先说一个我自己的真实感受。过去一年多大模型应用开发几乎被 Python 生态垄断，LangChain、LlamaIndex 这些框架的教程铺天盖地，Java 后端想接个大模型，要么自己裸写 HTTP 请求拼 JSON，要么在项目里塞一个 Python 微服务做中转，维护起来别扭得很。直到 LangChain4j 出现，这个局面才算真正被打破——它把大模型调用、提示词模板、对话记忆、RAG 检索增强、工具调用这些能力，用一套非常"Java 味"的 API 封装了起来，配合 Spring Boot 的自动装配，写起来几乎和平时写 Service 层没什么区别。

这篇文章面向的是有 Java 基础、写过 Spring Boot、但还没系统接触过大模型应用开发的后端同学。我会从 LangChain4j 的核心概念讲起，一路带到 AiService、Spring Boot 集成、RAG 落地，以及我在实际项目里踩过的坑。看完你应该能独立把一个"能对话、能查知识库、能调工具"的 AI 功能塞进现有的 Java 项目里，而不是停留在"跑通一个 Hello World"的阶段。

需要提前说明的是，LangChain4j 版本迭代很快，API 在不同大版本之间有过调整，我下面写的代码基于较新的稳定版本，如果你用的是老版本，个别类名和方法签名可能对不上，遇到编译报错先去看官方文档的对应版本说明，这是常态，别慌。

2. LangChain4j 到底解决了什么问题

2.1 从"裸调 API"到"框架封装"的演进逻辑

很多人第一次接大模型，写出来的代码大概是这样：用HttpClient或者RestTemplate拼一个请求体，把 API Key 塞进 Header，POST 到某个模型服务商的接口，然后解析返回的 JSON，从choices[0].message.content里把文本抠出来。跑通没问题，但一旦需求变复杂，问题就来了。

比如你想让模型记住上一轮对话，就得自己维护一个消息列表，每次请求把历史消息一起发过去；想换一家模型服务商，请求体和返回结构全变了，代码要大改；想加个"知识库问答"，得自己实现文本切分、向量化、相似度检索、把检索结果拼进提示词这一整套流程。这些活儿单拎出来都不难，但堆在一起就是一座小山，而且每个项目都要重写一遍。

LangChain4j 的价值就在于把这些重复劳动抽象成了标准组件。它定义了一套统一的ChatLanguageModel接口，OpenAI、通义千问、DeepSeek、Ollama 本地模型等等都实现这个接口，你换模型只需要换一行配置。它提供了ChatMemory管理对话历史，提供了EmbeddingStore和EmbeddingModel做向量检索，提供了AiService把"接口 + 注解"直接变成可调用的 AI 能力。这就是框架存在的意义——让你专注业务逻辑，而不是重复造轮子。

2.2 核心概念速览：模型、记忆、嵌入、AiService

在动手之前，先把几个核心概念理清楚，不然后面看代码会晕。

ChatLanguageModel是最基础的模型抽象，代表一个能对话的大模型。你给它一组消息，它返回一条回复。所有上层能力最终都建立在它之上。

ChatMemory负责对话记忆。大模型本身是无状态的，它不记得你上一句说了什么，所谓"记忆"其实是每次请求时把历史消息一起带上。ChatMemory 帮你管理这个历史列表，还能配置保留多少轮、超出后怎么淘汰。

EmbeddingModel 和 EmbeddingStore是 RAG 的两块基石。EmbeddingModel 把文本转成向量（一串浮点数），EmbeddingStore 负责存这些向量并支持相似度检索。RAG 的本质就是"先把知识库文本向量化存起来，用户提问时检索出最相关的片段，塞进提示词让模型基于这些片段回答"。

AiService是 LangChain4j 最讨喜的设计。你只需要定义一个 Java 接口，加上几个注解，框架就会在运行时用动态代理生成实现类。调用这个接口的方法，底层自动完成提示词组装、模型调用、结果解析。对 Java 后端来说，这种"声明式"的体验非常亲切，跟 Spring Data JPA 用接口定义 Repository 是一个思路。

2.3 和 Python LangChain 的定位差异

经常有人问，Java 已经有 Python 版 LangChain 了，为什么还要用 LangChain4j。我的看法是两者定位不同。Python 生态在实验、算法、数据处理上更灵活，适合快速验证想法。但企业级后端系统大量跑在 Java 上，你不可能为了加一个 AI 功能就把整个技术栈换掉。LangChain4j 的强项是"融入现有 Java 工程体系"——它能和 Spring Boot 无缝集成，能复用你现有的依赖注入、配置管理、日志、监控，能打包进你现有的 Jar 里部署。对于已经在维护 Java 系统的团队，这个价值是决定性的。

3. 环境搭建与第一个可运行示例

3.1 Maven 依赖与版本选择

先建一个标准的 Spring Boot 项目，我习惯用 Spring Initializr 生成骨架，Java 版本选 17 或 21，这两个都是长期支持版本，LangChain4j 对它们支持最好。然后在pom.xml里加依赖。

LangChain4j 的依赖是模块化的，核心包和各家模型的适配包分开。以接入 OpenAI 兼容接口为例（很多国产模型也兼容这套协议），核心依赖大概是这样：

<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>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> <version>0.35.0</version> </dependency>

这里有个坑要提醒：LangChain4j 的各个模块版本号必须保持一致，如果你只升级了核心包没升级适配包，很容易出现NoSuchMethodError这种运行时错误。我一般会在properties里定义一个langchain4j.version变量统一管理。

关于版本选择，我的建议是不要盲目追最新。LangChain4j 迭代快，新版本偶尔会有破坏性变更。生产项目里选一个发布了一段时间、社区反馈稳定的版本，比追新更重要。0.35.x 这个系列我用下来比较稳，API 也相对成熟。

3.2 配置模型连接参数

依赖加好后，在application.yml里配置模型连接信息。这里我用环境变量的方式注入 API Key，绝对不要把密钥硬编码进代码提交到仓库，这是安全底线。

langchain4j: open-ai: chat-model: base-url: ${AI_BASE_URL} api-key: ${AI_API_KEY} model-name: ${AI_MODEL_NAME} temperature: 0.7 timeout: PT60S embedding-model: base-url: ${AI_BASE_URL} api-key: ${AI_API_KEY} model-name: ${AI_EMBEDDING_MODEL}

temperature这个参数值得说一下，它控制输出的随机性，范围一般 0 到 2。做知识库问答、代码生成这类需要稳定准确的场景，我一般调到 0.2 到 0.3；做创意文案、头脑风暴可以调到 0.8 以上。timeout用 ISO-8601 的 Duration 格式，大模型响应慢，别设太短，60 秒是个比较稳妥的值。

3.3 用 AiService 写第一个对话接口

配置就绪后，写第一个 AiService。定义一个接口：

public interface Assistant { String chat(String userMessage); }

然后在配置类里把它装配成 Bean：

@Configuration public class AiConfig { @Bean public Assistant assistant(ChatLanguageModel chatModel) { return AiServices.create(Assistant.class, chatModel); } }

就这么几行，一个能对话的 AI 接口就有了。在 Controller 里注入Assistant，调用chat方法，底层自动把字符串包装成 UserMessage 发给模型，再把回复文本返回。这种体验对 Java 后端来说非常顺滑，你完全不用关心 HTTP 请求怎么拼、JSON 怎么解析。

如果你想让它带记忆，加一个ChatMemory就行：

@Bean public Assistant assistant(ChatLanguageModel chatModel, ChatMemory chatMemory) { return AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .chatMemory(chatMemory) .build(); } @Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.withMaxMessages(20); }

MessageWindowChatMemory是一个滑动窗口实现，保留最近 20 条消息，超出的自动淘汰。为什么用窗口而不是无限保留？因为模型的上下文长度有限，而且历史越长 token 消耗越大、响应越慢、成本越高。20 条对大多数客服、助手场景够用了。

4. 深入 AiService：注解驱动的 AI 能力

4.1 @SystemMessage 与角色设定

AiService 真正的威力在注解。@SystemMessage用来设定系统提示词，也就是给模型定角色、定规则。这个注解可以加在接口上，也可以加在方法上。

public interface CustomerService { @SystemMessage("你是一名专业的电商客服，回答要简洁礼貌，遇到退款问题引导用户提供订单号。") String answer(String question); }

系统提示词写得好不好，直接决定输出质量。我的经验是：明确角色、明确边界、明确输出格式。比如"你是客服"太笼统，"你是电商客服，只回答订单、物流、退换货相关问题，其他问题礼貌拒绝"就具体得多。如果要求返回 JSON，一定要在系统提示词里把字段结构写清楚，最好给个示例。

4.2 @UserMessage 与变量占位

@UserMessage用来定义用户消息模板，支持{{变量}}占位符，方法参数通过@V注解绑定。

@UserMessage("请把下面这段文本翻译成{{language}}：{{text}}") String translate(@V("text") String text, @V("language") String language);

这种模板化的写法比字符串拼接优雅得多，而且提示词集中管理，改起来方便。我习惯把常用的提示词模板都放在接口里，而不是散落在业务代码中，这样调整提示词不用动业务逻辑。

4.3 结构化输出：让模型返回对象

大模型返回的是文本，但业务代码往往需要对象。LangChain4j 支持直接把返回结果映射成 Java 对象或枚举。

public interface SentimentAnalyzer { @UserMessage("判断下面这句话的情感倾向：{{text}}") Sentiment analyze(@V("text") String text); } public enum Sentiment { POSITIVE, NEGATIVE, NEUTRAL }

框架会自动在提示词里加上"请从这几个枚举值中选择"的指令，并把返回文本解析成枚举。返回 POJO 也类似，框架会生成 JSON 格式要求并反序列化。这个能力在分类、抽取、打标签场景里特别省事。

不过要注意，结构化输出依赖模型的理解能力，小模型或者提示词写得含糊时，可能返回不符合格式的内容导致解析失败。我的做法是在系统提示词里把格式要求写死，并且对解析异常做兜底处理，不要让一次解析失败把整个请求搞崩。

4.4 工具调用：让 AI 触发你的 Java 方法

工具调用（Function Calling）是我觉得最实用的能力之一。你可以把某个 Java 方法标记成工具，模型在需要时会"决定"调用它，框架负责执行并把结果回传给模型。

public class WeatherTools { @Tool("查询指定城市的当前天气") public String getWeather(@P("城市名称") String city) { return weatherService.query(city); } } @Bean public Assistant assistant(ChatLanguageModel model) { return AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build(); }

用户问"北京今天天气怎么样"，模型识别出需要调用getWeather，框架执行后把结果喂回模型，模型再组织成自然语言回答。整个过程对业务代码透明。工具方法的描述（@Tool里的文字）非常关键，模型靠它判断什么时候该调用哪个工具，描述要准确、具体，别写"查询数据"这种模糊的话。

5. Spring Boot 集成与工程化实践

5.1 用 Starter 简化装配

前面手动写@Bean的方式适合理解原理，实际项目里更推荐用官方 Starter。引入langchain4j-spring-boot-starter后，很多组件可以自动装配，你只需要在配置文件里声明。

langchain4j: open-ai: chat-model: api-key: ${AI_API_KEY} model-name: gpt-4o-mini log-requests: true log-responses: true

log-requests和log-responses在调试阶段非常有用，能把实际发给模型的提示词和返回内容打到日志里。我强烈建议开发环境打开，生产环境关掉——因为提示词里可能包含用户隐私数据，落到日志里有合规风险。

5.2 多模型与多 AiService 的隔离

真实项目里往往不止一个 AI 场景，客服助手、代码助手、文档问答可能需要不同的模型、不同的提示词、不同的记忆策略。这时候就要做隔离，别把所有东西塞进一个 Assistant。

我的做法是按业务域拆分 AiService 接口，每个接口配独立的模型和记忆。如果多个模型实例需要共存，可以用@Qualifier区分，或者干脆用配置类手动构建，控制粒度更细。这里有个容易踩的坑：如果你定义了多个ChatLanguageModelBean 而没有指定主 Bean，自动装配会报"找到多个候选"的错误，记得用@Primary或者@Qualifier明确指定。

5.3 对话记忆的持久化方案

MessageWindowChatMemory默认存在内存里，应用重启就没了，而且多实例部署时各存各的，用户请求打到不同实例会"失忆"。生产环境必须做持久化。

LangChain4j 提供了ChatMemoryStore接口，你可以实现它把消息存到 Redis、数据库或者任何存储里。核心就是实现getMessages、updateMessages、deleteMessages三个方法，用会话 ID 作为 key。

public class RedisChatMemoryStore implements ChatMemoryStore { private final RedisTemplate<String, Object> redisTemplate; @Override public List<ChatMessage> getMessages(Object memoryId) { Object cached = redisTemplate.opsForValue().get(key(memoryId)); return cached == null ? new ArrayList<>() : (List<ChatMessage>) cached; } @Override public void updateMessages(Object memoryId, List<ChatMessage> messages) { redisTemplate.opsForValue().set(key(memoryId), messages, Duration.ofHours(2)); } @Override public void deleteMessages(Object memoryId) { redisTemplate.delete(key(memoryId)); } }

注意ChatMessage的序列化问题，用 JSON 序列化时最好配置好类型信息，否则反序列化回来可能变成LinkedHashMap而不是具体的消息类型。这个坑我踩过，排查了半天。

6. RAG 落地：让 AI 基于你的知识库回答

6.1 RAG 的核心流程拆解

RAG（检索增强生成）解决的是"模型不知道你私有数据"的问题。大模型的训练数据有截止时间，也不包含你公司的内部文档，直接问它只会瞎编。RAG 的思路是：把知识库文档切块、向量化、存进向量库；用户提问时，把问题也向量化，检索出最相似的几个文本块，拼进提示词，让模型基于这些内容回答。

整个流程分两个阶段。索引阶段（离线）：加载文档、切分、向量化、存储。检索阶段（在线）：问题向量化、相似度检索、组装提示词、调用模型。理解这两阶段，后面写代码就清晰了。

6.2 文档加载与切分策略

LangChain4j 提供了DocumentLoader加载各种格式的文档，DocumentSplitter负责切分。切分策略是 RAG 效果的关键，切得太大检索不精准，切得太小上下文不完整。

DocumentSplitter splitter = DocumentSplitters.recursive(500, 50); List<Document> documents = FileSystemDocumentLoader.loadDocuments("/docs", splitter);

recursive(500, 50)表示每块目标 500 个 token，块之间重叠 50 个 token。重叠是为了避免一句话被硬生生切断导致语义丢失。500 这个值不是固定的，中文场景我一般用 300 到 500，英文可以大一些。如果你的文档结构清晰（比如有明确章节），按标题切分效果更好。

6.3 向量存储选型与检索

向量存储的选择要看数据量。小规模（几千条以内）用内存版InMemoryEmbeddingStore就够，重启重建索引即可。数据量大或者要持久化，可以选 Redis、Elasticsearch、Milvus、PgVector 等，LangChain4j 都有对应适配。

EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(store) .build(); ingestor.ingest(documents);

检索时用EmbeddingStoreContentRetriever，可以配置返回条数maxResults和最低相似度minScore。minScore这个参数很关键，设太低会召回不相关内容干扰模型，设太高可能什么都召不回。我一般从 0.6 开始调，根据实际效果微调。

6.4 把检索器接入 AiService

最后把检索器接到 AiService 上，一个 RAG 问答就成型了：

@Bean public Assistant assistant(ChatLanguageModel model, ContentRetriever retriever) { return AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build(); }

框架会自动在每次提问前执行检索，把相关片段作为上下文注入提示词。你调用assistant.chat("...")时，模型已经"看到"了检索到的知识。这就是 LangChain4j 的 Easy RAG，几行代码搞定一套检索增强。

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

7.1 高频问题速查表

7.2 提示词调试的独家心得

提示词调试是 AI 应用开发里最耗时的环节。我的经验是：先把log-requests打开，看实际发出去的提示词长什么样，很多时候问题就出在提示词和你以为的不一样。然后做小步迭代，一次只改一个变量，改完立刻验证，别一次改一堆然后不知道是哪个起了作用。另外，把效果好的提示词版本化管理起来，用 Git 记录每次改动和对应效果，方便回滚。

7.3 成本与性能的平衡

大模型调用是要花钱的，token 就是钱。几个省钱技巧：简单任务用小模型，复杂任务才上大模型；控制历史消息长度，别把几十轮对话全带上；RAG 检索条数别贪多，3 到 5 条通常够用；对高频且答案固定的问题做缓存。性能方面，模型响应本身就有延迟，如果业务对响应时间敏感，可以考虑流式输出（Streaming），让用户先看到部分内容，体验会好很多。

7.4 安全与合规的注意事项

最后强调几点安全事项。API Key 必须用环境变量或密钥管理服务，绝不进代码仓库。用户输入要做基本的校验和过滤，防止提示词注入。涉及用户隐私的数据，日志里要脱敏。如果业务涉及特定行业，还要确认模型服务商的数据处理条款是否符合你的合规要求。这些不是技术问题，但一旦出事就是大问题，别等出事才重视。

8. 我个人的一些实践体会

写到这里，LangChain4j 从入门到 RAG 的主线基本走完了。最后分享几个我自己的体会。第一，别一上来就追求复杂架构，先用 AiService 把最简单的对话跑通，再逐步加记忆、加工具、加 RAG，每一步都验证清楚，这样出问题好定位。第二，提示词工程是核心技能，框架只是工具，同样的框架不同人写出来的效果天差地别，多花时间打磨提示词。第三，RAG 不是银弹，它对文档质量、切分策略、检索参数都很敏感，效果不好时先别怀疑模型，回头看看你的知识库和切分是不是有问题。第四，保持对版本变更的关注，LangChain4j 还在快速演进，定期看看 release notes，能帮你避开不少坑。Java 后端做大模型应用，现在正是好时候，工具链越来越成熟，值得投入时间。