Quarkus LangChain4j OpenAI extension provides seamless integration between Quarkus and OpenAI's Large Language Models, enabling developers to easily incorporate LLMs into their applications with support for chat, streaming, embeddings, moderation, and image generation.
Comprehensive configuration system for OpenAI models through Quarkus SmallRye Config. All configuration uses the quarkus.langchain4j.openai prefix and supports both default and named configurations for managing multiple model instances with different settings.
The configuration system is organized hierarchically:
quarkus.langchain4j.openai.*) - Global OpenAI settingsquarkus.langchain4j.openai.chat-model.*) - Settings for specific model typesquarkus.langchain4j.openai.{name}.*) - Multiple independent configurationsThe main configuration interface providing access to default and named configurations.
/**
* Root configuration for the OpenAI extension.
*
* Configuration prefix: quarkus.langchain4j.openai
*/
@ConfigRoot(phase = RUN_TIME)
@ConfigMapping(prefix = "quarkus.langchain4j.openai")
public interface LangChain4jOpenAiConfig {
/**
* Get the default OpenAI configuration.
*
* Access via: quarkus.langchain4j.openai.*
*/
OpenAiConfig defaultConfig();
/**
* Get named OpenAI configurations.
*
* Access via: quarkus.langchain4j.openai.{name}.*
*
* Returns:
* Map of configuration names to OpenAiConfig instances
*/
Map<String, OpenAiConfig> namedConfig();
}Configuration properties that apply to all model types for a given OpenAI instance (default or named).
/**
* Global configuration for an OpenAI instance.
*
* Configuration prefix:
* - Default: quarkus.langchain4j.openai
* - Named: quarkus.langchain4j.openai.{name}
*/
public interface OpenAiConfig {
/**
* Base URL of OpenAI API.
*
* Property: base-url
* Default: "https://api.openai.com/v1/"
*
* Set to a different URL for OpenAI-compatible API providers
* (e.g., OpenShift AI, Azure OpenAI, local providers).
*/
@WithDefault("https://api.openai.com/v1/")
String baseUrl();
/**
* Named TLS configuration to use for HTTPS connections.
*
* Property: tls-configuration-name
* Optional
*
* References a Quarkus named TLS configuration for custom
* certificates, client authentication, etc.
*/
Optional<String> tlsConfigurationName();
/**
* OpenAI API key.
*
* Property: api-key
* Required (default is "dummy" which triggers validation error)
*
* Obtain from: https://platform.openai.com/api-keys
* Format: sk-...
*/
@WithDefault("dummy")
String apiKey();
/**
* OpenAI Organization ID.
*
* Property: organization-id
* Optional
*
* For users belonging to multiple organizations, specify which
* organization is used for API requests. Find at:
* https://platform.openai.com/account/organization
*/
Optional<String> organizationId();
/**
* Timeout for OpenAI API calls.
*
* Property: timeout
* Default: 10s
*
* Maximum time to wait for API responses. Supports duration
* format: 10s, 30s, 1m, etc.
*/
@WithDefault("10s")
Optional<Duration> timeout();
/**
* Maximum number of retry attempts.
*
* Property: max-retries
* Default: 1
* Deprecated: Use MicroProfile Fault Tolerance instead
*
* Value of 1 means no retries (single attempt only).
* Built-in retry is deprecated in favor of MicroProfile Fault Tolerance.
*/
@WithDefault("1")
@Deprecated
Integer maxRetries();
/**
* Enable request logging.
*
* Property: log-requests
* Default: false
*
* Logs full request payloads to OpenAI API.
*/
@WithDefault("false")
Optional<Boolean> logRequests();
/**
* Enable response logging.
*
* Property: log-responses
* Default: false
*
* Logs full response payloads from OpenAI API.
*/
@WithDefault("false")
Optional<Boolean> logResponses();
/**
* Enable curl-style request logging.
*
* Property: log-requests-curl
* Default: false
*
* Logs requests as curl commands for easy debugging and reproduction.
*/
@WithDefault("false")
Optional<Boolean> logRequestsCurl();
/**
* Enable or disable the OpenAI integration.
*
* Property: enable-integration
* Default: true
*
* When false, returns "disabled" model implementations that don't
* make API calls. Useful for testing or feature flags.
*/
@WithDefault("true")
Boolean enableIntegration();
/**
* HTTP proxy type.
*
* Property: proxy-type
* Default: "HTTP"
* Options: "HTTP", "SOCKS"
*
* Type of proxy server to use.
*/
@WithDefault("HTTP")
String proxyType();
/**
* HTTP proxy host.
*
* Property: proxy-host
* Optional
*
* Hostname or IP address of proxy server.
*/
Optional<String> proxyHost();
/**
* HTTP proxy port.
*
* Property: proxy-port
* Default: 3128
*
* Port number of proxy server.
*/
@WithDefault("3128")
Integer proxyPort();
/**
* Chat model configuration.
*
* Access via: quarkus.langchain4j.openai.chat-model.*
*/
ChatModelConfig chatModel();
/**
* Embedding model configuration.
*
* Access via: quarkus.langchain4j.openai.embedding-model.*
*/
EmbeddingModelConfig embeddingModel();
/**
* Moderation model configuration.
*
* Access via: quarkus.langchain4j.openai.moderation-model.*
*/
ModerationModelConfig moderationModel();
/**
* Image model configuration.
*
* Access via: quarkus.langchain4j.openai.image-model.*
*/
ImageModelConfig imageModel();
}Configuration specific to chat and streaming chat models.
/**
* Configuration for OpenAI chat models.
*
* Configuration prefix:
* - Default: quarkus.langchain4j.openai.chat-model
* - Named: quarkus.langchain4j.openai.{name}.chat-model
*/
@ConfigGroup
public interface ChatModelConfig {
/**
* Model name to use.
*
* Property: model-name
* Default: "gpt-4o-mini"
*
* Options include: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo,
* o1-preview, o1-mini (reasoning models), etc.
*/
@WithDefault("gpt-4o-mini")
String modelName();
/**
* Sampling temperature.
*
* Property: temperature
* Default: 1.0
* Range: 0.0 to 2.0
*
* Controls randomness in generation:
* - 0.0: Deterministic, focused responses
* - 1.0: Balanced creativity and consistency
* - 2.0: Maximum randomness and creativity
*
* Recommended: Adjust temperature OR topP, not both.
*/
@WithDefault("1.0")
Double temperature();
/**
* Nucleus sampling (top-p).
*
* Property: top-p
* Default: 1.0
* Range: 0.0 to 1.0
*
* Alternative to temperature sampling. Model considers only tokens
* with top P probability mass:
* - 0.1: Only top 10% probability tokens
* - 1.0: All tokens considered
*
* Recommended: Adjust temperature OR topP, not both.
*/
@WithDefault("1.0")
Double topP();
/**
* Maximum number of tokens (deprecated).
*
* Property: max-tokens
* Optional
* Deprecated: Use max-completion-tokens for newer models
*
* Maximum tokens in the completion. Token count of prompt plus
* max_tokens cannot exceed model's context length.
*/
@Deprecated
Optional<Integer> maxTokens();
/**
* Maximum completion tokens.
*
* Property: max-completion-tokens
* Optional
*
* Upper bound for tokens in completion, including both visible
* output tokens and reasoning tokens (for reasoning models).
* Preferred over deprecated max-tokens.
*/
Optional<Integer> maxCompletionTokens();
/**
* Presence penalty.
*
* Property: presence-penalty
* Default: 0.0
* Range: -2.0 to 2.0
*
* Penalizes tokens based on whether they appear in the text:
* - Positive values: Encourage discussing new topics
* - Negative values: Encourage repetition
* - 0.0: No penalty
*/
@WithDefault("0")
Double presencePenalty();
/**
* Frequency penalty.
*
* Property: frequency-penalty
* Default: 0.0
* Range: -2.0 to 2.0
*
* Penalizes tokens based on frequency in existing text:
* - Positive values: Decrease likelihood of verbatim repetition
* - Negative values: Encourage repetition
* - 0.0: No penalty
*/
@WithDefault("0")
Double frequencyPenalty();
/**
* Enable chat model request logging.
*
* Property: log-requests
* Default: false (inherits from global if not set)
*
* Override global log-requests setting for chat models.
*/
Optional<Boolean> logRequests();
/**
* Enable chat model response logging.
*
* Property: log-responses
* Default: false (inherits from global if not set)
*
* Override global log-responses setting for chat models.
*/
Optional<Boolean> logResponses();
/**
* Response format specification.
*
* Property: response-format
* Optional
*
* Specify output format. For JSON mode, set to "json_object".
* Can also specify JSON schema for structured outputs.
*
* Note: Not all models support all response formats. See OpenAI docs.
*/
Optional<String> responseFormat();
/**
* Enable strict JSON schema validation.
*
* Property: strict-json-schema
* Optional
*
* When true, enforces strict adherence to JSON schema in
* structured outputs feature.
*/
Optional<Boolean> strictJsonSchema();
/**
* Stop sequences.
*
* Property: stop
* Optional
*
* List of strings where generation stops. Up to 4 sequences.
* Model stops generating when any stop sequence appears.
*/
Optional<List<String>> stop();
/**
* Reasoning effort for reasoning models.
*
* Property: reasoning-effort
* Optional
* Options: "minimal", "low", "medium", "high"
*
* Controls computational effort for reasoning models (o1 series).
* Lower effort produces faster responses with fewer reasoning tokens.
*
* Note: gpt-5-pro defaults to high effort and doesn't support other values.
*/
Optional<String> reasoningEffort();
/**
* Service tier for request processing.
*
* Property: service-tier
* Default: "default"
* Options: "auto", "default", "flex", "priority"
*
* Controls processing priority and pricing:
* - auto: Uses project settings
* - default: Standard pricing and performance
* - flex: Flexible processing tier
* - priority: Prioritized processing
*
* Response includes actual service_tier used (may differ from request).
*/
@WithDefault("default")
Optional<String> serviceTier();
}Configuration specific to embedding models.
/**
* Configuration for OpenAI embedding models.
*
* Configuration prefix:
* - Default: quarkus.langchain4j.openai.embedding-model
* - Named: quarkus.langchain4j.openai.{name}.embedding-model
*/
@ConfigGroup
public interface EmbeddingModelConfig {
/**
* Model name to use.
*
* Property: model-name
* Default: "text-embedding-ada-002"
*
* Options include: text-embedding-3-large, text-embedding-3-small,
* text-embedding-ada-002 (legacy), etc.
*/
@WithDefault("text-embedding-ada-002")
String modelName();
/**
* Enable embedding model request logging.
*
* Property: log-requests
* Default: false (inherits from global if not set)
*
* Override global log-requests setting for embedding models.
*/
Optional<Boolean> logRequests();
/**
* Enable embedding model response logging.
*
* Property: log-responses
* Default: false (inherits from global if not set)
*
* Override global log-responses setting for embedding models.
*/
Optional<Boolean> logResponses();
/**
* End-user identifier.
*
* Property: user
* Optional
*
* Unique identifier representing end-user. Helps OpenAI monitor
* and detect abuse. Should be consistent per user.
*/
Optional<String> user();
}Configuration specific to moderation models.
/**
* Configuration for OpenAI moderation models.
*
* Configuration prefix:
* - Default: quarkus.langchain4j.openai.moderation-model
* - Named: quarkus.langchain4j.openai.{name}.moderation-model
*/
@ConfigGroup
public interface ModerationModelConfig {
/**
* Model name to use.
*
* Property: model-name
* Default: "omni-moderation-latest"
*
* Options include: omni-moderation-latest, omni-moderation-2024-09-26,
* text-moderation-latest, text-moderation-stable, etc.
*/
@WithDefault("omni-moderation-latest")
String modelName();
/**
* Enable moderation model request logging.
*
* Property: log-requests
* Default: false (inherits from global if not set)
*
* Override global log-requests setting for moderation models.
*/
Optional<Boolean> logRequests();
/**
* Enable moderation model response logging.
*
* Property: log-responses
* Default: false (inherits from global if not set)
*
* Override global log-responses setting for moderation models.
*/
Optional<Boolean> logResponses();
}Configuration specific to image generation models (DALL-E).
/**
* Configuration for OpenAI image models (DALL-E).
*
* Configuration prefix:
* - Default: quarkus.langchain4j.openai.image-model
* - Named: quarkus.langchain4j.openai.{name}.image-model
*/
@ConfigGroup
public interface ImageModelConfig {
/**
* Model name to use.
*
* Property: model-name
* Default: "dall-e-3"
* Options: "dall-e-3", "dall-e-2"
*
* DALL-E 3 provides higher quality and more control.
* DALL-E 2 supports generating multiple images per request.
*/
@WithDefault("dall-e-3")
String modelName();
/**
* Enable image persistence to disk.
*
* Property: persist
* Default: false
*
* When true, generated images are automatically saved to disk.
* Implicitly enabled when persist-directory is set.
*/
Optional<Boolean> persist();
/**
* Directory for persisting generated images.
*
* Property: persist-directory
* Default: ${java.io.tmpdir}/dall-e-images
*
* Path where images are saved when persistence is enabled.
* Directory is created if it doesn't exist.
*/
@WithDefault("${java.io.tmpdir}/dall-e-images")
Optional<Path> persistDirectory();
/**
* Response format for generated images.
*
* Property: response-format
* Default: "url"
* Options: "url", "b64_json"
*
* Format of returned images:
* - url: HTTP URL to image (hosted by OpenAI temporarily)
* - b64_json: Base64-encoded image data
*/
@WithDefault("url")
String responseFormat();
/**
* Size of generated images.
*
* Property: size
* Default: "1024x1024"
*
* DALL-E 3 options: "1024x1024", "1792x1024", "1024x1792"
* DALL-E 2 options: "256x256", "512x512", "1024x1024"
*/
@WithDefault("1024x1024")
String size();
/**
* Quality of generated images.
*
* Property: quality
* Default: "standard"
* Options: "standard", "hd"
*
* DALL-E 3 only. "hd" creates images with finer details and
* greater consistency, at higher cost.
*/
@WithDefault("standard")
String quality();
/**
* Number of images to generate.
*
* Property: number
* Default: 1
* Range: 1-10
*
* Note: DALL-E 3 only supports n=1.
* DALL-E 2 supports 1-10 images.
*/
@WithDefault("1")
int number();
/**
* Style of generated images.
*
* Property: style
* Default: "vivid"
* Options: "vivid", "natural"
*
* DALL-E 3 only:
* - vivid: Hyper-real and dramatic images
* - natural: More natural, less hyper-real images
*/
@WithDefault("vivid")
String style();
/**
* End-user identifier.
*
* Property: user
* Optional
*
* Unique identifier representing end-user. Helps OpenAI monitor
* and detect abuse.
*/
Optional<String> user();
/**
* Enable image model request logging.
*
* Property: log-requests
* Default: false (inherits from global if not set)
*
* Override global log-requests setting for image models.
*/
Optional<Boolean> logRequests();
/**
* Enable image model response logging.
*
* Property: log-responses
* Default: false (inherits from global if not set)
*
* Override global log-responses setting for image models.
*/
Optional<Boolean> logResponses();
}Minimal configuration for getting started:
quarkus.langchain4j.openai.api-key=sk-your-api-keyThis uses all defaults: gpt-4o-mini for chat, standard timeouts, no logging.
Full configuration with all common options:
# Global OpenAI settings
quarkus.langchain4j.openai.api-key=sk-your-api-key
quarkus.langchain4j.openai.base-url=https://api.openai.com/v1/
quarkus.langchain4j.openai.organization-id=org-your-organization
quarkus.langchain4j.openai.timeout=30s
quarkus.langchain4j.openai.log-requests=true
quarkus.langchain4j.openai.log-responses=true
# Chat model settings
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o
quarkus.langchain4j.openai.chat-model.temperature=0.7
quarkus.langchain4j.openai.chat-model.max-completion-tokens=4096
quarkus.langchain4j.openai.chat-model.presence-penalty=0.1
quarkus.langchain4j.openai.chat-model.frequency-penalty=0.1
# Embedding model settings
quarkus.langchain4j.openai.embedding-model.model-name=text-embedding-3-large
# Image model settings
quarkus.langchain4j.openai.image-model.model-name=dall-e-3
quarkus.langchain4j.openai.image-model.size=1792x1024
quarkus.langchain4j.openai.image-model.quality=hd
quarkus.langchain4j.openai.image-model.persist=trueConfigure different model instances for different use cases:
# Default configuration (cost-effective)
quarkus.langchain4j.openai.api-key=sk-default-key
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
quarkus.langchain4j.openai.chat-model.temperature=0.3
# Premium configuration (high quality)
quarkus.langchain4j.openai.premium.api-key=sk-premium-key
quarkus.langchain4j.openai.premium.chat-model.model-name=gpt-4o
quarkus.langchain4j.openai.premium.chat-model.temperature=0.7
quarkus.langchain4j.openai.premium.chat-model.max-completion-tokens=8192
# Creative configuration (high temperature)
quarkus.langchain4j.openai.creative.api-key=sk-creative-key
quarkus.langchain4j.openai.creative.chat-model.model-name=gpt-4o
quarkus.langchain4j.openai.creative.chat-model.temperature=1.5
# Reasoning configuration (o1 models)
quarkus.langchain4j.openai.reasoning.api-key=sk-reasoning-key
quarkus.langchain4j.openai.reasoning.chat-model.model-name=o1-preview
quarkus.langchain4j.openai.reasoning.chat-model.reasoning-effort=high
quarkus.langchain4j.openai.reasoning.chat-model.max-completion-tokens=32768Configuration for enterprise environments with proxies and TLS:
# Global settings
quarkus.langchain4j.openai.api-key=sk-your-api-key
quarkus.langchain4j.openai.timeout=60s
# TLS configuration
quarkus.langchain4j.openai.tls-configuration-name=openai-tls
# HTTP proxy
quarkus.langchain4j.openai.proxy-type=HTTP
quarkus.langchain4j.openai.proxy-host=proxy.company.com
quarkus.langchain4j.openai.proxy-port=8080
# Logging for audit
quarkus.langchain4j.openai.log-requests=true
quarkus.langchain4j.openai.log-responses=true
quarkus.langchain4j.openai.log-requests-curl=trueConfigure for OpenShift AI or other OpenAI-compatible APIs:
# OpenShift AI configuration
quarkus.langchain4j.openai.base-url=https://your-openshift-ai-endpoint.com/v1/
quarkus.langchain4j.openai.api-key=your-openshift-key
quarkus.langchain4j.openai.tls-configuration-name=openshift-tlsConfigure for structured JSON outputs:
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o
quarkus.langchain4j.openai.chat-model.response-format=json_object
quarkus.langchain4j.openai.chat-model.strict-json-schema=true
quarkus.langchain4j.openai.chat-model.temperature=0.0Optimize for OpenAI's reasoning models (o1 series):
quarkus.langchain4j.openai.chat-model.model-name=o1-preview
quarkus.langchain4j.openai.chat-model.reasoning-effort=medium
quarkus.langchain4j.openai.chat-model.max-completion-tokens=32768
quarkus.langchain4j.openai.chat-model.service-tier=priority
quarkus.langchain4j.openai.timeout=120sUse profiles for different environments:
# Development (application-dev.properties)
quarkus.langchain4j.openai.api-key=sk-dev-key
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
quarkus.langchain4j.openai.log-requests=true
quarkus.langchain4j.openai.log-responses=true
# Production (application-prod.properties)
quarkus.langchain4j.openai.api-key=sk-prod-key
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o
quarkus.langchain4j.openai.log-requests=false
quarkus.langchain4j.openai.log-responses=false
quarkus.langchain4j.openai.tls-configuration-name=prod-tls
quarkus.langchain4j.openai.proxy-host=proxy.company.comDisable API calls for testing:
%test.quarkus.langchain4j.openai.enable-integration=falseThis returns "disabled" model implementations that don't make actual API calls.
All properties follow the pattern:
quarkus.langchain4j.openai[.{name}][.{model-type}].{property}Where:
{name} is optional for named configurations{model-type} is one of: chat-model, embedding-model, moderation-model, image-model{property} is the specific configuration propertyProperties are resolved with the following precedence (highest to lowest):
quarkus.langchain4j.openai.{name}.{model-type}.{property}quarkus.langchain4j.openai.{name}.{property}quarkus.langchain4j.openai.{model-type}.{property}quarkus.langchain4j.openai.{property}For example, log-requests can be set at:
// Duration type (used for timeouts)
// Format: <number><unit> where unit is: s (seconds), m (minutes), h (hours)
// Examples: "10s", "30s", "2m", "1h"
java.time.Duration
// Path type (used for directories)
// Format: Absolute or relative filesystem path
// Examples: "/tmp/images", "./generated", "${java.io.tmpdir}/dall-e"
java.nio.file.Path
// Proxy type
java.net.ProxyThe extension validates configuration at startup:
api-key is "dummy" (default) and base-url is the default OpenAI URL, startup fails with configuration errormax-retries must be >= 1, number must be 1-10quality, style) only work with specific models (DALL-E 3)configName must exist in configurationNever commit API keys - Use environment variables or secret management:
quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}Use different keys per environment - Dev, test, prod should have separate keys
Set appropriate timeouts - Prevent hanging requests
Enable logging selectively - Logging may expose sensitive data
Choose appropriate models - gpt-4o-mini is faster and cheaper for simple tasks
Set max-completion-tokens - Limit token usage and costs
Use streaming - For better UX in interactive applications
Configure reasonable timeouts - Balance responsiveness and success rate
Use appropriate temperature - Lower temperature (0.0-0.3) for deterministic tasks reduces variation
Limit max tokens - Set max-completion-tokens to prevent runaway generation
Choose right model - Don't use gpt-4o when gpt-4o-mini suffices
Use embeddings wisely - text-embedding-3-small is cheaper than text-embedding-3-large
Use named configurations - Group related settings together
Document configuration - Add comments explaining why specific values are used
Use profiles - Separate dev/test/prod configurations
Centralize common settings - Use global properties where appropriate
Install with Tessl CLI
npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-openai@1.7.0