🚀 LangChain4j 与 Spring Boot集成指南

让大模型无缝融入你的 Spring Boot 应用！

---

📖 集成方式概览

LangChain4j 提供了两种集成方式，满足不同场景需求：

方式	适用场景	特点
ChatModel	简单对话、快速集成	直接调用，灵活可控
AI Service	复杂业务、需要提示词管理	声明式编程，更优雅

---

💻 方式一：ChatModel 集成

1️⃣ 创建项目模块

2️⃣ Maven 依赖

<project>
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>com.whc</groupId>

        <artifactId>langChain4j-whc</artifactId>

        <version>1.0-SNAPSHOT</version>

    </parent>

    <artifactId>langchain4j-whc-boot-integration</artifactId>

    <packaging>jar</packaging>

    <name>langchain4j-whc-boot-integration</name>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>

        <maven.compiler.target>17</maven.compiler.target>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    </properties>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

        <!-- ChatModel 方式所需 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>

            <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>

        </dependency>

        <!-- AI Service 方式所需 -->
        <dependency>
            <groupId>dev.langchain4j</groupId>

            <artifactId>langchain4j-spring-boot-starter</artifactId>

        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>

            <artifactId>lombok</artifactId>

        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>

                <artifactId>spring-boot-maven-plugin</artifactId>

            </plugin>

        </plugins>

    </build>

</project>

💡 关键点：

• langchain4j-open-ai-spring-boot-starter — 用于 ChatModel 方式
• langchain4j-spring-boot-starter — 用于 AI Service 方式
• 版本号由父 POM 中的 langchain4j-bom 统一管理

3️⃣ 配置文件

server:
  port: 9002

spring:
  application:
    name: langChain_whc_boot_integration

langchain4j:
  open-ai:
    chat-model:
      api-key: ${AI_DEEPSEEK_API_KEY}
      model-name: ${AI_DEEPSEEK_MODEL_NAME}
      base-url: ${AI_DEEPSEEK_BASE_URL}
      log-requests: true

📌 注意：这里使用的是 langchain4j 前缀（而非 ai），这是 Spring Boot集成方式的标准配置。

4️⃣ Controller 接口

@RestController
@RequiredArgsConstructor
public class ChatController {

    private final ChatModel chatModel;

    @GetMapping("popular/chat")
    public String model(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        return chatModel.chat(message);
    }
}

5️⃣ 测试效果

问题：佛山有哪些脱口秀的地方？

🎉 ChatModel 方式集成成功！代码简洁，调用直接。

---

🤖 方式二：AI Service 集成

AI Service 是更优雅的集成方式，通过声明式接口定义，让代码更具可读性。

1️⃣ 定义 Service 接口

@AiService
public interface Assistant {

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

💡 核心注解：

• @AiService — 标记为 AI 服务接口，LangChain4j 会自动生成实现
• @SystemMessage — 定义系统提示词，塑造 AI 的角色和行为

2️⃣ Controller 接口

@RestController
class AssistantController {

    @Resource
    Assistant assistant;

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

3️⃣ 测试效果

问题：打工牛马何以解忧

🔥 AI Service 方式让提示词管理和业务逻辑完全解耦，更适合复杂场景！

---

⚙️ 模型参数详解

LangChain4j 支持丰富的模型参数配置，满足不同业务需求：

/**
 * ChatModelProperties 类用于配置 OpenAI 聊天模型的各种参数
 */
public class ChatModelProperties {

    /** API 基础 URL 地址 */
    private String baseUrl;

    /** API 密钥 */
    private String apiKey;

    /** 模型名称，如 gpt-3.5-turbo、qwen-plus 等 */
    private String modelName;

    /** 采样温度，控制生成文本的随机性，范围 0-2 */
    private Double temperature;

    /** 核采样参数，控制生成文本的多样性 */
    private Double topP;

    /** 停止序列，当生成的文本包含这些字符串时停止 */
    private List<String> stop;

    /** 每次响应的最大标记数 */
    private Integer maxTokens;

    /** 存在惩罚，增加或减少重复主题的可能性 */
    private Double presencePenalty;

    /** 频率惩罚，减少重复词语的出现频率 */
    private Double frequencyPenalty;

    /** 随机种子，控制生成结果的可重现性 */
    private Integer seed;

    /** 是否记录请求日志 */
    private Boolean logRequests;

    /** 是否记录响应日志 */
    private Boolean logResponses;

    /** 请求超时时间 */
    private Duration timeout;

    /** 最大重试次数 */
    private Integer maxRetries;

    // ... 更多参数
}

📌 常用参数速查：

• temperature — 值越高越有创意（0-2），值越低越稳定
• maxTokens — 限制输出长度
• seed — 固定种子可复现结果
• logRequests/logResponses — 调试时开启，生产环境建议关闭

---

📝 添加输入输出日志

实际开发中，我们经常需要查看 AI 的输入输出，方便调试和优化提示词。

1️⃣ 修改接口 — 自定义 SystemMessage

@AiService
public interface Assistant {

