watsonx.ai

• watsonx.ai API リファレンス
• watsonx.ai Java SDK
• watsonx.ai Java SDK ドキュメント

Maven依存関係

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-watsonx</artifactId>
    <version>1.23.0-beta33</version>
</dependency>

認証

Watsonx.ai は Authenticator インターフェースによる認証をサポートしています。

これにより、デプロイ環境に応じて異なる認証メカニズムを使用できます：

• IBMCloudAuthenticator – API キーを使用して IBM Cloud で認証します。最もシンプルな方法で、ビルダーメソッド apiKey(...) を指定した場合に使用されます。
• CP4DAuthenticator – Cloud Pak for Data のデプロイメントで認証します。
• カスタム認証子 – Authenticator インターフェースの任意の実装を使用できます。

WatsonxEmbeddingModel やその他のサービスビルダーは、.apiKey(...) によるショートカット、または .authenticator(...) による完全な Authenticator インスタンスのいずれかを受け付けます。

例

WatsonxEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key") // Simple IBM Cloud authentication
    .projectId("your-project-id")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .build();

WatsonxEmbeddingModel.builder()
    .baseUrl("https://my-instance-url")
    .authenticator( // For Cloud Pak for Data deployments
        CP4DAuthenticator.builder()
            .baseUrl("https://my-instance-url")
            .username("username")
            .apiKey("api-key")
            .build()
    )
    .projectId("my-project-id")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .build();

カスタム HttpClient と SSL 設定

カスタム HttpClient の使用

すべてのサービスと認証子は、ビルダーパターンを通じてカスタムの HttpClient インスタンスをサポートしています。これは特に Cloud Pak for Data 環境で便利で、カスタムの TLS/SSL 設定、プロキシ設定、その他の HTTP クライアントのプロパティを構成する必要がある場合があります。

HttpClient httpClient = HttpClient.newBuilder()
    .sslContext(createCustomSSLContext())
    .executor(ExecutorProvider.ioExecutor())
    .build();

EmbeddingModel embeddingModel = WatsonxEmbeddingModel.builder()
    .baseUrl("https://my-instance-url")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .projectId("project-id")
    .httpClient(httpClient) // Custom HttpClient
    .authenticator(
        CP4DAuthenticator.builder()
            .baseUrl("https://my-instance-url")
            .username("username")
            .apiKey("api-key")
            .httpClient(httpClient) // Custom HttpClient
            .build()
    )
    .build();

注意： Cloud Pak for Data でカスタムの HttpClient を使用する場合は、すべてのリクエストで一貫した HTTP の動作を確保するために、サービスビルダーと認証子ビルダーの両方に設定してください。

SSL 検証の無効化

SSL 証明書の検証だけを無効にしたい場合は、カスタムの HttpClient を指定する代わりに verifySsl(false) オプションを使用できます：

EmbeddingModel embeddingModel = WatsonxEmbeddingModel.builder()
    .baseUrl("https://my-instance-url")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .projectId("project-id")
    .verifySsl(false) // Disable SSL verification
    .authenticator(
        CP4DAuthenticator.builder()
            .baseUrl("https://my-instance-url")
            .username("username")
            .apiKey("api-key")
            .verifySsl(false) // Disable SSL verification
            .build()
    )
    .build();

IBM Cloud API キーの作成方法

https://cloud.ibm.com/iam/apikeys で Create + をクリックすると、API キーを作成できます。

プロジェクト ID の確認方法

1. https://dataplatform.cloud.ibm.com/projects/?context=wx にアクセスします
2. プロジェクトを開きます
3. Manage タブに移動します
4. Details セクションから Project ID をコピーします

WatsonxEmbeddingModel

WatsonxEmbeddingModel を使用すると、IBM watsonx.ai で埋め込みを生成し、検索、検索拡張生成（RAG）、類似度比較など、LangChain4j のベクトルベースの操作と統合できます。

これは LangChain4j の EmbeddingModel インターフェースを実装しています。

EmbeddingModel embeddingModel = WatsonxEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .build();

System.out.println(embeddingModel.embed("Hello from watsonx.ai"));

🔗 利用可能な埋め込みモデル ID を表示

リスナー

