Azure OpenAI-Clientbibliothek für Java – Version 1.0.0-beta.5

Artikel
10/02/2023

Azure OpenAI ist ein verwalteter Dienst, mit dem Entwickler Inhalte aus OpenAI-Modellen in Azure-Ressourcen bereitstellen, optimieren und generieren können.

Die Azure OpenAI-Clientbibliothek für Java ist eine Anpassung der REST-APIs von OpenAI, die eine idiomatische Schnittstelle und eine umfassende Integration in das restliche Azure SDK-Ökosystem bietet.

Verwenden Sie die Clientbibliothek für Azure OpenAI für Folgendes:

Konkrete Beispiele finden Sie unter den folgenden Links. Einige der häufigsten Szenarien werden behandelt:

Beispiel für Textvervollständigen
Streamingtext-Vervollständigungsbeispiel
Beispiel für Chat-Vervollständigungen
Beispiel für Streamingchat-Vervollständigungen
Beispiel für Einbettungen
Beispiel für die Bildgenerierung
Beispiel für die Audiotranskription
Beispiel für die Audioübersetzung

Wenn Sie den vollständigen Code für diese Codeausschnitte sehen möchten, lesen Sie unseren Beispielordner.

Quellcode | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Voraussetzungen

Java Development Kit (JDK) mit Version 8 oder höher
Azure-Abonnement
Azure OpenAI-Zugriff
Schnellstart: Erste Schritte beim Generieren von Text mithilfe von Azure OpenAI Service

Hinzufügen des Pakets zu Ihrem Produkt

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

Authentifizierung

Um mit dem Azure OpenAI-Dienst zu interagieren, müssen Sie eine instance der Clientklasse OpenAIAsyncClient oder OpenAIClient mithilfe von OpenAIClientBuilder erstellen. Um einen Client für die Verwendung mit Azure OpenAI zu konfigurieren, stellen Sie einen gültigen Endpunkt-URI für eine Azure OpenAI-Ressource zusammen mit den entsprechenden Schlüsselanmeldeinformationen, Tokenanmeldeinformationen oder Azure Identity-Anmeldeinformationen bereit, die für die Verwendung der Azure OpenAI-Ressource autorisiert sind.

Erstellen eines Azure OpenAI-Clients mit Schlüsselanmeldeinformationen

Abrufen von Azure OpenAI-Anmeldeinformationen key aus dem Azure-Portal.

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

oder

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

Unterstützung für Nicht-Azure OpenAI

Das SDK unterstützt auch den Betrieb mit dem öffentlichen Nicht-Azure OpenAI. Die Antwortmodelle bleiben gleich, nur die Einrichtung des OpenAIClient unterscheidet sich geringfügig. Rufen Sie zunächst einen Nicht-Azure OpenAI-API-Schlüssel aus open AI-Authentifizierungs-API-Schlüsseln ab. Richten Sie dann Ihre OpenAIClient wie folgt ein:

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

oder

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

Erstellen eines Azure OpenAI-Clients mit Azure Active Directory-Anmeldeinformationen

Das Azure SDK für Java unterstützt ein Azure Identity-Paket, das das Abrufen von Anmeldeinformationen von Microsoft Identity Platform vereinfacht.

Die Authentifizierung mit AAD erfordert eine anfängliche Einrichtung:

Hinzufügen des Azure Identity-Pakets

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

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren: Legen Sie die Werte der Client-ID, der Mandanten-ID und des Clientgeheimnisses der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET.

Die Autorisierung ist am einfachsten mit DefaultAzureCredential. Es findet die besten Anmeldeinformationen, die in seiner ausgeführten Umgebung verwendet werden können. Weitere Informationen zur Verwendung der Azure Active Directory-Autorisierung mit dem OpenAI-Dienst finden Sie in der zugehörigen Dokumentation.

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

Erstellen eines Clients mit Proxyoptionen

Erstellen Sie einen OpenAI-Client mit Proxyoptionen.

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

Wichtige Begriffe

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten OpenAI-Dienstaufgaben behandeln, einschließlich:

Beispiel für Textvervollständigen
Streamingtext-Vervollständigungsbeispiel
Beispiel für Chat-Vervollständigungen
Beispiel für Streamingchat-Vervollständigungen
Beispiel für Einbettungen
Beispiel für die Bildgenerierung
Beispiel für die Audiotranskription
Beispiel für die Audioübersetzung

Textvervollständigungen

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

Ein vollständiges Beispiel finden Sie unter Beispieltext-Vervollständigungen.

Streamingtext-Vervollständigungen

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

Ein vollständiges Beispiel finden Sie unter Streamingtext-Vervollständigungen.

Chatvervollständigungen

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

Ein vollständiges Beispiel finden Sie unter Beispiel für Chat-Vervollständigungen.

Ein function call Beispiel finden Sie unter Funktionsaufruf.

Ein Bring Your Own Data Beispiel finden Sie unter Bring Your Own Data.

Eine konzeptionelle Diskussion zur Texterfüllung finden Sie in der Servicedokumentation.

Streamingchat-Vervollständigungen

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

Ein vollständiges Beispiel finden Sie unter Streaming-Chat-Vervollständigung.

Texteinbettungen

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

Ein vollständiges Beispiel finden Sie unter Beispieleinbettung.

Eine konzeptionelle Diskussion zur openAI-Einbettung finden Sie in der Servicedokumentation.

Bildgenerierung

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

Ein vollständiges Beispiel finden Sie unter Beispielbildgenerierung.

Audiotranskription

Der OpenAI-Dienst beginnt audio transcription mit der Einführung von Whisper Modellen. Der folgende Codeausschnitt zeigt, wie Sie den Dienst zum Transkribieren von Audiodaten verwenden.

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

Ein vollständiges Beispiel finden Sie unter Beispiel für audiotranskription. Eine konzeptionelle Diskussion zu Whisper finden Sie in der Servicedokumentation.

Audioübersetzung

Der OpenAI-Dienst beginnt audio translation mit der Einführung von Whisper Modellen. Der folgende Codeausschnitt zeigt, wie Sie den Dienst zum Übersetzen von Audio verwenden.

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

Ein vollständiges Beispiel finden Sie unter Beispiel für die Audioübersetzung. Eine konzeptionelle Diskussion zu Whisper finden Sie in der Servicedokumentation.

Problembehandlung

Aktivieren der Clientprotokollierung

Sie können die Umgebungsvariable AZURE_LOG_LEVEL so festlegen, dass in der Clientbibliothek vorgenommene Protokollierungsanweisungen angezeigt werden. Durch das Festlegen von AZURE_LOG_LEVEL=2 würden beispielsweise alle Informations-, Warnungs- und Fehlerprotokollmeldungen angezeigt. Die Protokolliergrade finden Sie hier: Protokolliergrade.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring-SSL-Bibliothek ist eine Uber-JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet im Vergleich zur SSL-Standardimplementierung im JDK eine bessere Leistung. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Die Beispiele werden hier ausführlich erläutert.

Mitwirken

Ausführliche Informationen zum Mitwirken zu diesem Repository finden Sie im Leitfaden zur Mitarbeit.

Fork
Erstellen Ihres Featurebranch (git checkout -b my-new-feature)
Commit für Ihre Änderungen (git commit -am 'Add some feature')
Pushen an den Branch (git push origin my-new-feature)
Erstellen eines neuen Pull Request

Freigeben über