Spring Boot 集成

LangChain4j 为以下内容提供了 Spring Boot starters：

常用集成
声明式 AI 服务

Spring Boot Starters

Spring Boot starters 可通过配置属性帮助创建和配置语言模型、嵌入模型、嵌入存储以及其他核心 LangChain4j 组件。

要使用某个 Spring Boot starter，请导入对应的依赖。

Spring Boot starter 依赖的命名约定为：

langchain4j-{integration-name}-spring-boot-starter 用于 Spring Boot 3
langchain4j-{integration-name}-spring-boot4-starter 用于 Spring Boot 4

例如，对于 OpenAI（langchain4j-open-ai）：

Spring Boot 3：

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

Spring Boot 4：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot4-starter</artifactId>
    <version>1.18.1-beta28</version>
</dependency>

然后，你可以在 application.properties 文件中如下配置模型参数：

langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
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
...

在这种情况下，会自动创建 OpenAiChatModel 实例（ChatModel 的一种实现），你可以在需要的地方自动装配（autowire）它：

@RestController
public class ChatController {

    ChatModel chatModel;

    public ChatController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

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

如果你需要 StreamingChatModel 实例，请使用 streaming-chat-model 属性，而不是 chat-model：

langchain4j.open-ai.streaming-chat-model.api-key=${OPENAI_API_KEY}
...

声明式 AI 服务的 Spring Boot starter

LangChain4j 提供了一个 Spring Boot starter，用于自动配置 AI 服务、RAG、工具等。

假设你已经导入了某个集成 starter（见上文），再导入 langchain4j-spring-boot-starter（Spring Boot 3）或 langchain4j-spring-boot4-starter（Spring Boot 4）：

Spring Boot 3：

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

Spring Boot 4：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot4-starter</artifactId>
    <version>1.18.1-beta28</version>
</dependency>

现在你可以定义 AI 服务接口并用 @AiService 注解：

@AiService
interface Assistant {

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

可以把它理解为带有 AI 能力的标准 Spring Boot @Service。

应用启动时，LangChain4j starter 会扫描类路径，并找到所有标注了 @AiService 的接口。对于找到的每个 AI 服务，它会使用应用上下文中所有可用的 LangChain4j 组件创建该接口的实现，并将其注册为 bean，以便你可以在需要的地方自动装配：

@RestController
class AssistantController {

    @Autowired
    Assistant assistant;

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

自动组件装配

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

ChatModel
StreamingChatModel
ChatMemory
ChatMemoryProvider
ContentRetriever
RetrievalAugmentor
ToolProvider
任意 @Component 或 @Service 类中所有标注了 @Tool 的方法示例：

@Component
public class BookingTools {

    private final BookingService bookingService;

    public BookingTools(BookingService bookingService) {
        this.bookingService = bookingService;
    }

    @Tool
    public Booking getBookingDetails(String bookingNumber, String customerName, String customerSurname) {
        return bookingService.getBookingDetails(bookingNumber, customerName, customerSurname);
    }

    @Tool
    public void cancelBooking(String bookingNumber, String customerName, String customerSurname) {
        bookingService.cancelBooking(bookingNumber, customerName, customerSurname);
    }
}

备注

如果应用上下文中存在多个相同类型的组件，应用将无法启动。在这种情况下，请使用显式装配模式（见下文说明）。

显式组件装配

如果你有多个 AI 服务，并希望为每个服务装配不同的 LangChain4j 组件，可以使用显式装配模式（@AiService(wiringMode = EXPLICIT)）指定要使用的组件。

假设我们配置了两个 ChatModel：

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

# Ollama
langchain4j.ollama.chat-model.base-url=http://localhost:11434
langchain4j.ollama.chat-model.model-name=llama3.1

@AiService(wiringMode = EXPLICIT, chatModel = "openAiChatModel")
interface OpenAiAssistant {

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

@AiService(wiringMode = EXPLICIT, chatModel = "ollamaChatModel")
interface OllamaAssistant {

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

备注

在这种情况下，你必须显式指定所有组件。

更多细节见此处（Spring Boot 4 变体使用相同的 API）。

监听 AI 服务注册事件

以声明式方式完成 AI 服务开发后，你可以通过实现 ApplicationListener<AiServiceRegisteredEvent> 接口来监听 AiServiceRegisteredEvent。该事件在 AI 服务注册到 Spring 上下文时触发，使你可以在运行时获取所有已注册 AI 服务及其工具的信息。示例如下：

@Component
class AiServiceRegisteredEventListener implements ApplicationListener<AiServiceRegisteredEvent> {


    @Override
    public void onApplicationEvent(AiServiceRegisteredEvent event) {
        Class<?> aiServiceClass = event.aiServiceClass();
        List<ToolSpecification> toolSpecifications = event.toolSpecifications();
        for (int i = 0; i < toolSpecifications.size(); i++) {
            System.out.printf("[%s]: [Tool-%s]: %s%n", aiServiceClass.getSimpleName(), i + 1, toolSpecifications.get(i));
        }
    }
}

Flux

在流式场景中，你可以将 Flux<String> 用作 AI 服务的返回类型：

@AiService
interface Assistant {

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

为此，请导入 langchain4j-reactor 模块。更多细节见此处。

可观测性

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

@Configuration
class MyConfiguration {
    
