tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-openai-deployment

Quarkus extension deployment module for OpenAI integration with LangChain4j providing build-time processing and CDI bean generation

Overview

Eval results

Files

Quarkus LangChain4j OpenAI Deployment

Name: tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-openai-deployment
Author: tessl

A Quarkus extension deployment module that provides build-time processing and configuration for integrating OpenAI language models into Quarkus applications through LangChain4j. This module handles CDI bean generation, native image configuration, and service provider registration during the Quarkus build augmentation phase.

Package Information

Package Name: quarkus-langchain4j-openai-deployment
Maven Coordinates: io.quarkiverse.langchain4j:quarkus-langchain4j-openai-deployment:1.7.4
Language: Java
Type: Quarkus Deployment Module (Build-time Extension)
Installation: Add the runtime dependency quarkus-langchain4j-openai to your project (deployment module is automatically included)

Installation

Add this dependency to your Quarkus project's pom.xml:

<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-openai</artifactId>
    <version>1.7.4</version>
</dependency>

The deployment module is automatically included as a transitive dependency and provides build-time processing.

Core Imports

Standard imports for using OpenAI models via CDI injection:

// CDI injection
import jakarta.inject.Inject;

// Model interfaces from LangChain4j
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.chat.StreamingChatLanguageModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.moderation.ModerationModel;
import dev.langchain4j.model.image.ImageModel;

// Named model qualifier
import io.quarkiverse.langchain4j.ModelName;

// Common types for model interactions
import dev.langchain4j.data.message.ChatMessage;
import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.data.image.Image;
import dev.langchain4j.model.moderation.Moderation;
import dev.langchain4j.model.output.Response;

// For streaming responses
import dev.langchain4j.model.output.StreamingResponseHandler;

// For observability
import dev.langchain4j.model.chat.listener.ChatModelListener;

For Quarkus extension authors working with build items:

// Build items from core LangChain4j extension
import io.quarkiverse.langchain4j.deployment.items.ChatModelProviderCandidateBuildItem;
import io.quarkiverse.langchain4j.deployment.items.EmbeddingModelProviderCandidateBuildItem;
import io.quarkiverse.langchain4j.deployment.items.ModerationModelProviderCandidateBuildItem;
import io.quarkiverse.langchain4j.deployment.items.ImageModelProviderCandidateBuildItem;
import io.quarkiverse.langchain4j.deployment.items.SelectedChatModelProviderBuildItem;
import io.quarkiverse.langchain4j.deployment.items.SelectedEmbeddingModelCandidateBuildItem;
import io.quarkiverse.langchain4j.deployment.items.SelectedModerationModelProviderBuildItem;
import io.quarkiverse.langchain4j.deployment.items.SelectedImageModelProviderBuildItem;

// Quarkus build items
import io.quarkus.deployment.builditem.FeatureBuildItem;
import io.quarkus.arc.deployment.SyntheticBeanBuildItem;
import io.quarkus.deployment.builditem.nativeimage.ServiceProviderBuildItem;
import io.quarkus.deployment.builditem.nativeimage.ReflectiveClassBuildItem;

// Quarkus deployment APIs
import io.quarkus.deployment.annotations.BuildStep;
import io.quarkus.deployment.annotations.Record;
import io.quarkus.deployment.annotations.ExecutionTime;
import io.quarkus.deployment.builditem.BuildProducer;

Basic Usage

Configure OpenAI integration in application.properties:

quarkus.langchain4j.openai.api-key=sk-your-api-key-here
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
quarkus.langchain4j.openai.embedding-model.model-name=text-embedding-3-small

Inject and use OpenAI models in your application via CDI:

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.output.Response;
import jakarta.inject.Inject;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;

@ApplicationScoped
public class MyService {

    @Inject
    ChatLanguageModel chatModel;

    @Inject
    EmbeddingModel embeddingModel;

