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