    @Bean
    ChatModelListener chatModelListener() {
        return new ChatModelListener() {

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

            @Override
            public void onRequest(ChatModelRequestContext requestContext) {
                log.info("onRequest(): {}", requestContext.chatRequest());
            }

            @Override
            public void onResponse(ChatModelResponseContext responseContext) {
                log.info("onResponse(): {}", responseContext.chatResponse());
            }

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

应用上下文中的每个 ChatModelListener bean 都会自动注入到由我们任一 Spring Boot starter 创建的所有 ChatModel 和 StreamingChatModel bean 中。

Micrometer 指标

将 langchain4j-micrometer-metrics 依赖添加到项目中：

对于 Maven：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-micrometer-metrics</artifactId>
    <version>1.18.1-beta28</version>
</dependency>

对于 Gradle：

implementation 'dev.langchain4j:langchain4j-micrometer-metrics:1.18.1-beta28'

Micrometer（Actuator）配置

你还应在项目中加入必要的 Actuator 依赖。例如，如果使用 Spring Boot，可以向 pom.xml 添加以下依赖：

对于 Maven：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

对于 Gradle：

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

在属性中启用 /metrics Actuator 端点。

application.properties：

management.endpoints.web.exposure.include=metrics

application.yaml：

management:
  endpoints:
    web:
      exposure:
        include: metrics

配置 `MicrometerMetricsChatModelListener` bean

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

import dev.langchain4j.micrometer.metrics.listeners.MicrometerMetricsChatModelListener;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MetricsConfig {

    @Bean
    public MicrometerMetricsChatModelListener listener(MeterRegistry meterRegistry) {
        return new MicrometerMetricsChatModelListener(meterRegistry);
    }
}

查看指标

访问应用的 /actuator/metrics 端点即可查看指标。

例如，如果应用运行在 localhost:8080，可以访问 http://localhost:8080/actuator/metrics 查看指标。

Token 用量指标

在以下地址查看 token 用量指标：

http://localhost:8080/actuator/metrics/gen_ai.client.token.usage

按 Token 类型过滤

gen_ai.token.type 标签指示这些 token 用于输入还是输出：

Token 类型	端点
输入 token	`/actuator/metrics/gen_ai.client.token.usage?tag=gen_ai.token.type:input`
输出 token	`/actuator/metrics/gen_ai.client.token.usage?tag=gen_ai.token.type:output`

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

Micrometer Observation API

该实现使用 Micrometer Observation API 实现 ChatModelListener，通过添加以下依赖即可透明地生成指标与追踪：

对于 Maven：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-observation</artifactId>
</dependency>

对于 Gradle：

implementation 'dev.langchain4j:langchain4j-observation'

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

配置 ObservationChatModelListener bean

@Configuration
public class ObservationConfig {

    @Bean
    public ObservationChatModelListener listener(ObservationRegistry observationRegistry, MeterRegistry meterRegistry) {
        return new ObservationChatModelListener(observationRegistry, meterRegistry);
    }
}

该依赖需要按上文所述配置 SpringBoot Actuator。

关于 SpringBoot 应用的其他可观测性要求，请参阅： Building Your First Observed Application

关于 langchain4j-observation 库的更多细节，请查看可观测性文档。

测试

客户支持 Agent 的集成测试示例

支持的版本

LangChain4j Spring Boot 集成需要 Java 17，并同时支持：

Spring Boot 3（3.5+）— 使用带 -spring-boot-starter 后缀的 starter，符合 Spring Boot OSS 支持策略
Spring Boot 4（4.0+）— 使用带 -spring-boot4-starter 后缀的 starter

两个系列一并发布，并共享相同的版本号。请选择与项目中 Spring Boot 版本匹配的那一组 starter。

Spring Boot Starters​

声明式 AI 服务的 Spring Boot starter​

自动组件装配​

显式组件装配​

监听 AI 服务注册事件​

Flux​

可观测性​

Micrometer 指标​

Micrometer（Actuator）配置​

配置 MicrometerMetricsChatModelListener bean​

查看指标​

Token 用量指标​

按 Token 类型过滤​

Micrometer Observation API​

配置 ObservationChatModelListener bean​

测试​

支持的版本​

示例​

Spring Boot Starters

声明式 AI 服务的 Spring Boot starter

自动组件装配

显式组件装配

监听 AI 服务注册事件

Flux

可观测性

Micrometer 指标

Micrometer（Actuator）配置

配置 `MicrometerMetricsChatModelListener` bean

查看指标

Token 用量指标

按 Token 类型过滤

Micrometer Observation API

配置 ObservationChatModelListener bean

测试

支持的版本

示例