WatsonxEmbeddingModel と WatsonxGatewayEmbeddingModel はどちらも EmbeddingModelListener のリストを受け付け、すべてのリクエストの前、すべてのレスポンスの後、およびすべてのエラー発生時に通知されます。

EmbeddingModel embeddingModel = WatsonxEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .projectId("your-project-id")
    .modelName("ibm/granite-embedding-278m-multilingual")
    .listeners(List.of(new EmbeddingModelListener() {

        @Override
        public void onRequest(EmbeddingModelRequestContext context) {
            System.out.println(context.embeddingRequest().inputs().size() + " input(s)");
        }

        @Override
        public void onResponse(EmbeddingModelResponseContext context) {
            System.out.println(context.embeddingResponse().tokenUsage());
        }

        @Override
        public void onError(EmbeddingModelErrorContext context) {
            System.out.println(context.error().getMessage());
        }
    }))
    .build();

モデルゲートウェイ

IBM watsonx.ai の Model Gateway（モデルゲートウェイ） は、OpenAI と互換性のある埋め込みエンドポイントを公開しており、複数のプロバイダーがホストするモデル（たとえば OpenAI や、ご自身で登録した外部プロバイダー）へのリクエストを、単一の watsonx.ai エントリーポイントの背後でルーティングできます。LangChain4j は WatsonxGatewayEmbeddingModel を通じてこれと統合します。

注意： ゲートウェイは、使用前に管理者が構成しておく必要があります。指定するすべての modelName は、ゲートウェイにすでに登録されている ID でなければなりません。

WatsonxGatewayEmbeddingModel

インスタンスを作成するには、次を指定します：

• baseUrl(...) – IBM Cloud のエンドポイント URL（String、URI、または CloudRegion）
• apiKey(...) – IBM Cloud IAM API キー（または .authenticator(...) による完全な Authenticator）
• modelName(...) – ゲートウェイに登録された埋め込みモデルの ID（OpenAI 形式で記述）

projectId や spaceId は不要で、ゲートウェイがモデルを自ら解決します。

import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.watsonx.WatsonxGatewayEmbeddingModel;
import com.ibm.watsonx.ai.CloudRegion;

EmbeddingModel embeddingModel = WatsonxGatewayEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("text-embedding-3-small")
    .build();

System.out.println(embeddingModel.embed("Hello from the watsonx.ai Model Gateway"));

ゲートウェイ専用のパラメータ

ゲートウェイは、watsonx.ai の埋め込みエンドポイントにはない 3 つのパラメータを受け付けます。これらはビルダーで一度設定すれば、すべてのリクエストに適用されます。

ビルダーメソッド	説明
dimensions(...)	返されるベクトルの次元数（対応しているモデルの場合）
encodingFormat(...)	返されるベクトルの転送形式。FLOAT または BASE64。SDK が BASE64 をデコードするため、どちらの形式でも同じベクトルが得られます
user(...)	エンドユーザーの識別子。不正利用の監視に使用されます

EmbeddingModel embeddingModel = WatsonxGatewayEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("text-embedding-3-small")
    .dimensions(512)
    .encodingFormat(EncodingFormat.BASE64)
    .build();

同じ値は、ModelGatewayEmbeddingParameters を通じてリクエストごとに渡すこともできます。指定したパラメータはビルダーで設定されたものを置き換え、マージはされません。

WatsonxGatewayEmbeddingModel embeddingModel = WatsonxGatewayEmbeddingModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("text-embedding-3-small")
    .build();

ModelGatewayEmbeddingParameters parameters = ModelGatewayEmbeddingParameters.builder()
    .dimensions(256)
    .build();

Response<List<Embedding>> response = embeddingModel.embedAll(
    List.of(TextSegment.from("Hello"), TextSegment.from("World")), parameters);

3 つのうち dimensions だけが LangChain4j の埋め込みリクエスト API にも含まれているため、EmbeddingModel インターフェースから離れることなくリクエストごとに設定できます。リクエストの値はビルダーの値を上書きしますが、encodingFormat と user はビルダーで設定された値が維持されます。

EmbeddingResponse response = embeddingModel.embed(EmbeddingRequest.builder()
    .input("Hello from the watsonx.ai Model Gateway")
    .dimensions(256)
    .build());

例

• WatsonxEmbeddingModelTest