Development UI Guide

The Quarkus LangChain4j OpenAI deployment module provides development-time UI integration for testing image generation and content moderation models directly from the Quarkus Dev UI without writing code.

Capabilities

Accessing Development UI

The Development UI is available when running Quarkus in development mode.

Starting Development Mode:

mvn quarkus:dev

Accessing Dev UI:

Open your browser to: http://localhost:8080/q/dev-ui

Look for the LangChain4j OpenAI card in the extensions list.

Image Generation Testing

Interactive interface for testing OpenAI DALL-E image generation with real-time preview and configuration options.

Requirements:

• quarkus.langchain4j.openai.image-model.enabled=true (default)
• Valid API key configured

Features:

• Text prompt input for image generation
• Image size selection (1024x1024, 1024x1792, 1792x1024)
• Quality selection (standard, hd)
• Style selection (vivid, natural)
• Configuration selection (for multiple named configurations)
• Real-time image preview
• Download generated images
• Error display for failed generations

Usage Steps:

1. Navigate to Dev UI → LangChain4j OpenAI → Images page
2. Select configuration (if multiple configurations exist)
3. Enter image description prompt
4. Configure parameters:
   • Size: Choose from available dimensions
   • Quality: standard or hd (DALL-E 3 only)
   • Style: vivid or natural (DALL-E 3 only)
5. Click "Generate Image"
6. View generated image in preview
7. Download image if desired

Configuration Properties Used:

# Image model configuration for Dev UI
quarkus.langchain4j.openai.image-model.enabled=true
quarkus.langchain4j.openai.image-model.model-name=dall-e-3
quarkus.langchain4j.openai.api-key=sk-your-api-key

# Optional: Named configuration for Dev UI testing
quarkus.langchain4j.openai.test-images.api-key=sk-test-key
quarkus.langchain4j.openai.test-images.image-model.model-name=dall-e-3

Example Prompts:

• "A serene mountain landscape at sunset with purple sky"
• "Abstract geometric pattern in blue and gold"
• "Futuristic city with flying cars, digital art style"
• "Portrait of a cat wearing a space suit"

Moderation Testing

Interactive interface for testing OpenAI content moderation with category-specific results and detailed scores.

Requirements:

• quarkus.langchain4j.openai.moderation-model.enabled=true (default)
• Valid API key configured

Features:

• Text input for content to moderate
• Configuration selection (for multiple named configurations)
• Category-specific results display
• Flagged content indicators
• Detailed category scores
• Multiple text batch testing
• Error display for failed moderations

Usage Steps:

1. Navigate to Dev UI → LangChain4j OpenAI → Moderation Model page
2. Select configuration (if multiple configurations exist)
3. Enter text to moderate
4. Click "Moderate Content"
5. View results:
   • Overall flagged status
   • Category flags (hate, self-harm, sexual, violence, etc.)
   • Category scores (0.0 to 1.0)
   • Category thresholds

Configuration Properties Used:

# Moderation model configuration for Dev UI
quarkus.langchain4j.openai.moderation-model.enabled=true
quarkus.langchain4j.openai.moderation-model.model-name=omni-moderation-latest
quarkus.langchain4j.openai.api-key=sk-your-api-key

# Optional: Named configuration for Dev UI testing
quarkus.langchain4j.openai.test-moderation.api-key=sk-test-key
quarkus.langchain4j.openai.test-moderation.moderation-model.model-name=omni-moderation-latest

Moderation Categories:

• Hate: Content expressing hatred toward groups based on identity
• Hate/Threatening: Hateful content with violent or threatening language
• Self-Harm: Content promoting self-harm or suicide
• Self-Harm/Intent: Content with intent to engage in self-harm
• Self-Harm/Instructions: Content with instructions for self-harm
• Sexual: Sexual content intended to arouse
• Sexual/Minors: Sexual content involving minors
• Violence: Content depicting violence
• Violence/Graphic: Graphic violent content

