Freigeben über

Migrieren zur OpenAI-JavaScript-API-Bibliothek 4.x (klassisch)

Gilt nur für:klassisches Foundry-Portal. Dieser Artikel ist für das neue Foundry-Portal nicht verfügbar. Erfahren Sie mehr über das neue Portal.

Hinweis

Links in diesem Artikel können Inhalte in der neuen Microsoft Foundry-Dokumentation anstelle der jetzt angezeigten Foundry-Dokumentation (klassisch) öffnen.

Von Bedeutung

Die neuesten API-Beispiele finden Sie im API-Lebenszyklusartikel.

Authentifizieren des Clients

Es gibt mehrere Möglichkeiten, API-Anforderungen für Azure OpenAI zu authentifizieren. Es wird dringend empfohlen, Microsoft Entra ID Token zu verwenden. Weitere Informationen finden Sie in der Azure Identity-Dokumentation.

Microsoft Entra ID

Es gibt mehrere Möglichkeiten, sich mit dem Azure OpenAI mithilfe von Microsoft Entra ID Token zu authentifizieren. Die Standardeinstellung besteht darin, die klasse DefaultAzureCredential aus dem Paket @azure/identity zu verwenden, ihre Anwendung verwendet jedoch möglicherweise eine andere Anmeldeinformationsklasse. In diesem Leitfaden wird davon ausgegangen, dass Sie die DefaultAzureCredential-Klasse verwenden. Anmeldeinformationen können wie folgt erstellt werden:

import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();

Dieses Objekt wird dann an das zweite Argument der OpenAIClient- und AssistantsClient-Clientkonstruktoren übergeben.

Um den AzureOpenAI-Client zu authentifizieren, müssen wir jedoch die Funktion getBearerTokenProvider aus dem Paket @azure/identity verwenden. Diese Funktion erstellt einen Tokenanbieter, der AzureOpenAI intern verwendet, um Token für jede Anforderung abzurufen. Der Tokenanbieter wird wie folgt erstellt:

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const credential = new DefaultAzureCredential();
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

azureADTokenProvider wird beim Erstellen des AzureOpenAI-Clients an das Options-Objekt übergeben.

API-Schlüssel (hiervon wird dringend abgeraten)

API-Schlüssel werden für die Verwendung in der Produktion nicht empfohlen, da sie weniger sicher sind als andere Authentifizierungsmethoden. Es wurden bereits AzureKeyCredential Objekte wie folgt erstellt, um OpenAIClient oder AssistantsClient zu authentifizieren:

import { AzureKeyCredential } from "@azure/openai";
const apiKey = new AzureKeyCredential("your API key");

Andererseits kann AzureOpenAI durch Setzen der Umgebungsvariablen AZURE_OPENAI_API_KEY oder durch Setzen der String-Eigenschaft apiKey im Optionsobjekt beim Erstellen des AzureOpenAI-Clients mit einem API-Schlüssel authentifiziert werden.

Von Bedeutung

Verwenden Sie API-Schlüssel mit Vorsicht. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich. Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn sicher in Azure Key Vault. Weitere Informationen zur sicheren Verwendung von API-Schlüsseln in Ihren Apps finden Sie unter API-Schlüssel mit Azure Key Vault.

Weitere Informationen zur Sicherheit von AI-Diensten finden Sie unter Authenticate-Anforderungen an Azure KI Services.

Erstellen des Clients

import { AzureOpenAI } from "openai";
const deployment = "Your Azure OpenAI deployment";
const apiVersion = "2024-04-01-preview";
const options = { azureADTokenProvider, deployment, apiVersion }
const client = new AzureOpenAI(options);

Der Endpunkt der Azure OpenAI-Ressource kann durch Festlegen der Option endpoint angegeben werden, kann aber auch vom Client aus der Umgebungsvariable AZURE_OPENAI_ENDPOINT geladen werden. Dies ist die empfohlene Methode zum Festlegen des Endpunkts, da der Client so ohne Codeänderungen in verschiedenen Umgebungen verwendet werden kann und zudem der Endpunkt nicht im Code verfügbar gemacht wird.

