搞Java的兄弟们这两年是不是有点尴尬身边搞Python的同事天天拿LangChain写智能体、搞RAG咱Javaer只能眼巴巴看着想抄作业都没法抄。直到我遇到LangChain4j这个专为Java生态设计的LLM应用框架才算是彻底解了馋。这篇文章我用一个真实的入门项目带大家走一遍从环境搭建到对话、流式输出、Tool Calling、RAG全套摸下来保证你照着敲就能跑通咱Java人也能把大模型玩得明明白白。1. 项目定位与核心价值为什么Java生态偏偏需要它1.1 从痛点说起Java开发者做LLM应用的尴尬我先说个扎心的事实。现在市面上的LLM开发框架九成以上都是Python的天下。Python那边有完整的生态工具链一拉一大把文档多到看不完。而Java这边呢不是没有SDK但大多数都是各家大模型厂商自己做的那套客户端调个接口还行真要做Agent、做记忆管理、做RAG检索增强生成你就得从零开始拼轮子。我最早做的一个智能客服项目就吃过这个亏。当时要在现有的Spring Boot系统里接一个大模型接口本身调用倒是不难难的是几个硬骨头多轮对话的记忆管理得自己维护会话历史数组每次请求手动拼进去想让模型调用我们内部系统的库存查询接口得自己写函数调用的JSON Schema解析要把企业内部的文档库喂给模型做问答没有现成的切分、向量化、检索链路这些活本身不复杂但杂、碎、容易出错尤其一旦系统里跑着几百万流量的核心业务你绝对不敢用手写拼接的方式上生产。当时我就在想如果有个框架能把LLM开发里的这些“脏活累活”都抽象掉只暴露干净的接口给工程师那就太好了。1.2 LangChain4j到底解决了什么问题LangChain4j这个项目诞生的初衷就是给Java开发者提供一套和Python生态对标的能力。它把LLM应用开发中会遇到的高频场景统统做成了模块化组件你不需要关心底层的HTTP调用、JSON协议、消息历史的维护逻辑只要面向统一的抽象接口写业务就行。它的几个核心设计理念我实际用下来觉得非常对路模块化核心是langchain4j基础包然后按功能拆成langchain4j-open-ai、langchain4j-ollama、langchain4j-embeddings等一堆扩展包你用到哪个就引哪个不会把一堆用不着的依赖塞进你的Spring Boot工程。接口统一不管底层接的是哪家大模型你写的代码几乎是一样的。今天想从A厂切到B厂只换一个依赖和几行配置就行业务代码不用动。这一点对国内团队太重要了因为模型厂商的动向谁说得准。Java生态友好它天生和Spring Boot、Quarkus这些Java框架配合得很好。你可以用Bean管理模型对象可以在Service层里优雅地调用Agent能力做的工程化方案能直接嵌进现有的企业级系统而不是为了一个新项目单独开一套Python微服务。毫不夸张地说LangChain4j就是当前Java生态里做LLM应用最接近“正规军”的方案没有之一。对于业务系统以Java为主、又迫切想接入AI能力的团队来说它几乎是性价比最高的选择。1.3 你将从这个项目里得到什么这个入门项目不是简单的“调通一个接口”就完事我把它设计成了一条完整的“学习——实战——避坑”链路你跟着走一遍基本就能摸清LangChain4j的套路环境准备和Maven依赖怎么配用十几行代码跑通第一个对话Demo搞懂ChatLanguageModel、Message这一组核心抽象到底是干嘛的实现“打字机”一样的流式输出这个是聊天机器人必备体验用AiServices优雅地让模型按Java对象格式返回结构化数据亲手实现Tool Calling函数调用让模型可以真正操作你的Java方法跑通一个极简RAG流程让模型基于你自己的文档回答问题每一项我都会给出可直接复制的代码、关键参数的取舍说明以及我实际踩过的一些坑。有些坑网上文档里根本不会写但你早晚会遇上。2. 环境准备与第一个对话Demo先把水烧开2.1 兜底配置JDK和Maven正式开始之前先把地基打好。LangChain4j要求JDK 8以上但我建议你直接用JDK 17。倒不是因为JDK 8跑不起来而是后面你要用到一些语言特性以及Spring Boot 3.x的生态JDK 17会让你省很多事。Maven就用3.8以上版本这应该不是什么大问题。为了方便演示我新建了一个Maven工程目录结构就是标准的src/main/java。整个项目用到的依赖就三个核心加一个可选properties langchain4j.version1.0.0-beta1/langchain4j.version /properties dependencies !-- LangChain4j 核心 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- 接入兼容OpenAI协议的API厂商 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency !-- 本地模型可选方案 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version${langchain4j.version}/version /dependency !-- 日志建议带上 -- dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.5.6/version /dependency /properties这里有个版本选择的问题得提醒你。LangChain4j的版本迭代非常快API变化也比较激进。如果你用的版本和我这里不同个别方法名可能对不上。遇到这种情况不要慌去对应版本文档里查一下换个叫法就行。2.2 模型接入的两种路径接下来最关键的一步让LangChain4j能连上大模型。我建议新手走两条路都试一遍因为它们的侧重点完全不同。路径一接在线大模型API这是最快出效果的方式。现在国内能买到的大模型API基本都提供OpenAI兼容协议。LangChain4j里专门有个langchain4j-open-ai模块实际上就是走OpenAI的协议格式所以只要是兼容OpenAI格式的API都能用这个模块接。代码长这样ChatLanguageModel model OpenAiChatModel.builder() .baseUrl(https://你的API服务商地址/v1) .apiKey(你的API Key) .modelName(你选定的模型名称) .temperature(0.7) .logRequests(true) .logResponses(true) .build();这里baseUrl是API服务商给你的访问地址modelName是你购买的模型标识temperature控制生成随机性数值越大回答越发散做客服类场景建议调低到0.2左右免得模型太“话痨”。logRequests和logResponses建议开发期保持true能直接在日志里看到完整的请求和响应体定位问题很方便生产环境记得关掉。路径二接本地模型Ollama本地模型的好处是免费、数据不出内网、离线可用适合对数据隐私敏感的团队。我用的Ollama工具它是目前搭建本地模型服务最简单的方式之一下载安装后命令行执行ollama run qwen2.5:7b这样一条命令就能拉模型并起服务。Java这边连接Ollama就更简单了不需要API KeyChatLanguageModel model OllamaChatModel.builder() .baseUrl(http://localhost:11434) .modelName(qwen2.5:7b) .temperature(0.7) .build();注意modelName必须和你Ollama里已经拉取的名字一致。我第一次用的时候不小心MultiModelName写成qwen2.5没带:7b结果启动直接报模型不存在排查了半天。这个细节记一下能省你五分钟。2.3 十几行代码跑通第一个对话搞定模型对象之后跟大模型聊天就非常简单了核心就一行代码。public class ChatDemo { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .baseUrl(https://你的API服务商地址/v1) .apiKey(你的API Key) .modelName(你选定的模型名称) .build(); String answer model.generate(用一句话解释什么是大语言模型); System.out.println(answer); } }就这么朴素。model.generate(你的问题)传一个字符串进去模型就把回答当字符串返回给你。我让人印象深的是这个简单的Demo背后LangChain4j已经把HTTP连接、超时重试、请求格式封装、响应解析全给你处理完了。你在自己项目里写的话这些代码少说也得两三百行还不一定写得稳。跑通这段代码你就已经完成了从Java工程师到LLM应用开发者的“惊险一跳”。接下来要做的是理解这背后的组件关系然后往里面加真正的业务逻辑。3. 核心抽象拆解为什么说LangChain4j的设计“干净”3.1 ChatLanguageModel所有大模型入口的统一接口在LangChain4j里ChatLanguageModel是最高频的接口可以把它理解成“所有大模型入口的门面”。不管是OpenAI、Ollama还是其他厂商的模型对外表现都是ChatLanguageModel这个接口提供了多个generate重载方法。这个设计思路非常像JDBC——Java操作数据库时不管底下是MySQL还是PostgreSQL你都通过Connection、Statement这些标准接口操作换数据库只换驱动。LangChain4j把同一套哲学搬到了LLM领域。你写的Service层代码面向ChatLanguageModel编程将来从一家模型厂商切到另一家只要换Bean里配置的那个实现类就行业务代码纹丝不动。除了generate(String)这个最简单的方法它还有接收ChatMessage列表的方法这才是多轮对话的正确打开方式ListChatMessage messages new ArrayList(); messages.add(SystemMessage.from(你是一个专业的Java技术顾问。)); messages.add(UserMessage.from(帮我推荐一个Java的ORM框架)); messages.add(AiMessage.from(如果你需要轻量级可以考虑Jdbi如果追求生态完整MyBatis和Spring Data JPA都可以。)); messages.add(UserMessage.from(那MyBatis和Spring Data JPA我该怎么选)); ChatResponse response model.generate(messages);看到这里你应该嗅到了关键点LangChain4j并不是让你把记忆当成字符串拼来拼去而是用结构化的消息对象维护上下文。3.2 Message体系系统、用户、AI、工具四类消息的角色分工ChatMessage是一个顶层接口下面有四个实现类对应LLM世界里四类基础消息。我列个表你一眼就能看明白消息类型类名作用系统消息SystemMessage给模型设定角色行为规则比如“你是客服”“你只回答技术问题”用户消息UserMessage用户输入的问题或指令模型应答AiMessage模型的回复在多轮中作为历史上下文回传工具消息ToolMessage工具调用后的结果回传做Tool Calling时会用到日常开发中90%的场景就是这三种消息的组合开头放一条系统消息设定人设后面交错放用户消息和模型应答。特别要注意的是SystemMessage虽然在API调用中只是一条普通的消息记录但它对模型的行为约束能力非常强。你完全不prompt它模型也能答但加上一句角色定义之后回答质量会有肉眼可见的区别。我做过对比同样问“给我一个Java单例模式的写法”不加系统消息时模型可能给了五六个变体让人眼花缭乱加了“你是一位精通Java并发编程的专家回答要简洁、给出代码和说明”之后输出直接干净利落这属于免费的工程优化。3.3 AiServices不再手工拼消息让框架管记忆手工管理ChatMessage列表在小Demo里没啥问题可一旦业务复杂起来你就要开始处理会话过期、消息数量超限、历史裁剪……这时候再用List就非常痛苦。LangChain4j为此提供了AiServices这个高层的门面。它允许你做一个接口然后把模型能力直接绑定到方法上。我举个例子你感受一下interface Assistant { String chat(String userMessage); } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .build(); String answer assistant.chat(李白是哪位诗人);你没有看错你只管定义一个Java接口不需要写实现类AiServices会在底层自动生成一个动态代理把.chat()方法调用接住自动从chatMemory里取出历史消息和本次用户输入拼成完整的ChatMessage列表发给模型再把模型回答存回记忆里。这里MessageWindowChatMemory.withMaxMessages(20)的含义是最多保留最近20条消息。超过20条最老的自动被丢掉。这是防止Token爆掉的一种朴素但实用的策略适合大多数轻量级对话场景。我强烈建议你从第一步Demo之后就直接切到AiServices因为它才是写实际业务代码的正确姿势。4. 进阶实操流式输出、结构化输出与Tool Calling4.1 流式输出别再让用户干等那几秒如果你做的只是内部的命令行小工具同步等待模型返回没问题。但只要是面向用户的界面全等返回再渲染的体验只能用“灾难”形容——一段长回答往往要等5秒甚至更久才一次性冒出来用户早就以为系统挂了。解决方案是流式输出也就是让模型生成一个字就推一个字过来前端像打字机一样把字逐个打出来。LangChain4j里对应的接口叫StreamingChatLanguageModelStreamingChatLanguageModel streamingModel OpenAiStreamingChatModel.builder() .baseUrl(https://你的API服务商地址/v1) .apiKey(你的API Key) .modelName(你选定的模型名称) .build(); streamingModel.generate(请写一篇关于Java内存模型的短文, new StreamingResponseHandlerAiMessage() { Override public void onNext(String token) { System.out.print(token); // 收到增量token立即输出 } Override public void onComplete(ChatResponse response) { System.out.println(\n完成); } Override public void onError(Throwable error) { error.printStackTrace(); } });onNext方法就是流式推送的核心回调。注意这里拿到的token是一个个片段可能是一个词一个汉字甚至半个词你只管把它原样追加到页面上就行。如果你用的是Spring Boot做Web应用想把这套能力暴露给前端的话标准做法是用Spring WebFlux或SSEServer-Sent Events把onNext里的token通过SSE通道实时推给浏览器。我不建议在这里直接上WebSocketSSE对“服务端单向推送文本”这个场景的契合度是最高的实现也简单很多。4.2 结构化输出让模型把JSON“吐”成Java对象大模型问答最讨厌的一个场景是你跟它说“帮我解析一下这封邮件里的订单号、金额、客户名称”它倒是乖乖回答了但回答格式可能是散文可能是乱码JSON也可能是一个带markdown代码块标记的JSON。为了让它稳定输出结构化数据LangChain4j提供了一套非常优雅的方案你定义一个Java类再定义一个接口方法标注返回值模型就会按照你的Java类型约束输出。看代码record Person(String name, int age, String city) { } interface PersonExtractor { SystemMessage(你是一个信息提取助手请从用户输入中提取字段并返回。) Person extractPerson(String text); } PersonExtractor extractor AiServices.create(PersonExtractor.class, model); Person person extractor.extractPerson(张三今年28岁住在杭州); // 输出Person[name张三, age28, city杭州]我头一回用这个功能的时候整个人是震撼的。它背后的原理是LangChain4j把你定义的Person类型record或class转换成JSON Schema放到prompt里让模型生成对应结构的JSON然后再用Jackson把JSON反序列化回Java对象。整个过程无缝衔接你完全不用手工解析。这个方法简直是为信息抽取、表单自动填充、数据清洗等场景量身定做的。比起让模型“输出JSON然后你解析”这个方案能把解析失败率压到极低。毕竟模型不需要猜你要什么格式Schema已经给它了。4.3 Tool Calling让模型调用你的Java方法如果说结构化输出是让人舒服那Tool Calling就是整个LangChain4j里最让我觉得“值回票价”的功能。简单说它能让模型自己决定“我需要调用某个Java方法”然后框架帮你把参数传进去执行完方法再把结果回传给模型。我项目里一个真实的例子让大模型帮用户查询订单状态。模型本身不知道订单数据但它可以调用查询方法。定义工具非常简单就在接口里加一个带Tool注解的default方法或用Tool标记的实现方法interface OrderAssistant { String chat(String userMessage); Tool(根据订单ID查询订单状态) default String queryOrderStatus(ToolParam(订单ID) String orderId) { // 这里实际去查数据库 return 订单 orderId 当前状态为已发货预计明天送达; } }然后构建时把它构建进去OrderAssistant assistant AiServices.builder(OrderAssistant.class) .chatLanguageModel(model) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .tools(new OrderTool()) // 如果工具逻辑在另一个类也可以传入工具对象 .build();之后用户发一句“查一下订单12345678的物流”模型的回复就不是空话而是真的调用queryOrderStatus(12345678)拿到结果之后再基于这个结果组织语言回复用户。这个能力背后的机制是迭代式的多轮调用模型先返回一个“我要调用queryOrderStatus工具”的意图里面带着参数框架把ToolMessage回传给模型再让模型基于工具结果生成最终回复。用的时候我建议你务必要注意这几点Tool的描述文字要写清楚“这个方法是干什么的”因为模型是看着这段描述决定要不要调用的。描述越具体模型调用越准。你写成“查询订单状态”和“根据订单ID查询订单状态返回当前物流节点和预计送达时间”后者被正确调用的概率高得多。参数用ToolParam注明含义因为模型需要通过语义理解去生成参数值。工具方法不要抛非受检异常建议捕住并返回一个错误描述字符串。因为模型可能会根据“查询失败”的返回继续追问或转人工总比你日志里打了个异常栈、用户界面却卡死了强。4.4 提示词模板告别字符串拼接写业务系统的时候谁都会碰到“prompt里有动态变化的部分”的场景。没见过世面的做法是字符串拼接见过世面的做法是用模板。LangChain4j内置了PromptTemplate使用方式和MyBatis的SQL语句有点像。如果你在SQL里写过whereif你会发现这套方式异常亲切PromptTemplate template PromptTemplate.from( 你是{{companyName}}的客服助手。 用户问题是{{question}} 请用不超过{{wordLimit}}个字回答。 ); MapString, Object variables new HashMap(); variables.put(companyName, 某某科技); variables.put(question, 你们的退款政策是什么); variables.put(wordLimit, 50); Prompt prompt template.apply(variables); String response model.generate(prompt.text());模板变量用双大括号括起来apply方法传入一个变量Map就行。把提示词从代码里抽离出来放到配置文件或数据库是很适合团队协作的习惯——运营同学能直接调话术不用提代码。5. 再往深走一步极简RAG流程5.1 RAG到底解决什么问题大模型训练数据有截止日期你公司的内部制度、产品文档、特殊业务知识模型一概不知道。RAG检索增强生成的思路是用户提问时先从你自己的知识库里检索出相关的片段拼到prompt里给模型参考让模型基于这些资料回答。LangChain4j对RAG的支持是组合式的把下面这条链路串起来就行加载文档 - 切分 - 向量化(Embedding) - 存入向量库 - 检索 - 拼装prompt - 生成回答我建议你第一次做RAG时不要一上来就追求复杂架构先用最简单的“内存向量存储”跑通流程理解每一环在干什么再考虑换真正的向量数据库。5.2 快速跑通一个内存版RAG这里我用一个简化的例子演示怎么把一段关于产品介绍的文本变成可检索的知识。首先准备一个分割器和嵌入模型。LangChain4j通过TextSegment来表示文本片段通过EmbeddingModel来做文本向量化// 1. 加载文档这里直接用字符串模拟 String content 某某智能音箱支持语音控制、蓝牙连接、定时提醒电池续航12小时...; // 2. 切分成片段通常按字数设置窗口带重叠 DocumentSplitter splitter DocumentSplitters.recursive(300, 30); ListTextSegment segments splitter.split(content);然后是向量化和入库EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .baseUrl(https://你的API服务商地址/v1) .apiKey(你的API Key) .modelName(你选定的Embedding模型) .build(); EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); for (TextSegment segment : segments) { Embedding embedding embeddingModel.embed(segment).content(); store.add(embedding, segment); }到了检索环节LangChain4j提供了一个特别实用的EmbeddingStoreContentRetriever它帮你把“向量查询”“相似度排序”“取Top K片段”这些操作全部封装好ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) // 检索时返回几个最相关片段 .minScore(0.6) // 相似度低于0.6的片段直接丢弃 .build();最后把它接进AiServices整个RAG链路就通了Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build(); String answer assistant.chat(这个音箱支持蓝牙吗); // 模型会先检索相关文本片段再基于片段内容回答minScore这个阈值是我比较看重的参数。它的单位是相似度分数不同Embedding模型产出的分数范围不太一样。你在测试阶段可以先设低一点比如0.5看看检索出来的片段相关内容对不对然后逐步调高如果设太高可能什么都检索不到模型只能无奈地说“我不知道”。5.3 RAG落地前必须要想清楚的坑小文档用内存向量库没问题但企业级知识库规模上了几十万片段就得换真正能持久化的向量数据库了。LangChain4j有对应的模块接入方式和上面几乎一样替换实现类即可。切分大小很重要。切得太碎语义不完整切得太大token开销高、检索精度下降。我自己的经验是200500个字符一个片段重叠3050字符属于比较稳妥的起点。Embedding和对话模型是两个独立的模型配置不要误以为同一个模型对象可以干两件事。对话用ChatLanguageModel向量化用EmbeddingModel它们是两条独立的线。6. 新手必看的常见问题与排查实录6.1 常见报错速查表这组内容全部是我自己和身边同事实际踩过的坑整理成表给你现象大概率原因解决思路调用时报401认证失败API Key配置错误或未授权该模型检查apiKey是否复制完整检查模型名是否有该模型访问权限报404 Not FoundbaseUrl或modelName配错确认服务商地址格式一般以/v1结尾确认模型名准确报模型不存在Model Not ExistOllama未拉取对应模型先执行ollama list确保本地模型Tag完整匹配返回内容乱码或截断上下文长度超限、编码问题调低maxMessages减少历史消息数量确保服务端返回UTF-8Tool Calling一直没触发模型本身不支持工具调用或工具描述太模糊换成支持Tool Calling的模型优化Tool描述文案结构化输出报反序列化错误模型生成的JSON和Java类型不匹配或字段命名不一致给record字段加清晰说明必要时用Description注解字段含义6.2 我最想单独拎出来说的三个坑坑一日志里的明文Key泄漏问题开发环境为了排查问题我开了logRequests(true)结果有次顺手把日志贴到群里API Key全场可见。这要是在生产环境后果不堪设想。配置项本身没问题我的建议是开发期开、生产期关如果真的要定位生产问题优先用网关注入Header或者临时开30秒再关掉。坑二上下文长度爆掉对话“失忆”我用MessageWindowChatMemory.withMaxMessages(20)的时候以为20条消息肯定够了结果实战中发现20条消息在Token层面可能相当于两千个Token如果模型上下文窗口只有8K比如一些轻量模型一旦用户上传长文档或连续追问老消息还是会被丢掉——但如果你用的是另一个窗口更大的模型这个数量可以放宽。关键点是不要只按“条数”估算要按“Token”估算。主流做法是给每轮对话估算Token消耗用窗口大小除以每轮平均消耗得出一个安全的保留条数。坑三改了代码还是走旧逻辑LangChain4j的Builder模式有个特点对象构建完就不可变了。你如果调整了temperature参数没重启进程、只把新配置写在main方法里跑了个新实例那没问题但如果你在Spring Boot里用了单例Bean改了配置却没重启尝试效果还是旧的。改配置后务必确认Bean确实重新创建了。6.3 我的排查方法论做LLM应用的调试和传统Java调试有点不一样。传统问题我可以断点、一步步看变量LLM应用的问题很多时候是“提示词不对”或“模型这个场景下就是蠢”很难静态分析。我的排查顺序固定是这样先看日志。开启logRequests和logResponses看清发给模型的原始prompt长什么样、模型返回的原始响应长什么样。这一步能过滤掉70%的问题。复现简化。把业务逻辑剥掉用最少的代码直接调ChatLanguageModel如果简单代码能复现说明问题在模型或配置如果不能复现说明问题在你的业务封装层。查模型能力边界。有些模型不支持Tool Calling、有些Embedding模型不支持中文、有些长文本模型在长对话后性能下降明显。遇到怪问题先确认是不是模型本身的能力问题。查版本差异。LangChain4j更新频繁如果代码和网上教程对不上很可能版本变了。优先看你自己依赖的版本的文档或源码。7. 结尾说点个人心得我在把LangChain4j引入到实际项目之前其实犹豫过很久。Java生态做AI确实没有Python那边热闹社区资料也少遇到问题主要靠翻源码。但真正用了几个月之后我反而觉得LangChain4j这种“先标准化、再扩展”的思路特别对Java工程师的胃口——你不必成为一个提示词工程大师也能用干净的Java代码把LLM嵌进企业系统里。最后再分享一个实用小技巧新手阶段不要一上来就追新版本选一个稳定的发布版把核心接口源码下载下来花一晚上把ChatLanguageModel、AiServices、ChatMemory这几个关键类的源码读一遍。很多网上搜不到答案的疑难杂症看一遍源码心里就有底了。搞懂抽象背后的设计意图比背会一百个API示例都管用。祝各位Java同仁玩得开心早日把大模型真正用进自己的业务里。