Example Test Content:

• Safe content: "The weather is nice today"
• Potentially unsafe: Various categories can be tested (use responsibly for testing only)

Multiple Configuration Support

The Dev UI automatically detects and supports multiple named OpenAI configurations.

Configuration Example:

# Default configuration
quarkus.langchain4j.openai.api-key=sk-default
quarkus.langchain4j.openai.image-model.model-name=dall-e-3

# Development configuration
quarkus.langchain4j.openai.dev.api-key=sk-dev
quarkus.langchain4j.openai.dev.image-model.model-name=dall-e-3
quarkus.langchain4j.openai.dev.image-model.quality=hd

# Testing configuration
quarkus.langchain4j.openai.test.api-key=sk-test
quarkus.langchain4j.openai.test.moderation-model.model-name=text-moderation-stable

Dev UI Behavior:

• All configured model instances appear in configuration dropdown
• Switch between configurations to test different API keys or settings
• Configuration names displayed: "default", "dev", "test", etc.
• Each configuration uses its own API key and settings

JSON RPC Services

Backend services powering the Dev UI, implementing JSON RPC protocol for communication.

Image Generation RPC Service

package io.quarkiverse.langchain4j.openai.runtime.devui;

/**
 * JSON RPC service for Dev UI image generation.
 * Handles image generation requests from the Dev UI frontend.
 */
public class OpenAiImagesJsonRPCService {

    /**
     * Generate an image using specified configuration.
     *
     * @param configName Configuration name (e.g., "default")
     * @param prompt Image description prompt
     * @param size Image size (e.g., "1024x1024")
     * @param quality Image quality ("standard" or "hd")
     * @param style Image style ("vivid" or "natural")
     * @return Image URL or base64 data
     */
    public ImageResult generateImage(
        String configName,
        String prompt,
        String size,
        String quality,
        String style
    ) {
        // Implementation
    }

    /**
     * Get available configurations for image models.
     *
     * @return List of configuration names
     */
    public List<String> getConfigurations() {
        // Implementation
    }
}

Moderation RPC Service

package io.quarkiverse.langchain4j.openai.runtime.devui;

/**
 * JSON RPC service for Dev UI content moderation.
 * Handles moderation requests from the Dev UI frontend.
 */
public class OpenAiModerationModelsJsonRPCService {

    /**
     * Moderate content using specified configuration.
     *
     * @param configName Configuration name (e.g., "default")
     * @param text Text content to moderate
     * @return Moderation results with category flags and scores
     */
    public ModerationResult moderate(String configName, String text) {
        // Implementation
    }

    /**
     * Get available configurations for moderation models.
     *
     * @return List of configuration names
     */
    public List<String> getConfigurations() {
        // Implementation
    }
}

RPC Service Features:

• Automatic CDI injection of configured model instances
• Error handling and user-friendly error messages
• Support for all configuration properties
• Real-time execution without application restart

Error Handling

The Dev UI provides clear error messages for common issues.

Common Errors and Solutions:

"API key not configured":

• Solution: Set quarkus.langchain4j.openai.api-key in application.properties
• Or set environment variable: QUARKUS_LANGCHAIN4J_OPENAI_API_KEY

"Invalid API key":

• Solution: Verify API key is correct and has necessary permissions
• Check OpenAI account status and billing

"Model not enabled":

• Solution: Set quarkus.langchain4j.openai.image-model.enabled=true
• Or quarkus.langchain4j.openai.moderation-model.enabled=true

"Rate limit exceeded":

• Solution: Wait before retrying, or upgrade OpenAI plan
• Check OpenAI dashboard for rate limit information

"Network error":

• Solution: Check internet connection and proxy settings
• Verify base URL is correct
• Check firewall settings

"Insufficient quota":

• Solution: Add credits to OpenAI account
• Check billing settings in OpenAI dashboard

Dev UI Only in Development Mode

The Dev UI pages are only registered in development mode using the @BuildStep(onlyIf = IsDevelopment.class) annotation.

