LangChain4j入门：集成SpringBoot与核心概念全解析

导读：在 Java 生态中，Spring AI 和 LangChain4j 是两个主流的大模型应用开发框架。Spring AI 擅长统一抽象和快速接入，而 LangChain4j 则在 Agent 开发和复杂工作流编排上更胜一筹。本文将从"LangChain4j 是什么"讲起，手把手完成 Spring Boot 集成，并建立一张核心概念的认知地图，帮你快速搞懂这个框架的全貌。

---

一、LangChain4j 是什么

1.1 一句话定义

LangChain4j 是专门为 Java 设计的大语言模型（LLM）应用开发框架，于 2023 年开源，灵感来自 Python 的 LangChain，但绝非简单移植------它结合了 Java 的语言特性做了大量的重新设计，充分利用注解、接口代理等 Java 惯用范式，让 Java 开发者用起来非常自然。

1.2 与 Spring AI 的关系

很多同学学到这里会问：我已经有 Spring AI 了，为什么还要学 LangChain4j？先来回顾一下两者各自的强项。

Spring AI 的优势：

• 完美的统一抽象：不管底层是 OpenAI、DeepSeek 还是通义千问，上层代码完全一致
• 与 Spring 生态无缝集成，自动配置开箱即用
• 多模型切换成本极低
• 内置 Chat Client、Advisor 增强、Function Call、RAG 等能力

Spring AI 的短板：

• 复杂的 Agent 逻辑编排（多步任务分解、多角色协作、精细控制推理决策）虽然能做，但代码量大，很多东西需要自己搭建

LangChain4j 的差异化价值：

• 专注 Agent 开发，提供完整的 Agent 工具链
• 核心注解 @AiService 极其优雅，两行代码定义一个 AI 服务
• 从工具定义到执行循环、多步推理，都有成熟实现

下面用一张表格做直观对比：

对比维度	Spring AI	LangChain4j
定位	统一抽象，快速接入大模型	专注 Agent 开发，完整工具链
核心接口	ChatModel / ChatClient	ChatModel / @AiService
流式输出	返回 Flux	回调方式（StreamingChatResponseHandler）
RAG 管道	完整	完整（架构不同）
AI 服务注解	无	@AiService（核心特色）
Spring 集成	原生	官方 Starter 支持
学习曲线	低	稍高，但收益大

1.3 选型建议：不是二选一，而是各司其职

两者不是竞争关系，可以共存于同一个项目中。 选型思路非常简单：

• 普通对话接口 → 用 Spring AI 的 ChatClient，原生简洁
• 需要角色设定的客服系统 → 用 LangChain4j 的 @AiService 更优雅
• 复杂 Agent 工作流 → 用 LangChain4j 的 Agent 工具链更舒服

学完 LangChain4j 之后，你手里就有了两套工具，可以根据场景灵活选择。

---

二、Spring Boot 集成 LangChain4j 实战

2.1 项目创建与依赖配置

首先创建一个标准的 Spring Boot 项目，我们项目（com.jichi:langchain4j-ai）的技术选型如下：

• JDK 21
• Spring Boot 3.5.x
• LangChain4j 1.12.1（最新稳定版）

在 pom.xml 中，先继承 Spring Boot Parent，再引入 BOM 统一管理 LangChain4j 依赖版本，最后添加核心 Starter：

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- LangChain4j 最新稳定版，使用 OpenAI 兼容接口对接通义千问 -->
    <langchain4j.version>1.12.1</langchain4j.version>
</properties>

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.11</version>
    <relativePath/>
</parent>

<!-- BOM 统一依赖管理 -->
<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>
</dependencies>

这里的 BOM 管理和 Spring AI 的思路一模一样------统一版本号，避免依赖冲突。注意 langchain4j.version 通过 properties 统一管理，升级时只改一处。

2.2 配置文件

在 application.yml 中配置模型连接信息：

server:
  port: 8085

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

配置项和 Spring AI 非常相似，只是前缀从 spring.ai 变成了 langchain4j。有一个踩坑点 ：base-url 必须写在 chat-model 和 streaming-chat-model 每个子节点下面，放在顶层 open-ai 下是不生效的（Starter 不读顶层配置）。配好之后刷新 Maven，确认依赖下载完成即可。

2.3 第一个单轮对话

创建启动类和 Controller，写一个最简单的单轮聊天接口。先看启动类 LangChain4jApplication：

