Current version is 1.0.0-beta.3, click here for the index

Azure OpenAI client library for Java

Azure OpenAI is a managed service that allows developers to deploy, tune, and generate content from OpenAI models on Azure resources.

The Azure OpenAI client library for Java is an adaptation of OpenAI's REST APIs that provides an idiomatic interface and rich integration with the rest of the Azure SDK ecosystem.

Use the client library for Azure OpenAI to:

For concrete examples you can have a look at the following links. Some of the more common scenarios are covered:

Text completions sample
Streaming text completions sample
Chat completions sample
Streaming chat completions sample
Embeddings sample
Image Generation sample

If you want to see the full code for these snippets check out our samples folder.

Source code | API reference documentation | Product Documentation | Samples

Getting started

Prerequisites

Java Development Kit (JDK) with version 8 or above
Azure Subscription
Azure OpenAI access
Quickstart: Get started generating text using Azure OpenAI Service

Adding the package to your product

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-openai</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

Authentication

In order to interact with the Azure OpenAI Service you'll need to create an instance of client class, OpenAIAsyncClient or OpenAIClient by using OpenAIClientBuilder. To configure a client for use with Azure OpenAI, provide a valid endpoint URI to an Azure OpenAI resource along with a corresponding key credential, token credential, or Azure Identity credential that's authorized to use the Azure OpenAI resource.

Create a Azure OpenAI client with key credential

Get Azure OpenAI key credential from the Azure Portal.

OpenAIClient client = new OpenAIClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildAsyncClient();

Support for non-Azure OpenAI

The SDK also supports operating against the public non-Azure OpenAI. The response models remain the same, only the setup of the OpenAIClient is slightly different. First, get Non-Azure OpenAI API key from Open AI authentication API keys. Then setup your OpenAIClient as follows:

OpenAIClient client = new OpenAIClientBuilder()
    .credential(new NonAzureOpenAIKeyCredential("{openai-secret-key}"))
    .buildClient();

OpenAIAsyncClient client = new OpenAIClientBuilder()
    .credential(new NonAzureOpenAIKeyCredential("{openai-secret-key}"))
    .buildAsyncClient();

Create an Azure OpenAI client with Azure Active Directory credential

Azure SDK for Java supports an Azure Identity package, making it easy to get credentials from Microsoft identity platform.

Authentication with AAD requires some initial setup: * Add the Azure Identity package

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.9.1</version>
</dependency>

After setup, you can choose which type of credential from azure.identity to use. As an example, DefaultAzureCredential can be used to authenticate the client: Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Authorization is easiest using DefaultAzureCredential. It finds the best credential to use in its running environment. For more information about using Azure Active Directory authorization with OpenAI service, please refer to the associated documentation.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
    .credential(defaultCredential)
    .endpoint("{endpoint}")
    .buildClient();

Create a client with proxy options

Create an OpenAI client with proxy options.

// Proxy options
final String hostname = "{your-host-name}";
final int port = 447; // your port number

ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress(hostname, port))
    .setCredentials("{username}", "{password}");

OpenAIClient client = new OpenAIClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .clientOptions(new HttpClientOptions().setProxyOptions(proxyOptions))
    .buildClient();

Key concepts

Examples

The following sections provide several code snippets covering some of the most common OpenAI service tasks, including:

Text completions sample
Streaming text completions sample
Chat completions sample
Streaming chat completions sample
Embeddings sample
Image Generation sample

Text completions

List<String> prompt = new ArrayList<>();
prompt.add("Say this is a test");

Completions completions = client.getCompletions("{deploymentOrModelId}", new CompletionsOptions(prompt));

System.out.printf("Model ID=%s is created at %s.%n", completions.getId(), completions.getCreatedAt());
for (Choice choice : completions.getChoices()) {
    System.out.printf("Index: %d, Text: %s.%n", choice.getIndex(), choice.getText());
}

For a complete sample example, see sample Text Completions.

Streaming text completions

List<String> prompt = new ArrayList<>();
prompt.add("How to bake a cake?");

IterableStream<Completions> completionsStream = client
    .getCompletionsStream("{deploymentOrModelId}", new CompletionsOptions(prompt));

completionsStream.forEach(completions -> {
    System.out.printf("Model ID=%s is created at %s.%n", completions.getId(), completions.getCreatedAt());
    for (Choice choice : completions.getChoices()) {
        System.out.printf("Index: %d, Text: %s.%n", choice.getIndex(), choice.getText());
    }
});