    @SystemMessage("做个团结友爱的 Robot 吧!")
    String chat(String userMessage);
}

AssistantController 保持不变。

2️⃣ 开启日志配置

langchain4j:
  open-ai:
    chat-model:
      api-key: ${AI_DASHSCOPE_API_KEY}
      model-name: ${AI_DASHSCOPE_MODEL_NAME}
      base-url: ${AI_DASHSCOPE_BASE_URL}
      log-requests: true    # 开启请求日志
      log-responses: true   # 开启响应日志

3️⃣ 日志打印效果

可以看到 SystemMessage 注解内容已成功发送到模型：

🔍 日志中清晰展示了请求的完整结构，包括 System Message、User Message 和模型参数。

---

👂 ChatModel 监听器（Listener）

监听器是 LangChain4j 提供的可观测性机制，可以拦截请求、响应和异常，实现日志记录、监控、调试等功能。

📖 官方示例

ChatModelListener listener = new ChatModelListener() {

    @Override
    public void onRequest(ChatModelRequestContext requestContext) {
        ChatRequest chatRequest = requestContext.chatRequest();

        // 获取消息列表
        List<ChatMessage> messages = chatRequest.messages();
        System.out.println(messages);

        // 获取请求参数
        ChatRequestParameters parameters = chatRequest.parameters();
        System.out.println(parameters.modelName());
        System.out.println(parameters.temperature());
        System.out.println(parameters.topP());
        System.out.println(parameters.maxOutputTokens());

        // 存储自定义属性（可在 onResponse 中获取）
        Map<Object, Object> attributes = requestContext.attributes();
        attributes.put("my-attribute", "my-value");
    }

    @Override
    public void onResponse(ChatModelResponseContext responseContext) {
        ChatResponse chatResponse = responseContext.chatResponse();

        // 获取 AI 回复
        AiMessage aiMessage = chatResponse.aiMessage();
        System.out.println(aiMessage);

        // 获取响应元数据
        ChatResponseMetadata metadata = chatResponse.metadata();
        System.out.println(metadata.id());
        System.out.println(metadata.modelName());
        System.out.println(metadata.finishReason());

        // 获取 Token 用量
        TokenUsage tokenUsage = metadata.tokenUsage();
        System.out.println(tokenUsage.inputTokenCount());
        System.out.println(tokenUsage.outputTokenCount());
        System.out.println(tokenUsage.totalTokenCount());

        // 获取之前存储的自定义属性
        Map<Object, Object> attributes = responseContext.attributes();
        System.out.println(attributes.get("my-attribute"));
    }

    @Override
    public void onError(ChatModelErrorContext errorContext) {
        Throwable error = errorContext.error();
        error.printStackTrace();

        ChatRequest chatRequest = errorContext.chatRequest();
        System.out.println(chatRequest);
    }
};

// 注册监听器
ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(GPT_4_O_MINI)
        .listeners(List.of(listener))
        .build();

model.chat("Tell me a joke about Java");

💡 监听器的三个核心方法：

• onRequest — 请求发出前，可获取请求参数、存储上下文
• onResponse — 响应返回后，可获取回复内容、Token 用量
• onError — 发生异常时，可记录错误信息

🔧 Spring Boot集成方式

在 Spring Boot 中，只需声明一个 ChatModelListener Bean，会自动注入到所有 ChatModel 中：

@Configuration
public class SimpleChatModelListener {

    @Bean
    public ChatModelListener myChatModelListener() {
        return new ChatModelListener() {

            private static final Logger log = LoggerFactory.getLogger(ChatModelListener.class);

            @Override
            public void onRequest(ChatModelRequestContext requestContext) {
                // 存储自定义属性（谜语）
                requestContext.attributes().put("garlic", "弟兄七八个，围着柱子坐，大家一分手，衣服都扯破");
                requestContext.attributes().put("umbrella", "独木造高楼，没瓦没砖头，人在水下走，水在人上流");
                requestContext.attributes().put("sun", "画时圆，写时方，冬时短，夏时长");
                
                log.info("onRequest(): {}", requestContext.chatRequest());
            }

            @Override
            public void onResponse(ChatModelResponseContext responseContext) {
                // 获取之前存储的属性
                log.info(responseContext.attributes().get("garlic").toString());
                log.info("onResponse(): {}", responseContext.chatResponse());
            }

            @Override
            public void onError(ChatModelErrorContext errorContext) {
                log.info("onError(): {}", errorContext.error().getMessage());
            }
        };
    }
}

🧪 测试效果

请求时打印：

返回时打印：

🎯 可以看到：

• 请求日志中包含了完整的 ChatRequest 信息
• 响应日志中成功获取了之前存储的自定义属性（大蒜谜语）
• 监听器实现了请求和响应之间的上下文传递

---

📝 总结

✅	内容
1	掌握 ChatModel 集成方式
2	掌握 AI Service 集成方式
3	了解模型参数配置
4	实现输入输出日志
5	使用 ChatModelListener 实现可观测性

🚀 LangChain4j + Spring Boot 的组合，让 Java 开发者能以最优雅的方式集成大模型能力！

LangChain4j简述与示例
LangChain4j 与 Spring Boot集成指南
LangChain4j 流式模式实战指南