LangChain4j 集成 Spring Boot 完整教程
遵循官方文档核心流程,为你整理可直接落地的分步指南 + 代码示例 + 避坑要点,适配最新版 LangChain4j,零基础也能快速集成。
一、核心前置要求
官方明确的环境约束(必须满足,否则会出现依赖冲突/启动失败):
- JDK 版本:17 及以上(LangChain4j 基于 Java 17 开发,向下不兼容)
- Spring Boot 版本:3.0.x / 3.1.x / 3.2.x(推荐 3.2.x,生态最完善)
LangChain4j 集成 Spring Boot 教程,涵盖环境要求、依赖配置、模型密钥设置、核心开发用法(ChatLanguageModel 注入与 AiService 声明式接口)、多轮对话记忆及常见问题排查。适配 JDK 17+ 与 Spring Boot 3.x,提供 OpenAI 及本地 Ollama 模型配置示例。
遵循官方文档核心流程,为你整理可直接落地的分步指南 + 代码示例 + 避坑要点,适配最新版 LangChain4j,零基础也能快速集成。
官方明确的环境约束(必须满足,否则会出现依赖冲突/启动失败):
直接访问 Spring Initializr,快速生成项目骨架:
在 Spring Boot 项目的 pom.xml 中,添加 LangChain4j 核心依赖 + LLM 模型适配依赖(核心必加),完整依赖如下:
关键说明:LangChain4j 采用「核心包 + 模型适配器」解耦设计,必须同时引入「核心包」+「你要对接的大模型依赖」(示例用 OpenAI,支持阿里通义/百度文心/本地模型等)
<!-- 1. LangChain4j Spring Boot 核心启动器(必加) -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot-starter</artifactId>
<version>0.26.0</version>
<!-- 推荐最新稳定版,可去 Maven 仓库更新 -->
</dependency>
<!-- 2. OpenAI 模型适配器(对接 GPT-3.5/4,按需替换为其他模型) -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
<version>0.26.0</version>
</dependency>
<!-- 可选:Spring Web,用于编写测试接口 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
其他模型依赖替换(按需选择): 阿里通义千问:langchain4j-qwen-spring-boot-starter 百度文心一言:langchain4j-ernie-spring-boot-starter 本地模型(LLaMA/通义千问本地化):langchain4j-ollama-spring-boot-starter Azure OpenAI:langchain4j-azure-open-ai-spring-boot-starter
在项目的 src/main/resources/application.yml(或 application.properties)中,配置大模型的 API 密钥、基础地址,LangChain4j 会自动完成客户端注入,无需手动创建 Bean。
# application.yml 完整配置
langchain4j:
open-ai:
# 你的 OpenAI API 密钥(必填,从 OpenAI 官网获取)
api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 模型名称(可选,默认 gpt-3.5-turbo,可指定 gpt-4/gpt-4o)
chat-model:
model-name: gpt-3.5-turbo
# 超时时间(可选,默认 10s,网络差可调大)
timeout: 30s
langchain4j:
ollama:
base-url: http://localhost:11434
# Ollama 默认本地地址
chat-model:
model-name: qwen:7b # 本地部署的模型名称(LLaMA3/phi3 等)
核心注意:API-Key 必须真实有效,否则会报「401 Unauthorized」认证错误;国内访问 OpenAI 需要配置代理,可在配置中追加 proxy-host/proxy-port;所有配置项均以 langchain4j.xxx 为前缀,框架会自动绑定配置。
LangChain4j 集成 Spring Boot 的核心优势:基于「声明式 API」+「Spring 自动注入」,无需编写复杂的 LLM 客户端代码,仅需定义接口 + 注解,即可实现大模型调用。
这是官方推荐的基础用法,直接注入框架自动创建的 ChatLanguageModel Bean,一行代码调用大模型,适合简单对话场景。
import dev.langchain4j.model.chat.ChatLanguageModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ChatController {
// 核心:自动注入大模型客户端(框架已根据配置创建)
@Autowired
private ChatLanguageModel chatLanguageModel;
// 测试接口:http://localhost:8080/chat?message=你好
@GetMapping("/chat")
public String chat(@RequestParam String message) {
// 一行代码调用大模型,返回响应结果
return chatLanguageModel.generate(message);
}
}
这是 LangChain4j 的灵魂用法,也是官方重点推荐的方式:仅定义一个接口,无需实现类,框架会自动为接口生成代理实现,支持对话、工具调用、记忆、提示词模板等高级能力,完全贴合 Spring 开发习惯。
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.spring.AiService;
// 关键注解:标记为 AI 服务,框架自动生成实现类
@AiService
public interface AssistantService {
// 注解说明:
// @SystemMessage:系统提示词(定义 AI 角色、行为约束)
// @UserMessage:用户输入占位符(接收前端传入的参数)
@SystemMessage("你是一个专业的 Java 开发助手,回答简洁、准确,只提供技术干货")
String chatWithJavaExpert(@UserMessage String userQuestion);
// 支持多参数、自定义提示词模板
@SystemMessage("你是一个翻译专家,将{sourceLang}翻译成{targetLang},保持语义不变")
String translate(@UserMessage String content, String sourceLang, String targetLang);
}
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class AiController {
// 注入 AI Service(框架自动生成代理对象,直接使用)
@Autowired
private AssistantService assistantService;
// 测试 1:Java 技术问答 → http://localhost:8080/ai/ask?question=Spring Bean 生命周期
@GetMapping("/ai/ask")
public String askJava(@RequestParam String question) {
return assistantService.chatWithJavaExpert(question);
}
// 测试 2:多参数翻译 → http://localhost:8080/ai/translate?content=Hello&sourceLang=英文&targetLang=中文
@GetMapping("/ai/translate")
public String translate(@RequestParam String content, @RequestParam String sourceLang, @RequestParam String targetLang) {
return assistantService.translate(content, sourceLang, targetLang);
}
}
该方式核心优势(生产级必用): 无实现类:仅定义接口,极大简化开发; 提示词解耦:通过注解管理提示词,无需硬编码; 高度可扩展:支持函数调用、上下文记忆、多轮对话、输出格式化等; Spring 原生兼容:支持依赖注入、AOP、事务等 Spring 特性。
直接运行项目的启动类(xxxApplication.java),控制台无报错即启动成功,框架会打印如下关键日志(说明大模型客户端注入成功):
INFO --- [main] d.l.s.a.OpenAiAutoConfiguration: OpenAI ChatModel configured
INFO --- [main] d.l.s.s.AiServiceBeanPostProcessor: Created AI service proxy for interface com.example.demo.service.AssistantService
在 src/test/java 下编写单元测试,无需启动 Web 服务即可验证:
import com.example.demo.service.AssistantService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest
class Langchain4jDemoApplicationTests {
@Autowired
private AssistantService assistantService;
@Test
void testAiService() {
String result = assistantService.chatWithJavaExpert("什么是 LangChain4j?");
System.out.println("AI 响应:\n" + result);
}
}
LangChain4j 为 Spring 集成提供了专属注解,是开发的核心,整理官方核心注解如下:
| 注解 | 作用 |
|---|---|
@AiService | 标记接口为 AI 服务,框架自动生成代理实现类(核心) |
@SystemMessage | 定义系统提示词,约束 AI 角色、行为(支持静态文本/动态参数) |
@UserMessage | 标记用户输入的占位符,接收方法参数 |
@AssistantMessage | 标记 AI 的历史回复,用于多轮对话上下文管理 |
@MemoryId | 标记会话 ID,实现多轮对话记忆(不同用户隔离会话) |
基于 @MemoryId 实现会话级记忆,让 AI 记住上下文,官方示例改造如下:
@AiService
public interface ChatService {
// @MemoryId:指定会话 ID,框架自动管理该 ID 的对话上下文
String chat(@MemoryId String sessionId, @UserMessage String userMessage);
}
调用时传入唯一的 sessionId(如用户 ID),即可实现多轮对话上下文关联。
官方强调:LangChain4j 的所有依赖必须保持版本一致,否则会出现类冲突、方法找不到等问题。 最佳实践:在 pom.xml 中统一管理版本号:
<properties>
<langchain4j.version>0.26.0</langchain4j.version>
</properties>
<dependencies>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot-starter</artifactId>
<version>${langchain4j.version}</version>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
<version>${langchain4j.version}</version>
</dependency>
</dependencies>
原因:JDK 版本低于 17,LangChain4j 基于 Java17 开发,必须升级 JDK 到 17+。
原因:API-Key 配置错误/过期,或 OpenAI 代理配置失效,核对:
langchain4j:
open-ai:
api-key: sk-xxx
proxy-host: 127.0.0.1
proxy-port: 7890
原因:缺少模型适配器依赖(仅加了核心包,未加 OpenAI/Ollama 等适配器),必须同时引入「核心包 + 模型适配器」。
解决方案:在配置中增大超时时间:
langchain4j:
open-ai:
chat-model:
timeout: 60s # 超时时间调大至 60 秒
本次基于 LangChain4j 官方 Spring Boot 集成教程,提炼出核心落地流程,关键要点如下:
进阶方向(官方教程后续内容):可继续学习「工具调用(Function Calling)」「向量数据库集成」「本地模型部署」「多模态支持」,这些都是 LangChain4j 的核心能力,适配企业级 AI 应用开发。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online