Die API-Version muss angegeben werden. Dies ist erforderlich, um sicherzustellen, dass es zwischen API-Vorschauversionen nicht zu Unterbrechungen in vorhandenem Code kommt. Weitere Informationen zu Azure OpenAI-API-Versionen finden Sie in API-Versionsverwaltungsdokumentation. Zudem ist die deployment-Eigenschaft nicht erforderlich, es wird jedoch empfohlen, sie festzulegen. Sobald die deployment-Eigenschaft festgelegt wurde, wird sie als Standardbereitstellung für alle Vorgänge verwendet, die diese erfordern. Wenn der Client nicht mit der Option deployment erstellt wird, sollte die model-Eigenschaft im Options-Objekt mit dem Bereitstellungsnamen festgelegt werden. Audiovorgänge wie audio.transcriptions.create erfordern jedoch, dass die Option deployment beim Erstellen des Clients auf den Bereitstellungsnamen festgelegt ist.

API-Unterschiede

Es gibt wichtige Unterschiede zwischen den OpenAIClient- und AssistantsClient-Clients und dem AzureOpenAI-Client:

  • Vorgänge werden sowohl in OpenAIClient als auch in AssistantsClient als flache Liste von Methoden dargestellt, z. B. client.getChatCompletions. In AzureOpenAI werden Vorgänge in geschachtelten Gruppen gruppiert, z. B. client.chat.completions.create.
  • OpenAIClient und AssistantsClient umbenennen viele der Namen, die in der Azure OpenAI-API verwendet werden. So wird beispielsweise in der API Snake Case verwendet, im Client aber Camel Case. In AzureOpenAI werden Namen mit der Azure OpenAI-API identisch gehalten.

Beispiele für die Migration

In den folgenden Abschnitten finden Sie Beispiele für die Migration von OpenAIClient und AssistantsClient zu AzureOpenAI.

Chatvervollständigungen

const result = await client.chat.completions.create({ messages, model: '', max_tokens: 100 });

Beachten Sie Folgendes:

  • Die getChatCompletions-Methode wurde durch die chat.completions.create-Methode ersetzt.
  • Der messages-Parameter wird jetzt im Options-Objekt mit der messages-Eigenschaft übergeben.
  • Die maxTokens-Eigenschaft wurde in max_tokens umbenannt, und der deploymentName-Parameter wurde entfernt. Im Allgemeinen sind die Namen der Eigenschaften im options-Objekt die gleichen wie in der Azure OpenAI-API, wobei die snake_case-Notation anstelle der camelCase-Notation verwendet wird, die in der AssistantsClient zum Einsatz kommt. Dies gilt für alle Eigenschaften in sämtlichen Anforderungen und Antworten im AzureOpenAI-Client.
  • Der deploymentName-Parameter ist nicht erforderlich, wenn der Client mit der Option deployment erstellt wurde. Wenn der Client nicht mit der Option deployment erstellt wurde, sollte die model-Eigenschaft im Options-Objekt mit dem Bereitstellungsnamen festgelegt werden.

Streaming-Chatvervollständigungen

const stream = await client.chat.completions.create({ model: '', messages, max_tokens: 100, stream: true });

Azure auf Ihren Daten

import "@azure/openai/types";

const azureSearchEndpoint = "Your Azure Search resource endpoint";
const azureSearchIndexName = "Your Azure Search index name";
const result = await client.chat.completions.create({ model: '', messages, data_sources: [{
      type: "azure_search",
      parameters: {
        endpoint: azureSearchEndpoint,
        index_name: azureSearchIndexName,
        authentication: {
          type: "system_assigned_managed_identity",
        }
      }
    }]
});
  • "@azure/openai/types" wird importiert, wodurch Azure spezifische Definitionen (z. B. data_sources) zu den Clienttypen hinzugefügt werden.
  • Die azureExtensionOptions-Eigenschaft wurde durch die innere data_sources-Eigenschaft ersetzt.
  • Die eigenschaft parameters wurde hinzugefügt, um die Parameter der Erweiterung umzuschließen, die das Schema der Azure OpenAI-API spiegeln.
  • Camel Case-Eigenschaften wurden durch Snake Case-Eigenschaften ersetzt.

Audio-Transkription

import { createReadStream } from "fs";

