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>

身份认证

Watsonx.ai 支持通过 Authenticator 接口进行身份验证。

这使你可以根据部署方式使用不同的认证机制：

• IBMCloudAuthenticator —— 使用 API 密钥向 IBM Cloud 认证。这是最简单的方式，在你提供 apiKey(...) builder 方法时使用。
• CP4DAuthenticator —— 向 Cloud Pak for Data 部署认证。
• 自定义认证器 —— 可使用 Authenticator 接口的任意实现。

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

Example

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

所有服务与认证器都通过 builder 模式支持自定义的 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 时，请确保同时在服务 builder 和认证器 builder 上设置它，以保证所有请求的 HTTP 行为一致。

禁用 SSL 验证

如果你只需禁用 SSL 证书验证，可以使用 verifySsl(false) 选项，而不必提供自定义 HttpClient：

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 密钥。

如何找到你的 Project ID

1. 访问 https://dataplatform.cloud.ibm.com/projects/?context=wx
2. 打开你的项目
3. 进入 Manage 标签
4. 从 Details 部分复制 Project ID

WatsonxEmbeddingModel

WatsonxEmbeddingModel 让你能使用 IBM watsonx.ai 生成嵌入，并将它们与 LangChain4j 基于向量的操作集成，例如搜索、检索增强生成（RAG）与相似度比较。

它实现了 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();

模型网关（Model Gateway）

IBM watsonx.ai 的 Model Gateway 暴露一个与 OpenAI 兼容的嵌入端点，能在单个 watsonx.ai 入口之后，将请求路由到由多家提供者（例如 OpenAI，或你自己注册的外部提供者）托管的模型。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 嵌入端点所没有的参数。它们可以在 builder 上设置一次，并适用于每个请求。

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

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

dimensions 是三者中唯一也属于 LangChain4j 嵌入请求 API 的，因此它可在不脱离 EmbeddingModel 接口的前提下逐次请求设置。请求中的值会覆盖 builder 的值，而 encodingFormat 与 user 仍沿用 builder 上设置的值。

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

示例

• WatsonxEmbeddingModelTest