    public String askQuestion(String question) {
        return chatModel.generate(question);
    }

    public float[] getEmbedding(String text) {
        Response<Embedding> response = embeddingModel.embed(TextSegment.from(text));
        return response.content().vector();
    }
}

The deployment module automatically creates CDI beans for all enabled model types (chat, embedding, moderation, image) based on your configuration. Beans are injected using standard CDI @Inject and can be qualified with @ModelName for named configurations.

Architecture

This deployment module follows the Quarkus extension pattern with separation between build-time (deployment) and runtime concerns:

Build-Time Processing (Deployment Module)

Configuration Processing: Validates and processes build-time configuration for model enablement
Provider Registration: Registers OpenAI as a candidate provider for chat, embedding, moderation, and image models
Bean Generation: Creates synthetic CDI beans for selected model types with proper scopes and qualifiers
Native Image Support: Registers service providers and reflective classes for GraalVM native compilation
Dev UI Integration: Provides development-time UI for testing image and moderation models

Runtime Processing (Runtime Module)

Configuration Loading: Processes runtime configuration properties for API keys, timeouts, model parameters
Model Instantiation: Creates LangChain4j OpenAI model instances with Quarkus-specific enhancements
Resource Management: Handles lifecycle, shutdown, and cleanup of OpenAI clients

Capabilities

Configuration

Comprehensive configuration system supporting four model types (chat, embedding, moderation, image) with global and model-specific settings, multiple named configurations, proxy support, and fine-grained logging control.

# Global settings
quarkus.langchain4j.openai.base-url=https://api.openai.com/v1/
quarkus.langchain4j.openai.api-key=sk-...
quarkus.langchain4j.openai.timeout=10s
quarkus.langchain4j.openai.log-requests=false

# Chat model settings
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
quarkus.langchain4j.openai.chat-model.temperature=1.0

Configuration Reference

CDI Beans

Automatic CDI bean generation for injectable model instances with support for default and named configurations, allowing applications to use OpenAI models through dependency injection without manual instantiation.

@Inject
ChatLanguageModel chatModel;

@Inject
StreamingChatLanguageModel streamingChatModel;

@Inject
EmbeddingModel embeddingModel;

@Inject
ModerationModel moderationModel;

@Inject
ImageModel imageModel;

CDI Beans Reference

Build Items

Build items produced and consumed by this deployment module for integration with other Quarkus extensions, enabling extensibility and composition of AI capabilities.

Produces:

Provider candidate build items for model selection
Synthetic bean build items for CDI integration
Service provider and reflective class build items for native image support
Dev UI build items for development-time testing

Build Items Reference

Development UI

Development-time UI integration for testing image generation and content moderation models directly from Quarkus Dev UI without writing code, including configuration selection and real-time testing.

Available in development mode at http://localhost:8080/q/dev-ui

Development UI Guide

Runtime Components

Runtime classes and APIs including the enhanced QuarkusOpenAiClient, model builder factories, and configuration classes for advanced use cases and programmatic model creation.

QuarkusOpenAiClient.Builder builder = QuarkusOpenAiClient.builder()
    .baseUrl("https://api.openai.com/v1/")
    .openAiApiKey(apiKey)
    .configName("custom")
    .tlsConfigurationName("my-tls")
    .proxy(proxy)
    .logCurl(true);

Runtime Components Reference

Named Configurations

The extension supports multiple named OpenAI configurations for scenarios requiring different API keys, models, or settings:

# Default configuration
quarkus.langchain4j.openai.api-key=sk-default-key
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini

# Named configuration "premium"
quarkus.langchain4j.openai.premium.api-key=sk-premium-key
quarkus.langchain4j.openai.premium.chat-model.model-name=gpt-4o

Inject named models using the @ModelName qualifier:

@Inject
@ModelName("premium")
ChatLanguageModel premiumModel;

Native Image Support

The deployment module provides complete GraalVM native image support through:

