跳到主要内容

Spring Boot 統合

LangChain4j は、以下のための Spring Boot starters を提供しています:

Spring Boot Starters​

Spring Boot starters は、プロパティを通じて 言語モデル、 埋め込みモデル、 埋め込みストア、 およびその他の LangChain4j のコアコンポーネントを作成・設定するのに役立ちます。

Spring Boot starters のいずれかを使用するには、 対応する依存関係をインポートします。

Spring Boot starter 依存関係の命名規則は次のとおりです:

  • Spring Boot 4 の場合:langchain4j-{integration-name}-spring-boot4-starter
  • Spring Boot 3 の場合:langchain4j-{integration-name}-spring-boot-starter

たとえば、OpenAI(langchain4j-open-ai)の場合:

Spring Boot 4:

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

Spring Boot 3:

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
<version>1.23.0-beta33</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 のインスタンスが必要な場合は、 chat-model の代わりに streaming-chat-model プロパティを使用します:

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

宣言的 AI サービスの Spring Boot starter​

LangChain4j は、 AI サービス、RAG、ツール などを自動設定する Spring Boot starter を提供しています。

インテグレーション starter のいずれかをすでにインポートしていると仮定して(上記参照)、 langchain4j-spring-boot4-starter(Spring Boot 4)または langchain4j-spring-boot-starter(Spring Boot 3)をインポートします:

Spring Boot 4:

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot4-starter</artifactId>
<version>1.23.0-beta33</version>
</dependency>

Spring Boot 3:

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot-starter</artifactId>
<version>1.23.0-beta33</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
  • ToolExecutionErrorHandler と ToolArgumentsErrorHandler(エラー処理を参照)
  • @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))を使用して、使用するコンポーネントを指定できます。

2 つの 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);
}
备注

この場合、すべてのコンポーネントを明示的に指定する必要があります。

設定によるコンポーネントの選択​

Bean 名をハードコードする代わりに、プロパティプレースホルダーを使用できます。 これにより、AI サービスに配線されるコンポーネントを設定で変更できます(たとえば環境やプロファイルごと):

my-app.assistant.chat-model-bean=ollamaChatModel
my-app.assistant.tool-beans=weatherTools,calendarTools
@AiService(
wiringMode = EXPLICIT,
chatModel = "${my-app.assistant.chat-model-bean:openAiChatModel}",
tools = "${my-app.assistant.tool-beans}"
)
interface Assistant {

String chat(String userMessage);
}

注意点がいくつかあります:

  • プレースホルダーは、LLM モデルの名前(例:llama3.1)ではなく、Bean 名(例:ollamaChatModel)に解決されなければなりません。 モデル名は ChatModel Bean 自体で設定します(例:langchain4j.ollama.chat-model.model-name)。
  • デフォルト値はコロンの後に指定できます:${my-app.assistant.chat-model-bean:openAiChatModel}。
  • プレースホルダーが解決できず、デフォルト値もない場合、アプリケーションは起動に失敗します。
  • プレースホルダーが空の値に解決された場合、その属性は設定されていないものとして扱われます。
  • tools の場合、プレースホルダーはカンマ区切りの複数の Bean 名に解決できます。

