Spring Boot 統合
LangChain4j は、以下のための Spring Boot starters を提供しています:
- 人気のあるインテグレーション
- 宣言的 AI サービス
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 サービスに自動的に配線されます:
ChatModelStreamingChatModelChatMemoryChatMemoryProviderContentRetrieverRetrievalAugmentorToolProviderToolExecutionErrorHandlerと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)に解決されなければなりません。 モデル名はChatModelBean 自体で設定します(例: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やClientHttpConnectorBean は使用されません。代わりにClientHttpRequestFactoryBuilderCustomizerとClientHttpConnectorBuilderCustomizerBean でカスタマイズしてください。設定 は次のとおりです:- Spring Boot 4:
spring.http.clients.*(両方の種類のリクエストに適用) - Spring Boot 3:ブロッキングリクエストには
spring.http.client.*、ノンブロッキングリクエストにはspring.http.reactiveclient.*(Spring Boot 自身のクライアントと同じ)。リアクティブ Web アプリケーションでは、Spring Boot 3 はspring.http.client.*を適用しないため、ブロッキングリクエストはデフォルトを使用します。
- Spring Boot 4:
- 複数の 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とClientHttpConnectorBuilderBean を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 に
自動的に注入されます。