const result = await client.audio.transcriptions.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • Die getAudioTranscription-Methode wurde durch die audio.transcriptions.create-Methode ersetzt.
  • Beim Erstellen von AzureOpenAI muss die Option deployment auf den Bereitstellungsnamen festgelegt sein, damit Audiovorgänge wie audio.transcriptions.create verwendet werden können.
  • Die model-Eigenschaft muss im Options-Objekt festgelegt werden. Ihr Wert wird jedoch nicht im Vorgang verwendet, sodass Sie sie auf einen beliebigen Wert festlegen können.
  • Die file-Eigenschaft akzeptiert verschiedene Typen (einschließlich Buffer, fs.ReadaStream und Blob), in diesem Beispiel wird jedoch mit fs.createReadStream eine Datei von einem Datenträger gestreamt.

Audioübersetzung

import { createReadStream } from "fs";

const result = await client.audio.translations.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • Die getAudioTranslation-Methode wurde durch die audio.translations.create-Methode ersetzt.
  • Alle anderen Änderungen sind identisch mit denen im Beispiel für die Audiotranskription.

Assistants

Die folgenden Beispiele zeigen, wie Sie einige der AssistantsClient-Methoden migrieren.

Erstellung des Assistenten

const options = ...;
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);
  • Die createAssistant-Methode wurde durch die beta.assistants.create-Methode ersetzt.

Threaderstellung

Das folgende Beispiel zeigt, wie Sie den createThread-Methodenaufruf migrieren.

const assistantThread = await assistantsClient.beta.threads.create();
  • Die createThread-Methode wurde durch die beta.threads.create-Methode ersetzt.

Nachrichtenerstellung

Das folgende Beispiel zeigt, wie Sie den createMessage-Methodenaufruf migrieren.

const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);
  • Die createMessage-Methode wurde durch die beta.threads.messages.create-Methode ersetzt.
  • Die Nachrichtenspezifikation wurde von einer Parameterliste in ein Objekt verschoben.

Läufe

Zum Ausführen eines Assistenten in einem Thread wird die createRun-Methode verwendet, um eine Ausführung zu erstellen, und dann wird ein loop verwendet, um den Ausführungsstatus abzufragen, bis er sich in einem Terminalzustand befindet. Das folgende Beispiel zeigt, wie Sie die Ausführungserstellung und den Abruf migrieren.

Dieser Code kann migriert und vereinfacht werden, indem Sie die createAndPoll-Methode verwenden, die eine Ausführung erstellt und diese abfragt, bis sie sich in einem Endzustand befindet.

const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
  • Die createRun-Methode wurde durch die beta.threads.runs.create- und createAndPoll-Methoden ersetzt.
  • Die createAndPoll-Methode wird verwendet, um eine Ausführung zu erstellen und abzufragen, bis sie sich in einem Endzustand befindet.

Verarbeiten von Ausführungsergebnissen

Seiten können mithilfe der for await Schleife durchlaufen werden.

for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    ...
  }
}

Einbettungen

Das folgende Beispiel zeigt, wie Sie den getEmbeddings-Methodenaufruf migrieren.

const embeddings = await client.embeddings.create({ input, model: '' });
  • Die getEmbeddings-Methode wurde durch die embeddings.create-Methode ersetzt.
  • Der input-Parameter wird jetzt im Options-Objekt mit der input-Eigenschaft übergeben.
  • Der Parameter deploymentName wurde entfernt. Der deploymentName-Parameter ist nicht erforderlich, wenn der Client mit der Option deployment erstellt wurde. Wenn der Client nicht mit der Option deployment erstellt wurde, sollte die model-Eigenschaft im Options-Objekt mit dem Bereitstellungsnamen festgelegt werden.

Bildgenerierung

Das folgende Beispiel zeigt, wie Sie den getImages-Methodenaufruf migrieren.

  const results = await client.images.generate({ prompt, model: '', n, size });
  • Die getImages-Methode wurde durch die images.generate-Methode ersetzt.
  • Der prompt-Parameter wird jetzt im Options-Objekt mit der prompt-Eigenschaft übergeben.
  • Der Parameter deploymentName wurde entfernt. Der deploymentName-Parameter ist nicht erforderlich, wenn der Client mit der Option deployment erstellt wurde. Wenn der Client nicht mit der Option deployment erstellt wurde, sollte die model-Eigenschaft im Options-Objekt mit dem Bereitstellungsnamen festgelegt werden.

Inhaltsfilter

