Biblioteca de clientes do OpenAI do Azure para Java – versão 1.0.0-beta.5

  • Artigo

O OpenAI do Azure é um serviço gerenciado que permite que os desenvolvedores implantem, ajustem e gerem conteúdo de modelos OpenAI em recursos do Azure.

A biblioteca de clientes do OpenAI do Azure para Java é uma adaptação das APIs REST do OpenAI que fornece uma interface idiomática e uma integração avançada com o restante do ecossistema do SDK do Azure.

Use a biblioteca de clientes do OpenAI do Azure para:

Para obter exemplos concretos, você pode dar uma olhada nos links a seguir. Alguns dos cenários mais comuns são abordados:

Se você quiser ver o código completo desses snippets marcar nossa pasta de exemplos.

Código-fonte | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Pré-requisitos

Adicionando o pacote ao seu produto

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

Autenticação

Para interagir com o Serviço OpenAI do Azure, você precisará criar uma instância da classe de cliente, OpenAIAsyncClient ou OpenAIClient usando OpenAIClientBuilder. Para configurar um cliente para uso com o OpenAI do Azure, forneça um URI de ponto de extremidade válido para um recurso openAI do Azure juntamente com uma credencial de chave correspondente, credencial de token ou credencial de identidade do Azure autorizada a usar o recurso OpenAI do Azure.

Criar um cliente OpenAI do Azure com credencial de chave

Obtenha a credencial do OpenAI key do Azure no Portal do Azure.

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

ou

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

Suporte para OpenAI não Azure

O SDK também dá suporte à operação no OpenAI público não Azure. Os modelos de resposta permanecem os mesmos, apenas a configuração do OpenAIClient é ligeiramente diferente. Primeiro, obtenha a chave da API OpenAI que não seja do Azure em Chaves de API de autenticação de IA aberta. Em seguida, configure o OpenAIClient da seguinte maneira:

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

ou

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

Criar um cliente OpenAI do Azure com a credencial do Azure Active Directory

O SDK do Azure para Java dá suporte a um pacote de Identidade do Azure, facilitando a obtenção de credenciais de plataforma de identidade da Microsoft.

A autenticação com o AAD requer alguma configuração inicial:

  • Adicionar o pacote de Identidade do Azure
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Após a instalação, você pode escolher qual tipo de credencial de azure.identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente: defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

A autorização é mais fácil usando DefaultAzureCredential. Ele encontra a melhor credencial a ser usada em seu ambiente de execução. Para obter mais informações sobre como usar a autorização do Azure Active Directory com o serviço OpenAI, consulte a documentação associada.

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

Criar um cliente com opções de proxy

Crie um cliente OpenAI com opções de proxy.

// 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();

Principais conceitos

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas de serviço OpenAI mais comuns, incluindo:

Preenchimentos de textos

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());
}

Para obter um exemplo completo, consulte Exemplo de Conclusões de Texto.

Conclusões de texto de streaming

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

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

completionsStream
    .stream()
    // Remove .skip(1) when using Non-Azure OpenAI API
    // Note: the first chat completions can be ignored when using Azure OpenAI service which is a known service bug.
    // TODO: remove .skip(1) when service fix the issue.
    .skip(1)
    .forEach(completions -> System.out.print(completions.getChoices().get(0).getText()));

Para obter um exemplo completo, consulte Exemplo de Conclusões de Texto de Streaming.

Preenchimentos de chat

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());
}

Para obter um exemplo completo, consulte Conclusões de chat de exemplo.

Para obter function call um exemplo, consulte chamada de função.

Para obter Bring Your Own Data um exemplo, consulte Traga seus próprios dados.

Consulte a documentação do serviço para obter uma discussão conceitual sobre a conclusão do texto.

Conclusões de chat de streaming

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
    .stream()
    // Remove .skip(1) when using Non-Azure OpenAI API
    // Note: the first chat completions can be ignored when using Azure OpenAI service which is a known service bug.
    // TODO: remove .skip(1) when service fix the issue.
    .skip(1)
    .forEach(chatCompletions -> {
        ChatMessage delta = chatCompletions.getChoices().get(0).getDelta();
        if (delta.getRole() != null) {
            System.out.println("Role = " + delta.getRole());
        }
        if (delta.getContent() != null) {
            System.out.print(delta.getContent());
        }
    });

Para obter um exemplo completo, consulte Exemplos de Conclusões de Chat de Streaming.

Inserções de texto

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);
    }
}

Para obter um exemplo completo, consulte Exemplo de inserção.

Consulte a documentação do serviço para obter uma discussão conceitual sobre a inserção openAI.

Geração de imagem

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());
    }
}

Para obter um exemplo completo, consulte Geração de imagem de exemplo.

Transcrição de áudio

O serviço OpenAI começa a dar audio transcription suporte com a introdução de Whisper modelos. O snippet de código a seguir mostra como usar o serviço para transcrever áudio.

String fileName = "{your-file-name}";
Path filePath = Paths.get("{your-file-path}" + fileName);

byte[] file = BinaryData.fromFile(filePath).toBytes();
AudioTranscriptionOptions transcriptionOptions = new AudioTranscriptionOptions(file)
    .setResponseFormat(AudioTranscriptionFormat.JSON);

AudioTranscription transcription = client.getAudioTranscription("{deploymentOrModelId}", fileName, transcriptionOptions);

System.out.println("Transcription: " + transcription.getText());

Para obter um exemplo completo, consulte Transcrição de áudio de exemplo. Consulte a documentação do serviço para obter uma discussão conceitual sobre Whisper.

Tradução de Áudio

O serviço OpenAI começa a dar audio translation suporte com a introdução de Whisper modelos. O snippet de código a seguir mostra como usar o serviço para traduzir áudio.

String fileName = "{your-file-name}";
Path filePath = Paths.get("{your-file-path}" + fileName);

byte[] file = BinaryData.fromFile(filePath).toBytes();
AudioTranslationOptions translationOptions = new AudioTranslationOptions(file)
    .setResponseFormat(AudioTranslationFormat.JSON);

AudioTranslation translation = client.getAudioTranslation("{deploymentOrModelId}", fileName, translationOptions);

System.out.println("Translation: " + translation.getText());

Para obter um exemplo completo, consulte Tradução de Áudio de exemplo. Consulte a documentação do serviço para obter uma discussão conceitual sobre Whisper.

Solução de problemas

Habilitar o log do cliente

Você pode definir a variável de ambiente AZURE_LOG_LEVEL para exibir instruções de log feitas na biblioteca de cliente. Por exemplo, a configuração AZURE_LOG_LEVEL=2 mostraria todas as mensagens informativas, de aviso e de log de erros. Os níveis de log podem ser encontrados aqui: níveis de log.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

  • Os exemplos são explicados em detalhes aqui.

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

  1. Bifurcar
  2. Criar seu branch de recurso (git checkout -b my-new-feature)
  3. Confirmar suas alterações (git commit -am 'Add some feature')
  4. Enviar por push para o branch (git push origin my-new-feature)
  5. Criar nova solicitação de pull