package com.jichi.langchain4j;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class LangChain4jApplication {

    public static void main(String[] args) {
        SpringApplication.run(LangChain4jApplication.class, args);
    }
}

然后是 SimpleChatController------注入 ChatModel，一行代码完成对话：

package com.jichi.langchain4j.controller.chat;

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

启动项目，发送请求 GET /chat?message=你是什么模型，返回"通义千问"相关信息，说明集成成功。注意这里注入的是 dev.langchain4j.model.chat.ChatModel 接口，Starter 会根据配置自动创建 OpenAI 兼容的实现。

2.4 多轮对话的底层实现

单轮对话搞定了，接下来看多轮对话。LangChain4j 的多轮对话需要手动维护消息历史，来看 MultiTurnChatController 的实现：

package com.jichi.langchain4j.controller.chat;

import dev.langchain4j.data.message.*;
import dev.langchain4j.model.chat.ChatModel;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/chat")
public class MultiTurnChatController {

    private final ChatModel chatModel;

    public MultiTurnChatController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @PostMapping("/multi-turn")
    public String multiTurnChat(@RequestBody MultiTurnRequest request) {
        List<ChatMessage> messages = new ArrayList<>();

        // 系统消息（角色设定）
        messages.add(new SystemMessage("你是一个 Java 技术助手，只回答 Java 相关问题。"));

        // 历史对话
        for (HistoryMessage h : request.history()) {
            messages.add(new UserMessage(h.user()));
            messages.add(new AiMessage(h.assistant()));
        }

        // 当前用户消息
        messages.add(new UserMessage(request.message()));

        AiMessage response = chatModel.chat(messages).aiMessage();
        return response.text();
    }

    record MultiTurnRequest(
            List<HistoryMessage> history,
            String message
    ) {}

    record HistoryMessage(String user, String assistant) {}
}

消息类型包括 SystemMessage、UserMessage、AiMessage，这和 Spring AI 中的消息类型基本对齐，都是大模型交互的通用标准。注意这里用了 Java 的 record 来定义请求体，非常简洁。

注意：这里展示的是底层实现方式，实际开发中我们更常用 @AiService + ChatMemory 的组合来优雅地处理多轮对话，后面会详细介绍。

2.5 流式输出

LangChain4j 的流式输出与 Spring AI 的 Flux 方式不同，采用的是回调机制 。来看 StreamingChatController 的实现：

package com.jichi.langchain4j.controller.chat;

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

核心区别在于：Spring AI 返回 Flux<String> 做响应式流，LangChain4j 则通过 StreamingChatResponseHandler 的三个回调方法（onPartialResponse、onCompleteResponse、onError）来处理流式数据。注意 SseEmitter 设置了 60 秒超时时间，避免长时间无响应导致连接挂起。两种风格各有千秋，回调方式在控制粒度上更灵活。

---

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

在深入每个组件之前，我们先建立一张全局认知地图。了解整体架构后再逐个突破，学习效率会高很多。

LangChain4j 的核心骨架由以下六大组件构成：

┌─────────────────────────────────────────────────────┐
│                      Agent                          │
│          （组合所有组件，自主推理与执行）               │
├──────────┬──────────┬───────────┬───────────────────┤
│ AI       │  Tools   │   Chat    │   RAG Pipeline    │
│ Service  │  工具体系 │  Memory   │   检索增强管道     │
├──────────┴──────────┴───────────┴───────────────────┤
│              ChatModel（底层通信）                    │
└─────────────────────────────────────────────────────┘

3.1 ChatModel ------ 底层通信层

这是与大模型 API 通信的核心接口，类似于传统后端中的"数据库连接"。

• chat(String message)：单条消息对话
• chat(List<ChatMessage>)：支持多轮对话，传入包含 SystemMessage、UserMessage、AiMessage 的消息列表

LangChain4j 支持主流模型提供商：OpenAI、Claude、通义千问、DeepSeek、Ollama 等。切换模型只需更换对应的依赖包和配置，上层代码无需改动。

3.2 @AiService ------ 最核心的特色设计

这是 LangChain4j 区别于其他框架的杀手级特性。 它的设计理念和 Spring Data JPA 完全一致：你只需要定义接口，框架自动生成底层实现。

来看项目中最简单的 SimpleAssistant：

package com.jichi.langchain4j.service;

import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.spring.AiService;

@AiService  // 告诉 LangChain4j：这是一个 AI 服务，帮我生成实现
public interface SimpleAssistant {

