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.22.0-beta32</version>
</dependency>

模型网关（Model Gateway）

图像生成仅能通过 IBM watsonx.ai 的 Model Gateway 使用，它暴露一个与 OpenAI 兼容的 images 端点，并将请求路由到其中注册的各提供者所托管的模型。没有对应的基础模型方式，因此 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());
}

每次请求所接受的图像数量取决于模型，因此某个模型允许的值可能被另一个模型拒绝。

保存生成的图像

图像会以一个链接或 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。

参数

每个参数都可以在 builder 上设置一次，并适用于所有请求。

Builder 方法	描述
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 返回链接或 B64_JSON 返回 Base64 数据
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 逐次请求传入。所提供的参数会替换 builder 上设置的值，而非与它们合并。

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 只在这里可用，它们不在 builder 上。图像数量已通过 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，且仅生成一张图像。

词元用量

词元用量只由那些会统计提示词词元的模型上报，因此 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(...) builder 方法时使用。
• CP4DAuthenticator —— 向 Cloud Pak for Data 部署认证。
• 自定义认证器 —— 可使用 Authenticator 接口的任意实现。

WatsonxGatewayImageModel 及其他服务 builder 既接受通过 .apiKey(...) 的快捷方式，也接受通过 .authenticator(...) 的完整 Authenticator 实例。

Example

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();