跳到主要内容

カスタマイズ可能な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の モデルでは使用されず、モデルは常に独自のタイムアウトを設定します。代わりにモデルのビルダーでタイムアウトを設定してください。

JDKクライアントでのHTTPバージョン​

JDKのHttpClientが使用される場合(Springが自動的に選択する場合(クラスパスにApache HttpComponents、Jetty、Reactor Nettyがない場合)も、 clientHttpRequestFactoryBuilder(...)またはclientHttpConnectorBuilder(...)で自分で設定する場合も同様)、 SpringRestClientはJdkHttpClientと同じ動作をします。プレーンなhttp://リクエストはHTTP/1.1で送信され、https:// リクエストはサーバーが対応していればHTTP/2を使用します。これはブロッキングとノンブロッキングの両方のリクエストに適用されます。 プレーンHTTPでHTTP/2が使用されない理由については、HTTPバージョンを参照してください。

备注

バージョン1.23.0-beta33より前は、SpringRestClientはプレーンなhttp://のURLに対してもHTTP/2を使用していました。 古いバージョンを使用していて、HTTPバージョンで説明した症状が発生する場合は、 バージョンを明示的に設定してください:

SpringRestClientBuilder springRestClientBuilder = SpringRestClient.builder()
.clientHttpRequestFactoryBuilder(ClientHttpRequestFactoryBuilder.jdk()
.withHttpClientCustomizer(builder -> builder.version(HttpClient.Version.HTTP_1_1)))
.clientHttpConnectorBuilder(ClientHttpConnectorBuilder.jdk() // only needed for non-blocking requests
.withHttpClientCustomizer(builder -> builder.version(HttpClient.Version.HTTP_1_1)));

ApacheのHttpClientのカスタマイズ​

org.apache.hc.client5.http.impl.classic.HttpClientBuilder httpClientBuilder = org.apache.hc.client5.http.impl.classic.HttpClientBuilder.create();

ApacheHttpClientBuilder apacheHttpClientBuilder = ApacheHttpClient.builder()
.httpClientBuilder(httpClientBuilder);

OpenAiChatModel model = OpenAiChatModel.builder()
.httpClientBuilder(apacheHttpClientBuilder)
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();