Service provider registration for SPI mechanism
Reflective class registration for JSON serialization
Build-time configuration processing
Synthetic CDI bean generation compatible with native compilation

Build a native executable:

mvn clean package -Pnative

Common Types

Core type definitions used across all model types for requests, responses, and data structures.

Response Type

Generic response wrapper containing model output and metadata.

package dev.langchain4j.model.output;

/**
 * Generic response wrapper for model outputs.
 * Contains the response content and metadata about token usage and finish reason.
 */
public class Response<T> {

    /**
     * Get the response content.
     */
    public T content();

    /**
     * Get token usage information.
     */
    public TokenUsage tokenUsage();

    /**
     * Get the reason why generation finished.
     */
    public FinishReason finishReason();
}

/**
 * Token usage information for API calls.
 */
public class TokenUsage {
    /**
     * Number of tokens in the input.
     */
    public Integer inputTokenCount();

    /**
     * Number of tokens in the output.
     */
    public Integer outputTokenCount();

    /**
     * Total number of tokens used.
     */
    public Integer totalTokenCount();
}

/**
 * Reason why model generation finished.
 */
public enum FinishReason {
    /** Generation completed naturally */
    STOP,
    /** Generation stopped due to length limit */
    LENGTH,
    /** Generation stopped due to content filter */
    CONTENT_FILTER,
    /** Other reason */
    OTHER
}

Chat Message Types

Message types for conversational AI interactions.

package dev.langchain4j.data.message;

/**
 * Base interface for chat messages.
 */
public interface ChatMessage {
    /**
     * Get the message type.
     */
    ChatMessageType type();

    /**
     * Get the message text content.
     */
    String text();
}

/**
 * Message type enumeration.
 */
public enum ChatMessageType {
    SYSTEM,
    USER,
    AI,
    TOOL_EXECUTION_RESULT
}

/**
 * AI-generated message in a conversation.
 */
public class AiMessage implements ChatMessage {
    /**
     * Create an AI message with text content.
     */
    public static AiMessage from(String text);

    /**
     * Get the text content of the message.
     */
    public String text();
}

/**
 * User message in a conversation.
 */
public class UserMessage implements ChatMessage {
    /**
     * Create a user message with text content.
     */
    public static UserMessage from(String text);

    /**
     * Get the text content of the message.
     */
    public String text();
}

/**
 * System message providing context or instructions.
 */
public class SystemMessage implements ChatMessage {
    /**
     * Create a system message with text content.
     */
    public static SystemMessage from(String text);

    /**
     * Get the text content of the message.
     */
    public String text();
}

Embedding Types

Types for text embeddings and vector representations.

package dev.langchain4j.data.embedding;

/**
 * Vector embedding representation of text.
 */
public class Embedding {
    /**
     * Get the embedding vector as float array.
     */
    public float[] vector();

    /**
     * Get the dimensionality of the embedding.
     */
    public int dimension();
}

package dev.langchain4j.data.segment;

/**
 * Text segment for embedding.
 */
public class TextSegment {
    /**
     * Create a text segment from a string.
     */
    public static TextSegment from(String text);

    /**
     * Get the text content.
     */
    public String text();
}

Image Types

Types for image generation and manipulation.

package dev.langchain4j.data.image;

/**
 * Image data and metadata.
 */
public class Image {
    /**
     * Get the image URL (when response format is URL).
     */
    public URI url();

    /**
     * Get base64-encoded image data (when response format is b64_json).
     */
    public String base64Data();

    /**
     * Get the revised prompt used for generation (DALL-E 3).
     */
    public String revisedPrompt();
}

Moderation Types

Types for content moderation and safety checks.

package dev.langchain4j.model.moderation;

/**
 * Content moderation result with category flags and scores.
 */
public class Moderation {
    /**
     * Whether content was flagged as potentially harmful.
     */
    public boolean flagged();

