LangChain4j 入门指南

前言最近经常有小伙伴问我——“老的Java项目做AI应用开发到底该用什么框架”我的回答是LangChain4j。今天这篇文章我就从零开始把LangChain4j的核心概念、底层原理、实战代码从头到尾给你拆解一遍。希望对你会有所帮助。一、LangChain4j到底是什么有些小伙伴可能会说“LangChain4j不就是Python LangChain的Java版吗”还真不是。LangChain4j从名字上看确实跟Python的LangChain有关系但它不是LangChain的简单移植。它完全从头开始设计遵循Java的编程习惯——类型安全、POJO、注解、接口、依赖注入、流式API。截至2026年LangChain4j在GitHub上已经积累了超过12,200颗Star和2,300次Fork最新版本为1.15.1保持着活跃的开发节奏。它原生支持20个LLM提供商和30个向量存储并且与Spring Boot、Quarkus、Helidon、Micronaut等主流Java框架有一流集成。一句话说清LangChain4j是专为Java/Kotlin开发者打造的大语言模型应用开发框架提供统一、标准化的API屏蔽各类大模型、向量数据库、文档解析的底层差异让Java开发者无需重复造轮子快速构建稳定、可扩展的AI业务应用。1.1 不用LangChain4j你得面对什么直接对接大模型API你要处理的麻烦事可不少每个厂商的API格式不一样、参数名不一样、返回结构不一样每次调用都要手动处理HTTP请求、JSON解析、认证和重试多轮对话要手动管理消息历史想让AI基于你的文档回答要做RAG想让AI查天气、查订单要做工具调用。LangChain4j的解决方案这些复杂功能都已封装成现成组件拿来就用。二、一张图看懂LangChain4j的架构在写代码之前我们先建立一个整体认知。图片LangChain4j的整体架构分层清晰五大核心模块支撑所有AI业务能力Model模型层统一封装各类大模型、嵌入模型调用逻辑屏蔽API差异Memory记忆层管理多轮对话记忆支持内存、持久化、分段记忆Document文档层支持PDF、Word、TXT等多格式文档加载、解析、文本切片、清洗Embedding Store向量存储层统一封装向量化与向量检索逻辑。LangChain4j采用清晰的分层架构设计核心抽象层langchain4j-core是整个框架的基石定义了所有核心接口和数据模型。三、LangChain4j的“七件套”LangChain4j的组件体系非常清晰下面我逐个给你拆解。3.1 Model模型层它是AI的“大脑”。Model是与大模型交互的入口。LangChain4j提供了统一的接口来对接不同的模型提供商。目前主要有两类APILanguageModel输入输出都是String现在用得越来越少了ChatModel应用最广泛的API接收多个ChatMessage作为输入输出一个AiMessage支持文本、图片等多模态输入示例创建一个ChatModel// 以OpenAI为例 ChatModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4) .build(); // 发送消息 ChatResponse response model.chat( UserMessage.from(你好请介绍一下自己) ); System.out.println(response.aiMessage().text());3.2 ChatMessage消息类型它是对话的基本单元。LangChain4j支持五种消息类型消息类型描述主要用途UserMessage用户输入的消息用户提问AiMessageAI生成的回复模型输出SystemMessage系统消息设置AI的角色和行为ToolExecutionResultMessage工具执行结果函数调用后回传结果CustomMessage自定义消息扩展场景3.3 ChatMemory记忆层它让AI“记住”对话。大模型本身是无状态的不会记录对话历史。LangChain4j提供了ChatMemory来管理对话上下文。两种内置的记忆淘汰策略MessageWindowChatMemory基于消息滑动窗口仅保留最近的N条消息TokenWindowChatMemory基于Token滑动窗口只保留最近的N个Token// 创建记忆保留最近10条消息 ChatMemory memory MessageWindowChatMemory.builder() .maxMessages(10) .build(); // 添加用户消息 memory.add(UserMessage.from(我叫张三)); // 获取AI回复 AiMessage response model.chat(memory.messages()).aiMessage(); memory.add(response); // 下一轮对话会自动带上历史 memory.add(UserMessage.from(我叫什么名字)); AiMessage response2 model.chat(memory.messages()).aiMessage(); // 模型会记得你叫张三 一个关键概念LangChain4j提供的是“记忆”而非“历史记录”。记忆会根据算法对历史进行改造——淘汰某些消息、总结多条消息、去除不重要的细节、注入额外信息等。3.4 Tools工具层它让AI“长出手脚”。Tools函数调用是LangChain4j最强大的功能之一。它让LLM可以调用外部工具——网络搜索、调用外部API、执行特定代码等。示例定义一个数学工具import dev.langchain4j.agent.tool.Tool; public class CalculatorTools { Tool(对给定的2个数字求和) double sum(double a, double b) { return a b; } Tool(返回给定数字的平方根) double squareRoot(double x) { return Math.sqrt(x); } }⚠️ 重点工具描述一定要写清楚AI能否正确调用工具全看这个描述让AI使用工具ChatModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4) .build(); // 把工具传给模型 ChatRequest request ChatRequest.builder() .messages(UserMessage.from(475695037565的平方根是多少)) .toolSpecifications(ToolSpecifications.from(CalculatorTools.class)) .build(); ChatResponse response model.chat(request); // AI会返回一个toolExecutionRequest表示它想调用squareRoot工具工具调用的完整流程AiServices发送消息和工具架构给LLMLLM回复函数调用如add(42, 58)LangChain4j执行Calculator方法将结果反馈回去。3.5 AiServices高层API它能做声明式AI开发。AiServices是LangChain4j的高层API也是最让Java开发者感到亲切的部分。它的核心思想是面向接口编程你只需要定义一个Java接口用注解标明它需要哪些能力系统提示词、用户消息模板、记忆、工具等AiServices会为你生成一个动态代理对象内部自动编排所有组件。最简单的AiService示例interface Assistant { String chat(String userMessage); } // 创建AI服务 Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .build(); // 直接调用 String reply assistant.chat(你好请介绍一下自己); System.out.println(reply);带系统提示词和记忆的AiServiceinterface ChatAssistant { SystemMessage(你是一个专业的Java技术顾问请用中文回答问题) String chat(UserMessage String userMessage); } // 创建带记忆的AI服务 ChatMemory chatMemory MessageWindowChatMemory.builder() .maxMessages(10) .build(); ChatAssistant assistant AiServices.builder(ChatAssistant.class) .chatLanguageModel(model) .chatMemory(chatMemory) .build(); // 多轮对话自动带记忆 String reply1 assistant.chat(我叫张三); String reply2 assistant.chat(我叫什么名字); // AI记得你叫张三AiServices支持的能力包括静态/动态系统消息通过SystemMessage注解或systemMessageProvider()配置静态/动态用户消息通过UserMessage注解或UserMessage标注参数共享记忆通过chatMemory(ChatMemory)配置多用户记忆通过chatMemoryProvider()和MemoryId标注参数RAG检索增强通过contentRetriever()或retrievalAugmentor()配置3.6 RAG检索增强生成它让AI“有据可查”。RAG是LangChain4j的核心能力之一。它的流程是用户提问 → 从知识库检索相关文档 → 把问题和检索到的文档一起发给AI → AI生成基于文档的回复。在LangChain4j中RAG的核心组件是RetrievalAugmentor。它就像RAG系统的“中央处理器”专门负责给用户的问题“加料”——通过调用各种检索渠道把找到的相关知识片段“贴”到原始问题里让大模型回答时能参考这些资料。// 1. 加载文档 Document document FileSystemDocumentLoader.loadDocument(knowledge.txt); // 2. 切片 DocumentSplitter splitter DocumentSplitters.recursive(300, 0); ListTextSegment segments splitter.split(document); // 3. 向量化存储 EmbeddingModel embeddingModel new BgeSmallEnV15EmbeddingModel(); EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore(); for (TextSegment segment : segments) { Embedding embedding embeddingModel.embed(segment).content(); embeddingStore.add(embedding, segment); } // 4. 创建ContentRetriever ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(3) .build(); // 5. 创建带RAG的AiService Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build(); // 6. 提问AI会基于知识库回答 String answer assistant.chat(公司的请假流程是什么);标准版RAG还可以做更多定制加载Markdown文档并按需切割、补充文件名信息、自定义Embedding模型、自定义内容检索器。进阶版RAG支持查询转换器、查询路由、内容聚合器、内容注入器等特性将整个RAG流程流水线化RAG Pipeline。3.7 MCP协议它让AI拥有“USB接口”。有些小伙伴可能会问“除了自定义工具LangChain4j还能接入外部服务吗”MCPModel Context Protocol就是干这个的。你可以把MCP想象成AI应用的“USB接口”它为AI提供了与外部工具、资源和服务交互的标准化方式。在LangChain4j中集成MCP非常方便!-- 引入MCP依赖 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-mcp/artifactId version1.1.0-beta7/version /dependencyConfiguration public class McpConfig { Bean public McpToolProvider mcpToolProvider() { // 1. 配置与MCP服务的通讯方式SSE McpTransport transport new HttpMcpTransport.Builder() .sseUrl(https://open.bigmodel.cn/api/mcp/web_search/sse?Authorizatinotallow apiKey) .build(); // 2. 创建MCP客户端 McpClient mcpClient new DefaultMcpClient.Builder() .transport(transport) .build(); // 3. 从MCP客户端获取工具提供者 return McpToolProvider.builder() .mcpClients(mcpClient) .build(); } }四、实战光说不练假把式。下面我用Spring Boot LangChain4j快速搭建一个AI对话应用。4.1 第一步创建项目并添加依赖properties java.version21/java.version spring-boot.version3.4.5/spring-boot.version langchain4j.version1.15.1/langchain4j.version /properties dependencies !-- Spring Boot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- LangChain4j核心 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- OpenAI兼容适配器兼容DeepSeek/Ollama/DashScope等 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency !-- Spring Boot集成 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency /dependencies关键理解langchain4j-open-ai不只是对接OpenAI它是一个OpenAI兼容协议适配器。任何提供/v1/chat/completions端点的服务DeepSeek、Ollama、SiliconFlow、通义千问DashScope都能用。4.2 第二步配置application.ymllangchain4j: open-ai: chat-model: api-key: ${OPENAI_API_KEY} model-name: gpt-4 temperature: 0.7 log-requests: true log-responses: true embedding-model: api-key: ${OPENAI_API_KEY} model-name: text-embedding-ada-0024.3 第三步定义AiService接口package com.example.service; import dev.langchain4j.service.SystemMessage; import dev.langchain4j.service.UserMessage; import dev.langchain4j.service.MemoryId; import dev.langchain4j.service.spring.AiService; AiService public interface ChatAssistant { SystemMessage(你是一个专业的AI助手请用中文回答问题简洁友好。) String chat(UserMessage String userMessage); // 带会话ID的多用户记忆 SystemMessage(你是一个专业的AI助手请用中文回答问题。) String chat(MemoryId String sessionId, UserMessage String userMessage); }4.4 第四步写Controllerpackage com.example.controller; import com.example.service.ChatAssistant; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/chat) public class ChatController { private final ChatAssistant chatAssistant; public ChatController(ChatAssistant chatAssistant) { this.chatAssistant chatAssistant; } PostMapping public String chat(RequestBody ChatRequest request) { return chatAssistant.chat(request.getMessage()); } PostMapping(/session) public String chatWithSession(RequestBody SessionChatRequest request) { return chatAssistant.chat(request.getSessionId(), request.getMessage()); } } record ChatRequest(String message) {} record SessionChatRequest(String sessionId, String message) {}4.5 第五步启动应用SpringBootApplication public class Application { public static void main(String[] args) { runApplication(Application.class, args); } }启动后访问POST /api/chat就能跟AI对话了。前后不到50行代码一个完整的AI对话服务就跑起来了。五、进阶用法5.1 结构化输出它让AI返回Java对象。许多LLM支持生成结构化格式通常是JSON的输出这些输出可以轻松映射到Java对象并在应用程序中使用。// 1. 定义要提取的数据结构 public class PersonInfo { public String name; public int age; public String city; } // 2. 在AiService中指定返回类型 interface PersonExtractor { UserMessage(从以下文本中提取人物信息{{text}}) PersonInfo extractPerson(V(text) String text); } // 3. 调用 PersonExtractor extractor AiServices.builder(PersonExtractor.class) .chatLanguageModel(model) .build(); PersonInfo info extractor.extractPerson(张三今年28岁住在北京); System.out.println(info.name); // 张三 System.out.println(info.age); // 285.2 流式响应它能像ChatGPT一样逐字输出。通过StreamingChatLanguageModel实现流式传输无需等待完整答案加载实时响应用户。StreamingChatLanguageModel model OpenAiStreamingChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4) .build(); model.chat(UserMessage.from(写一首关于Java的诗), new StreamingResponseHandlerAiMessage() { Override public void onNext(String token) { System.out.print(token); // 实时打印每个token } Override public void onComplete(ResponseAiMessage response) { System.out.println(\n--- 生成完成 ---); } Override public void onError(Throwable error) { error.printStackTrace(); } } );六、优缺点优点1. 统一API多模型无缝切换LangChain4j提供统一的API屏蔽了不同LLM提供商和向量存储的差异。从OpenAI切换到通义千问只需改配置业务代码几乎不用动。2. 极致多模型适配原生支持OpenAI、通义千问、文心一言、Llama3、Claude等15主流大模型一套代码无缝切换。3. 声明式开发效率极高AiServices让开发者只需定义接口加注解框架自动生成实现。告别冗余的模板代码。4. 模块化可插拔架构对话、记忆、文档加载、切片、向量存储、工具调用组件完全解耦按需组合。5. 全场景能力覆盖原生支持RAG、流式对话、多轮记忆、函数调用、Agent智能编排、文档解析。6. 与Spring生态完美融合提供Spring Boot Starter完美融入Java主流技术栈。7. 社区活跃迭代快速自2023年初启动以来社区持续活跃。2026年已发布1.14.0、1.15.1等多个版本。缺点1. 学习曲线较陡需要理解LLM应用开发的新概念Prompt模板、记忆管理、工具调用、RAG、Agent等。相比Spring AILangChain4j配置更多、学习曲线更陡但胜在能拿捏细节、掌控力拉满。2. 版本迭代快存在破坏性变更版本更新频繁可能导致API变化升级时需要关注Release Notes。3. 官方文档不够完善有开发者反映“根本找不到关键内容的官方文档该有的重要内容是一点都不介绍”。4. 部分高级功能仍在开发中虽然核心功能已经就位但部分功能还在开发中。七、LangChain4j vs Spring AI很多开发者会纠结到底选Spring AI还是LangChain4j对比维度Spring AILangChain4j核心定位Spring生态的AI基础设施JVM上的LLM应用开发工具箱框架依赖强依赖Spring Boot不依赖Spring是通用Java库功能丰富度基础功能功能更丰富、更灵活学习曲线较低较高适用场景简单功能、快速接入复杂工作流、Agent、高级定制选型建议如果你是Spring生态的深度用户刚开始学习AI推荐先从Spring AI入门快速完成模型接入当需要构建复杂的Agent、RAG或工作流时推荐LangChain4j两者也可以混用——在Spring Boot项目中按需使用LangChain4j的特定能力本质区别如果说Spring AI是个熟练的装配工那LangChain4j就更像是个逻辑缜密的架构师。八、生产避坑指南有些小伙伴可能会在实践过程中踩坑这里我整理了几个常见问题坑1工具调用的描述要写清楚AI能否正确调用工具全看Tool的描述。描述太模糊AI可能不知道该在什么时候调用。坑2多模型切换时注意配置冲突当同时配置多个模型提供商时需要为每个命名模型明确指定provider。坑3对话记忆不是历史记录LangChain4j提供的是“记忆”而非完整“历史记录”记忆会根据算法对历史进行改造。坑4模型能力不一致同一品牌不同型号的能力差别很大先跑最小可用Demo验证。坑5AiMessage.text()为null的情况在多Agent设置中当LLM返回纯工具调用响应无文本内容时处理AiMessage的text字段可能抛出NPE。坑6依赖版本要匹配LangChain4j的版本要与后端模型SDK的版本对齐避免兼容性问题。九、写在最后回到最初的问题Java做AI应用开发到底该用什么框架如果你是一个Java后端开发者想在Spring Boot项目里快速集成AI能力——LangChain4j是目前最好的选择之一。它不是Python LangChain的简单移植而是为Java从头设计的、遵循Java编程习惯的AI应用开发框架。它提供统一的API、声明式的AiServices、丰富的组件库、与Spring生态的无缝集成。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。