カスタマイズ可能なHTTPクライアント
OpenAI、Ollama、MCP Streamable HTTP トランスポートなど、一部の LangChain4j モジュールでは、リモート API の呼び出しに使う HTTP クライアントをカスタマイズできます。
langchain4j-http-client モジュールは、これらのモジュールがリモート API を呼び出すための HttpClient SPI を実装します。
つまり、基盤となるHTTPクライアントをカ スタマイズでき、
HttpClient SPIを実装することで他の任意のHTTPクライアントも統合できます。
現在、次の組み込み実装があります:
langchain4j-http-client-jdkモジュールのJdkHttpClient。 サポート対象のモジュール(例:langchain4j-open-ai)でほかの実装を使用しない場合のフォールバックです。langchain4j-http-client-spring-boot4-restclient/langchain4j-http-client-spring-restclientモジュールのSpringRestClient。 サポートされているモジュールのSpring Bootスターター(例:langchain4j-open-ai-spring-boot4-starter/langchain4j-open-ai-spring-boot-starter)を使用する場合、デフォルトで使用されます。langchain4j-http-client-apacheモジュールのApacheHttpClient。langchain4j-http-client-okhttpモジュールのOkHttpClient。
HTTP クライアントの選択
builder またはクライアントを明示的に渡さない場合、サポート対象のモジュールはクラスパス上の HttpClientBuilderFactory 実装を検出します。JDK クライアントはフォールバックです。
| 利用可能な実装 | 選択されるクライアント |
|---|---|
| JDK のみ | JDK |
| JDK 以外が一種類のみ | そのクライアント |
| JDK とそれ以外が一種類 | JDK 以外のクライアント |
| JDK 以外の複数の実装が最高優先度で同点 | 競合エ ラー |
ファクトリーは priority() をオーバーライドして選択に影響を与えられます。値が高いほど優先されます。デフォルトは 0、JDK ファクトリーは PrioritizedFactory.YIELDS_TO_OTHERS(-100)です。最高優先度で同点の場合、クラスパスの順序に依存せずエラーになります。
システムプロパティ langchain4j.http.clientBuilderFactory を指定すると優先度より優先されます。値は利用可能なファクトリーの完全修飾クラス名です。ほかの実装があっても JDK を選ぶ例:
-Dlangchain4j.http.clientBuilderFactory=dev.langchain4j.http.client.jdk.JdkHttpClientBuilderFactory
builder を明示的に渡すと、検出とこのシステムプロパティは使用されません。
MCP Streamable HTTP トランスポートには別の規則があります。カスタム HTTP クライアントを参照してください。
JDKのHttpClientのカスタマイズ
HttpClient.Builder httpClientBuilder = HttpClient.newBuilder()
.sslContext(...);
JdkHttpClientBuilder jdkHttpClientBuilder = JdkHttpClient.builder()
.httpClientBuilder(httpClientBuilder);
OpenAiChatModel model = OpenAiChatModel.builder()
.httpClientBuilder(jdkHttpClientBuilder)
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
HTTPバージョン
デフォルトでは、JdkHttpClientはhttps://のURLに対して(サーバーが対応していれば)HTTP/2を使用し、
プレーンなhttp://のURLに対してはHTTP/1.1を使用します。プレーンHTTP上でHTTP/2を使うにはUpgrade: h2cリクエストが必要ですが、多くのサーバーは
これを正しく処理しません。たとえば、uvicorn上でhttptoolsパーサーを使用して動作するPythonサーバー
(vLLMやXinferenceなど)はリクエストボディを無視し、TomcatやReactor NettyでHTTP/2を有効にしたJavaサーバーは
大きなリクエストを拒否したり、応答を停止したりします。
典型的な症状は、リクエストボディがないというサーバーエラー(例:Field required)、
Unsupported upgrade request、413 Request Entity Too Large、あるいはタイムアウトするまでリクエストがハングすることです。
バージョン1.23.0より前は、JdkHttpClientはプレーンなhttp://のURLに対してもHTTP/2を使用していました。
古いバージョンを使用していて上記の症状が発生する場合は、以下に示すように
.version(HttpClient.Version.HTTP_1_1)を指定したHttpClient.Builderを渡してください。
独自のHttpClient.Builderを指定した場合(たとえば、プロキシやSSLContextを設定するため)、
そこで設定されたHTTPバージョンがすべてのURLに使用されます。バージョンを設定しなかった場合、JDKのデフォルトは
HTTP/2であるため、プレーンなhttp://リクエストでは再びUpgrade: h2cリクエストが送信されます。
その場合にHTTP/1.1を使用するには、バージョンを明示的に設定します:
HttpClient.Builder httpClientBuilder = HttpClient.newBuilder()
.proxy(...)
.version(HttpClient.Version.HTTP_1_1);
JdkHttpClientBuilder jdkHttpClientBuilder = JdkHttpClient.builder()
.httpClientBuilder(httpClientBuilder);
逆に、プレーンHTTPサーバーがUpgrade: h2cリクエストに対応していて、HTTP/2を使用したい場合は、
.version(HttpClient.Version.HTTP_2)を指定したビルダーを渡してください。
HttpClientの実装は、ノンブロッキングの対応メソッドも提供できます。単一のレスポンス用のexecuteAsync(...)と、
パース済みのServer-Sent EventsのコールドなFlow.Publisherを返すstream(...)です。同梱のJDK、OkHttp、
Apacheの各クライアントは両方を実装しており、spring-webfluxがクラスパスにある場合はSpringRestClientも両方を実装します。
ノンブロッキングとリアクティブを参照してください。
SpringのRestClientのカスタマイズ
SpringRestClientBuilder springRestClientBuilder = SpringRestClient.builder()
.restClientBuilder(RestClient.builder())
.clientHttpRequestFactoryBuilder(ClientHttpRequestFactoryBuilder.httpComponents())
.streamingRequestExecutor(new VirtualThreadTaskExecutor());
OpenAiChatModel model = OpenAiChatModel.builder()
.httpClientBuilder(springRestClientBuilder)
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
SpringRestClientは、ブロッキングリクエストをRestClientで、ノンブロッキングリクエスト(executeAsync(...)と
stream(...))をWebClientで送信します。後者にはクラスパス上のspring-webfluxが必要です。spring-webfluxはオプションのため、
WebClient.BuilderはWebClientBuilderHolderに包んで渡します:
SpringRestClientBuilder springRestClientBuilder = SpringRestClient.builder()
.restClientBuilder(RestClient.builder())
.webClientBuilder(WebClientBuilderHolder.of(WebClient.builder()))
.clientHttpConnectorBuilder(ClientHttpConnectorBuilder.reactor()); // optional: pins the connector
SpringRestClientは、タイムアウトを適用するためにリクエストファクトリーとコネクターを自身で構築します。そのため、RestClient.Builderに設定したリクエストファクトリーや、
WebClient.Builderに設定したコネクターは使用されません。代わりに
clientHttpRequestFactoryBuilder(...)とclientHttpConnectorBuilder(...)でHTTPクライアントを選択してください。
SSLバンドルやリダイレクトなど、Spring BootのHTTPクライアント設定を適用するには、Spring Bootが構成する
設定Beanをインジェクトして渡します:Spring Boot 4ではhttpClientSettings(...)でHttpClientSettingsを、
Spring Boot 3ではclientHttpRequestFactorySettings(...)でClientHttpRequestFactorySettingsを、
clientHttpConnectorSettings(...)でClientHttpConnectorSettingsを渡します。これらの設定に含まれるタイムアウトはLangChain4jの
モデルでは使用されず、モデルは常に独自のタイムアウトを設定します。代わりにモデルのビルダーでタイムアウトを設定してください。