0%

langchain4j SpringBoot集成

Posted on In

LangChain4j 提供了对 Spring Boot 的一流集成支持，让你能够以声明式的方式在 Spring Boot 应用中快速使用 AI 服务。只需添加对应的 starter 依赖，即可自动配置 ChatModel、StreamingChatModel 等核心组件，并通过 @AiService 注解轻松定义具备 AI 能力的服务接口。

要求：LangChain4j Spring Boot 集成需要 Java 17 及以上版本，同时支持 Spring Boot 3 和 Spring Boot 4 两大系列。两个系列同步发布，共享相同的版本号。请根据你项目中使用的 Spring Boot 版本选择对应的 starter 组合。

添加 Starter 依赖

Spring Boot starter 依赖的命名规范为：

1
2
langchain4j-{集成名称}-spring-boot-starter   (Spring Boot 3)
langchain4j-{集成名称}-spring-boot4-starter  (Spring Boot 4)

Spring Boot 3

Maven (pom.xml)：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Gradle (build.gradle)：

1
implementation 'dev.langchain4j:langchain4j-open-ai-spring-boot-starter:${langchain4j.version}'

Spring Boot 4

Maven (pom.xml)：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot4-starter</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Gradle (build.gradle)：

1
implementation 'dev.langchain4j:langchain4j-open-ai-spring-boot4-starter:${langchain4j.version}'

配置模型参数

使用ChatModel

在 application.properties 文件中配置模型参数：

1
2
3
4
5
6
# OpenAI Chat Model 配置
langchain4j.open-ai.chat-model.base-url=https://api.deepseek.com
langchain4j.open-ai.chat-model.api-key=your-api-key-here
langchain4j.open-ai.chat-model.model-name=deepseek-v4-pro
langchain4j.open-ai.chat-model.temperature=0.7
langchain4j.open-ai.chat-model.max-tokens=2048

配置完成后，OpenAiChatModel（ChatModel 的一个实现）的实例将被自动创建，你可以在需要的地方直接通过 @Autowired 注入使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import dev.langchain4j.model.chat.ChatModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class MyChatComponent {

    @Autowired
    private ChatModel chatModel;

    public String chat(String userMessage) {
        return chatModel.chat(userMessage);
    }
}

使用 StreamingChatModel

如果你需要流式响应，可以使用 streaming-chat-model 相关属性代替 chat-model：

1
2
3
langchain4j.open-ai.streaming-chat-model.base-url=https://api.deepseek.com
langchain4j.open-ai.streaming-chat-model.api-key=your-api-key-here
langchain4j.open-ai.streaming-chat-model.model-name=deepseek-v4-pro

然后通过 @Autowired 注入 StreamingChatModel：

1
2
3
4
5
6
7
8
9
import dev.langchain4j.model.chat.StreamingChatModel;
import org.springframework.beans.factory.annotation.Autowired;

@Component
public class MyStreamingComponent {

    @Autowired
    private StreamingChatModel streamingChatModel;
}

AI Service 声明式定义

添加核心 Starter

在已导入某个集成 starter（如 OpenAI starter）的基础上，还需导入 LangChain4j Spring Boot 核心 starter：

Spring Boot 3：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Spring Boot 4：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot4-starter</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

定义 AI Service 接口

使用 @AiService 注解来定义 AI Service 接口：

1
2
3
4
5
6
7
8
9
import dev.langchain4j.service.AiService;
import dev.langchain4j.service.UserMessage;

@AiService
public interface Assistant {

    @UserMessage("请用简洁的语言回答以下问题：{{it}}")
    String chat(String userMessage);
}

你可以将其理解为一个标准的 Spring Boot @Service，但具备了 AI 能力。

当应用启动时，LangChain4j starter 会扫描 classpath 中所有被 @AiService 注解标记的接口，并为每个 AI Service 自动生成实现类，使用应用上下文中所有可用的 LangChain4j 组件进行装配，然后注册为 Spring Bean，供你在需要的地方通过 @Autowired 注入使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    @Autowired
    private Assistant assistant;

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