Ergebnisse des Inhaltsfilters sind Teil der Antworttypen von Chatvervollständigungen in OpenAIClient. AzureOpenAI verfügt jedoch nicht über eine direkte Entsprechung der contentFilterResults-Eigenschaft in der ChatCompletion.Choice-Schnittstelle. Auf die Ergebnisse des Inhaltsfilters kann zugegriffen werden, indem "@azure/openai/types" importiert wird und auf die Eigenschaft content_filter_results zugegriffen wird. Das folgende Beispiel zeigt, wie Sie auf die Ergebnisse des Inhaltsfilters zugreifen.

import "@azure/openai/types";

const result = await client.chat.completions.create({ model: '', messages });
for (const choice of results.choices) {
  const filterResults = choice.content_filter_results;
  if (!filterResults) {
    console.log("No content filter is found");
    return;
  }
  if (filterResults.error) {
    console.log(
      `Content filter ran into the error ${filterResults.error.code}: ${filterResults.error.message}`);
  }
  const { hate, sexual, self_harm, violence } = filterResults;
  ...
}
  • Camel Case-Eigenschaften wurden durch Snake Case-Eigenschaften ersetzt.
  • "@azure/openai/types" wird importiert, der Azure-spezifische Definitionen (z. B. content_filter_results) zu den Clienttypen hinzufügt, finden Sie im Abschnitt Azure types weitere Informationen.

Vergleich der Typen

In der folgenden Tabelle werden mehrere Typnamen aus @azure/openai sowie ihre jeweils nächste openai-Entsprechung untersucht und dargestellt. Die Namensunterschiede veranschaulichen einige der oben genannten Änderungen. Diese Tabelle bietet eine Übersicht. Weitere Details und Codebeispiele finden Sie in den folgenden Abschnitten.

