watsonx.ai

• watsonx.ai API Reference
• watsonx.ai Java SDK
• watsonx.ai Java SDK documentation

Maven の依存関係

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

Model Gateway

画像生成は、IBM watsonx.ai の Model Gateway を通じてのみ利用できます。Model Gateway は OpenAI 互換の画像エンドポイントを公開し、そこに登録されたプロバイダーがホストするモデルにリクエストをルーティングします。対応する基盤モデル（foundation model）はないため、WatsonxGatewayImageModel がこの統合における唯一の画像モデルです。

注意: 使用する前に、管理者がゲートウェイを設定しておく必要があります。渡す modelName は、すべてゲートウェイに登録済みの ID でなければなりません。

WatsonxGatewayImageModel

WatsonxGatewayImageModel は LangChain4j の ImageModel インターフェースを実装しています。インスタンスを作成するには、次を指定します。

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

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

import com.ibm.watsonx.ai.CloudRegion;
import dev.langchain4j.data.image.Image;
import dev.langchain4j.model.image.ImageModel;
import dev.langchain4j.model.watsonx.WatsonxGatewayImageModel;

ImageModel imageModel = WatsonxGatewayImageModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("gpt-image-1")
    .build();

Image image = imageModel.generate("A futuristic city at sunset").content();

複数の画像を生成する

Response<List<Image>> response = imageModel.generate("A futuristic city at sunset", 3);

for (Image image : response.content()) {
    System.out.println(image.base64Data());
}

1 回のリクエストで受け付けられる画像の枚数はモデルによって異なるため、あるモデルで許可される値が別のモデルでは拒否されることがあります。

生成した画像を保存する

画像は、モデルや要求されたレスポンス形式に応じて、リンクまたは Base64 データのいずれかで返されます。

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

Image image = imageModel.generate("A futuristic city at sunset").content();

if (image.base64Data() != null) {
    Files.write(Path.of("image.png"), Base64.getDecoder().decode(image.base64Data()));
} else {
    System.out.println(image.url());
}

モデルが生成した画像の形式を報告する場合、mimeType() にその形式（例: image/png）が格納されます。

パラメータ

すべてのパラメータは、ビルダーで一度設定すれば、すべてのリクエストに適用されます。

ビルダーのメソッド	説明
background(...)	生成される画像の背景。TRANSPARENT、OPAQUE、AUTO のいずれか。透過には、それをサポートする出力形式、つまり PNG または WEBP が必要です
moderation(...)	生成される画像をどの程度厳しくフィルタリングするか。LOW または AUTO
outputCompression(...)	0 ～ 100 の圧縮レベル。JPEG と WEBP 形式でのみ指定できます
outputFormat(...)	生成される画像のファイル形式。PNG、JPEG、WEBP、AUTO のいずれか
quality(...)	生成される画像の品質。AUTO、HIGH、MEDIUM、LOW、HD、STANDARD のいずれか
responseFormat(...)	画像の返却方法。リンクの場合は URL、Base64 データの場合は B64_JSON
size(...)	生成される画像の寸法（例: SIZE_1024X1024）
style(...)	生成される画像の視覚的なスタイル。VIVID または NATURAL
user(...)	エンドユーザーの識別子。不正利用の監視に使用されます

これらにはそれぞれ String を受け取るオーバーロードもあり、列挙型がまだ対応していない値を指定するのに便利です。

import com.ibm.watsonx.ai.gateway.image.ModelGatewayImageParameters.OutputFormat;
import com.ibm.watsonx.ai.gateway.image.ModelGatewayImageParameters.Quality;
import com.ibm.watsonx.ai.gateway.image.ModelGatewayImageParameters.Size;

ImageModel imageModel = WatsonxGatewayImageModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("gpt-image-1")
    .size(Size.SIZE_1024X1024)
    .quality(Quality.LOW)
    .outputFormat(OutputFormat.PNG)
    .build();

リクエストごとのパラメータ

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

import com.ibm.watsonx.ai.gateway.image.ModelGatewayImageParameters;

WatsonxGatewayImageModel imageModel = WatsonxGatewayImageModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key")
    .modelName("gpt-image-1")
    .build();

ModelGatewayImageParameters parameters = ModelGatewayImageParameters.builder()
    .size(Size.SIZE_1024X1024)
    .quality(Quality.HIGH)
    .n(2)
    .build();

Response<List<Image>> response = imageModel.generate("A futuristic city at sunset", parameters);

n と partialImages はここでのみ指定でき、ビルダーにはありません。画像の枚数は、generate(prompt, n) を通じて、すでに LangChain4j の画像リクエスト API の一部になっています。また、エンドポイントは結果をストリーミングしないため、partialImages は効果がありません。

モデル固有の動作

ゲートウェイはリクエストをモデルのプロバイダーに転送するため、すべてのパラメータがすべてのモデルで有効になるわけではありません。

モデル	動作
gpt-image-1	常に Base64 データで応答し、responseFormat は無視されます。トークン使用量を報告する唯一のモデルです
dall-e-3	responseFormat に従います。修正後のプロンプトを返す唯一のモデルで、image.revisedPrompt() で読み取れます
dall-e-2	responseFormat に従います。quality と style はサポートしません

パラメータを設定しなかった場合に適用されるデフォルトは、responseFormat が url、outputFormat が jpeg、size が 1024x1024、quality が auto、画像は 1 枚のみです。

トークン使用量

トークン使用量は、プロンプトのトークンを数えるモデルでのみ報告されるため、response.tokenUsage() は null になる場合があります。

Response<Image> response = imageModel.generate("A futuristic city at sunset");

if (response.tokenUsage() != null) {
    System.out.println(response.tokenUsage().totalTokenCount());
}

サポートされない操作

このエンドポイントはプロンプトからの画像生成のみを行うため、ImageModel インターフェースの編集メソッドに対応する機能はありません。edit(Image, String) または edit(Image, Image, String) を呼び出すと、IllegalArgumentException がスローされます。

認証

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

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

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

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

例

WatsonxGatewayImageModel.builder()
    .baseUrl(CloudRegion.FRANKFURT)
    .apiKey("your-api-key") // Simple IBM Cloud authentication
    .modelName("gpt-image-1")
    .build();

WatsonxGatewayImageModel.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()
    )
    .modelName("gpt-image-1")
    .build();