LangChain4j：为Java开发者打开大模型应用的大门

一、为什么需要LangChain4j？

2023年初ChatGPT引爆了大模型热潮，Python和JavaScript生态迅速涌现出LangChain、LlamaIndex等优秀框架，但Java开发者却面临一个尴尬的局面——想开发AI应用，要么直接调用各大厂商的原生API，代码臃肿且难以切换；要么只能望洋兴叹。

LangChain4j正是在这样的背景下诞生的。它由Java社区发起，目标是为Java开发者提供一套简洁、统一、功能完备的大模型集成框架。虽然名字里有”LangChain”，但它实际上是融合了LangChain、Haystack、LlamaIndex等社区优秀思想的产物，并加入了许多Java生态特有的创新。

简单来说：LangChain4j就是Java生态中的LangChain。

二、LangChain4j能解决什么问题？

2.1 消除模型差异，一套代码适配所有

每个大模型厂商都有自己的API格式和调用方式。如果直接对接OpenAI、通义千问、Claude等，你需要为每个模型写一套适配代码。而LangChain4j提供了统一的API，切换模型时只需修改几行配置，核心业务代码完全不用动。

2.2 封装复杂逻辑，专注业务

集成AI不只是”发请求、收回复”这么简单。要实现一个智能客服，你需要考虑：

如何管理对话上下文？
如何让AI基于私有知识库回答？
如何让AI调用外部工具（查天气、查订单）？

这些复杂逻辑LangChain4j都已封装成现成的组件。你只需关注”客服该回答什么”，不用操心”怎么让AI记住对话”。

2.3 贴合Java生态，上手零门槛

LangChain4j完全遵循Java开发习惯：支持Maven/Gradle依赖管理、与Spring Boot和Quarkus完美集成、API设计简洁直观。如果你熟悉Java，几乎不用额外学习就能快速上手。

三、核心概念速览

在使用LangChain4j之前，先了解三个核心概念：

概念	说明	类比
ChatLanguageModel	与LLM交互的入口，负责发送请求、接收响应	数据库连接
Prompt	给AI的指令，支持模板化	SQL模板
AiServices	高层API，用声明式方式构建AI应用	Spring的@Repository

此外，LangChain4j提供两个抽象层次：

低层：直接操作ChatLanguageModel、UserMessage等原语，灵活性最高
高层：使用AiServices，通过注解和接口声明，自动处理复杂逻辑

四、快速上手：跑通第一个AI应用

下面我们用Spring Boot + LangChain4j + 阿里通义千问，快速实现一个AI对话。

4.1 添加依赖

xml

<properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <langchain4j.version>1.12.2</langchain4j.version>
    </properties>


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


    <dependencies>
        <!-- SpringBoot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
        </dependency>
				
      
      
      	        <!-- LangChain4j 低级AI交互-->
<!--        <dependency>-->
<!--            <groupId>dev.langchain4j</groupId>-->
<!--            <artifactId>langchain4j-open-ai</artifactId>-->
<!--            <version>${langchain4j.version}</version>-->
<!--        </dependency>-->

        <!-- LangChain4j 高级AI交互，如RAG-->
<!--        <dependency>-->
<!--            <groupId>dev.langchain4j</groupId>-->
<!--            <artifactId>langchain4j</artifactId>-->
<!--            <version>${langchain4j.version}</version>-->
<!--        </dependency>-->
      
      

      	<!-- LangChain4j 低级AI交互starter 已包含上面 langchain4j-open-ai 基础包 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
            <version>${langchain4j-spring-boot-starter.version}</version>
        </dependency>
	
        <!-- LangChain4j 高级AI交互starter 包含 上面langchain4j高级aiservice相关的包-->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-spring-boot-starter</artifactId>
            <version>${langchain4j-spring-boot-starter.version}</version>
        </dependency>
      
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

    </dependencies>

4.2 低级和高级API对比

特性	低级 API (`ChatLanguageModel`)	高级 API (`@AiService`)
代码量	较多	极少
灵活性	极高	较高
自动解析输出	❌ 返回 String	✅ 可返回 POJO
对话记忆	❌ 需手动实现	✅ 内置支持
工具调用	❌ 需手动处理	✅ 自动处理
适用场景	需要精细控制	大部分业务场景

💡 建议：优先使用高级 API，除非你需要非常底层的控制。

4.3 配置API Key

在application.yml中添加：

yaml

langchain4j:
  open-ai:
    chat-model:
   		# 模型名称，这里我选用的 DeepSeek 的 deepseek-chat， 支持多家 AI厂商，OpenAI、Anthropic、Google Gemini、通义千问、智谱等
      model-name: deepseek-chat
      base-url: https://api.deepseek.com
      # 你的 API Key
      api-key: ${your_api_key}  #从环境变量获取，不硬编码
      # 温度参数（0-1，越高越随机性越高）
      temperature: 0.7
      # 最大输出 token 数
      max-tokens: 2000
      # 开启日志（便于调试）
      log-requests: true
      log-responses: true

4.4 编写AI服务

java

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

@AiService
public interface AiAssistant {
    
    @SystemMessage("你是一个专业的编程助手，帮助用户解答Java开发问题。")
    String chat(String userMessage);
}

就这么简单！@AiService注解会自动将接口与配置的模型绑定，@SystemMessage定义AI的角色和行为。

4.5 在Controller中使用

java

@RestController
@RequestMapping("/api/ai")
public class AiController {
    
    @Resource
    private AiAssistant aiAssistant;
    
    @PostMapping("/chat")
    public String chat(@RequestParam String question) {
        return aiAssistant.chat(question);
    }
}

用 Postman 发送请求，AI会返回关于 Stream API 的专业解答。