    @SystemMessage("你是一个友好的 AI 助手，用简洁的语言回答问题")
    String chat(String userMessage);
}

就这么几行代码，一个带角色设定的 AI 服务就定义好了。使用时直接注入，来看 AssistantController：

package com.jichi.langchain4j.controller.aiservice;

import com.jichi.langchain4j.service.SimpleAssistant;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/assistant")
public class AssistantController {

    private final SimpleAssistant assistant;

    public AssistantController(SimpleAssistant assistant) {
        this.assistant = assistant;
    }

    @GetMapping
    public String ask(@RequestParam String question) {
        return assistant.chat(question);
    }
}

对比传统方式需要手动构建 SystemMessage、调用 ChatModel、解析 Response 的繁琐流程，@AiService 将这一切都封装到了注解背后，代码量减少了 80% 以上。

同样支持结构化输出，比如项目中的代码审查服务 CodeReviewer：

package com.jichi.langchain4j.service;

import com.jichi.langchain4j.model.CodeReviewRequest;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.spring.AiService;

@AiService
public interface CodeReviewer {

    @SystemMessage("你是代码审查专家")
    @UserMessage("""
            请 review 以下 {{language}} 代码：

            ```{{language}}
            {{code}}
            ```

            重点关注：{{focusAreas}}
            """)
    String review(CodeReviewRequest request);
}

其中 CodeReviewRequest 是一个 record，用模板变量 {``{language}}、{``{code}}、{``{focusAreas}} 将字段映射到 Prompt 中：

package com.jichi.langchain4j.model;

public record CodeReviewRequest(
    String language,
    String code,
    String focusAreas  // "性能、空指针、事务"
) {}

框架会自动将 record 的字段填充到 @UserMessage 模板里，实现声明式的 Prompt 管理。

3.3 Tools 工具体系 ------ AI 的外部能力扩展

工具体系就是 Function Call 的 LangChain4j 版本------让 AI 自主决定什么时候调用外部能力（发邮件、查天气、查数据库等）。

来看项目中的 WeatherTools：

package com.jichi.langchain4j.tools;

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;

@Component
public class WeatherTools {

    @Tool("查询指定城市的实时天气信息，包括温度、天气状况和风力")
    public String getWeather(
            @P("城市名称，例如：北京、上海、广州") String city) {
        // 实际项目调用天气 API，这里用 Mock 数据演示
        return String.format("%s：晴天，温度18°C，风力2级", city);
    }

    @Tool("查询未来几天的天气预报")
    public String getWeatherForecast(
            @P("城市名称") String city,
            @P("查询天数，1-7之间的整数") int days) {
        return String.format("%s未来%d天：周一晴18°C，周二多云15°C......", city, days);
    }
}

用 @Tool 注解标注方法，写上描述；用 @P 注解标注参数，写上参数含义。框架就会自动将其注册为大模型可调用的工具。当用户问"北京今天天气怎么样"时，模型会自主判断需要调用 getWeather 工具，拿到结果后再组织回答。

3.4 ChatMemory ------ 对话记忆管理

没有记忆的 AI 就像金鱼------每次对话都是全新的开始。ChatMemory 解决的就是对话历史管理问题。

来看项目中的 ChatAssistant 接口：

package com.jichi.langchain4j.service.chatMemory;

import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;

public interface ChatAssistant {
    @SystemMessage("你是一个 Java 技术助手，记住用户在对话中提到的技术栈和问题背景")
    String chat(@MemoryId String sessionId, @UserMessage String message);
}

通过 @MemoryId 注解指定记忆标识（通常是用户的 Session ID），框架会自动维护每个用户的对话历史。不同用户之间的对话互不干扰，你不需要手动管理消息列表。

3.5 RAG Pipeline ------ 检索增强生成管道

RAG 管道分为两条：入库管道 和检索管道。

入库管道（Ingestion）：

原始文档 → 文档加载 → 文本分块 → Embedding 向量化 → 存入向量数据库

检索管道（Retrieval）：

用户问题 → 问题向量化 → 向量相似度检索 → 获取文档片段 → 组装到 Prompt 上下文 → 大模型回答

LangChain4j 支持主流向量数据库：PGVector、Milvus、Pinecone 等，和 Spring AI 的 RAG 能力对等，只是架构设计不同。

3.6 Agent ------ 一切组件的大融合

Agent 是 LangChain4j 的终极形态，它将上面所有组件组合在一起，形成一个自主推理、调用工具、多步执行的智能系统。

