Compartir a través de

Biblioteca cliente de Azure OpenAI para Java: versión 1.0.0-beta.5

  • Artículo

Azure OpenAI es un servicio administrado que permite a los desarrolladores implementar, optimizar y generar contenido a partir de modelos openAI en recursos de Azure.

La biblioteca cliente de Azure OpenAI para Java es una adaptación de las API REST de OpenAI que proporciona una interfaz idiomática y una integración enriquecida con el resto del ecosistema del SDK de Azure.

Use la biblioteca cliente de Azure OpenAI para:

Para obtener ejemplos concretos, puede echar un vistazo a los vínculos siguientes. Se tratan algunos de los escenarios más comunes:

Si desea ver el código completo de estos fragmentos de código, consulte nuestra carpeta de ejemplos.

Código fuente | Documentación de referencia de API | Documentación del producto | Ejemplos

Introducción

Requisitos previos

Adición del paquete al producto

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

Authentication

Para interactuar con el servicio OpenAI de Azure, deberá crear una instancia de clase cliente, OpenAIAsyncClient o OpenAIClient mediante OpenAIClientBuilder. Para configurar un cliente para su uso con Azure OpenAI, proporcione un URI de punto de conexión válido a un recurso de Azure OpenAI junto con una credencial de clave, una credencial de token o una credencial de identidad de Azure autorizada para usar el recurso de Azure OpenAI.

Creación de un cliente de Azure OpenAI con credenciales de clave

Obtenga las credenciales de Azure OpenAI key desde Azure Portal.

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

or

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

Compatibilidad con OpenAI que no sea de Azure

El SDK también admite el funcionamiento en el openAI público que no es de Azure. Los modelos de respuesta siguen siendo los mismos, solo la configuración de OpenAIClient es ligeramente diferente. En primer lugar, obtenga la clave de API openAI que no sea de Azure de las claves de API de autenticación de Open AI. A continuación, configure lo OpenAIClient siguiente:

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

or

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

Creación de un cliente de Azure OpenAI con credenciales de Azure Active Directory

El SDK de Azure para Java admite un paquete de identidad de Azure, lo que facilita la obtención de credenciales de Plataforma de identidad de Microsoft.

La autenticación con AAD requiere una configuración inicial:

  • Adición del paquete de identidad de Azure
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Después de la instalación, puede elegir el tipo de credencial de azure.identity que se va a usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar al cliente: establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

La autorización es más fácil mediante DefaultAzureCredential. Encuentra la mejor credencial para usar en su entorno en ejecución. Para más información sobre el uso de la autorización de Azure Active Directory con el servicio OpenAI, consulte la documentación asociada.

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

Creación de un cliente con opciones de proxy

Cree un cliente openAI con opciones 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();

Conceptos clave

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas del servicio OpenAI más comunes, entre las que se incluyen:

Finalizaciones de texto

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 obtener un ejemplo completo, consulte Finalizaciones de texto de ejemplo.

Finalizaciones 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 obtener un ejemplo de ejemplo completo, consulte Finalizaciones de texto de streaming de ejemplo.

Finalizaciones 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 obtener un ejemplo completo, consulte Finalizaciones de chat de ejemplo.

Para obtener un function call ejemplo, consulte llamada de función.

Para obtener Bring Your Own Data un ejemplo, consulte Traiga sus propios datos.

Consulte la documentación del servicio para obtener una explicación conceptual de la finalización del texto.

Finalizaciones de chat en 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 obtener un ejemplo completo, consulte finalizaciones de chat de streaming de ejemplo.

Incrustaciones 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 obtener un ejemplo de ejemplo completo, consulte inserción de ejemplo.

Consulte la documentación del servicio para obtener una explicación conceptual de la inserción de openAI.

Generación de imágenes

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 obtener un ejemplo completo, consulte generación de imágenes de ejemplo.

Transcripción de audio

El servicio OpenAI comienza a admitir audio transcription con la introducción de Whisper modelos. En el fragmento de código siguiente se muestra cómo usar el servicio para transcribir audio.

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 obtener un ejemplo de ejemplo completo, consulte transcripción de audio de ejemplo. Consulte la documentación del servicio para obtener una explicación conceptual de Whisper.

Traducción de audio

El servicio OpenAI comienza a admitir audio translation con la introducción de Whisper modelos. En el fragmento de código siguiente se muestra cómo usar el servicio para traducir audio.

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 obtener un ejemplo completo, consulte traducción de audio de ejemplo. Consulte la documentación del servicio para obtener una explicación conceptual de Whisper.

Solución de problemas

Habilitación del registro de cliente

Puede establecer la variable de entorno AZURE_LOG_LEVEL para ver las instrucciones de registro realizadas en la biblioteca cliente. Por ejemplo, al establecer AZURE_LOG_LEVEL=2, se mostrarán todos los mensajes informativos, de advertencia y de registro de errores. Los niveles de registro se pueden encontrar aquí: niveles de registro.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

  • Los ejemplos se explican en detalle aquí.

Contribuciones

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

  1. Bifurcarlo
  2. Creación de la rama de características (git checkout -b my-new-feature)
  3. Confirmar los cambios (git commit -am 'Add some feature')
  4. Inserción en la rama (git push origin my-new-feature)
  5. Creación de una nueva solicitud de incorporación de cambios