4.6 `@AIService`注解属性详解

@AiService 注解是 LangChain4j 与 Spring Boot 集成的核心，它将一个普通的 Java 接口声明为一个功能强大的 AI 服务，并允许你通过其属性进行精细化的配置。

下表详细列出了 @AiService 注解支持的所有属性及其作用：

属性	类型	必填	描述
`wiringMode`	`AiServiceWiringMode`	否	装配模式。决定如何为 AI 服务提供所需组件（如模型、记忆等）。 • `AUTOMATIC` (默认)：框架会尝试从 Spring 的 `ApplicationContext` 中自动查找并装配所有匹配类型的组件。 • `EXPLICIT`：必须通过注解的其他属性（如 `chatModel`、`tools`）显式指定所需组件的 Bean 名称，精确控制依赖。
`chatModel`	`String`	否	对话模型的 Bean 名称。用于指定一个实现了 `ChatLanguageModel` 接口的 Bean。当 `wiringMode` 设为 `EXPLICIT` 时，需要此项来明确指定模型。
`streamingChatModel`	`String`	否	流式对话模型的 Bean 名称。用于指定一个实现了 `StreamingChatLanguageModel` 接口的 Bean，支持流式输出。同样，在 `EXPLICIT` 模式下使用。
`chatMemory`	`String`	否	聊天记忆的 Bean 名称。用于指定一个 `ChatMemory` 的 Bean。配置后，AI 服务将具备多轮对话的记忆能力，能够记住上下文。
`chatMemoryProvider`	`String`	否	聊天记忆提供者的 Bean 名称。用于指定一个 `ChatMemoryProvider` 的 Bean。与 `chatMemory` 不同，它可以根据 `@MemoryId` 为不同的会话（用户）提供独立的记忆空间，实现会话隔离。
`contentRetriever`	`String`	否	内容检索器的 Bean 名称。用于指定一个 `ContentRetriever` 的 Bean。这是实现 RAG（检索增强生成）模式的关键组件，能从外部数据源（如向量数据库）检索相关信息，作为上下文提供给 LLM。
`retrievalAugmentor`	`String`	否	检索增强器的 Bean 名称。用于指定一个 `RetrievalAugmentor` 的 Bean。这是 `contentRetriever` 的更高级和灵活的替代方案，可以对整个 RAG 流程进行更精细的控制。
`moderationModel`	`String`	否	内容审核模型的 Bean 名称。用于指定一个 `ModerationModel` 的 Bean，可以对用户输入和 AI 输出进行内容审核，过滤掉不安全或不合适的对话。
`tools`	`String[]`	否	工具 Bean 的名称数组。用于注册一个或多个 `@Component` 类（该类中包含用 `@Tool` 注解的方法）的 Bean 名称。这使得 LLM 能够调用这些外部工具/函数来执行特定任务，如查询天气、计算等。

两种装配模式 (`wiringMode`) 的选择

wiringMode 是决定你如何配置 AI 服务的核心，理解它有助于在便捷性和精确性之间做出权衡。

自动装配 (AUTOMATIC)：这是默认模式，代码最简洁。你只需声明 @AiService，框架会“智能”地从 Spring 容器中寻找所需组件并注入。
- 优点：零配置，开发速度极快。
- 缺点：当 Spring 容器中存在多个同类型 Bean（比如你配置了两个 ChatLanguageModel）时，框架可能无法确定该注入哪一个，从而导致启动失败或行为不确定。
手动装配 (EXPLICIT)：在这种模式下，你需要通过注解的各个属性（如 chatModel、tools）精确地指定所需组件的 Bean 名称。
- 优点：清晰、安全。完全避免了 Bean 冲突的问题，服务的依赖关系在接口定义上一目了然，非常适合复杂项目。
- 缺点：需要多写一点配置。

4.7 四种消息类型

LangChain4j 定义了四种消息角色，理解它们能让你更好地控制 AI 行为。

消息类型总结

消息类型	创建方式	用途	谁发送
`SystemMessage`	`SystemMessage.from(text)`	设定 AI 的行为准则、角色	开发者
`UserMessage`	`UserMessage.from(text)`	用户的问题或指令	用户
`AiMessage`	模型返回	AI 的回复	AI 模型
`ToolExecutionResultMessage`	`ToolExecutionResultMessage.from(...)`	工具调用的结果，如查询日期/天气	工具/函数

五、LangChain4j的能力全景

除了基础对话，LangChain4j还支持：

功能	说明
RAG（检索增强生成）	让AI基于私有知识库回答问题，支持PDF、Word、网页等多种文档
函数调用（Tool Calling）	AI可以主动调用Java方法，如查天气、查数据库
流式输出	支持SSE流式响应，提升用户体验
多模态	支持图文混合输入（需模型支持）
结构化输出	将AI输出自动映射到Java POJO
15+ LLM提供商	OpenAI、Anthropic、Google Gemini、通义千问、智谱等
20+ 向量数据库	Pinecone、Milvus、PgVector、Chroma等

六、与Spring AI的对比

很多Java开发者会问：LangChain4j和Spring AI怎么选？

维度	LangChain4j	Spring AI
成熟度	更高，功能更丰富	相对早期
社区生态	活跃，集成更多	Spring官方背书
API风格	灵活，支持声明式	更”Spring化”
学习曲线	平缓	平缓

个人建议：目前LangChain4j功能更完善，适合生产项目；Spring AI值得关注，生态前景好。

七、写在最后

LangChain4j的出现，让Java开发者不再是大模型时代的”局外人”。它用Java的方式解决了Java的问题——统一API、封装复杂度、贴合生态。无论你是想在现有项目中引入AI能力，还是从零构建智能应用，LangChain4j都值得一试。

LangChain4j是什么