For a complete sample example, see sample Streaming Text Completions.

Chat completions

List<ChatMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatMessage(ChatRole.SYSTEM, "You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatMessage(ChatRole.USER, "Can you help me?"));
chatMessages.add(new ChatMessage(ChatRole.ASSISTANT, "Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatMessage(ChatRole.USER, "What's the best way to train a parrot?"));

ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelId}",
    new ChatCompletionsOptions(chatMessages));

System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
    ChatMessage message = choice.getMessage();
    System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
    System.out.println("Message:");
    System.out.println(message.getContent());
}

For a complete sample example, see sample Chat Completions.

For function call sample, see sample function call.

Please refer to the service documentation for a conceptual discussion of text completion.

Streaming chat completions

List<ChatMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatMessage(ChatRole.SYSTEM, "You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatMessage(ChatRole.USER, "Can you help me?"));
chatMessages.add(new ChatMessage(ChatRole.ASSISTANT, "Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatMessage(ChatRole.USER, "What's the best way to train a parrot?"));

IterableStream<ChatCompletions> chatCompletionsStream = client.getChatCompletionsStream("{deploymentOrModelId}",
    new ChatCompletionsOptions(chatMessages));

chatCompletionsStream.forEach(chatCompletions -> {
    System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
    for (ChatChoice choice : chatCompletions.getChoices()) {
        ChatMessage message = choice.getDelta();
        if (message != null) {
            System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
            System.out.println("Message:");
            System.out.println(message.getContent());
        }
    }

    CompletionsUsage usage = chatCompletions.getUsage();
    if (usage != null) {
        System.out.printf("Usage: number of prompt token is %d, "
                + "number of completion token is %d, and number of total tokens in request and response is %d.%n",
            usage.getPromptTokens(), usage.getCompletionTokens(), usage.getTotalTokens());
    }
});

For a complete sample example, see sample Streaming Chat Completions.

Text embeddings

EmbeddingsOptions embeddingsOptions = new EmbeddingsOptions(
    Arrays.asList("Your text string goes here"));

Embeddings embeddings = client.getEmbeddings("{deploymentOrModelId}", embeddingsOptions);

for (EmbeddingItem item : embeddings.getData()) {
    System.out.printf("Index: %d.%n", item.getPromptIndex());
    for (Double embedding : item.getEmbedding()) {
        System.out.printf("%f;", embedding);
    }
}

For a complete sample example, see sample Embedding.

Please refer to the service documentation for a conceptual discussion of openAI embedding.

Image Generation

ImageGenerationOptions imageGenerationOptions = new ImageGenerationOptions(
    "A drawing of the Seattle skyline in the style of Van Gogh");
ImageResponse images = client.getImages(imageGenerationOptions);

for (ImageLocation imageLocation : images.getData()) {
    ResponseError error = imageLocation.getError();
    if (error != null) {
        System.out.printf("Image generation operation failed. Error code: %s, error message: %s.%n",
            error.getCode(), error.getMessage());
    } else {
        System.out.printf(
            "Image location URL that provides temporary access to download the generated image is %s.%n",
            imageLocation.getUrl());
    }
}

For a complete sample example, see sample Image Generation.

Troubleshooting

Enable client logging

You can set the AZURE_LOG_LEVEL environment variable to view logging statements made in the client library. For example, setting AZURE_LOG_LEVEL=2 would show all informational, warning, and error log messages. The log levels can be found here: log levels.

Default HTTP Client

All client libraries by default use the Netty HTTP client. Adding the above dependency will automatically configure the client library to use the Netty HTTP client. Configuring or changing the HTTP client is detailed in the HTTP clients wiki.

Default SSL library

All client libraries, by default, use the Tomcat-native Boring SSL library to enable native-level performance for SSL operations. The Boring SSL library is an uber jar containing native libraries for Linux / macOS / Windows, and provides better performance compared to the default SSL implementation within the JDK. For more information, including how to reduce the dependency size, refer to the performance tuning section of the wiki.

Next steps

Samples are explained in detail here.

Contributing

For details on contributing to this repository, see the contributing guide.

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Packages

Package

Description

com.azure.ai.openai

Package containing the classes for OpenAI.

com.azure.ai.openai.models

Package containing the data models for OpenAI.

Azure SDK for Java Reference Documentation