1. 从Java工程师到AI应用开发：LangChain4j到底解决了什么问题
如果你是一名写了几年Spring Boot的Java工程师，最近大概率会有一种被时代推着走的焦虑感。Python那边LangChain、LlamaIndex玩得风生水起，各种AI Agent、RAG知识库的教程铺天盖地，而Java生态里能拿得出手的大模型应用开发框架，前两年几乎是空白。LangChain4j就是在这个背景下出现的——它不是LangChain的Java翻译版，而是一套从零设计的、符合Java工程师思维习惯的LLM应用开发框架。
我最初接触LangChain4j是在一个企业内部知识库项目上。当时团队的技术栈清一色是Spring Boot + MyBatis-Plus，运维体系也是围绕Java构建的。如果为了接一个大模型能力就引入Python服务，意味着要多维护一套运行环境、多一套依赖管理、多一套部署流程，这对小团队来说成本太高。LangChain4j的价值就在于，它让Java工程师可以用自己熟悉的注解、接口、依赖注入方式，把大模型能力直接嵌进现有的Spring Boot工程里。
具体来说，LangChain4j解决的核心问题有三个层面。第一层是统一抽象：不同厂商的大模型API（OpenAI、通义千问、文心一言、Ollama本地模型等）接口格式各不相同，LangChain4j用ChatLanguageModel、EmbeddingModel、StreamingChatLanguageModel等接口把它们统一起来，切换模型只需要换一个实现类。第二层是能力编排：AI应用不是简单调一次API就完事，往往涉及提示词模板、对话记忆、工具调用、检索增强等多个环节，LangChain4j提供了AiServices这种声明式的方式来编排这些能力。第三层是工程集成：它天然适配Spring Boot，可以通过@AiService注解把AI能力注入到你的Service层，和现有的业务代码无缝衔接。
这篇文章适合谁看？如果你有Java基础，会用Maven或Gradle，写过Spring Boot项目，但对大模型应用开发完全没有头绪，那这篇内容就是为你准备的。我会从环境搭建开始，一步步带你跑通第一个AI服务，然后深入到RAG知识库、Embedding向量检索、AI Agent工具调用这些进阶场景。整个过程不需要你懂Python，不需要你了解深度学习原理，只需要你有一颗愿意动手的心。
提示：LangChain4j的版本迭代非常快，本文基于1.x稳定版本编写。如果你在实操时发现某些API对不上，先去官方GitHub的Release Notes确认版本差异，这是新手最容易踩的第一个坑。
2. 环境准备：Java工程师上手LangChain4j前必须理清的几件事
2.1 JDK版本与构建工具的选择逻辑
LangChain4j要求JDK 17及以上，这一点没有商量余地。原因不是框架作者故意设门槛，而是它大量使用了Record、Sealed Class、Pattern Matching这些Java 17才正式稳定的特性。如果你所在的公司还在用JDK 8，那要么推动升级，要么只能放弃这个框架。我实测过在JDK 11上强行编译，会在dev.langchain4j.internal包下报一堆语法错误，改都改不动。
构建工具方面，Maven和Gradle都支持，但我建议用Maven。原因很实际：LangChain4j的模块拆分非常细，langchain4j-core、langchain4j-open-ai、langchain4j-ollama、langchain4j-spring-boot-starter等等，每个模块的依赖关系在Maven的dependencyManagement里管理起来更直观。Gradle虽然灵活，但在处理这种多模块BOM（Bill of Materials）时，新手容易搞混implementation和api的区别，导致运行时找不到类。
一个典型的pom.xml核心依赖配置如下：
<properties> <langchain4j.version>1.0.0</langchain4j.version> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> </properties> <dependencies> <!-- 核心抽象层 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>${langchain4j.version}</version> </dependency> <!-- OpenAI兼容接口实现，国内模型大多兼容此协议 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>${langchain4j.version}</version> </dependency> <!-- Spring Boot集成 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> <version>${langchain4j.version}</version> </dependency> </dependencies>这里有个细节值得展开：为什么推荐用langchain4j-open-ai而不是直接找某个国内厂商的专用模块？因为目前国内主流大模型厂商（通义千问、DeepSeek、智谱等）都提供了OpenAI兼容的API端点。你只需要改baseUrl和apiKey，就能用同一套代码切换模型。这比每换一个模型就换一套SDK要省事得多。
2.2 API Key的安全管理：别把密钥写死在代码里
新手最容易犯的错误，就是把API Key直接硬编码在Java类里，然后一不小心提交到了Git仓库。我见过不止一个团队因为这个原因被刷爆了账单。正确的做法是利用Spring Boot的配置体系，把密钥放在环境变量或配置中心里。
在application.yml中这样配置：
langchain4j: open-ai: chat-model: base-url: ${AI_BASE_URL:https://api.openai.com/v1} api-key: ${AI_API_KEY} model-name: ${AI_MODEL_NAME:gpt-4o-mini} temperature: 0.7 timeout: PT60S embedding-model: base-url: ${AI_BASE_URL:https://api.openai.com/v1} api-key: ${AI_API_KEY} model-name: ${AI_EMBEDDING_MODEL:text-embedding-3-small}然后在启动脚本或IDE的运行配置里设置环境变量AI_API_KEY。这样做的好处是，代码仓库里永远不会有明文密钥，不同环境（开发、测试、生产）可以用不同的Key，互不干扰。
注意：
temperature参数控制输出的随机性。做知识库问答时建议调到0.2以下，让回答更稳定、更贴近检索到的原文；做创意文案生成时可以调到0.8以上。这个参数没有绝对标准，要根据你的业务场景反复调试。
2.3 本地模型还是云端API：一个务实的选型判断
很多教程一上来就让你用Ollama跑本地模型，理由是"免费、数据不出内网"。这话没错，但有个前提：你的机器得有足够的显存。一个7B参数的模型，量化后大概需要6-8GB显存；13B的模型需要12GB以上。如果你的开发机是16GB内存的轻薄本，跑本地模型会卡到让你怀疑人生。
我的建议是分阶段来：开发调试阶段用云端API，因为响应快、效果好，能让你快速验证业务逻辑；生产部署时再根据数据敏感性和成本预算决定是否切换到本地模型或私有化部署。LangChain4j的好处就在于，切换模型只需要改配置，代码一行不用动。
如果你确实需要本地跑，Ollama是最省事的选择。安装好Ollama后，执行ollama pull qwen2.5:7b拉取模型，然后在LangChain4j里这样配置：
ChatLanguageModel model = OllamaChatModel.builder() .baseUrl("http://localhost:11434") .modelName("qwen2.5:7b") .temperature(0.3) .build();这里有个实测经验：Ollama默认的上下文窗口是2048个token，做RAG的时候很容易不够用。你需要在Modelfile里调整num_ctx参数，或者创建模型时指定ollama run qwen2.5:7b --parameter num_ctx 8192。这个坑我在第一次做文档问答时踩过，检索出来的内容稍微长一点，模型就"忘记"了前面的对话。
3. 第一个AI服务：从ChatLanguageModel到AiServices的演进
3.1 最原始的调用方式与它的局限
理解LangChain4j的最好方式，是先看最底层、最笨的写法，然后一步步看它如何抽象。最原始的调用长这样：
ChatLanguageModel model = OpenAiChatModel.builder() .apiKey(System.getenv("AI_API_KEY")) .modelName("gpt-4o-mini") .build(); String answer = model.generate("用一句话解释什么是Java的反射机制"); System.out.println(answer);这段代码能跑通，但它暴露了几个问题。第一，提示词和业务代码耦合在一起，改个措辞就要重新编译。第二，没有对话记忆，每次调用都是独立的，用户问"那它有什么缺点"时，模型根本不知道"它"指的是什么。第三，返回的是纯字符串，如果你想让它返回结构化数据（比如JSON），还得自己写解析逻辑，模型稍微不听话就解析失败。
这些问题在真实项目里会被放大。想象一下你要做一个客服机器人，需要维护多轮对话、需要根据用户意图调用不同的后端接口、需要把回答格式化成前端要的结构——用原始的generate方法写，代码会变成一团乱麻。
3.2 用AiServices声明式地定义AI接口
LangChain4j的AiServices是解决上述问题的核心武器。它的思路很像MyBatis的Mapper接口：你只定义接口和方法签名，框架帮你生成实现。看一个例子：
interface CustomerServiceBot { @SystemMessage("你是一名专业的电商客服，回答要简洁、礼貌，不确定的信息不要编造。") String chat(@MemoryId String userId, @UserMessage String message); } CustomerServiceBot bot = AiServices.builder(CustomerServiceBot.class) .chatLanguageModel(model) .chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20)) .build(); String reply = bot.chat("user-001", "我上周买的鞋子想退货，怎么操作？");这段代码里有几个关键点值得拆解。@SystemMessage定义的是系统提示词，相当于给模型设定角色和边界，这部分内容不会出现在对话历史里，但每次调用都会带上。@UserMessage标记的参数是用户输入。@MemoryId是对话记忆的隔离键——不同用户的对话历史互不干扰，这在多用户场景下是必须的。
MessageWindowChatMemory.withMaxMessages(20)表示只保留最近20条消息。为什么要限制？因为大模型的上下文窗口是有限的，而且按token计费。如果不限制，一个用户聊了几百轮之后，每次请求都会带上全部历史，成本会指数级上升，而且超出窗口后模型会直接报错。20条是一个经验值，大概能覆盖10轮左右的问答，对大多数客服场景够用了。
3.3 结构化输出：让模型返回Java对象而不是一堆文本
实际项目里，我们往往需要模型返回结构化的数据。比如从用户的一段话里提取订单号、退货原因、期望处理方式。LangChain4j支持直接把返回值定义成Java Record或POJO：
record ReturnRequest( String orderId, String reason, String expectedAction ) {} interface ReturnParser { @UserMessage("从以下用户描述中提取退货信息：{{it}}") ReturnRequest parse(String userInput); } ReturnParser parser = AiServices.create(ReturnParser.class, model); ReturnRequest request = parser.parse("订单号是20241125001，鞋子尺码不对想换大一码");框架会自动把返回值类型的信息转换成提示词的一部分，告诉模型"请按这个JSON结构输出"，然后自动反序列化成Java对象。实测下来，GPT-4o-mini这种级别的模型，结构化输出的成功率在95%以上。如果遇到解析失败，框架会抛出OutputParsingException，你可以在业务层做重试或降级处理。
提示：结构化输出对字段名很敏感。建议用英文命名Record的字段，并在
@UserMessage里用中文明确说明每个字段的含义。我试过用中文拼音做字段名，模型经常搞混，改成英文后准确率明显提升。
4. RAG知识库实战：让模型回答它没见过的内容
4.1 RAG要解决的核心矛盾与基本流程
大模型有两个天生的短板：一是知识有截止日期，训练数据之后发生的事情它不知道；二是它不知道你公司的内部文档、产品手册、历史工单。RAG（Retrieval-Augmented Generation，检索增强生成）就是用来补这个短板的。
它的基本流程分两步。离线阶段：把你的文档切分成小块（chunk），用Embedding模型把每块转成向量，存进向量数据库。在线阶段：用户提问时，把问题也转成向量，在数据库里找最相似的几个chunk，把它们拼进提示词里，让模型基于这些内容回答。
这个流程听起来简单，但每一步都有坑。文档怎么切？切太大，检索出来的内容包含太多无关信息，干扰模型；切太小，上下文不完整，模型理解不了。Embedding模型选哪个？不同模型对中文的支持差异很大。检索出来多少条合适？太多会超出上下文窗口，太少可能漏掉关键信息。
4.2 文档切分策略：按语义切而不是按字数切
LangChain4j提供了几种DocumentSplitter。最常用的是DocumentSplitters.recursive(maxSegmentSizeInChars, maxOverlapSizeInChars)。它的逻辑是优先按段落切，段落太长再按句子切，句子还长再按字符切。maxOverlapSizeInChars是相邻块之间的重叠字符数，设置重叠是为了避免关键信息刚好被切在边界上导致丢失。
我的经验值是：中文文档maxSegmentSizeInChars设在500-800之间，maxOverlapSizeInChars设在50-100之间。为什么是这个范围？因为中文一个字符大约对应1.5个token，800字符大概是1200个token。检索时取top 3-5个块，总共3000-6000个token，加上系统提示词和对话历史，控制在主流模型8K-16K的上下文窗口内比较安全。
DocumentSplitter splitter = DocumentSplitters.recursive(600, 80); List<Document> documents = FileSystemDocumentLoader.loadDocuments( Paths.get("/data/knowledge-base"), new ApachePdfBoxDocumentParser() ); List<TextSegment> segments = splitter.splitAll(documents);这里有个容易忽略的点：PDF解析出来的文本经常带有页眉页脚、页码、乱码。直接切分会把噪声也存进向量库，检索时匹配到这些噪声，回答质量会大打折扣。建议在切分前加一步清洗，用正则把纯数字行、重复出现的页眉文本过滤掉。
4.3 Embedding模型的选择与向量库的落地
Embedding模型的选择直接决定检索质量。目前中文场景下，我实测过几个主流选项：OpenAI的text-embedding-3-small效果稳定但需要联网；通义千问的text-embedding-v3对中文支持很好；本地的bge-large-zh系列在离线场景下表现不错，但需要自己部署推理服务。
向量数据库方面，LangChain4j支持很多种。开发阶段我强烈建议用内存向量库InMemoryEmbeddingStore，零配置、启动快，适合验证流程。数据量大了之后（超过几万条向量），再换成PostgreSQL的pgvector扩展或Milvus。pgvector的好处是你不需要额外维护一个数据库，复用现有的PG实例就行。
EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .apiKey(System.getenv("AI_API_KEY")) .modelName("text-embedding-3-small") .build(); EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(store) .build(); ingestor.ingest(documents);4.4 把检索能力接入AiServices
最后一步是把检索到的内容喂给模型。LangChain4j提供了ContentRetriever接口，最常用的是EmbeddingStoreContentRetriever：
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.7) .build(); interface KnowledgeBot { String answer(@UserMessage String question); } KnowledgeBot bot = AiServices.builder(KnowledgeBot.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();maxResults(5)表示取最相似的5个块，minScore(0.7)是相似度阈值，低于这个分数的块直接丢弃。这个阈值很关键：设太低，会检索到不相关的内容，模型容易被误导；设太高，可能什么都检索不到，模型只能凭自己的知识瞎编。0.7是一个比较稳妥的起点，实际项目中要根据你的文档质量和Embedding模型的表现来微调。
注意：RAG最常见的失败模式是"检索到了但模型没用"。表现是回答里出现了文档中没有的信息。这通常是因为系统提示词没有强调"只基于提供的上下文回答"。在
@SystemMessage里明确写上"如果上下文中没有相关信息，请直接说不知道，不要编造"，能显著降低幻觉率。
5. AI Agent工具调用：让模型从"会说"变成"会做"
5.1 工具调用的本质：模型输出结构化指令
AI Agent这个词被炒得很热，但剥开概念的外壳，它的核心机制其实很朴素：模型在回答时，如果判断需要调用外部能力，就输出一段结构化的指令（通常是JSON），告诉程序"我要调用哪个函数、传什么参数"。程序执行完函数后，把结果再喂回给模型，模型基于结果生成最终回答。
LangChain4j用@Tool注解来标记可被模型调用的方法。看一个查天气的例子：
class WeatherTools { @Tool("根据城市名称查询当前天气") String getWeather(@P("城市名称，如北京、上海") String city) { // 实际项目中这里调用天气API return city + "今天晴，气温15-22度"; } } interface WeatherAgent { String chat(@UserMessage String message); } WeatherAgent agent = AiServices.builder(WeatherAgent.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build(); String result = agent.chat("北京今天天气怎么样？");当用户问天气时，模型会先输出一个调用getWeather("北京")的指令，LangChain4j拦截这个指令，执行方法，拿到结果，再让模型生成自然语言回答。整个过程对调用方是透明的，你只需要调chat方法。
5.2 工具设计的三条实战原则
工具能不能被正确调用，很大程度上取决于你怎么定义它。我踩过不少坑，总结出三条原则。
第一，工具描述要写清楚"什么时候用"，而不只是"这是什么"。比如你有两个工具，一个查订单状态，一个查物流轨迹。如果描述只写"查询订单"和"查询物流"，模型经常搞混。改成"当用户询问订单是否已付款、是否已发货时使用此工具"和"当用户询问包裹当前在哪个城市、预计何时送达时使用此工具"，准确率会高很多。
第二，参数类型尽量用String，避免复杂对象。模型生成JSON参数时，对嵌套对象的支持不稳定。如果确实需要多个参数，拆成多个String参数，在方法内部再组装。我试过让模型直接生成一个包含List的复杂对象，十次里有三次格式是错的。
第三，工具方法内部要做好异常处理。模型调用工具时传的参数可能不符合预期，比如传了一个不存在的城市名。如果方法直接抛异常，整个对话就中断了。正确的做法是捕获异常，返回一个友好的错误信息字符串，让模型自己决定怎么跟用户解释。
5.3 多工具协作与调用链的观察
当你有多个工具时，模型可能会连续调用多个。比如用户说"帮我查一下北京天气，如果下雨就提醒我带伞"，模型会先调天气工具，拿到结果后判断是否下雨，再决定要不要调提醒工具。这种链式调用是Agent能力的体现，但也容易出问题——如果第一个工具返回的结果格式不清晰，模型可能无法正确判断下一步。
调试多工具协作时，打开LangChain4j的日志很有帮助。在application.yml里加上：
logging: level: dev.langchain4j: DEBUG这样你能看到每次请求的完整提示词、模型的原始输出、工具调用的参数和返回值。我第一次调Agent时，发现模型反复调用同一个工具，看了日志才知道是工具返回的内容里包含了触发再次调用的关键词，调整返回格式后就正常了。
6. 从Demo到生产：那些教程不会告诉你的坑
6.1 超时与重试：大模型API不是永远可靠的
云端大模型API的响应时间波动很大，快的时候一两秒，慢的时候十几秒甚至超时。如果你的服务没有设置合理的超时和重试，用户体验会很差。LangChain4j的模型配置里可以设置timeout，但重试逻辑需要自己实现。
我的做法是在Service层包一层重试，用Spring Retry或者手写一个简单的循环。重试次数设2-3次，每次间隔递增（比如1秒、3秒、5秒）。注意不要对所有异常都重试——如果是API Key无效这种认证错误，重试多少次都没用，只会浪费时间。只对超时和5xx错误重试。
@Retryable( retryFor = {TimeoutException.class, WebClientException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000, multiplier = 2) ) public String askWithRetry(String question) { return bot.chat(question); }6.2 Token成本控制：别让账单吓到你
按token计费意味着每一次调用都是真金白银。一个没优化好的RAG应用，单次问答消耗上万token是常有的事。控制成本有几个抓手：限制对话记忆条数（前面提到的withMaxMessages）；控制检索块数量（maxResults不要设太大）；压缩系统提示词（能一句话说清就别写三段）；对简单问题走缓存（相同问题直接返回上次的结果）。
我做过一个统计：一个日活1000的客服机器人，如果每次问答平均消耗3000 token，用GPT-4o-mini的话，一个月成本大概在几十美元。但如果对话记忆不限制、检索块设成10个，成本会翻好几倍。这些参数在开发阶段感觉不到，上线后账单会教你做人。
6.3 流式输出：提升用户体验的关键一步
大模型生成一段完整回答可能需要好几秒，用户盯着空白屏幕等待的体验很糟糕。流式输出让文字像打字机一样逐字出现，感知上的等待时间大大缩短。LangChain4j支持StreamingChatLanguageModel，配合Spring的SseEmitter可以很方便地实现服务端推送。
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamChat(@RequestParam String message) { SseEmitter emitter = new SseEmitter(60_000L); streamingModel.generate(message, new StreamingResponseHandler<>() { @Override public void onNext(String token) { try { emitter.send(token); } catch (IOException e) { emitter.completeWithError(e); } } @Override public void onComplete(Response<AiMessage> response) { emitter.complete(); } @Override public void onError(Throwable error) { emitter.completeWithError(error); } }); return emitter; }这里有个细节：流式输出和工具调用、RAG检索的配合需要额外注意。检索必须在流式生成开始之前完成，否则你没法把检索结果拼进提示词。工具调用在流式模式下也更复杂，因为模型可能在流的中途决定调用工具。我的建议是，如果场景涉及复杂的Agent编排，先用非流式跑通逻辑，再考虑是否值得改成流式。
6.4 测试策略：怎么测一个"不确定"的系统
传统Java项目的单元测试是确定性的：输入A，断言输出B。但大模型的输出是不确定的，同样的输入可能得到不同的回答。这让很多Java工程师很不适应。
我的测试策略分三层。第一层是契约测试：不测具体内容，只测格式。比如结构化输出能不能成功反序列化、工具调用有没有被触发、返回结果是不是非空。第二层是回归测试：准备一组标准问题和期望答案的关键词，每次修改提示词或换模型后跑一遍，看命中率有没有下降。第三层是人工评估：定期抽样真实对话，人工判断回答质量。自动化测试能保证系统不崩，但回答好不好，最终还是得人来判断。
7. 一些个人体会与后续可以探索的方向
写到这里，LangChain4j从入门到能跑通一个带RAG和工具调用的AI服务，核心路径基本覆盖了。回顾我自己的学习过程，最大的感受是：Java工程师做AI应用开发，优势不在算法，而在工程。模型能力是厂商提供的，提示词效果是可以调优的，但如何把AI能力稳定、高效、可维护地集成进现有系统，这才是Java工程师的主场。
LangChain4j这个框架还在快速演进，我目前关注的两个方向，一个是和Spring AI的生态融合，另一个是Agent编排能力的增强。如果你已经跑通了本文的基础流程，下一步可以试试把知识库换成pgvector做持久化、给Agent加上更多业务工具、或者研究一下如何用LangChain4j做多Agent协作。这些内容展开又是另一篇长文了，有机会再单独聊。
最后分享一个我踩过的坑作为收尾：不要在@Tool方法里做耗时操作。我一开始把一个需要调用外部HTTP接口、平均响应3秒的方法标成了工具，结果模型调用它之后整个对话卡住，用户以为系统挂了。后来改成异步执行加轮询查询状态，体验才好起来。工具方法要快，最好在几百毫秒内返回，这是Agent设计的一条铁律。