詳細はこちらをご覧ください (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​

ストリーミング時には、AI サービスの戻り値の型として Flux<String> を使用できます:

@AiService
interface Assistant {

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

このためには、langchain4j-reactor モジュールをインポートしてください。 詳細はこちらをご覧ください。

このモジュールは、ノンブロッキングモード向けの Mono<T> と Flux<AiServiceStreamingEvent> も提供します。 また、starter は langchain4j.executor.use-spring-task-executor=true を指定することで、LangChain4j がオフロードする処理を Spring 自身のタスクエグゼキューター経由で実行でき、トレーシング、MDC、 セキュリティコンテキストが非同期呼び出しにも引き継がれます。

OpenAI、Mistral AI、Ollama の starter は、Spring の HTTP クライアントを使ってリクエストを送信します。ブロッキング 呼び出しには RestClient、ノンブロッキングモードには WebClient を使用します。そのため、これらの starter のいずれかでノンブロッキングモードを使用し、 かつそれをサポートするプロバイダーを使用する場合(プロバイダーのサポートを参照)、クラスパスに WebClient が 必要です。Flux<String> と TokenStream には不要です。

  • Spring Boot 4: spring-boot-starter-webclient を追加します。
  • Spring Boot 3: org.springframework:spring-webflux を追加します。アプリケーションが Web アプリケーションでない場合( spring-boot-starter-web がない場合)は、spring.main.web-application-type=none も設定してください。Spring Boot は、 クラスパスに spring-webflux があるアプリケーションをリアクティブ Web アプリケーションとして扱うためです。

アプリケーションが WebFlux アプリケーションでない限り、この目的で spring-boot-starter-webflux を使用するのは避けてください。Web サーバーも 持ち込んでしまいます。WebClient がない場合、ノンブロッキング呼び出しは、何を追加すべきかを示す AsyncNotSupportedException で失敗します。 これらのリクエストの設定方法については、HTTP クライアントを参照してください。

HTTP クライアント​

OpenAI、Mistral AI、Ollama の starter は、Spring Boot が自身のクライアントを設定するのと同じ方法で設定された Spring の HTTP クライアントを使ってリクエストを送信します。 その他の starter は独自の HTTP クライアントを使用するため、このセクションは該当しません。 たとえば OpenAiChatModel.builder() で自分で構築したモデルは、この方法では設定されません。 カスタマイズ可能な HTTP クライアントに示されているように、HTTP クライアントビルダーを渡してください。

  • ビルダー: ブロッキングリクエストはアプリケーションの RestClient.Builder から、ノンブロッキングリクエストは その WebClient.Builder から構築されます。そのため、各ビルダーに設定されたフィルター、デフォルトヘッダー、オブザーバビリティが適用され、 自分のサービス用の認証情報を追加するフィルターは、モデルプロバイダーへのリクエストでも実行されます。2 つのビルダー は別々に設定されます。一方のカスタマイズは他方には適用されません。アプリケーションのビルダーが @LoadBalanced(Spring Cloud)の場合は、通常の @Primary ビルダーも宣言するか、以下に示すようにモデルの HTTP クライアント ビルダー Bean を宣言してください。ロードバランスされたビルダーは、モデルプロバイダーのホスト名をサービス名として解決してしまいます。
  • HTTP クライアントと設定: リクエストは、Spring Boot が使用するよう設定されている HTTP クライアントで送信されます。 そのカスタマイザー(たとえばプロキシ)も含まれ、リダイレクトや SSL バンドルなどの Spring Boot の HTTP クライアント設定も適用されます。 LangChain4j はタイムアウトを適用するためにリクエストファクトリーとコネクターを自身で構築するため、アプリケーションの ClientHttpRequestFactory や ClientHttpConnector Bean は使用されません。代わりに ClientHttpRequestFactoryBuilderCustomizer と ClientHttpConnectorBuilderCustomizer Bean でカスタマイズしてください。設定 は次のとおりです:
    • Spring Boot 4:spring.http.clients.*(両方の種類のリクエストに適用)
    • Spring Boot 3:ブロッキングリクエストには spring.http.client.*、ノンブロッキングリクエストには spring.http.reactiveclient.* (Spring Boot 自身のクライアントと同じ)。リアクティブ Web アプリケーションでは、Spring Boot 3 は spring.http.client.* を適用しないため、ブロッキングリクエストはデフォルトを使用します。
  • 複数の Bean: アプリケーションにこれらの型の Bean が複数あり(ビルダー、Spring Boot の HTTP クライアントビルダーとその設定)、そのいずれも @Primary でない場合、LangChain4j はそのいずれも使用しません。代わりに新しい ビルダーまたはデフォルトを使用し、警告をログに記録します。
  • タイムアウトは常に LangChain4j から取得されます(例:langchain4j.open-ai.chat-model.timeout)。 設定されていない場合、接続タイムアウトは 15 秒、読み取りタイムアウトは 60 秒です。推論モデルや 初回使用時にロードされるローカルモデルなど、低速なモデルでは引き上げてください。Spring Boot の connect-timeout と read-timeout は、 これらのリクエストには影響しません。

したがって、Spring Boot で設定した SSL バンドルはモデルプロバイダーの証明書も信頼する必要があり、その中のクライアント 証明書もモデルプロバイダーに提示されます。別の設定でモデルのリクエストを送信するには、 その HTTP クライアントビルダー Bean を自分で宣言します。その名前は、モデル Bean の名前に HttpClientBuilder を付けたものです。 たとえば openAiChatModelHttpClientBuilder や ollamaEmbeddingModelHttpClientBuilder です。Spring Boot 4 の場合:

import dev.langchain4j.http.client.HttpClientBuilder;
import dev.langchain4j.http.client.spring.restclient.SpringRestClient;
import org.springframework.boot.http.client.HttpClientSettings;
import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestClient;

@Bean
HttpClientBuilder openAiChatModelHttpClientBuilder() {
return SpringRestClient.builder()
.restClientBuilder(RestClient.builder())
// no SSL bundle, so the JVM's default trust store is used; the same as not setting it.
// To use another SSL bundle: HttpClientSettings.ofSslBundle(sslBundles.getBundle("..."))
.httpClientSettings(HttpClientSettings.defaults())
.createDefaultStreamingRequestExecutor(false); // a chat model does not stream
}

Spring Boot 3 では、ブロッキングリクエストとノンブロッキングリクエストの設定は別々に設定します:

import dev.langchain4j.http.client.HttpClientBuilder;
import dev.langchain4j.http.client.spring.restclient.SpringRestClient;
import org.springframework.boot.http.client.ClientHttpRequestFactorySettings;
import org.springframework.boot.http.client.reactive.ClientHttpConnectorSettings;
import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestClient;

@Bean
HttpClientBuilder openAiChatModelHttpClientBuilder() {
return SpringRestClient.builder()
.restClientBuilder(RestClient.builder())
.clientHttpRequestFactorySettings(ClientHttpRequestFactorySettings.defaults())
.clientHttpConnectorSettings(ClientHttpConnectorSettings.defaults())
.createDefaultStreamingRequestExecutor(false);
}

このような Bean は、設定だけでなく、starter がそのモデルの HTTP クライアントに対して構成するすべてを置き換えます。 それ以外を維持するには、自分で渡してください:

  • アプリケーションの RestClient.Builder を restClientBuilder(...) で渡します。例では新しいものを渡しており、 アプリケーションのフィルターやインターセプターがモデルプロバイダーへのリクエストに適用されないようにしています。
  • ノンブロッキングリクエスト用に、アプリケーションの WebClient.Builder を webClientBuilder(WebClientBuilderHolder.of(webClientBuilder)) で渡します。渡さない場合は、新しい WebClient.builder() が使用されます。
  • Spring Boot が選択した HTTP クライアントとそのカスタマイザー:ClientHttpRequestFactoryBuilder と ClientHttpConnectorBuilder Bean を clientHttpRequestFactoryBuilder(...) と clientHttpConnectorBuilder(...) に渡します。
  • ストリーミングモデルの場合、ストリームを読み取るスレッドにコンテキスト(たとえばトレーシング、MDC、セキュリティ)を引き継ぐタスクエグゼキューターを streamingRequestExecutor(...) で渡します。starter はこれを、 モデル Bean の名前に TaskExecutor を付けた名前の Bean として宣言します。たとえば openAiStreamingChatModelTaskExecutor です。

LangChain4j に専用の WebClient.Builder を与えるには、WebClientBuilderHolder Bean を宣言します:

import dev.langchain4j.http.client.spring.restclient.WebClientBuilderHolder;
import org.springframework.context.annotation.Bean;
import org.springframework.web.reactive.function.client.WebClient;

@Bean
WebClientBuilderHolder langchain4jWebClientBuilder() {
return WebClientBuilderHolder.of(WebClient.builder());
}

オブザーバビリティ​

ChatModel または StreamingChatModel Bean のオブザーバビリティを有効にするには、1 つ以上の 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.23.0-beta33</version>
</dependency>

Gradle の場合:

implementation 'dev.langchain4j:langchain4j-micrometer-metrics:1.23.0-beta33'

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 にアクセスしてメトリクスを表示できます。

トークン使用量メトリクス​

トークン使用量メトリクスは次の場所で表示できます:

http://localhost:8080/actuator/metrics/gen_ai.client.token.usage
トークンタイプによるフィルタリング​

gen_ai.token.type タグは、トークンが入力用か出力用かを示します:

トークンタイプエンドポイント
入力トークン/actuator/metrics/gen_ai.client.token.usage?tag=gen_ai.token.type:input
出力トークン/actuator/metrics/gen_ai.client.token.usage?tag=gen_ai.token.type:output

注意:gen_ai.client.token.usage メトリクスはヒストグラム(DistributionSummary)です。タグなしのエンドポイントでは、すべてのトークンタイプ、モデル、プロバイダーにわたる集計統計(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 ライブラリの詳細については、オブザーバビリティのドキュメントを参照してください。

テスト​

サポートされているバージョン​

LangChain4j Spring Boot 統合には Java 17 が必要で、次の両方をサポートしています:

  • Spring Boot 4(4.0+)— -spring-boot4-starter サフィックスの付いた starter を使用します
  • Spring Boot 3(3.5+)— -spring-boot-starter サフィックスの付いた starter を使用します。これは Spring Boot OSS サポートポリシーに沿ったものです

両方のファミリーは同時にリリースされ、同じバージョン番号を共有します。プロジェクトの Spring Boot バージョンに合った starter のセットを選択してください。

例​