IBM watsonx.ai Moderation Model

IBM watsonx.ai provides moderation capabilities through multiple detectors that can identify unsafe, sensitive, or policy-violating content. Quarkus integrates the LangChain4j WatsonxModerationModel, exposing each detector type as a dedicated configuration group.

Supported detector types include:

  • PII - Detects Personally Identifiable Information

  • HAP - Detects hate, abuse, or profanity

  • Granite Guardian - Detects harmful or risky content

Each detector can be enabled individually.

Prerequisites

To use watsonx.ai models, configure the following required values in your application.properties file:

Base URL

The base-url depends on the region of your service instance:

quarkus.langchain4j.watsonx.base-url=https://us-south.ml.cloud.ibm.com

Project ID

Obtain the Project Id via:

quarkus.langchain4j.watsonx.project-id=23d...
You may use the optional space-id as an alternative.

API Key

Create an API key by visiting https://cloud.ibm.com/iam/apikeys and clicking Create +.

quarkus.langchain4j.watsonx.api-key=your-api-key
You can also use the QUARKUS_LANGCHAIN4J_WATSONX_API_KEY environment variable.

Dependency

Add the following dependency to your project:

<dependency>
  <groupId>io.quarkiverse.langchain4j</groupId>
  <artifactId>quarkus-langchain4j-watsonx</artifactId>
  <version>1.14.0.CR3</version>
</dependency>

Even better, if you use the Quarkus platform BOM (default for projects generated), add the Quarkus Langchain4J BOM and all dependency versions will align:

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>${quarkus.platform.artifact-id}</artifactId>
                <version>${quarkus.platform.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>quarkus-langchain4j-bom</artifactId> (1)
                <version>${quarkus.platform.version}</version> (2)
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
      <dependency>
        <groupId>io.quarkiverse.langchain4j</groupId>
        <artifactId>quarkus-langchain4j-watsonx</artifactId>
        (3)
      </dependency>
    </dependencies>
1 In your dependencyManagement section, add the quarkus-langchain4j-bom
2 Inherit the version from your platform version
3 Voilà, no need for version alignment anymore

Configuration

Enable detectors in application.properties using their dedicated flags:

# Base Watsonx configuration
quarkus.langchain4j.watsonx.base-url=${BASE_URL}
quarkus.langchain4j.watsonx.api-key=${API_KEY}
quarkus.langchain4j.watsonx.project-id=${PROJECT_ID}

# Enable specific moderation detectors
quarkus.langchain4j.watsonx.moderation-model.hap.enabled=true
quarkus.langchain4j.watsonx.moderation-model.pii.enabled=true
quarkus.langchain4j.watsonx.moderation-model.granite-guardian.enabled=true

Each detector configuration group may also expose additional settings depending on its capabilities. If a moderation model is configured, Quarkus will automatically create and register a ModerationModel bean.

Injection

@Inject
ModerationModel moderationModel;

Usage

var response = moderationModel.moderate("Some text to analyze");

boolean flagged = response.content().flagged();
Map<String, Object> metadata = response.metadata();

System.out.println("Flagged? " + flagged);
System.out.println("Metadata: " + metadata);

Metadata

A moderation response includes metadata describing the detection:

Key Description

detection

The assigned label for the detected content

detection_type

Detector that triggered the flag

start

Start index of the detected segment

end

End index of the detected segment

score

Confidence score

Example:

System.out.println(metadata.get("detection_type"));
System.out.println(metadata.get("score"));
For inline moderation within a chat request (without a second network call), see the Inline moderation section of the IBM watsonx.ai Chat Model page.