    /**
     * Content expressing hatred toward groups based on identity.
     */
    public boolean hate();

    /**
     * Hateful content that includes violence or serious harm.
     */
    public boolean hateThreatening();

    /**
     * Content promoting self-harm or suicide.
     */
    public boolean selfHarm();

    /**
     * Sexual content intended to arouse.
     */
    public boolean sexual();

    /**
     * Sexual content involving minors.
     */
    public boolean sexualMinors();

    /**
     * Content depicting violence.
     */
    public boolean violence();

    /**
     * Graphic violent content.
     */
    public boolean violenceGraphic();

    /**
     * Get category scores (0.0 to 1.0).
     */
    public ModerationScore scores();
}

Streaming Types

Types for streaming responses from chat models.

package dev.langchain4j.model.output;

/**
 * Handler for streaming response tokens.
 * Receives tokens as they are generated in real-time.
 */
public interface StreamingResponseHandler<T> {
    /**
     * Called when a new token is generated.
     * @param token The generated token
     */
    void onNext(String token);

    /**
     * Called when streaming completes successfully.
     * @param response The complete response with metadata
     */
    void onComplete(Response<T> response);

    /**
     * Called when an error occurs during streaming.
     * @param error The error that occurred
     */
    void onError(Throwable error);
}

Model Types

Chat Models

Conversational AI models supporting single-turn and multi-turn conversations with extensive parameter control (temperature, top-p, tokens, penalties) and structured output support.

Default model: gpt-4o-mini

Streaming Chat Models

Same as chat models but with streaming response support for real-time token generation and progressive UI updates.

Embedding Models

Text embedding models for converting text into numerical vector representations for semantic search, similarity comparison, and RAG applications.

Default model: text-embedding-ada-002

Moderation Models

Content moderation models for detecting potentially harmful content across multiple categories including hate speech, self-harm, sexual content, and violence.

Default model: omni-moderation-latest

Image Models

Image generation models (DALL-E) for creating images from text descriptions with configurable size, quality, style, and persistence options.

Default model: dall-e-3

Integration Features

Chat Model Listeners

The deployment module supports injection of ChatModelListener instances into chat and streaming chat models for:

Request/response logging
Metrics collection
Custom observability
Audit trails

Listeners are automatically discovered and injected via CDI.

Proxy Support

Built-in HTTP/HTTPS proxy configuration for corporate environments:

quarkus.langchain4j.openai.proxy-type=HTTP
quarkus.langchain4j.openai.proxy-host=proxy.example.com
quarkus.langchain4j.openai.proxy-port=8080

TLS Configuration

Integration with Quarkus TLS configuration for custom certificates and SSL/TLS settings:

quarkus.langchain4j.openai.tls-configuration-name=my-tls-config

Observability

Integration with Quarkus observability stack including:

Request/response logging with cURL format support
Metrics collection via listeners
Distributed tracing support
Cost estimation for token usage

Disabling Integration

The extension can be completely disabled without breaking the build:

quarkus.langchain4j.openai.enable-integration=false

When disabled, the deployment module produces "disabled" model instances that throw descriptive exceptions, allowing compilation and testing without valid OpenAI credentials.

Build-Time Model Enablement

Individual model types can be disabled at build time to reduce application size and startup time:

quarkus.langchain4j.openai.chat-model.enabled=true
quarkus.langchain4j.openai.embedding-model.enabled=false
quarkus.langchain4j.openai.moderation-model.enabled=false
quarkus.langchain4j.openai.image-model.enabled=false

Disabled models will not produce CDI beans or register service providers.

Extension Authors

Extension developers can integrate with this deployment module by:

Consuming provider candidate build items to check OpenAI availability
Consuming selected provider build items to access configured models
Injecting generated CDI beans in their own synthetic beans
Producing additional listeners or interceptors for model customization

See Build Items Reference for details on build item APIs.

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-openai-deployment

docs

runtime-components.md

tile.json