跳至主要內容

Spring Boot 集成

LangChain4j 提供了 Spring Boot Starter，用于：

Spring Boot Starters

Spring Boot Starter 可以帮助你通过配置文件快速创建和配置语言模型、向量模型、向量存储，以及其他 LangChain4j 核心组件。

要使用 Spring Boot Starter，只需引入相应依赖。

依赖命名规范为：langchain4j-{integration-name}-spring-boot-starter。

例如，如果要使用 OpenAI（langchain4j-open-ai），依赖如下：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
    <version>1.3.0-beta9</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 的一个实现）会被自动创建，
你可以直接在需要的地方注入使用：

@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：

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

声明式 AI Services 的 Spring Boot Starter

LangChain4j 提供了一个 Spring Boot Starter，
用于自动配置 AI Services、RAG、Tools 等。

在引入了某个具体集成的 Starter（见上文）后，再额外引入：

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

你就可以定义一个 AI Service 接口，并用 @AiService 注解：

@AiService
interface Assistant {

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

它类似于一个标准的 Spring Boot @Service，但自带 AI 能力。

应用启动时，LangChain4j Starter 会扫描所有带 @AiService 的接口，
为每个接口生成实现类，并将其注册为 Spring Bean，
这样你就可以直接注入使用：

@RestController
class AssistantController {

    @Autowired
    Assistant assistant;

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

自动组件注入

如果上下文中存在以下组件，它们会被自动注入到 AI Service：

  • ChatModel
  • StreamingChatModel
  • ChatMemory
  • ChatMemoryProvider
  • ContentRetriever
  • RetrievalAugmentor
  • 所有 @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 Service，且需要为它们分别指定不同的组件，
可以通过 @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);
}

更多细节见 源码文档。

监听 AI Service 注册事件

在完成声明式 AI Service 开发后，可以通过实现
ApplicationListener<AiServiceRegisteredEvent> 来监听 AI Service 注册事件。

该事件会在 AI Service 注册到 Spring 容器时触发，
允许你在运行时获取已注册的 AI Service 及其工具信息：

@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

在流式响应场景下，可以将 AI Service 的返回类型声明为 Flux<String>：

@AiService
interface Assistant {

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

为此，请引入 langchain4j-reactor 模块。
更多细节见 这里。

可观测性（Observability）

若要为 ChatModel 或 StreamingChatModel 启用可观测性，
只需声明一个或多个 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 中。

测试

支持的版本

LangChain4j 的 Spring Boot 集成要求：

  • Java 17
  • Spring Boot 3.2

示例

最近更新