LangChain4j 集成 Spring Boot 完整教程

其他模型依赖替换（按需选择）： 阿里通义千问：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。

示例 1：对接 OpenAI（GPT-3.5/4）配置

# 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

示例 2：对接本地 Ollama 模型（本地化部署，无网络依赖）

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 为前缀，框架会自动绑定配置。

四、第三步：核心开发（2 种主流用法，覆盖 90% 场景）

LangChain4j 集成 Spring Boot 的核心优势：基于「声明式 API」+「Spring 自动注入」，无需编写复杂的 LLM 客户端代码，仅需定义接口 + 注解，即可实现大模型调用。

用法 1：极简用法 - 直接注入 ChatLanguageModel（快速调用）

这是官方推荐的基础用法，直接注入框架自动创建的 ChatLanguageModel Bean，一行代码调用大模型，适合简单对话场景。

编写测试 Controller

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);
    }
}

用法 2：高级用法 - 声明式 AI Service（核心推荐，生产级）

这是 LangChain4j 的灵魂用法，也是官方重点推荐的方式：仅定义一个接口，无需实现类，框架会自动为接口生成代理实现，支持对话、工具调用、记忆、提示词模板等高级能力，完全贴合 Spring 开发习惯。

步骤 1：定义 AI Service 接口（核心，无实现类）

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);
}

步骤 2：注入并使用 AI Service（和普通 Spring 服务完全一致）

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 特性。

五、第四步：启动并测试项目

1. 启动 Spring Boot 应用

直接运行项目的启动类（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

2. 接口测试（2 种方式）

方式 1：浏览器/Postman 直接调用

• 极简对话：http://localhost:8080/chat?message=介绍 LangChain4j
• AI 助手问答：http://localhost:8080/ai/ask?question=Spring Boot 自动装配原理
• 翻译功能：http://localhost:8080/ai/translate?content=LangChain4j is awesome&sourceLang=英文&targetLang=中文

方式 2：单元测试（推荐）

在 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);
    }
}

六、官方教程核心扩展（关键知识点）

1. 核心注解速查表（开发必备）

LangChain4j 为 Spring 集成提供了专属注解，是开发的核心，整理官方核心注解如下：

2. 多轮对话记忆（生产级必备）

基于 @MemoryId 实现会话级记忆，让 AI 记住上下文，官方示例改造如下：

@AiService
public interface ChatService {
    // @MemoryId：指定会话 ID，框架自动管理该 ID 的对话上下文
    String chat(@MemoryId String sessionId, @UserMessage String userMessage);
}

调用时传入唯一的 sessionId（如用户 ID），即可实现多轮对话上下文关联。

3. 依赖版本管理（避坑关键）

官方强调：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>

七、常见问题&避坑指南（官方文档未明确，实操总结）

问题 1：启动报错 java: 无法访问 dev.langchain4j.service.spring.AiService

原因：JDK 版本低于 17，LangChain4j 基于 Java17 开发，必须升级 JDK 到 17+。

问题 2：调用接口报 401 Unauthorized

原因：API-Key 配置错误/过期，或 OpenAI 代理配置失效，核对：

1. application.yml 中 api-key 是否正确； 国内环境需配置代理：

langchain4j:
  open-ai:
    api-key: sk-xxx
    proxy-host: 127.0.0.1
    proxy-port: 7890

问题 3：ChatLanguageModel 注入失败（No qualifying bean）

原因：缺少模型适配器依赖（仅加了核心包，未加 OpenAI/Ollama 等适配器），必须同时引入「核心包 + 模型适配器」。

问题 4：响应超时 TimeoutException

解决方案：在配置中增大超时时间：

langchain4j:
  open-ai:
    chat-model:
      timeout: 60s # 超时时间调大至 60 秒

八、总结（官方教程核心精华）

本次基于 LangChain4j 官方 Spring Boot 集成教程，提炼出核心落地流程，关键要点如下：

1. 环境约束：JDK17+ + Spring Boot3.x，版本必须匹配；
2. 依赖原则：核心启动器 + 模型适配器缺一不可；
3. 配置核心：通过 langchain4j.xxx 前缀配置模型密钥/地址，框架自动注入客户端；
4. 开发 2 种方式：
   • 极简：注入 ChatLanguageModel 快速调用；
   • 生产：用 @AiService 声明接口，框架自动实现（推荐）；
5. 核心优势：完全贴合 Spring 开发习惯，无侵入、低代码、高扩展。

进阶方向（官方教程后续内容）：可继续学习「工具调用（Function Calling）」「向量数据库集成」「本地模型部署」「多模态支持」，这些都是 LangChain4j 的核心能力，适配企业级 AI 应用开发。