自动装配的组件

如果应用上下文中存在以下组件，它们将被自动装配到 AI Service 中：

组件 说明
ChatModel 聊天模型（必选）
ChatMemory 聊天记忆，用于多轮对话
ToolProvider 工具提供者，用于函数调用
RetrievalAugmentor 检索增强生成（RAG）组件
ContentRetriever 内容检索器
ModerationModel 内容审核模型

⚠️ 注意：如果应用上下文中存在多个同类型的组件，应用将启动失败。此时需要使用显式装配模式（见下文）。

显式装配模式

如果你有多个 AI Service，并且希望为每个 AI Service 装配不同的 LangChain4j 组件，可以通过显式装配模式来指定：

1
2
3
4
@AiService(wiringMode = EXPLICIT, chatModel = "myChatModel", chatMemory = "myChatMemory")
public interface Assistant {
    String chat(String message);
}

假设你配置了两个 ChatModel Bean：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@Configuration
public class ModelConfig {

    @Bean
    @Primary
    public ChatModel openAiChatModel() {
        return OpenAiChatModel.builder()
                .baseUrl("https://api.openai.com/v1")
                .apiKey("sk-...")
                .modelName("gpt-4o")
                .build();
    }

    @Bean
    public ChatModel anotherChatModel() {
        return OpenAiChatModel.builder()
                .baseUrl("https://api.openai.com/v1")
                .apiKey("sk-...")
                .modelName("gpt-4o-mini")
                .build();
    }
}

在这种情况下，你必须通过 @AiService(wiringMode = EXPLICIT) 显式指定所有组件。更多细节可参考官方文档（Spring Boot 4 变体使用相同的 API）。

监听 AI Service 注册事件

当你以声明式方式完成 AI Service 的开发后，可以通过实现 ApplicationListener 接口来监听 AiServiceRegisteredEvent 事件。该事件在 AI Service 被注册到 Spring 上下文时触发，允许你在运行时获取所有已注册 AI Service 及其工具的信息。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
import dev.langchain4j.spring.AiServiceRegisteredEvent;
import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Component;

@Component
public class AiServiceEventListener implements ApplicationListener<AiServiceRegisteredEvent> {

    @Override
    public void onApplicationEvent(AiServiceRegisteredEvent event) {
        System.out.println("AI Service 已注册: " + event.getAiServiceClass().getName());
        System.out.println("工具数量: " + event.getToolSpecifications().size());
    }
}

流式响应

在使用流式响应时，可以将 AI Service 方法的返回类型定义为 Flux：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import dev.langchain4j.service.AiService;
import dev.langchain4j.service.UserMessage;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@AiService
public interface StreamingAssistant {

    @UserMessage("请详细介绍一下{{it}}")
    Flux<String> streamChat(String topic);
}

@RestController
public class StreamingController {

    @Autowired
    private StreamingAssistant streamingAssistant;

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(String topic) {
        return streamingAssistant.streamChat(topic);
    }
}

为此，请导入 langchain4j-reactor 模块：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-reactor</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

更多细节请参考官方文档。

可观测性（Observability）

ChatModelListener

要为 ChatModel 或 StreamingChatModel Bean 启用可观测性，你需要声明一个或多个 ChatModelListener Bean：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import dev.langchain4j.service.ChatModelListener;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ObservabilityConfig {

    @Bean
    public ChatModelListener myChatModelListener() {
        return new ChatModelListener() {
            @Override
            public void onRequest(ChatModelRequest request) {
                System.out.println("请求发送: " + request.messages());
            }

            @Override
            public void onResponse(ChatModelResponse response) {
                System.out.println("收到响应: " + response.response());
            }

            @Override
            public void onError(Throwable error) {
                System.err.println("发生错误: " + error.getMessage());
            }
        };
    }
}

