OpenAI Chat Models
OpenAI is a leading AI research organization known for its groundbreaking Large Language Models (LLMs) like GPT-4.
It provides various chat models, which are specialized LLMs designed for conversational tasks such as chatbots, virtual assistants, and interactive applications. These models also support advanced capabilities like reasoning and function calling.
|
This extension can be used with any provider that supports OpenAI-compatible APIs, including OpenAI itself, OpenShift AI, and others. If you’re using a provider other than OpenAI, ensure that the authentication and endpoint configuration are set up accordingly. |
Prerequisites
OpenAI Account and API Key
To use OpenAI models in your Quarkus application:
-
Generate an API key from the API Keys page.
-
Add the following to your
application.properties:quarkus.langchain4j.openai.api-key=sk-...
|
Use environment variables
You can use the environment variable |
|
Using configuration placeholders
You can also reference an environment variable directly in your properties file: |
OpenAI Quarkus Extension
To enable OpenAI chat model support, add the following dependency to your pom.xml:
<dependency>
<groupId>io.quarkiverse.langchain4j</groupId>
<artifactId>quarkus-langchain4j-openai</artifactId>
<version>1.15.0.CR2</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-openai</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 |
|
This extension also provides:
These are enabled by default and can be configured separately. |
Configuration
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Base URL of OpenAI API Environment variable: |
string |
|
If set, the named TLS configuration with the configured name will be applied to the REST Client Environment variable: |
string |
|
OpenAI API key Environment variable: |
string |
|
Environment variable: |
string |
|
Timeout for OpenAI calls Environment variable: |
|
|
The maximum number of times to retry. 1 means exactly one attempt, with retrying disabled. Environment variable: |
int |
|
Whether the OpenAI client should log requests Environment variable: |
boolean |
|
Whether the OpenAI client should log responses Environment variable: |
boolean |
|
Whether the OpenAI client should log requests as cURL commands Environment variable: |
boolean |
|
Whether to enable the integration. Defaults to Environment variable: |
boolean |
|
Proxy configuration name. There are some rules for using Quarkus Proxy Registry configuration:
Environment variable: |
string |
|
Which OpenAI API the chat model should target.
When not set, the mode is selected automatically: Environment variable: |
|
|
Model name to use Environment variable: |
string |
|
What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. If not set, the parameter is omitted from the request and the model’s own default applies. Environment variable: |
double |
|
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or temperature, but not both. If not set, the parameter is omitted from the request and the model’s own default applies. Environment variable: |
double |
|
An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. Environment variable: |
int |
|
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. Environment variable: |
double |
|
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. Environment variable: |
double |
|
Whether chat model requests should be logged Environment variable: |
boolean |
|
Whether chat model responses should be logged Environment variable: |
boolean |
|
The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. Environment variable: |
string |
|
Whether responses follow JSON Schema for Structured Outputs Environment variable: |
boolean |
|
The list of stop words to use. Environment variable: |
list of string |
|
Constrains effort on reasoning for reasoning models. Currently supported values are Note: The Environment variable: |
string |
|
Specifies the processing type used for serving the request. If set to When the service tier parameter is set, the response body will include the Environment variable: |
string |
|
Whether to store the generated model response for later retrieval via the Responses API. Environment variable: |
boolean |
|
The unique ID of the previous response to the model, used to create multi-turn conversations. Environment variable: |
string |
|
A summary of the reasoning performed by the model, for reasoning models. Supported values are Environment variable: |
string |
|
An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. Environment variable: |
int |
|
The maximum number of total calls to built-in tools that can be processed in a response. Environment variable: |
int |
|
Whether to allow the model to run tool calls in parallel. Environment variable: |
boolean |
|
Additional output data to include in the model response. Environment variable: |
list of string |
|
The truncation strategy to use for the model response. Supported values are Environment variable: |
string |
|
Constrains the verbosity of the model’s response. Supported values are Environment variable: |
string |
|
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Environment variable: |
string |
|
The retention policy for the prompt cache. Environment variable: |
string |
|
A stable identifier used to help detect users of your application that may be violating OpenAI’s usage policies. Environment variable: |
string |
|
The number of most likely tokens to return at each token position, each with an associated log probability. Environment variable: |
int |
|
Whether to enforce strict schema validation on tool/function definitions. Environment variable: |
boolean |
|
Whether obfuscation fields should be included in streaming events. Only applies to the streaming chat model. Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether embedding model requests should be logged Environment variable: |
boolean |
|
Whether embedding model responses should be logged Environment variable: |
boolean |
|
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Environment variable: |
string |
|
Model name to use Environment variable: |
string |
|
Whether moderation model requests should be logged Environment variable: |
boolean |
|
Whether moderation model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when Environment variable: |
boolean |
|
The path where the generated images will be persisted to disk. This only applies of Environment variable: |
path |
|
The size of the generated images. Supported values: Environment variable: |
string |
|
The quality of the image that will be generated. Supported values: Environment variable: |
string |
|
The number of images to generate. Must be between 1 and 10. Environment variable: |
int |
|
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Environment variable: |
string |
|
The output format of the generated image. Supported values: Only supported for Environment variable: |
string |
|
The background type for the generated image. Supported values: Only supported for Environment variable: |
string |
|
The compression level for the generated image (0-100). Only supported for Environment variable: |
int |
|
The moderation level for the image generation request. Supported values: Only supported for Environment variable: |
string |
|
Whether image model requests should be logged Environment variable: |
boolean |
|
Whether image model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether audio transcription model requests should be logged Environment variable: |
boolean |
|
Whether audio transcription model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether decision model requests should be logged Environment variable: |
boolean |
|
Whether decision model responses should be logged Environment variable: |
boolean |
|
This property is deprecated: Use The Proxy type Environment variable: |
string |
|
This property is deprecated: Use The Proxy host Environment variable: |
string |
|
This property is deprecated: Use The Proxy port Environment variable: |
int |
|
This property is deprecated: For newer OpenAI models, use The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens can’t exceed the model’s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096). Environment variable: |
int |
|
Type |
Default |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Whether the model should be enabled Environment variable: |
boolean |
|
Base URL of OpenAI API Environment variable: |
string |
|
If set, the named TLS configuration with the configured name will be applied to the REST Client Environment variable: |
string |
|
OpenAI API key Environment variable: |
string |
|
Environment variable: |
string |
|
Timeout for OpenAI calls Environment variable: |
|
|
The maximum number of times to retry. 1 means exactly one attempt, with retrying disabled. Environment variable: |
int |
|
Whether the OpenAI client should log requests Environment variable: |
boolean |
|
Whether the OpenAI client should log responses Environment variable: |
boolean |
|
Whether the OpenAI client should log requests as cURL commands Environment variable: |
boolean |
|
Whether to enable the integration. Defaults to Environment variable: |
boolean |
|
Proxy configuration name. There are some rules for using Quarkus Proxy Registry configuration:
Environment variable: |
string |
|
Which OpenAI API the chat model should target.
When not set, the mode is selected automatically: Environment variable: |
|
|
Model name to use Environment variable: |
string |
|
What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. If not set, the parameter is omitted from the request and the model’s own default applies. Environment variable: |
double |
|
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or temperature, but not both. If not set, the parameter is omitted from the request and the model’s own default applies. Environment variable: |
double |
|
An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. Environment variable: |
int |
|
Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. Environment variable: |
double |
|
Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. Environment variable: |
double |
|
Whether chat model requests should be logged Environment variable: |
boolean |
|
Whether chat model responses should be logged Environment variable: |
boolean |
|
The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. Environment variable: |
string |
|
Whether responses follow JSON Schema for Structured Outputs Environment variable: |
boolean |
|
The list of stop words to use. Environment variable: |
list of string |
|
Constrains effort on reasoning for reasoning models. Currently supported values are Note: The Environment variable: |
string |
|
Specifies the processing type used for serving the request. If set to When the service tier parameter is set, the response body will include the Environment variable: |
string |
|
Whether to store the generated model response for later retrieval via the Responses API. Environment variable: |
boolean |
|
The unique ID of the previous response to the model, used to create multi-turn conversations. Environment variable: |
string |
|
A summary of the reasoning performed by the model, for reasoning models. Supported values are Environment variable: |
string |
|
An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. Environment variable: |
int |
|
The maximum number of total calls to built-in tools that can be processed in a response. Environment variable: |
int |
|
Whether to allow the model to run tool calls in parallel. Environment variable: |
boolean |
|
Additional output data to include in the model response. Environment variable: |
list of string |
|
The truncation strategy to use for the model response. Supported values are Environment variable: |
string |
|
Constrains the verbosity of the model’s response. Supported values are Environment variable: |
string |
|
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Environment variable: |
string |
|
The retention policy for the prompt cache. Environment variable: |
string |
|
A stable identifier used to help detect users of your application that may be violating OpenAI’s usage policies. Environment variable: |
string |
|
The number of most likely tokens to return at each token position, each with an associated log probability. Environment variable: |
int |
|
Whether to enforce strict schema validation on tool/function definitions. Environment variable: |
boolean |
|
Whether obfuscation fields should be included in streaming events. Only applies to the streaming chat model. Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether embedding model requests should be logged Environment variable: |
boolean |
|
Whether embedding model responses should be logged Environment variable: |
boolean |
|
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Environment variable: |
string |
|
Model name to use Environment variable: |
string |
|
Whether moderation model requests should be logged Environment variable: |
boolean |
|
Whether moderation model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when Environment variable: |
boolean |
|
The path where the generated images will be persisted to disk. This only applies of Environment variable: |
path |
|
The size of the generated images. Supported values: Environment variable: |
string |
|
The quality of the image that will be generated. Supported values: Environment variable: |
string |
|
The number of images to generate. Must be between 1 and 10. Environment variable: |
int |
|
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Environment variable: |
string |
|
The output format of the generated image. Supported values: Only supported for Environment variable: |
string |
|
The background type for the generated image. Supported values: Only supported for Environment variable: |
string |
|
The compression level for the generated image (0-100). Only supported for Environment variable: |
int |
|
The moderation level for the image generation request. Supported values: Only supported for Environment variable: |
string |
|
Whether image model requests should be logged Environment variable: |
boolean |
|
Whether image model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether audio transcription model requests should be logged Environment variable: |
boolean |
|
Whether audio transcription model responses should be logged Environment variable: |
boolean |
|
Model name to use Environment variable: |
string |
|
Whether decision model requests should be logged Environment variable: |
boolean |
|
Whether decision model responses should be logged Environment variable: |
boolean |
|
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|
You can define multiple configurations to support different OpenAI models:
# Default OpenAI model configuration
quarkus.langchain4j.openai.chat-model.model-name=gpt-6-luna
quarkus.langchain4j.openai.api-key=sk-...
# Custom OpenAI model configuration
quarkus.langchain4j.openai.some-name.chat-model.model-name=o3
quarkus.langchain4j.openai.some-name.api-key=sk-...
quarkus.langchain4j.openai.some-name.chat-model.temperature=0.8You can then select the model to use in your application by using the @RegisterAiService annotation with the modelName attribute:
import io.quarkiverse.langchain4j.RegisterAiService;
@RegisterAiService(modelName = "some-name")
public interface MyService {
// ...
}Or use the @ModelName annotation for programmatic injection:
import dev.langchain4j.model.chat.ChatModel;
import io.quarkiverse.langchain4j.ModelName;
import jakarta.inject.Inject;
// ...
@Inject @ModelName("some-name") ChatModel chatModel;If no model name is specified, the default configuration is used.
Responses API
OpenAI offers two chat APIs: the classic /v1/chat/completions endpoint and the newer
Responses API (/v1/responses). The Responses API is required
for models that are only exposed through it (for example gpt-5-pro, o1-pro), is the only way to use tools (function
calling, including skills) with GPT-6 models when reasoning is enabled (see Using GPT-6 models), and unlocks
Responses-specific settings.
Which API the chat model targets is controlled by the quarkus.langchain4j.openai.chat-model.mode property
(chat-completion or responses). When it is not set, the mode is selected automatically:
-
responseswhen the base URL is the OpenAI API (https://api.openai.com/v1/, the default); -
chat-completionfor any other base URL, which is what OpenAI-compatible endpoints such as Ollama, vLLM, llama.cpp or LM Studio implement.
The resolved mode is logged at startup. To pin a mode explicitly, for example to keep using Chat Completions against OpenAI or to use the Responses API against a compatible gateway, set the property:
quarkus.langchain4j.openai.chat-model.mode=chat-completion
quarkus.langchain4j.openai.api-key=sk-...mode is a runtime property: it can be changed without rebuilding the application and can be set per named configuration
(quarkus.langchain4j.openai.<name>.chat-model.mode).
Both the blocking ChatModel and the StreamingChatModel are supported in this mode, including tool/function calling and
structured outputs. The injection points and AI service usage are unchanged — only the underlying API and endpoint differ.
Responses-specific options are configured under quarkus.langchain4j.openai.chat-model.responses.*, for example:
quarkus.langchain4j.openai.chat-model.responses.store=false
quarkus.langchain4j.openai.chat-model.responses.reasoning-summary=auto
quarkus.langchain4j.openai.chat-model.responses.max-output-tokens=1024|
In |
Migrating from Chat Completions
Because the Responses API is now selected automatically for https://api.openai.com/v1/, an existing configuration
written for Chat Completions is affected as follows:
-
quarkus.langchain4j.openai.chat-model.max-completion-tokensand the deprecatedmax-tokenskeep capping the output: whenquarkus.langchain4j.openai.chat-model.responses.max-output-tokensis not set,max-completion-tokensis used as the Responses output limit, andmax-tokensafter that. -
quarkus.langchain4j.openai.chat-model.presence-penalty,frequency-penaltyandstophave no equivalent on the Responses API and are ignored. -
quarkus.langchain4j.openai.max-retriesis ignored, see the warning below. -
quarkus.langchain4j.openai.log-requests-curlis ignored.
When the mode was selected automatically and one of the ignored settings is set explicitly, a warning listing them is
logged at startup. Set quarkus.langchain4j.openai.chat-model.mode=chat-completion to keep the previous behavior.
|
Retries are not performed on the Responses API
Retries are not going to be added to the Responses path. Use MicroProfile Fault Tolerance instead, which works with both APIs and gives you control over delays, jitter and which exceptions are retried: This requires the |
Using GPT-6 models
GPT-6 models are reasoning models, and OpenAI applies a server-side default reasoning effort of medium when
quarkus.langchain4j.openai.chat-model.reasoning-effort is not set. On the Chat Completions endpoint, OpenAI rejects
requests that combine tools with any reasoning effort other than none, and not every GPT-6 model accepts none:
| Model | Supports reasoning-effort=none |
Tools on Chat Completions |
|---|---|---|
|
yes |
only with |
|
yes |
only with |
|
no (lowest is |
no, the Responses API is required |
|
no (defaults to |
no, the Responses API is required |
With the automatic mode selection described above, models used against OpenAI target the Responses API, where tools work
with any reasoning effort. If you force mode=chat-completion with a GPT-6 model, either avoid tools or set
quarkus.langchain4j.openai.chat-model.reasoning-effort=none with a model that supports it.
Advanced usage
The OpenAI extension internally uses a Quarkus REST Client to make API calls. This client can also be used directly:
import java.net.URI;
import java.net.URISyntaxException;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.jboss.resteasy.reactive.RestStreamElementType;
import dev.ai4j.openai4j.completion.CompletionChoice;
import io.quarkiverse.langchain4j.openai.common.OpenAiRestApi;
import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
import io.smallrye.mutiny.Multi;
@Path("restApi")
@ApplicationScoped
public class QuarkusRestApiResource {
private final OpenAiRestApi restApi;
private final String token;
public QuarkusRestApiResource() throws URISyntaxException {
this.restApi = QuarkusRestClientBuilder.newBuilder()
.baseUri(new URI("https://api.openai.com/v1/"))
.build(OpenAiRestApi.class);
this.token = "sometoken";
}
@GET
@Path("language/streaming")
@RestStreamElementType(MediaType.TEXT_PLAIN)
public Multi<String> languageStreaming() {
return restApi.streamingCompletion(
createCompletionRequest("Write a short 1 paragraph funny poem about Enterprise Java"), token, null)
.map(r -> {
if (r.choices() != null) {
if (r.choices().size() == 1) {
CompletionChoice choice = r.choices().get(0);
var text = choice.text();
if (text != null) {
return text;
}
}
}
return "";
});
}
}|
In the example above, |
Dynamic Authorization Headers
In some scenarios, you may need to dynamically inject authorization headers into OpenAI requests.
There are two supported approaches:
Using a ContainerRequestFilter annotated with @Provider.
Create a filter implementing ResteasyReactiveClientRequestFilter:
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.ext.Provider;
import org.jboss.resteasy.reactive.client.spi.ResteasyReactiveClientRequestContext;
import org.jboss.resteasy.reactive.client.spi.ResteasyReactiveClientRequestFilter;
@Provider
@ApplicationScoped
public class RequestFilter implements ResteasyReactiveClientRequestFilter {
@Inject
MyAuthorizationService myAuthorizationService;
@Override
public void filter(ResteasyReactiveClientRequestContext requestContext) {
/*
* All requests will be filtered here, therefore make sure that you make
* the necessary checks to avoid putting the Authorization header in
* requests that do not need it.
*/
requestContext.getHeaders().putSingle("Authorization", ...);
}
}Ensure the filter is selective if other requests use the same HTTP client infrastructure.
Using AuthProvider
This method allows associating a custom token provider per model using @ModelName:
import io.quarkiverse.langchain4j.ModelName;
import io.quarkiverse.langchain4j.auth.ModelAuthProvider;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
@ApplicationScoped
@ModelName("my-model-name") //you can omit this if you have only one model or if you want to use the default model
public class TestClass implements ModelAuthProvider {
@Inject MyTokenProviderService tokenProviderService;
@Override
public String getAuthorization(Input input) {
/*
* The `input` will contain some information about the request
* about to be passed to the remote model endpoints
*/
return "Bearer " + tokenProviderService.getToken();
}
}This approach is ideal for multi-tenant setups or dynamic token rotation.