Alter Typname Nächster neuer Typ Symboltyp Änderungsbeschreibung
OpenAIClient AzureOpenAI Klasse Diese Klasse ersetzt die vorherige Klasse, und es gibt keine gemeinsamen Methoden. Weitere Informationen finden Sie im Abschnitt AzureOpenAI unten.
AudioResult Transcription/Transcription Schnittstelle Je nach aufrufendem Vorgang ersetzen die beiden Schnittstellen die vorherige Schnittstelle.
AudioResultFormat Inline-Union-Typ der response_format-Eigenschaft Alias Nicht vorhanden
AudioResultSimpleJson Transcription/Transcription Schnittstelle Je nach aufrufendem Vorgang ersetzen die beiden Schnittstellen die vorherige Schnittstelle.
AudioResultVerboseJson N/A Schnittstelle
AudioSegment N/A Schnittstelle
AudioTranscriptionTask N/A Alias
AzureChatEnhancementConfiguration, AzureChatEnhancements, AzureChatExtensionConfiguration, AzureChatExtensionConfigurationUnion, AzureChatExtensionDataSourceResponseCitation, AzureChatExtensionsMessageContext, AzureChatExtensionType, AzureChatGroundingEnhancementConfiguration, AzureChatOCREnhancementConfiguration, AzureCosmosDBChatExtensionConfiguration, AzureCosmosDBFieldMappingOptions, AzureExtensionsOptions, AzureGroundingEnhancement, AzureGroundingEnhancementCoordinatePoint, AzureGroundingEnhancementLine, AzureGroundingEnhancementLineSpan, AzureMachineLearningIndexChatExtensionConfiguration, AzureSearchChatExtensionConfiguration, AzureSearchIndexFieldMappingOptions, AzureSearchQueryType, ContentFilterBlocklistIdResult, ContentFilterCitedDetectionResult, ContentFilterDetectionResult, ContentFilterErrorResults, ContentFilterResult, ContentFilterResultDetailsForPrompt, ContentFilterResultsForChoice, ContentFilterSeverity, ContentFilterResultsForPrompt, ContentFilterSuccessResultDetailsForPrompt, ContentFilterSuccessResultsForChoice, ElasticsearchChatExtensionConfiguration, ElasticsearchIndexFieldMappingOptions, ElasticsearchQueryType, ImageGenerationContentFilterResults, ImageGenerationPromptFilterResults, OnYourDataAccessTokenAuthenticationOptions, OnYourDataApiKeyAuthenticationOptions, OnYourDataAuthenticationOptions, OnYourDataAuthenticationOptionsUnion, OnYourDataConnectionStringAuthenticationOptions, OnYourDataDeploymentNameVectorizationSource, OnYourDataEncodedApiKeyAuthenticationOptions, OnYourDataEndpointVectorizationSource, OnYourDataKeyAndKeyIdAuthenticationOptions, OnYourDataModelIdVectorizationSource, OnYourDataSystemAssignedManagedIdentityAuthenticationOptions, OnYourDataUserAssignedManagedIdentityAuthenticationOptions, OnYourDataVectorizationSource, OnYourDataVectorizationSourceType, OnYourDataVectorizationSourceUnion, PineconeChatExtensionConfiguration, PineconeFieldMappingOptions N/A Schnittstellen und Aliase Weitere Informationen finden Sie im Abschnitt Azure Typen unten
AzureKeyCredential N/A Klasse Der API-Schlüssel kann als Zeichenfolgenwert angegeben werden.
ChatChoice ChatCompletion.Choice Schnittstelle
ChatChoiceLogProbabilityInfo Logprobs Schnittstelle
ChatCompletions ChatCompletion und ChatCompletionChunk Schnittstelle
ChatCompletionsFunctionToolCall ChatCompletionMessageToolCall Schnittstelle
ChatRequestFunctionMessage ChatCompletionFunctionMessageParam Schnittstelle
ChatRequestMessage ChatCompletionMessageParam Schnittstelle
ChatRequestMessageUnion ChatCompletionMessageParam
ChatRequestSystemMessage ChatCompletionSystemMessageParam Schnittstelle
ChatRequestToolMessage ChatCompletionToolMessageParam Schnittstelle
ChatRequestUserMessage ChatCompletionUserMessageParam Schnittstelle
ChatResponseMessage Delta / ChatCompletionMessage Schnittstelle
ChatRole N/A Alias
ChatTokenLogProbabilityInfo TopLogprob Schnittstelle
ChatTokenLogProbabilityResult ChatCompletionTokenLogprob Schnittstelle
Choice Choice Schnittstelle
Completions Completion Schnittstelle
CompletionsFinishReason N/A Alias
CompletionsLogProbabilityModel Logprobs Schnittstelle
CompletionsUsage CompletionUsage Schnittstelle
EmbeddingItem Embedding Schnittstelle
Embeddings CreateEmbeddingResponse Schnittstelle
EmbeddingsUsage CreateEmbeddingResponse.Usage Schnittstelle
EventStream Stream Schnittstelle
FunctionCall FunctionCall Schnittstelle
FunctionCallPreset N/A Alias
FunctionDefinition Function Schnittstelle
FunctionName N/A Alias
GetAudioTranscriptionOptions TranscriptionCreateParams Schnittstelle
GetAudioTranslationOptions TranslationCreateParams Schnittstelle
GetChatCompletionsOptions ChatCompletionCreateParamsNonStreaming und ChatCompletionCreateParamsStreaming Schnittstelle
GetCompletionsOptions CompletionCreateParams Schnittstelle
GetEmbeddingsOptions EmbeddingCreateParams Schnittstelle
GetImagesOptions ImageGenerateParams Schnittstelle
ImageGenerationData Image Schnittstelle
ImageGenerationQuality N/A Alias
ImageGenerationResponseFormat N/A Alias
ImageGenerations ImagesResponse Schnittstelle
ImageGenerationStyle N/A Alias
ImageSize N/A Alias
MaxTokensFinishDetails N/A Schnittstelle
OpenAIClientOptions AzureClientOptions Schnittstelle
OpenAIError OpenAIError Schnittstelle
OpenAIKeyCredential N/A Klasse
StopFinishDetails N/A Schnittstelle

Azure-Typen

AzureOpenAI stellt eine Verbindung mit der Azure OpenAI her und kann alle im Dienst verfügbaren Operationen aufrufen. Die Typen der Anforderungen und Antworten werden jedoch von der OpenAI geerbt und werden noch nicht aktualisiert, um die zusätzlichen Features widerzuspiegeln, die ausschließlich vom Azure OpenAI-Dienst unterstützt werden. TypeScript-Benutzer müssen "@azure/openai/types" aus @azure/openai@2.0.0-beta.1 importieren, wodurch Azure-spezifische Definitionen in vorhandene Typen integriert werden. Beispiele im Migrationsexamples-Abschnitt zeigen, wie man das macht.

Nächste Schritte

  • Last updated on