应用上下文中所有的 ChatModelListener Bean 都会被自动注入到由 Spring Boot starter 创建的所有 ChatModel 和 StreamingChatModel Bean 中。

Micrometer Metrics 指标

添加依赖

Maven：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-micrometer-metrics</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Gradle：

1
implementation 'dev.langchain4j:langchain4j-micrometer-metrics:${langchain4j.version}'

添加 Actuator 依赖

你的项目中还需要包含必要的 Actuator 依赖。以 Spring Boot 为例：

Maven：

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle：

1
implementation 'org.springframework.boot:spring-boot-starter-actuator'

启用 /metrics 端点

在 application.properties 中：

1
management.endpoints.web.exposure.include=metrics

或在 application.yaml 中：

1
2
3
4
5
management:
  endpoints:
    web:
      exposure:
        include: metrics

注册指标监听器

在 Spring Boot 应用中，你可以将监听器定义为 Bean 并注入 MeterRegistry：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import dev.langchain4j.service.ChatModelListener;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MetricsConfig {

    @Bean
    public ChatModelListener metricsListener(MeterRegistry meterRegistry) {
        return new ChatModelListener() {
            @Override
            public void onResponse(ChatModelResponse response) {
                meterRegistry.counter("langchain4j.requests.total").increment();
                // 记录 token 使用量等指标
            }

            @Override
            public void onError(Throwable error) {
                meterRegistry.counter("langchain4j.requests.errors").increment();
            }
        };
    }
}

查看指标

启动应用后，可以通过访问应用的 /actuator/metrics 端点来查看指标：

1
GET /actuator/metrics

查看 Token 使用指标：

1
GET /actuator/metrics/gen_ai.client.token.usage

gen_ai.token.type 标签用于区分 Token 是用于输入（input）还是输出（output）：

标签值 说明
input 输入 Token（提示词）
output 输出 Token（模型生成内容）

注意：gen_ai.client.token.usage 指标是一个直方图（DistributionSummary）。不带任何标签访问该端点时，会显示所有 Token 类型、模型和提供商的聚合统计信息（count、total、max）。

Micrometer Observation API（指标 + 链路追踪）

通过 Micrometer Observation API 实现 ChatModelListener，可以添加以下依赖来透明地生成指标和链路追踪：

Maven：

1
2
3
4
5
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-micrometer-observation</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Gradle：

1
implementation 'dev.langchain4j:langchain4j-micrometer-observation:${langchain4j.version}'

你需要按如下方式实例化 Observation 监听器：

1
2
3
4
5
6
7
8
9
10
11
12
13
import dev.langchain4j.observation.ChatModelObservationListener;
import io.micrometer.observation.ObservationRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ObservationConfig {

    @Bean
    public ChatModelObservationListener observationListener(ObservationRegistry observationRegistry) {
        return new ChatModelObservationListener(observationRegistry);
    }
}

关于 Spring Boot 应用中更多可观测性的需求，请参考：Building Your First Observed Application。

日志能力

1
2
3
4
...
langchain4j.open-ai.chat-model.log-requests = true
langchain4j.open-ai.chat-model.log-responses = true
logging.level.dev.langchain4j = DEBUG

总结

功能 说明
Starter 依赖 按命名规范引入对应集成的 Spring Boot starter
自动配置 通过 application.properties 配置模型参数，自动创建 ChatModel / StreamingChatModel Bean
@AiService 声明式定义 AI 服务接口，自动生成实现并注册为 Spring Bean
自动装配 自动注入 ChatModel、ChatMemory、ToolProvider、RetrievalAugmentor 等组件
显式装配 多 Bean 场景下通过 wiringMode = EXPLICIT 精确控制组件装配
事件监听 通过 AiServiceRegisteredEvent 在运行时获取注册信息
流式响应 配合 langchain4j-reactor 模块，支持 Flux 返回类型
可观测性 支持 ChatModelListener、Micrometer Metrics 和 Micrometer Observation（指标 + 链路追踪）