LangChain4j 1.4.0 快速入门：JDK 11+ 基线迁移与首个 AI Service 构建

前言

LangChain4j 1.4.0 的发布为 Java 生态带来了全新的 LLM 应用开发体验。相比 1.3.x 版本，1.4.0 进行了架构层面的重大革新，模块结构更加精简，Agentic 能力显著增强，同时引入了 MCP 流式传输、工具并发执行等企业级特性。

本文将带你从零开始，完成 1.4.0 版本的环境搭建，理解新版模块化架构，并通过一个极简示例构建你的第一个 AI Service。

一、版本差异：1.4.0 vs 1.3.x

1.1 核心架构变化

LangChain4j 1.4.0 在模块化设计上进行了大幅优化：

模块结构对比：

复制代码

1.3.x 版本（10+ 个核心模块）
├── langchain4j
├── langchain4j-core
├── langchain4j-open-ai（嵌入在主模块）
├── langchain4j-pinecone
├── langchain4j-chroma
├── langchain4j-redis
├── langchain4j-pgvector
├── langchain4j-milvus
├── langchain4j-qdrant
└── ... 其他集成模块

1.4.0 版本（6+1+1+2 精简结构）
├── 核心模块（6个）
│   ├── langchain4j-core（核心抽象）
│   ├── langchain4j（主入口）
│   ├── langchain4j-open-ai（OpenAI 集成，独立）
│   ├── langchain4j-http（HTTP 客户端）
│   ├── langchain4j-code-execution-engine-graalvm-polyglot（代码执行）
│   └── langchain4j-agentic（Agent 模式）
├── 测试模块（1个）
│   └── langchain4j-test（测试工具）
├── SEO 模块（1个）
│   └── langchain4j-seo（日志与监控）
└── Spring Boot 集成（2个）
    ├── langchain4j-spring-boot-starter
    └── langchain4j-open-ai-spring-boot-starter

1.2 破坏性变更清单

OpenAI 模块独立化
- 1.3.x：OpenAI 集成嵌入在 langchain4j 主模块中
- 1.4.0：langchain4j-open-ai 成为独立模块，需显式引入依赖
JDK 基线提升
- 最低要求从 JDK 8 提升至 JDK 11+
- 原因：GraalVM Polyglot 代码执行引擎需要 JDK 11+
工具参数校验器变更
- 引入工具参数校验器与异常处理器（Breaking Change）
- PR #3536 带来的 API 变更
Agentic 范围 JSON 序列化
- 优化了 AgenticScope 的 JSON 序列化方式
- PR #3656

1.3 新特性概览

特性	描述	PR 编号
Agentic 增强	声明式 API 增强，支持复杂代理流程	#3587, #3602, #3533, #3594
MCP 流式传输	支持流式 HTTP 传输，低延迟高吞吐	#3534, #3494, #3578, #3570
工具并发执行	支持并发执行多个工具调用	#3512, #3069, #3536
多模态支持	ImageContent 与 TextContent 混合	#3420
代码执行引擎	GraalVM Polyglot 集成	新模块

二、依赖管理：BOM 统一版本控制

2.1 使用 BOM 管理版本

LangChain4j 1.4.0 提供了 BOM（Bill of Materials），避免手动管理多个依赖版本。

Maven 配置：

xml 复制代码

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-bom</artifactId>
            <version>1.4.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle 配置：

groovy 复制代码

dependencies {
    implementation platform('dev.langchain4j:langchain4j-bom:1.4.0')
}

2.2 核心依赖配置

Maven：

xml 复制代码

<dependencies>
    <!-- 核心模块 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
    </dependency>
    
    <!-- OpenAI 集成（1.4.0 独立模块） -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
    </dependency>
</dependencies>

Gradle：

groovy 复制代码

dependencies {
    implementation 'dev.langchain4j:langchain4j'
    implementation 'dev.langchain4j:langchain4j-open-ai'
}

2.3 可选模块配置

xml 复制代码

<!-- 代码执行引擎 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-code-execution-engine-graalvm-polyglot</artifactId>
</dependency>

<!-- 测试支持 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- Spring Boot 集成 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
</dependency>

三、极简示例：首个 AI Service 构建

3.1 定义 AI Service 接口

java 复制代码

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

@AiService
public interface Assistant {
    
    @SystemMessage("你是一个友好的AI助手")
    String chat(@UserMessage String userMessage);
}

3.2 构建 AI Service 实例

java 复制代码

import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

public class QuickStart {
    public static void main(String[] args) {
        // 1. 创建 ChatModel（1.4.0 统一入口）
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o")
                .build();
        
        // 2. 构建 AI Service
        Assistant assistant = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .build();
        
        // 3. 调用 AI Service
        String response = assistant.chat("你好，请介绍一下 LangChain4j");
        System.out.println(response);
    }
}

3.3 执行流程图

复制代码

┌─────────────────────────────────────────────────────────────┐
│                     AI Service 执行流程                      │
└─────────────────────────────────────────────────────────────┘

┌─────────┐    ┌────────────┐    ┌─────────────┐    ┌───────┐
│ 用户调用 │ -> │ @AiService │ -> │ ChatModel   │ -> │ LLM   │
│ chat()  │    │ 接口代理   │    │ (OpenAI)    │    │ API   │
└─────────┘    └────────────┘    └─────────────┘    └───────┘
    │                │                  │               │
    │ 1. 注入参数    │ 2. 构建 Prompt   │ 3. 发送请求   │ 4. 返回结果
    └────────────────┴──────────────────┴───────────────┘

详细步骤：
1. 用户调用 assistant.chat("Hello")
2. @AiService 代理拦截调用
3. 读取 @SystemMessage 和 @UserMessage 注解
4. 构建完整 Prompt（系统提示 + 用户消息）
5. 通过 ChatModel 发送到 LLM
6. LLM 返回文本响应
7. 返回给用户