其工作模式遵循经典的 ReAct（Reasoning + Acting）循环：

用户输入 → 推理（Reasoning）→ 行动（Acting）→ 观察（Observation）→ 再推理 → ...

来看项目中 SmartAgent 的定义和配置。先是接口定义：

package com.jichi.langchain4j.service.agent;

import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;

public interface SmartAgent {

    @SystemMessage("""
            你是一个智能助手，拥有以下工具：
            - 查天气：可以获取任何城市的实时天气
            - 搜索：可以搜索互联网获取信息
            - 计算：可以执行加减乘除运算

            根据用户的问题，决定是否需要使用工具。
            需要多个信息时，可以多次调用工具。
            综合所有工具的返回结果，给出准确的最终答案。
            """)
    String chat(@MemoryId String sessionId, @UserMessage String message);
}

再看 SmartAgentConfig，通过 AiServices.builder 将模型、工具、记忆组装在一起：

package com.jichi.langchain4j.config;

import com.jichi.langchain4j.service.agent.SmartAgent;
import com.jichi.langchain4j.tools.agent.ArithmeticMathTools;
import com.jichi.langchain4j.tools.agent.CityWeatherTools;
import com.jichi.langchain4j.tools.agent.WebSearchTools;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SmartAgentConfig {

    @Bean
    public SmartAgent smartAgent(
            ChatModel chatModel,
            CityWeatherTools weatherTools,
            WebSearchTools searchTools,
            ArithmeticMathTools mathTools) {

        return AiServices.builder(SmartAgent.class)
                .chatModel(chatModel)
                .tools(weatherTools, searchTools, mathTools)
                .chatMemoryProvider(memoryId ->
                        MessageWindowChatMemory.withMaxMessages(20))
                .build();
    }
}

告诉它用什么模型、有哪些工具可用（天气、搜索、计算）、记忆窗口保留最近 20 条消息，Agent 就搭建好了。剩下的推理和决策，框架帮你搞定。

3.7 传统后端类比，一张表理清关系

如果你是 Spring 开发者，下面这个类比可以帮你快速建立直觉：

LangChain4j 组件	传统后端类比	职责
ChatModel	DataSource / 数据库连接	底层通信
@AiService	DAO 接口（如 JPA Repository）	声明式服务定义
Tools	Service 方法	业务能力扩展
ChatMemory	HttpSession	会话状态管理
Embedding	向量数据库连接	语义检索基础设施
Agent	复杂业务逻辑编排	自主决策与执行

---

四、学习路线图

掌握了全局认知地图后，后续的学习路径如下：

1. 入门起步（本文）：了解 LangChain4j 是什么、Spring Boot 集成、核心概念全览
2. AI Service 深入 ：@AiService、@SystemMessage、结构化输出、声明式 Prompt
3. 工具体系 ：@Tool 定义、异常处理、动态工具注册
4. 记忆系统：短期记忆、持久化记忆、多轮对话管理
5. RAG 管道：文档入库、检索增强、向量数据库集成
6. Agent 开发：执行循环、自主多步推理、复杂工作流编排
7. 工程化实践：可观测性、生产环境注意事项

---

五、总结

本文覆盖了 LangChain4j 入门的三大核心内容：

1. 定位与选型：LangChain4j 专注 Agent 开发和复杂工作流编排，与 Spring AI 是互补关系而非替代关系。快速接入选 Spring AI，构建 Agent 选 LangChain4j，两者可以共存。

2. Spring Boot 集成：通过引入 BOM + Starter 依赖、配置模型连接信息，几分钟即可跑通单轮对话、多轮对话和流式输出。整体集成体验和 Spring AI 类似，上手成本很低。

3. 核心概念认知地图 ：ChatModel 负责底层通信，@AiService 提供声明式服务定义（杀手级特性），Tools 扩展外部能力，ChatMemory 管理对话记忆，RAG Pipeline 实现检索增强，Agent 将所有组件融合为自主推理系统。

LangChain4j 最打动人的设计是 @AiService 注解------只需定义接口，框架自动生成实现，这和 Spring Data JPA 的理念如出一辙。对于 Java 开发者来说，这种"面向接口编程"的方式几乎没有学习障碍。

掌握了这张认知地图，后续深入每个组件时就不会迷路。下一篇我们将重点拆解 @AiService 的使用方式和高级特性，敬请期待。

---

如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎在评论区交流你在 LangChain4j 使用中遇到的问题。