LangChain4j 集成 IBM watsonx.ai 图像生成WatsonxGatewayImageModel 完整使用指南【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4jwatsonx.ai 的图片生成能力只能通过 IBMModel Gateway暴露本指南围绕 LangChain4j 中唯一对应的实现WatsonxGatewayImageModel讲解如何完成 Maven 依赖引入、模型实例构建、单张/批量图片生成、结果保存以及全部生成参数尺寸、质量、输出格式、响应格式、审核等级等的配置方式与底层行为。阅读完本文你将能够基于当前仓库的 langchain4j-watsonx 模块在 JVM 应用中用统一的ImageModel接口调用注册在 IBM Model Gateway 中的 OpenAI 风格图像模型如gpt-image-1、dall-e-3、dall-e-2并正确处理 Base64/URL 结果、Token 用量统计与认证方案切换。背景为什么只有 Model Gateway 一种途径与 watsonx.ai 的对话Chat与嵌入Embedding能力不同图像生成在 IBM watsonx.ai 中没有对应的基础模型foundation model接口。图片生成仅通过 watsonx.ai 的Model Gateway提供Gateway 暴露了一个与 OpenAI images 端点兼容的接口请求会被路由到管理员在 Gateway 中注册的各类提供商模型因此WatsonxGatewayImageModel是该集成中唯一的图像模型实现。在使用之前需要特别注意的是Gateway 必须由管理员预先配置并且你传入的每一个modelName都必须是已经在 Gateway 中注册过的模型 id。这一约束写在了官方集成文档中也从源码的构建方式得到印证——模型 id 通过modelId(...)直接传给底层 IBM SDK 的ModelGatewayImageService见 WatsonxGatewayImageModel.java。引入 Maven 依赖在项目中加入以下依赖版本号以当前仓库发布版本为准示例为文档标注版本dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-watsonx/artifactId version1.20.0-beta30/version /dependency从仓库的 pom.xml 可以看到该模块依赖langchain4j-core并封装了 IBM 官方com.ibm.watsonx:watsonx-aiSDK当前仓库锁定版本 0.40.0同时排除了其 Jackson 传递依赖以避免版本冲突。使用langchain4j-bom其中已收录langchain4j-watsonx见 langchain4j-bom/pom.xml可以统一管理版本号。快速上手构建模型并生成第一张图构建WatsonxGatewayImageModel需要三个核心要素构建方法说明baseUrl(...)IBM Cloud 端点 URL可传String、URI或预定义枚举CloudRegionapiKey(...)IBM Cloud IAM API key也可以用.authenticator(...)传入完整的AuthenticatormodelName(...)在 Gateway 中注册的图像模型 id按 OpenAI 风格书写例如gpt-image-1与 watsonx.ai 其他服务不同这里不需要projectId或spaceId——模型由 Gateway 自行解析。最小可用示例单张图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();关于baseUrl(...)的底层行为从 WatsonxConnectionBuilder.java 可以看到它有三个重载传CloudRegion时会自动映射为该区域的 ML 端点baseUrl.mlEndpoint()传String时会被解析为URI。同一个抽象构建器还提供了version(...)API 版本日期如2024-05-31、timeout(...)默认 60 秒、logRequests(...)/logResponses(...)请求/响应体调试日志、httpClient(...)自定义 HTTP 客户端以及verifySsl(...)默认开启 SSL 校验等连接级配置它们在构建WatsonxGatewayImageModel时同样可用。一次生成多张图generate(prompt, n)返回一个包含多张图片的ResponseListImageResponseListImage response imageModel.generate(A futuristic city at sunset, 3); for (Image image : response.content()) { System.out.println(image.base64Data()); }需要留意的是每个请求可接受的图片数量取决于具体模型一个模型允许的数量另一个模型可能会拒绝。从源码 Javadoc 看n的取值范围是 1 到 10见 WatsonxGatewayImageModel.java单元测试也验证了generate(prompt, 2)会把n2写进请求参数并返回两张图见 WatsonxGatewayImageModelTest.java。保存生成的图片返回的图片根据模型与所请求的响应格式可能是链接或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()); }当模型报告了生成图片的格式时image.mimeType()会携带该信息例如image/png。这一映射逻辑实现在 Converter.javatoImage(...)会把 SDK 返回的b64Json、revisedPrompt与url组装进 LangChain4j 的Image对象并按image/ outputFormat生成 MIME 类型注意只有部分模型会报告输出格式因此 MIME 类型可能保持未设置状态。单图生成时如果模型返回了多张图实现会取第一张返回见 WatsonxGatewayImageModel.java。生成参数构建器级配置以下参数都可以在构建器上一次性设置并作用于之后的所有请求构建器方法说明background(...)生成图片的背景取值TRANSPARENT、OPAQUE或AUTO透明背景要求输出格式支持透明通道即PNG或WEBPmoderation(...)生成图片的过滤严格程度取值LOW或AUTOoutputCompression(...)压缩级别 0100仅JPEG与WEBP格式接受outputFormat(...)生成图片的文件格式取值PNG、JPEG、WEBP或AUTOquality(...)生成图片的质量取值AUTO、HIGH、MEDIUM、LOW、HD或STANDARDresponseFormat(...)图片返回方式URL返回链接B64_JSON返回 Base64 数据size(...)生成图片的尺寸例如SIZE_1024X1024style(...)生成图片的视觉风格取值VIVID或NATURALuser(...)终端用户标识符用于滥用监控每个枚举重载之外都还有一个接收String的重载用于覆盖枚举尚未包含的新值。源码中每个 setter 都成对出现枚举值与字符串值例如background(Background)与background(String)、size(Size)与size(String)见 WatsonxGatewayImageModel.java枚举值在写入请求前会被展开为小写字符串如vivid、b64_json、1024x1024这一点由单元测试逐一断言见 WatsonxGatewayImageModelTest.java。组合示例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(); ResponseListImage response imageModel.generate(A futuristic city at sunset, parameters);这里有两个字段只在按请求传参时可用构建器上没有对应方法n生成图片数量。LangChain4j 的图片请求 API 已通过generate(prompt, n)暴露了该能力因此无需在构建器上重复提供partialImages该参数实际不会产生效果因为 Gateway 的图片端点不支持流式输出。替换而非合并的语义在源码 Javadoc 中有明确说明见 WatsonxGatewayImageModel.java单元测试should_override_the_builder_parameters_with_the_given_parameters也验证了传入参数会覆盖构建器设置如1024x1024被替换为512x512见 WatsonxGatewayImageModelTest.java。模型特有行为与默认值Gateway 会把请求转发给对应模型的提供商因此并非每个参数都会被每个模型接受模型行为gpt-image-1总是以 Base64 数据应答忽略responseFormat是唯一报告 Token 用量的模型dall-e-3遵循responseFormat是唯一返回修订后提示词revised prompt的模型可通过image.revisedPrompt()读取dall-e-2遵循responseFormat不支持quality或style各参数留空时的默认值为responseFormat为urloutputFormat为jpegsize为1024x1024quality为auto默认只生成一张图。这些默认行为由 SDK 侧应用LangChain4j 侧只在用户显式设置时才把字段写入请求——从 Converter.java 与测试用例可以看到未设置outputFormat时 MIME 类型保持为空、未设置n时请求中不携带该字段assertNull(payload.n())。Token 用量统计Token 用量只有统计提示词 Token 的模型才会返回因此response.tokenUsage()可能为null读取前需要判空ResponseImage response imageModel.generate(A futuristic city at sunset); if (response.tokenUsage() ! null) { System.out.println(response.tokenUsage().totalTokenCount()); }在实现层面SDK 响应中的Usage输入/输出/总 Token会被转换成 LangChain4j 的TokenUsage见 Converter.java因此可以通过inputTokenCount()、outputTokenCount()与totalTokenCount()分别访问测试中对(10, 20, 30)的 Token 三元组做了逐一断言见 WatsonxGatewayImageModelTest.java。不支持的图像编辑操作该端点只支持从提示词生成图片ImageModel接口中的图像编辑方法没有对应实现。调用edit(Image, String)或edit(Image, Image, String)会抛出IllegalArgumentException——单元测试与集成测试都覆盖了这一行为见 WatsonxGatewayImageModelTest.java 与 WatsonxGatewayImageModelIT.java。认证方式apiKey 快捷方式与 Authenticatorwatsonx.ai 支持通过Authenticator接口进行认证使你可以根据部署环境选择不同的机制IBMCloudAuthenticator—— 使用 API key 向IBM Cloud认证这是最简单的方式也是使用.apiKey(...)构建方法时所用的认证器CP4DAuthenticator—— 面向Cloud Pak for Data部署环境自定义 Authenticator—— 任何实现了Authenticator接口的实现都可以使用。WatsonxGatewayImageModel与其他 watsonx 服务构建器一样既接受.apiKey(...)快捷方式也接受通过.authenticator(...)传入完整的Authenticator实例。从源码可以看到构建时优先使用authenticator仅当它为null时才回退到apiKey见 WatsonxGatewayImageModel.java测试也验证了传入authenticator时不会再调用apiKey见 WatsonxGatewayImageModelTest.java。示例两种认证配置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();测试与验证参考如果你想在本地验证WatsonxGatewayImageModel的行为仓库提供了两层测试单元测试WatsonxGatewayImageModelTest.java基于 Mockito 模拟底层ModelGatewayImageService覆盖构建器全参数字段映射、多图生成、参数覆盖、编辑不支持、SDK 异常到 LangChain4j 异常如InternalServerException的映射等集成测试WatsonxGatewayImageModelIT.java需要设置环境变量WATSONX_API_KEY、WATSONX_URL与WATSONX_GATEWAY_IMAGE_MODEL才会执行真实调用 Gateway 验证图片生成、多图生成、参数生效以及不支持的尺寸123x456会抛出InvalidRequestException。从测试中可以看到gpt-image-1总是以可解码的 Base64 数据应答且不返回 URL这与文档所述模型行为一致。集成测试同时验证了指定OutputFormat.PNG时返回的图片 MIME 类型为image/png见 WatsonxGatewayImageModelIT.java可直接作为自己应用中保存图片逻辑的参考。【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考