LangChain4j 入门指南：环境搭建与基础概念

学习时间：2026/3/27
技术栈：Spring Boot 4.0.5 + LangChain4j 1.12.2 + 通义千问模型

一、LangChain4j 是什么？

LangChain4j 是 Java/Kotlin 版本的 LangChain，是一个专注于 AI 应用开发的框架。它帮助开发者快速构建基于大语言模型（LLM）的应用，提供了：

• 统一的 API：屏蔽不同模型提供商的差异
• 丰富的组件：对话记忆、工具调用、RAG、Agent 等
• 简洁的用法：声明式设计，易于使用

二、项目初始化

2.1 创建 Spring Boot 项目

使用 Spring Initializr 或 IDE 创建 Spring Boot 4.x 项目。

2.2 Maven 依赖配置

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <properties>
        <java.version>21</java.version>
        <langchain4j.version>1.12.2</langchain4j.version>
        <langchain4j.community.version>1.12.2-beta22</langchain4j.community.version>
    </properties>

    <dependencies>
        <!-- 阿里百炼 Starter -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-community-dashscope-spring-boot-starter</artifactId>
        </dependency>

        <!-- LangChain4j 核心库 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j</artifactId>
            <version>${langchain4j.version}</version>
        </dependency>

        <!-- Spring Boot Web 支持 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
    </dependencies>
</project>

关键点：

• langchain4j-community-dashscope-spring-boot-starter：阿里云通义千问模型的集成包
• langchain4j：核心框架，提供 AI 服务抽象
• 同时引入 WebFlux 和 WebMvc，支持响应式流式输出

2.3 配置文件

# application.yaml
langchain4j:
  community:
    dashscope:
      chat-model: # 普通对话模型配置
        api-key: ${ALI_AI}  # 阿里云 DashScope API Key
        model-name: qwen-max # 模型名称
      streaming-chat-model: # 流式对话模型
        api-key: ${ALI_AI}
        model-name: qwq-32b

学习要点：

1. 双模型配置：
   • chat-model：普通对话模型（qwen-max）
   • streaming-chat-model：流式对话模型（qwq-32b）
2. 环境变量管理密钥：使用 ${ALI_AI} 避免硬编码

注册阿里云百炼 API Key

三、基础对话功能

3.1 普通对话

@RestController
@RequestMapping("/ai")
public class ChatController {
		
	// 相关Bean在配置langchain4j.community.dashscope.chat-model.api-key后自动注册
	// 见 dev.langchain4j.community.dashscope.spring.DashScopeAutoConfiguration
    private final QwenChatModel qwenChatModel;

    public ChatController(QwenChatModel qwenChatModel) {
        this.qwenChatModel = qwenChatModel;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return qwenChatModel.chat(message);
    }
}

3.2 流式对话

@GetMapping(value = "/streaming-chat", produces = "text/stream;charset=UTF-8")
public Flux<String> streamingChat(@RequestParam String message) {
    return Flux.create(sink ->
        // qwenStreamingChatModel Bean注册同前文qwenChatModel 
        // 配置langchain4j.community.dashscope.streaming-chat-model.api-key即可自动注册
        qwenStreamingChatModel.chat(message, new StreamingChatResponseHandler() {
            @Override
            public void onPartialResponse(String partialResponse) {
                sink.next(partialResponse);  // 逐token推送
            }
            
            @Override
            public void onCompleteResponse(ChatResponse completeResponse) {
                sink.complete();  // 完成响应
            }
            
            @Override
            public void onError(Throwable error) {
                sink.error(error);
            }
        }));
}

关键技术点：

1. 响应式编程：使用 Reactor 的 Flux 实现流式输出
2. 回调处理：StreamingChatResponseHandler 三个关键方法
   • onPartialResponse()：接收部分响应
   • onCompleteResponse()：响应完成
   • onError()：错误处理
3. 字符集设置：produces = "text/stream;charset=UTF-8" 防止中文乱码

四、总结

本文介绍了 LangChain4j 的基本概念和入门使用：

• LangChain4j 是 Java 生态的 AI 应用开发框架
• 提供同步和流式两种对话方式
• Spring Boot 集成简单，配置方便