LangChain4j 入门教程

一、LangChain4j 和Spring AI 什么关系

1.1回顾：Spring AI 擅长什么

Spring AI 的核心设计哲学是统一抽象—— 无论底层是 OpenAI、DeepSeek 还是通义千问，上层代码保持一致。它的优势非常明显：

• 与 Spring 生态无缝集成

• 多模型切换成本极低

• 自动配置，开箱即用

但是，Spring AI 在复杂 Agent 逻辑编排方面并不是最擅长的。当你的任务是：

• 让 AI 自主分解一个多步任务，逐步执行

• 多个 AI 角色协作完成一个复杂工作流

• 精细控制每一步的推理过程和工具调用决策

Spring AI 能做，但代码会写得比较“重”，很多底层需要自己搭建。而 LangChain4j 正是在这个方向深耕，提供了更完整的 Agent 开发工具链。

1.2 LangChain4j 是什么

LangChain4j 是一个专为 Java 设计的 LLM 应用开发框架，2023 年开源。它灵感来自 Python 的 LangChain，但不是简单移植——结合了 Java 语言特性做了大量重新设计。

GitHub: https://github.com/langchain4j/langchain4j

官网文档地址：https://docs.langchain4j.dev/

核心特点

1. @AiService：最优雅的 AI 接口定义方式

这是 LangChain4j 最有特色的设计。你只需要定义一个 Java 接口，加几个注解，框架就帮你生成实现。

@AiService interface CustomerServiceAgent { @SystemMessage("你是一个专业客服，只回答产品相关问题") String chat(String userMessage); }

就这几行代码，一个带角色设定的 AI 服务就好了。后面会专门讲解@AiService的威力。

2. Agent 工具链完整

工具定义、执行循环、多步推理、Human-in-the-loop 等能力都有成熟实现，不需要自己造轮子。

3. 支持主流模型和向量库

模型：OpenAI、Anthropic、通义千问、DeepSeek、Ollama……
向量库：PGVector、Qdrant、Milvus、Chroma…… 覆盖面和 Spring AI 不相上下。

1.3 Spring AI vs LangChain4j：到底怎么选？

选型建议

• 需要快速接入大模型到已有 Spring 项目→ Spring AI

• 需要构建复杂 Agent 工作流→ LangChain4j

两者不是竞争关系，可以共存于同一项目。
很多企业级项目两个都用：Spring AI 处理简单模型调用，LangChain4j 处理复杂 Agent 逻辑。

二、快速上手：从零搭建 Spring Boot + LangChain4j

2.1 创建项目

使用 Spring Initializr，选择：

• Java 21

• Spring Boot 3.x

• 依赖：Spring Web

结构如下：

创建langchain4j模块来跑通第一个langchain4j 应用

