最近不少做Java后端的朋友跟我聊到同一个问题：Python生态里大模型开发已经玩出花了，Java这边到底怎么下手？翻开各种AI教程，示例几乎全是Python，对Java工程师来说确实劝退。其实Java生态早就有对应的成熟方案，LangChain4j就是其中比较靠谱的一个。它把大模型对话、工具调用、知识库检索这些能力封装成Java程序员熟悉的接口风格，核心思路是把LLM应用开发变成“配置加接口”的组合，你平时写Spring Boot的那套习惯基本可以平移过来。这篇文章我会从一个Java开发者的视角，把LangChain4j的核心概念、环境搭建、RAG落地和排坑经验完整串一遍，新手照着走就能跑通。
1. 项目定位：为什么Java团队需要LangChain4j
1.1 自己调用大模型API，痛点在哪里
很多团队一开始是让后端同学直接用HttpClient去调模型的HTTP接口的。诚实地讲，跑通一个最简单的对话没问题，但只要是稍微真实一点的需求，就会开始反复写类似的代码：自己拼JSON请求体、处理鉴权头、解析返回结构、维护多轮会话的历史消息数组。更麻烦的是工具调用，也就是让大模型调用Java方法去获取实时数据，这时候需要自己写一个循环：模型返回tool_calls，你执行对应方法，再把结果作为一条新消息回传给模型，模型基于结果生成最终回复。这个循环本身逻辑不复杂，但每次新项目都要重新实现一遍，很容易写出边界条件没处理好的Bug，比如工具返回超时、参数类型对不上、历史消息越来越多导致请求体膨胀。
更现实的问题是，这种手写方案没有一个统一抽象。你今天接的是OpenAI，明天想换国内的厂商或者其他开源模型，接口风格完全不一样，改动量不小。如果你的项目只是做一两个接口，手写也没问题；如果是打算正经做一个带知识库、带工具调用、带多轮记忆的智能体应用，那这套重复劳动的成本就很可观了。
1.2 LangChain4j给Java生态补齐了什么
LangChain4j的定位可以理解成“Java版的LLM应用脚手架”，它把大模型应用里那些高频重复的环节都抽象成了稳定组件。最核心的几个能力：一个是统一的模型入口，无论底层接哪家大模型，上层都通过一个ChatLanguageModel接口去对话；一个是AiServices，它允许你定义一个普通的Java接口，框架自动生成实现，把接口方法变成与大模型交互的入口；还有一个是工具调用，你只要在方法上打一个@Tool注解，大模型就能在对话过程中自动决定是否调用这个方法；另外RAG（检索增强生成）相关的组件也都是现成的，从文档切分、向量化到语义检索，都有对应的API。
这套设计对Java开发者非常友好，因为整个开发模式和你熟悉的依赖注入、接口驱动、类型安全这些习惯是对齐的。写智能体应用不再是“面向字符串编程”，而是面向Java类型和接口编程。类型安全这个优势在项目变大之后尤其明显：参数传错了编译期就能发现，而不是等到线上跑起来才报错。
1.3 和手写方案、Python LangChain的取舍
如果你之前接触过Python那边的LangChain，LangChain4j虽然名字相似，但不是简单翻译，而是基于Java语言特点重新设计的。Python版胜在组件丰富、社区资料多，但动态类型在项目规模变大以后维护成本会高一点，而且要把Python服务嵌入到现有Java后端本身就有环境成本和部署成本。手写HTTP方案则没有框架依赖，对简单的单接口场景其实是够用的，但复杂链路下代码量会呈指数级增长。
我的建议是：如果你只是调一次模型玩一玩，手写没问题；如果你要做的是智能体、文档问答、自动化工具编排这类正经功能，直接引入LangChain4j更划算。尤其是现有系统本身就是Spring Boot技术栈的时候，集成成本极低，后面我会专门讲整合方式。
2. 环境准备与第一个可运行Demo
2.1 Maven依赖怎么加
先建一个普通的Maven项目，JDK建议17以上。LangChain4j的核心包和模型适配包是分离的，所以至少要加两个依赖：核心包langchain4j，以及你想用的模型供应商适配包。我在写这篇文章时用到的是1.1.0版本，如果你的中央仓库能拉到更新的稳定版，直接替换版本号就行，接口变化不大。
<properties> <langchain4j.version>1.1.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> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-ollama</artifactId> <version>${langchain4j.version}</version> </dependency> </dependencies>需要注意的一个点是：langchain4j-open-ai这个包不仅适配OpenAI官方接口，也适配很多提供“OpenAI兼容接口”的服务商，你可以通过自定义baseUrl指向任意兼容服务，这一点非常灵活。
2.2 两种模型接入方式：外部API与本地Ollama
如果你已经在用大模型API，直接在代码里构建模型对象即可，通过环境变量读取密钥，不要硬编码到源码里。以OpenAI为例：
ChatLanguageModel model = OpenAiChatModel.builder() .apiKey(System.getenv("OPENAI_API_KEY")) .modelName("gpt-4o-mini") .temperature(0.7) .build();如果不想依赖外部服务，更推荐用Ollama在本地跑开源模型。先在本机安装Ollama，然后拉一个中文效果还不错的模型，比如通义千问的Qwen系列：
ollama pull qwen2.5:7b代码侧只需要把适配器换成Ollama的实现：
ChatLanguageModel model = OllamaChatModel.builder() .baseUrl("http://localhost:11434") .modelName("qwen2.5:7b") .temperature(0.7) .build();我个人建议新手直接从Ollama开始，原因是完全不需要考虑网络和密钥问题，在本地就能把整条链路跑通。等理解了核心概念之后，再切换到真实API或生产级配置，会顺畅得多。Ollama对机器配置要求不算高，7B量化模型在16G内存的Mac上可以流畅运行，Windows和Linux环境也支持。
2.3 最小可运行代码：五步走通对话
万事开头难，所以我把最小Demo砍到极致。新建一个Main类，代码如下：
import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.ollama.OllamaChatModel; public class Main { public static void main(String[] args) { ChatLanguageModel model = OllamaChatModel.builder() .baseUrl("http://localhost:11434") .modelName("qwen2.5:7b") .temperature(0.7) .build(); String answer = model.generate("用一句话介绍你自己"); System.out.println(answer); } }直接运行main方法，控制台就会输出模型的回答。这里有几个细节值得说一下：model.generate(String)是最简单的方法，适合快速验证链路；temperature控制的是生成随机性，值越大回答越发散，一般在0.2到0.8之间比较合理，做知识问答建议调低一点，比如0.2，减少自由发挥。这个Demo跑通之后，你已经有了一件重要的事：确认你的Java工程能够正常连通大模型。
如果是通过OpenAI接口，只需要把构建模型那段换成OpenAiChatModel，其余代码完全不变。这也是LangChain4j设计的核心优势之一：上层调用不感知模型供应商差异。
3. 核心概念拆解：从ChatModel到AiServices
3.1 ChatLanguageModel：统一的大模型入口
上面的Demo里我们已经用过ChatLanguageModel了，这个接口是整个框架的地基。它的定位就是“一个Java方法对应一次大模型调用”，内部帮你处理了HTTP通信、认证、重试、序列化这些琐事。除了最基础的generate(String)，更常用的是基于消息对象的对话方法：
Response<AiMessage> response = model.chat(UserMessage.from("帮我写一段Java冒泡排序代码")); System.out.println(response.content().text());这里涉及几个消息类型：UserMessage代表用户输入，AiMessage代表模型输出，SystemMessage设置系统的角色或行为约束，还有ToolExecutionResultMessage用来承载工具执行结果。这种消息设计，本质上就是对齐大模型API里的消息数组，只是用强类型方式暴露给你，写起来更不容易出错。
理解这个抽象之后，你会发现整条链路其实很简单：无论是简单的问答、多轮对话，还是后来要做的工具调用、RAG检索，最终都是组合这些消息类型而已。框架做的事就是帮你把这些消息编排好。
3.2 AiServices：让接口声明变成智能体服务
如果只有ChatLanguageModel，LangChain4j其实只是把HTTP调用封装了一下，真正的杀伤力在AiServices。它的核心机制是：你定义一个普通的Java接口，声明一个方法，AiServices会在运行时通过动态代理生成实现类。这个实现类的逻辑就是：把你的参数变成一条用户消息发给大模型，拿到模型回复后返回给你。
举个例子，定义一个问候助手接口：
interface Assistant { String chat(String userMessage); } Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .build(); String answer = assistant.chat("你好，给我介绍一下你自己");这看起来很简单，但妙处在于，接口方法签名其实是完全可控的。你可以定义带多个参数的方法，返回值也可以定义成自定义类型，框架会自动完成消息转换和结果解析。接口和实现分离的设计，也让单元测试变得方便，需要mock的时候直接mock接口就行。
AiServices真正让人眼前一亮的功能是和工具调用结合。假设你想让大模型能获取实时时间，传统做法是你自己去查时间再拼到Prompt里，但用了工具调用之后，你只需要写一个普通类：
public class DateTimeTool { @Tool("获取当前日期，返回格式为 yyyy-MM-dd") public String today() { return LocalDate.now().toString(); } @Tool("计算两个整数相加的结果") public int add(int a, int b) { return a + b; } }然后在构建Assistant时把工具对象传进去：
Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new DateTimeTool()) .build(); String answer = assistant.chat("今天是几号？顺便算一下 23 加 19 是多少？");这里的执行流程很有意思：你的问题会先发给模型，模型判断“今天几号”这个信息它自己不知道，需要一个工具来获取，于是返回一个工具调用请求；AiServices收到请求后，通过反射调用DateTimeTool.today()方法，把结果包装成消息再回传给模型；模型看到工具返回的日期之后，生成最终的自然语言回复。整个过程对调用方完全透明，你只是调了一个接口方法而已。
这种“模型自主决策调用Java方法”的能力，就是智能体应用的基础。业务上完全可以把查询订单、查库存、查用户余额这些已有服务方法都暴露成工具，让大模型根据用户意图去组合调用，相当于给你的大模型应用接上了公司现有系统的数据能力。
3.3 记忆管理：让对话有上下文
用上面的Assistant直接进行多轮对话，你很快会发现一个尴尬的问题：第二轮提问时，模型好像“忘了”第一轮聊过什么。原因很简单，每次assistant.chat()默认只发送当前这一条消息，没有把历史消息带过去。要让对话有记忆，需要显式配置ChatMemory。
LangChain4j提供了两种内存实现：MessageWindowMemory和ChatMemory。前者按照消息条数裁剪历史，比如只保留最近20条，实现简单，适合大多数场景；后者按照token预算裁剪历史，适合上下文窗口比较紧张的大模型。使用方法是在构建Assistant时传入内存对象：
ChatMemory memory = MessageWindowMemory.withMaxMessages(20); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .tools(new DateTimeTool()) .build();配置之后，每一轮对话的历史消息会自动维护。有几个细节值得注意：一是按条数裁剪时，如果消息很长，可能会把上下文撑爆，所以更稳妥的是按照token估算裁剪；二是如果要做多用户多会话隔离，不能所有用户共用一个ChatMemory，应该在每次会话创建时单独构建一个内存实例。这一点在将来接入Web应用时尤其关键，否则用户A的问题会出现在用户B的对话里。
4. 实战：构建一个文档问答助手（RAG落地）
4.1 场景设定与文档切分
大模型应用里最实用的一个方向是文档问答，也叫RAG（Retrieval Augmented Generation，检索增强生成）。假设你有一份产品说明书或内部FAQ文档，希望用户提问时，AI能根据文档内容回答，而不是自由发挥。直观的做法是把整份文档塞进Prompt再让模型回答，但文档一大就会超出上下文窗口，而且并不是所有内容都和问题相关，塞进去反而会影响回答质量。
RAG的思路是：先把文档切成小段，再对每一段做向量化，存进向量数据库。用户提问时，先把问题向量化，在库里做相似度检索，找出最相关的几个片段，然后把“问题+相关片段”一起发给模型，让模型基于检索到的资料来回答。说白了就是给大模型开卷考试，只让它看和题目有关的几页讲义。
LangChain4j里第一步是加载文档。最简单的方式是直接从一个String构建Document：
Document document = Document.from("这里放你的完整文档内容，比如产品FAQ、操作手册等...");但文档一般都比较长，直接整段向量化效果不好，因为向量是整段的语义压缩，内容一长，检索精度就会下降。所以需要拆分，框架提供了DocumentSplitters工具类，常用的拆分策略是按递归字符分割：
DocumentSplitter splitter = DocumentSplitters.recursive(300, 50); List<TextSegment> segments = splitter.split(document);300指的是每段目标字符数，50是相邻段落之间的重叠字符数。为什么要有重叠？因为段与段之间的边界可能正好切断一个完整语义单元，重叠一点可以让信息不丢失。这两个参数需要根据文档实际情况调整，技术文档可以适当调大，对话记录这种碎片化内容可以调小。
4.2 向量化与向量存储
文档切好之后，需要把每一段转成向量。LangChain4j提供了EmbeddingModel抽象，你可以用OpenAI的向量模型，也可以继续用Ollama本地的向量模型。本地方案如下：
EmbeddingModel embeddingModel = OllamaEmbeddingModel.builder() .baseUrl("http://localhost:11434") .modelName("nomic-embed-text") .build();如果模型镜像没拉过，先执行ollama pull nomic-embed-text。向量模型的选择对中文场景影响比较大，本地方案里nomic-embed-text属于通用型，效果中规中矩，够用于学习；生产环境建议用中文效果更好的专用向量模型。
向量化之后需要存储。入门阶段最简单的方式是使用内存版InMemoryEmbeddingStore，数据存在进程内存里，重启就没了，不适合生产，但非常适合验证逻辑：
EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); List<Embedding> embeddings = embeddingModel.embedAll(segments).content(); store.addAll(embeddings, segments);如果你的文档量比较大，比如几万段，内存版就不够用了，LangChain4j支持多种向量数据库适配，像PGVector、Chroma、Milvus都有对应的集成包。从内存版切换到外部向量库时，API变化很小，主要是在构建store的方式上不同。
4.3 检索增强问答：把资料注入上下文
存储完成之后，核心是构建一个检索器，让用户在提问时自动完成“语义检索->拼接上下文->模型回答”这条链路。LangChain4j提供了EmbeddingStoreRetriever：
EmbeddingStoreRetriever retriever = EmbeddingStoreRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) .minScore(0.65) .build();maxResults控制最多取几个片段，取值太小可能漏掉关键信息，太大又会引入噪声并占用上下文窗口，一般是3到5个。minScore是最低相似度阈值，低于这个值的片段会被过滤掉，阻止模型拿不相关内容硬答，阈值调太高容易检索不到结果，建议从0.6到0.7起步。
接着通过ContentRetriever把它注入AiServices：
ContentRetriever contentRetriever = ContentRetriever.from(retriever); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .contentRetriever(contentRetriever) .build(); String answer = assistant.chat("根据提供的资料，发票丢失后应该怎么处理？");整个过程里，框架会自动完成：把你的问题向量化，去向量库找出最相关的几段文本，把“相关资料”和你的问题一起组装进发送给模型的Prompt。你写的代码和普通对话接口几乎一样，区别只是构建Assistant时多配置了一个contentRetriever。
这里有一个很重要的思维转变：RAG的“检索”不是用SQL的精确匹配，而是语义匹配。问题里哪怕没有出现文档里的原词，只要语义相近就能被召回。这就是为什么向量检索在这个链路里不可替代。当然，这套链路也不是零成本，文档切分参数、向量模型效果、相似度阈值都会直接影响回答质量，需要根据实际效果调参。
5. 常见问题与排坑手册
5.1 依赖版本与构建问题
新手最容易踩的坑是Maven依赖下载失败或者版本不兼容。先确认你的Maven镜像源能正常访问中央仓库，再确认你写的是已发布的版本号。LangChain4j版本迭代比较快，有些试用版在中央仓库存在时间很短，用旧教程里的版本号经常拉不下来，解决办法是去中央仓库搜一下最新的稳定版。另外，注意JDK版本，LangChain4j 1.x要求JDK 17以上，如果用JDK 8会遇到编译错误。
还有一个常见问题是，部分依赖传递冲突，尤其项目本身在用老版本Spring或某些HTTP客户端库时。一般建议是使用Maven依赖树检查一下，优先保留LangChain4j带来的版本，因为它对兼容性要求更严格。
5.2 工具调用不生效、响应异常
很多人在配置@Tool之后发现模型不调用工具，或者报参数解析错误。我排查下来最常见的原因有三个：一是工具方法的描述不够清晰，模型不知道这个方法应该在什么时候用，描述里要把使用条件、参数含义、返回值说明写清楚；二是参数类型过于复杂，比如传自定义对象或Map，模型返回的JSON解析不到Java对象上，建议参数尽量用基本类型和字符串；三是工具类上有一些框架扫描不到的方法，构建AiServices的时候忘了把工具对象传进.tools()。
另外一个容易被忽略的问题是，工具方法内部如果有网络调用或数据库查询，一定要设置合理的超时时间，否则模型可能一直等待工具返回。我自己习惯是在工具方法内部加上try-catch，返回一段明确错误信息，而不是直接抛异常，这样模型还能根据错误信息调整回答方式。
5.3 上下文超限与并发安全
多轮对话时间长了，报出上下文超长错误是很正常的。如果你用的ChatMemory按消息条数裁剪，但每条消息本身很长，也可能触发上下文窗口上限。排查思路是看请求日志里实际发送的tokens数量，然后调整ChatMemory的裁剪策略，比如从MessageWindowMemory换到按token预算裁剪的ChatMemory，或者把历史消息截断得更激进一些。
并发安全方面，ChatLanguageModel的实现类一般是无状态的，可以作为一个单例被多个线程共用。但ChatMemory是有状态的，同一个会话内的多轮消息都维护在里面，多个用户共用同一个内存实例就会互相串话。实际项目里应该在每个会话创建时new一个ChatMemory，或者按userId维度做隔离。
6. 和Java工程团队整合的几点建议
6.1 接入Spring Boot的配置方式
LangChain4j为Spring Boot提供了官方starter，集成体验很顺。引入依赖时，除了核心包，还要加对应的starter适配包：
<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> <version>${langchain4j.version}</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-ollama-spring-boot-starter</artifactId> <version>${langchain4j.version}</version> </dependency>然后在application.properties里配置模型参数：
langchain4j.ollama.chat-model.base-url=http://localhost:11434 langchain4j.ollama.chat-model.model-name=qwen2.5:7b langchain4j.ollama.chat-model.temperature=0.2配置完成后，ChatLanguageModel会被Spring容器自动创建，直接注入Service即可。更推荐的做法是把你定义的Assistant接口注册成Spring Bean，业务代码里注入这个接口，完全屏蔽底层细节。这也符合你熟悉的依赖注入习惯。
6.2 与数据访问层结合：让智能体查库
Java后端团队最关心的一个问题是：怎么让大模型访问现有数据库数据。方案是把你已有的Mapper方法封装成@Tool。比如用户问“帮我查一下手机号138开头的用户余额”，大模型可以自动决定调用一个查询方法：
@Component public class UserQueryTool { private final UserMapper userMapper; public UserQueryTool(UserMapper userMapper) { this.userMapper = userMapper; } @Tool("根据手机号查询用户余额，入参为手机号字符串，返回余额数值") public String queryUserBalance(String phone) { User user = userMapper.selectByPhone(phone); return user == null ? "用户不存在" : String.valueOf(user.getBalance()); } }这样你的智能体应用就不只是“聊天机器人”，而是能够结合企业真实业务数据做查询和决策的服务。需要注意给工具方法写清楚返回格式，模型对“返回余额数值”这样的描述理解得会比较好。另外，涉及敏感数据的操作，建议在工具方法内部做权限校验，不能只依赖模型层面的判断。
6.3 再往下可以做的方向
把基础链路跑通之后，可以探索的方向还有几个：流式输出，用StreamingChatLanguageModel配合SSE把回答流式推给前端，体验会比一次性返回好很多；结构化输出，让你的Assistant接口方法返回一个自定义Java对象，由框架来自动解析模型输出；多工具协同，把查询、计算、通知类工具组合起来，构造成能独立完成任务的智能体。这些方向都有对应的官方示例，上手路径比从零开始顺畅得多。
我个人在实际操作中的体会是，LangChain4j最值得花时间研究的不是API本身，而是“让模型自主决定调用什么工具”这套思维。把现有系统的能力暴露成工具，让大模型成为调度者，业务价值能立刻体现出来。最后再分享一个小技巧：刚开始接入时，工具返回的内容一定要用纯文本和明确的数字格式，不要返回大段JSON或HTML，模型对这些复杂格式的理解和提取不如结构化文本稳定。先跑通最小闭环，再逐步增加复杂度，是最稳妥的路线。