When Dev UI is Available:

• Running with mvn quarkus:dev
• Running with gradle quarkusDev
• Development mode explicitly enabled

When Dev UI is NOT Available:

• Production builds (mvn clean package)
• Native image builds (mvn clean package -Pnative)
• Test mode (mvn test)
• Application running from JAR

Build-Time Condition:

package io.quarkus.deployment;

/**
 * Condition that is true only in development mode.
 * Used to conditionally register Dev UI components.
 */
public class IsDevelopment implements BooleanSupplier {
    @Override
    public boolean getAsBoolean() {
        return LaunchMode.current() == LaunchMode.DEVELOPMENT;
    }
}

This ensures Dev UI code and dependencies are excluded from production builds, reducing application size and attack surface.

Web Component Integration

The Dev UI uses web components for the frontend interface.

Registered Web Components:

Images Component:

• Component: qwc-images.js
• Title: "Images"
• Icon: font-awesome-solid:palette
• Build-time data: imageModelConfigurations (list of config names)

Moderation Component:

• Component: qwc-moderation.js
• Title: "Moderation model"
• Icon: font-awesome-solid:triangle-exclamation
• Build-time data: moderationModelConfigurations (list of config names)

Component Registration:

package io.quarkus.devui.spi.page;

/**
 * Builder for web component pages in Dev UI.
 */
public class Page {

    public static WebComponentPageBuilder webComponentPageBuilder() {
        return new WebComponentPageBuilder();
    }

    public static class WebComponentPageBuilder {
        /**
         * Set page title displayed in Dev UI.
         */
        public WebComponentPageBuilder title(String title);

        /**
         * Set web component JavaScript file.
         */
        public WebComponentPageBuilder componentLink(String componentLink);

        /**
         * Set icon using Font Awesome class.
         */
        public WebComponentPageBuilder icon(String icon);

        public Page build();
    }
}

Testing Without Valid API Key

To test application build and startup without valid OpenAI credentials, disable integration:

quarkus.langchain4j.openai.enable-integration=false

Behavior:

• Application builds and starts successfully
• Dev UI pages are not shown (models are disabled)
• Model beans throw exceptions when used
• No API calls are made

This allows development and testing of application logic without requiring OpenAI API access.

Customizing Dev UI Experience

Hiding Specific Pages:

# Disable image model to hide Images page
quarkus.langchain4j.openai.image-model.enabled=false

# Disable moderation model to hide Moderation page
quarkus.langchain4j.openai.moderation-model.enabled=false

Using Different Models in Dev Mode:

# Use cheaper/faster models in development
%dev.quarkus.langchain4j.openai.image-model.model-name=dall-e-2
%dev.quarkus.langchain4j.openai.image-model.quality=standard

# Use latest models in production
%prod.quarkus.langchain4j.openai.image-model.model-name=dall-e-3
%prod.quarkus.langchain4j.openai.image-model.quality=hd

Verbose Logging for Debugging:

# Enable request/response logging in dev mode
%dev.quarkus.langchain4j.openai.log-requests=true
%dev.quarkus.langchain4j.openai.log-responses=true
%dev.quarkus.langchain4j.openai.log-requests-curl=true

View logs in console to debug Dev UI interactions with OpenAI API.

Dev UI Benefits

Rapid Prototyping

Test OpenAI capabilities without writing code:

• Experiment with different prompts
• Try various parameter combinations
• Validate API key configuration
• Test content moderation rules

Configuration Validation

Verify configuration is correct:

• Test API connectivity
• Validate API key permissions
• Check rate limits
• Confirm model availability

Cost Estimation

Estimate API costs before production:

• Test prompt variations
• Measure token usage
• Compare model pricing
• Optimize parameters for cost

Team Collaboration

Share results with team members:

• Demonstrate capabilities to stakeholders
• Gather requirements through experimentation
• Define moderation policies
• Create example prompts for documentation