2.2引入pom依赖

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.5.14</version> <relativePath/> </parent> <groupId>com.studying</groupId> <artifactId>langchain4j</artifactId> <version>1.0-SNAPSHOT</version> <properties> <maven.compiler.source>21</maven.compiler.source> <maven.compiler.target>21</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <java.version>21</java.version> <!-- LangChain4j 最新稳定版2026/05/02，使用 OpenAI 兼容接口对接通义千问 --> <langchain4j.version>1.14.0</langchain4j.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-bom</artifactId> <version>${langchain4j.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- LangChain4j Spring Boot Starter（核心 + 自动配置） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> </dependency> <!-- OpenAI 模块——通义千问提供 OpenAI 兼容接口，通过 base-url 指向 DashScope --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies> </project>

2.3 配置application.yml

langchain4j: open-ai: # base-url 必须写在每个子节点下，顶层写不生效（Starter 不读） chat-model: base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${DASHSCOPE_API_KEY} # 从环境变量读，不要硬编码 model-name: qwen-max temperature: 0.7 max-tokens: 2048 streaming-chat-model: base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${DASHSCOPE_API_KEY} model-name: qwen-max

2.4第一个对话——最简单的方式

最简单的用法——直接注入ChatModel并调用：

package com.stduying.controller; import dev.langchain4j.model.chat.ChatModel; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/chat") public class SimpleChatController { private final ChatModel chatModel; public SimpleChatController(ChatModel chatModel) { this.chatModel = chatModel; } @GetMapping public String chat(@RequestParam String message) { return chatModel.chat(message); } }

2.5 流式输出

LangChain4j 使用回调接口实现流式输出，配合 Spring 的SseEmitter：

package com.stduying.controller; import dev.langchain4j.model.chat.StreamingChatModel; import dev.langchain4j.model.chat.response.ChatResponse; import dev.langchain4j.model.chat.response.StreamingChatResponseHandler; import org.springframework.http.MediaType; import org.springframework.web.bind.annotation.*; import org.springframework.web.servlet.mvc.method.annotation.SseEmitter; @RestController @RequestMapping("/chat") public class StreamingChatController { private final StreamingChatModel streamingChatModel; public StreamingChatController(StreamingChatModel streamingChatModel) { this.streamingChatModel = streamingChatModel; } @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamChat(@RequestParam String message) { SseEmitter emitter = new SseEmitter(60_000L); streamingChatModel.chat(message, new StreamingChatResponseHandler() { @Override public void onPartialResponse(String partialResponse) { try { emitter.send(partialResponse); } catch (Exception e) { emitter.completeWithError(e); } } @Override public void onCompleteResponse(ChatResponse completeResponse) { emitter.complete(); } @Override public void onError(Throwable error) { emitter.completeWithError(error); } }); return emitter; } }

2.6对比 Spring AI 的集成方式

最大的区别马上就来。建立 LangChain4j 的整体认知地图，有了这张图再看后面每节才不会迷失。

三、核心概念全览——LangChain4j 的认知地图

3.1 LangChain4j 的整体架构

3.2 ChatModel——模型调用的核心接口

public interface ChatModel { String chat(String userMessage); ChatResponse chat(ChatRequest request); }

最底层的接口，直接和大模型 API 通信。实际开发中很少直接用它，更多是通过上层@AiService或 Agent 间接使用。

LangChain4j 支持的模型（部分）：

3.3 @AiService——AI 接口层

这是 LangChain4j 最有特色的设计，也是后面用得最多的。

核心思路：用 Java 接口定义 AI 能力，框架自动生成实现。这是 LangChain4j 设计最优雅的地方

// 1. 定义接口 @AiService interface TechAssistant { @SystemMessage("你是一个 Java 技术助手，只回答 Java 相关问题，用简洁的语言回答") String chat(String question); @SystemMessage("你是一个代码审查专家") CodeReviewResult reviewCode(@UserMessage String code); } // 2. 注入使用（LangChain4j 自动生成实现） @Autowired TechAssistant techAssistant; // 3. 调用 String answer = techAssistant.chat("什么是 Spring AOP？");

3.4 Tools——工具体系

工具让模型能调用外部能力——查天气、查数据库、发邮件……

@Component public class WeatherTools { @Tool("查询指定城市的实时天气") public String getWeather(String city) { // 调用天气 API return city + "：晴天，18°C，微风"; } @Tool("查询汇率") public double getExchangeRate(String from, String to) { // 调用汇率 API return 7.24; } }

3.5 ChatMemory——对话记忆

没有记忆的 AI 每次都当第一次见面，用户体验很差。LangChain4j 提供了ChatMemory管理对话历史：

// 消息窗口记忆：保留最近 N 条消息 ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); // Token 窗口记忆：按 Token 数量限制，不超过上下文窗口 ChatMemory memory = TokenWindowChatMemory.withMaxTokens(4096, tokenizer);

配合@AiService使用：

@AiService interface ChatService { @SystemMessage("你是一个友好的助手") String chat(@MemoryId String sessionId, @UserMessage String message); // ↑ 用 sessionId 区分不同用户的对话历史 }

3.6 RAG Pipeline——检索增强生成

让模型能回答私有知识库里的问题。LangChain4j 的 RAG 分两条管道：

Ingestion Pipeline（入库管道）：

原始文档（PDF/Word/TXT） → DocumentLoader（加载） → DocumentTransformer（分块） → EmbeddingModel（向量化） → EmbeddingStore（存入向量库）

Retrieval Pipeline（检索管道）：

用户问题 → EmbeddingModel（向量化问题） → EmbeddingStore（相似度检索） → ContentRetriever（取回文档片段） → RetrievalAugmentor（注入 Prompt 上下文） → ChatModel（带上下文回答）

3.7 Agent——自主推理执行

Agent 是把上面所有组件组合起来，形成一个能自主推理、调工具、多步执行的系统。鸡哥认为这是整个模块四最重要的部分，前面讲的所有组件最终都是为 Agent 服务的。

用户输入 ↓ Think（推理：我需要什么信息/操作） ↓ Act（行动：调用工具或 RAG 检索） ↓ Observe（观察：看工具返回了什么） ↓ Think（再次推理：够了吗？还需要什么？） ↓ ...循环直到有足够信息... ↓ Answer（最终答案）

LangChain4j 的 Agent 实现：

// Agent 需要：模型 + 工具 + 记忆 Agent agent = AiServices.builder(Agent.class) .chatModel(chatModel) .tools(weatherTools, searchTools, calculatorTools) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .build();

3.8各组件的关系总结