Spring Boot 集成 LangChain4j 实战指南

Spring Boot 集成 LangChain4j 实战指南 | 极客日志

Spring Boot 集成 LangChain4j 实战指南

1. 概述

LangChain4j 是一个用于构建基于大语言模型 (LLM) 的 Java 应用程序的开源框架。它提供了与 Spring Boot 的深度集成能力，使得开发者能够利用 Spring 生态系统的优势（如依赖注入、自动配置）来快速构建 AI 应用。

本文档将详细介绍如何在 Spring Boot 项目中无缝集成 LangChain4j，涵盖基础聊天模型配置、声明式 AI 服务开发、工具调用以及最佳实践。

2. 环境准备与依赖引入

2.1 版本要求

LangChain4j 的 Spring Boot 集成对运行环境有明确要求：

Java 版本：必须使用 Java 17 或更高版本。
Spring Boot 版本：建议升级到 Spring Boot 3.2 及以上，以享受最新的自动配置特性。

2.2 Maven 依赖配置

在 pom.xml 中，你需要引入相应的 Starter 依赖。LangChain4j 采用了模块化设计，不同的集成对应不同的 Starter。

2.2.1 核心依赖

首先引入核心的 Spring Boot Starter，它负责扫描和配置 AI 服务：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.34.0</version>
</dependency>

2.2.2 模型集成依赖

根据你选择的模型提供商，引入对应的集成包。例如，使用 OpenAI 模型：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
    <version>0.34.0</version>
</dependency>

如果是其他模型（如 Azure OpenAI、Ollama 等），请将 open-ai 替换为对应的集成名称（如 azure-open-ai, ollama 等）。

3. 配置文件设置

在 application.properties 或 application.yml 中配置模型参数。推荐使用环境变量来管理敏感信息（如 API Key），避免硬编码。

3.1 基础 Chat 模型配置

# 设置 OpenAI API Key，实际生产环境建议使用 ${OPENAI_API_KEY} 读取环境变量
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
# 指定使用的模型名称，例如 GPT-4o
langchain4j.open-ai.chat-model.model-name=gpt-4o
# 开启请求日志，便于调试
langchain4j.open-ai.chat-model.log-requests=true
# 开启响应日志
langchain4j.open-ai.chat-model.log-responses=true

3.2 流式输出配置

如果需要支持流式响应（Streaming），需额外配置 streaming-chat-model：

langchain4j.open-ai.streaming-chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.streaming-chat-model.model-name=gpt-4o

启动后，Spring Boot 会自动创建 OpenAiChatModel 实例（实现 ChatLanguageModel 接口）以及 StreamingChatLanguageModel 实例，并注册到 Spring 容器中。

4. 基础聊天功能实现

通过依赖注入，可以在任何 Spring Bean 中使用已配置的模型。

4.1 同步聊天示例

创建一个 REST Controller 来处理简单的文本生成请求：

import dev.langchain4j.model.chat.ChatLanguageModel;
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 {

    private final ChatLanguageModel chatLanguageModel;

    // 构造函数注入
    public ChatController(ChatLanguageModel chatLanguageModel) {
        this.chatLanguageModel = chatLanguageModel;
    }

    @GetMapping("/chat")
    public String model(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        // 直接调用模型生成回复
        return chatLanguageModel.generate(message);
    }
}

4.2 流式聊天示例

对于需要实时反馈的场景，可以使用流式模型。注意返回类型可能需要调整为 SseEmitter 或使用 WebFlux。

import dev.langchain4j.model.chat.StreamingChatLanguageModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StreamingChatController {

    private final StreamingChatLanguageModel streamingChatLanguageModel;

    public StreamingChatController(StreamingChatLanguageModel streamingChatLanguageModel) {
        this.streamingChatLanguageModel = streamingChatLanguageModel;
    }

    @GetMapping("/chat-stream")
    public void streamChat(@RequestParam String message) {
        // 此处应结合 SseEmitter 处理流式数据推送
        // streamingChatLanguageModel.generate(message, new TokenStream() { ... });
    }
}