3.4 1.4.0 新特性：流式响应

java 复制代码

import dev.langchain4j.model.StreamingResponseHandler;

@AiService
public interface StreamingAssistant {
    
    TokenStream chat(@UserMessage String userMessage);
}

// 使用示例
StreamingAssistant assistant = AiServices.builder(StreamingAssistant.class)
        .streamingChatModel(streamingModel)
        .build();

assistant.chat("请写一段代码").onNext(token -> {
    System.out.print(token); // 逐词输出
}).onComplete(response -> {
    System.out.println("\n完成！");
}).onError(error -> {
    error.printStackTrace();
});

四、迁移指南：JDK 8 -> JDK 11

4.1 兼容性检查清单

检查项	JDK 8	JDK 11+	备注
`java.util.Optional`	支持	支持	无变化
`java.util.stream.Stream`	支持	支持	无变化
`java.time` API	支持	支持	无变化
Lambda 表达式	支持	支持	无变化
GraalVM Polyglot	❌ 不支持	✅ 支持	1.4.0 新特性
HttpClient	❌ 需第三方	✅ 内置	HTTP/2 支持

4.2 代码变更点

1. 模块依赖变更（1.4.0）

xml 复制代码

<!-- 1.3.x 版本 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.3.0</version>
</dependency>

<!-- 1.4.0 版本：OpenAI 模块独立 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.4.0</version>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.4.0</version>
</dependency>

2. 工具参数校验器变更

java 复制代码

// 1.3.x 版本
@Tool("计算平方根")
double sqrt(double x) {
    return Math.sqrt(x);
}

// 1.4.0 版本：支持参数校验
@Tool("计算平方根")
double sqrt(
    @P(value = "需要计算平方根的数字", required = true) double x
) {
    return Math.sqrt(x);
}

4.3 升级步骤

复制代码

步骤 1：更新 JDK 版本
├── 下载 JDK 11+（推荐 JDK 17 或 21）
├── 配置 JAVA_HOME 环境变量
└── 验证：java -version

步骤 2：更新依赖版本
├── 修改 pom.xml 或 build.gradle
├── 更新 langchain4j 版本至 1.4.0
└── 添加 langchain4j-open-ai 依赖

步骤 3：代码适配
├── 检查工具方法参数注解
├── 更新 AgenticScope JSON 序列化
└── 测试所有 AI Service 调用

步骤 4：验证新特性
├── 测试 MCP 流式传输
├── 测试工具并发执行
├── 测试 GraalVM 代码执行
└── 测试多模态输入

五、1.4.0 新特性快速预览

5.1 Agentic 增强

java 复制代码

// 1.4.0 新增：程序化定义代理名称与描述
Agent agent = Agent.builder()
        .name("客服助手")
        .description("提供7x24小时客户服务")
        .tools(customerServiceTools)
        .build();

5.2 MCP 流式传输

java 复制代码

// 1.4.0 新增：MCP 流式传输
McpToolExecutor executor = McpToolExecutor.builder()
        .streamableHttpTransport(true) // 启用流式传输
        .build();

5.3 工具并发执行

java 复制代码

// 1.4.0 新增：并发执行多个工具
@AiService
public interface ConcurrentAssistant {
    @UserMessage("同时查询{{city1}}和{{city2}}的天气")
    String queryWeather(
        @P("城市1") String city1,
        @P("城市2") String city2
    );
}

// AI 会并发调用 getWeather 工具两次

5.4 多模态支持

java 复制代码

// 1.4.0 新增：图文混合输入
UserMessage message = UserMessage.from(
    ImageContent.from("https://example.com/image.jpg"),
    TextContent.from("请描述这张图片")
);

六、常见问题

Q1: 如何选择 JDK 版本？

A: 推荐使用 JDK 17 LTS 版本。原因：

稳定性：LTS 版本长期支持
性能：相比 JDK 11 有显著性能提升
生态：主流框架（Spring Boot 3.x）要求 JDK 17+

Q2: 1.4.0 与 1.3.x 兼容吗？

A: 部分兼容，但需要注意：

OpenAI 模块独立化是破坏性变更
工具参数校验器 API 有变化
建议使用 BOM 统一管理版本

Q3: 如何调试 AI Service？

A: 1.4.0 提供了日志功能：

yaml 复制代码

# application.yml
langchain4j:
  open-ai:
    chat-model:
      log-requests: true  # 记录请求
      log-responses: true # 记录响应

Q4: GraalVM 需要单独安装吗？

A: 不需要。langchain4j-code-execution-engine-graalvm-polyglot 模块包含了必要的依赖，只需引入依赖即可使用。

七、小结

本文介绍了 LangChain4j 1.4.0 的核心变化和新特性，包括：

架构革新：模块结构从 10+ 个精简为 6+1+1+2
破坏性变更：OpenAI 模块独立、JDK 基线提升、工具参数校验器变更
依赖管理：使用 BOM 统一版本控制
首个 AI Service：通过极简示例展示了如何构建 AI Service
迁移指南：JDK 8 到 JDK 11 的兼容性检查清单
新特性预览：Agentic 增强、MCP 流式传输、工具并发执行、多模态支持

下一步学习：

文章 2：《LangChain4j 核心抽象：ChatMessage、UserMessage 与模型无关设计》
文章 3：《LangChain4j 异常处理与测试框架：企业级健壮性实践》

参考文献：

LangChain4j 官方文档：https://docs.langchain4j.dev/
LangChain4j GitHub Releases：https://github.com/langchain4j/langchain4j/releases
LangChain4j 1.4.0 新特性解析：https://blog.csdn.net/JIANqiao19931029/article/details/152211120