5. 声明式 AI 服务 (@AiService)

LangChain4j 提供了强大的声明式编程能力，允许通过接口定义 AI 行为，类似于标准的 Spring @Service。

5.1 定义 AI 服务接口

使用 @AiService 注解标记接口，并使用提示词注解定义系统指令。

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

@AiService
interface Assistant {

    @SystemMessage("You are a polite and helpful assistant.")
    String chat(String userMessage);
}

5.2 使用 AI 服务

启动时，LangChain4j 会扫描类路径下所有带有 @AiService 的接口，并根据上下文中的组件（如 ChatModel、EmbeddingStore 等）自动生成实现类。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
class AssistantController {

    @Autowired
    private Assistant assistant;

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

5.3 高级提示词控制

除了 @SystemMessage，还可以使用 @UserMessage 动态注入上下文，或者使用 @MemoryId 管理会话状态。

@AiService
class AdvancedAssistant {

    @SystemMessage("You are an expert developer.")
    String answer(@UserMessage String question, @MemoryId Long memoryId);
}

6. 工具调用 (Tool Use)

为了让 AI 执行具体操作（如查询数据库、调用外部 API），可以注册自定义工具。

6.1 定义工具类

使用 @Component 和 @Tool 注解。

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

@Component
public class BookingTools {

    // 模拟业务服务
    private BookingService bookingService;

    @Tool("Cancels a booking based on the provided details")
    public String cancelBooking(String bookingNumber, String customerName, String customerSurname) {
        try {
            bookingService.cancelBooking(bookingNumber, customerName, customerSurname);
            return "Booking cancelled successfully.";
        } catch (Exception e) {
            return "Error cancelling booking: " + e.getMessage();
        }
    }
}

6.2 集成到 AI 服务

在 @AiService 接口中声明方法，LangChain4j 会自动识别并注入工具。

@AiService
interface SupportAgent {
    String chat(String userMessage);
}

当用户询问如何取消预订时，AI 会自动选择调用 cancelBooking 工具。

7. RAG (检索增强生成) 集成概览

虽然本文主要关注 Chat 模型，但 LangChain4j 也支持 RAG 模式，即结合私有知识库回答问题。

7.1 嵌入模型配置

需要引入 Embedding Model 的 Starter（如 langchain4j-embeddings-all-minilm-l6-v2）。

7.2 向量存储配置

配置一个向量存储（如 Redis, PostgreSQL, Elasticsearch）作为 EmbeddingStore。

7.3 构建 RAG 服务

使用 @RagResponseBuilder 或手动构建 RetrievalAugmentor 来实现知识检索。

8. 常见问题与最佳实践

8.1 安全性

API Key 管理：永远不要将 API Key 提交到代码仓库。务必使用环境变量或密钥管理服务（如 Vault）。
输入过滤：对用户输入进行校验，防止 Prompt Injection 攻击。

8.2 性能优化

缓存：对于重复的查询，考虑在应用层实现缓存机制。
超时设置：配置合理的 HTTP 超时时间，防止 LLM 响应过慢阻塞线程。

8.3 错误处理

异常捕获：LLM 调用可能因网络或服务端问题失败，建议在 Service 层添加 try-catch 块并提供友好的降级策略。
重试机制：对于偶发性错误，可配置指数退避重试策略。

9. 总结

通过 LangChain4j 的 Spring Boot Starter，开发者可以极大地简化 AI 应用的开发流程。从基础的对话机器人到复杂的 RAG 系统，Spring 的自动配置和依赖注入机制让 AI 组件的管理变得像普通 Bean 一样简单。建议在实际项目中遵循上述最佳实践，确保应用的安全性、稳定性和可扩展性。

Spring Boot 集成 LangChain4j 实战指南