Migrowanie do biblioteki openAI JavaScript API 4.x (wersja klasyczna)

Dotyczy tylko:Portal Foundry (Classic). Ten artykuł nie jest dostępny dla nowego portalu Foundry. Dowiedz się więcej o nowym portalu.

Uwaga / Notatka

Linki w tym artykule mogą otwierać zawartość w nowej dokumentacji Microsoft Foundry zamiast dokumentacji Foundry (klasycznej), którą obecnie przeglądasz.

Ważna

Najnowsze przykłady interfejsu API można znaleźć w artykule dotyczącym cyklu życia interfejsu API.

Uwierzytelnianie klienta

Istnieje kilka sposobów uwierzytelniania żądań interfejsu API do Azure OpenAI. Zdecydowanie zalecamy używanie tokenów Microsoft Entra ID. Aby uzyskać więcej informacji, zobacz dokumentację Azure Identity.

Microsoft Entra ID

Istnieje kilka sposobów uwierzytelniania za pomocą Azure OpenAI przy użyciu tokenów Microsoft Entra ID. Domyślnym sposobem jest użycie klasy DefaultAzureCredential z pakietu @azure/identity, ale aplikacja może używać innej klasy poświadczeń. Na potrzeby tego przewodnika zakładamy, że używasz DefaultAzureCredential klasy . Poświadczenie można utworzyć w następujący sposób:

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

Przekaż ten obiekt do drugiego argumentu konstruktora OpenAIClient .

Aby uwierzytelnić klienta AzureOpenAI, musimy jednak użyć funkcji getBearerTokenProvider z pakietu @azure/identity. Ta funkcja tworzy dostawcę tokenów, który AzureOpenAI używa wewnętrznie do uzyskiwania tokenów dla każdego żądania. Dostawca tokenu jest tworzony w następujący sposób:

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

azureADTokenProvider jest przekazywany do obiektu opcji podczas tworzenia klienta AzureOpenAI.

(Niepolecany) Klucz API

Nie używaj kluczy interfejsu API w środowisku produkcyjnym, ponieważ są one mniej bezpieczne niż inne metody uwierzytelniania. Wcześniej tworzono obiekty AzureKeyCredential w następujący sposób do uwierzytelniania elementu OpenAIClient:

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

Z drugiej strony, AzureOpenAI można uwierzytelnić za pomocą klucza API, ustawiając zmienną środowiskową AZURE_OPENAI_API_KEY lub ustawiając właściwość łańcucha znaków apiKey w obiekcie options podczas tworzenia klienta AzureOpenAI.

Ważna

Używaj kluczy interfejsu API z ostrożnością. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie. Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w Azure Key Vault. Aby uzyskać więcej informacji na temat bezpiecznego używania kluczy interfejsu API w aplikacjach, zobacz API keys with Azure Key Vault (Klucze interfejsu API Azure Key Vault

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań do usług Azure AI.

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

Punkt końcowy zasobu Azure OpenAI można określić, ustawiając opcję endpoint, ale można go również załadować przez klienta ze zmiennej środowiskowej AZURE_OPENAI_ENDPOINT. Jest to zalecany sposób ustawiania punktu końcowego, ponieważ umożliwia klientowi używanie go w różnych środowiskach bez zmiany kodu, a także ochronę punktu końcowego przed uwidocznieniem w kodzie.

Należy określić wersję interfejsu API. Jest to konieczne, aby upewnić się, że istniejący kod nie przerywa pracy między wersjami interfejsu API w wersji zapoznawczej. Zapoznaj się z dokumentacją wersjonowania API, aby dowiedzieć się więcej na temat wersji API Azure OpenAI. Ponadto właściwość nie jest wymagana, deployment ale zaleca się jej ustawienie. Gdy deployment zostanie ustawiony, jest używany jako domyślna konfiguracja wdrożeniowa dla wszystkich operacji, które go wymagają. Jeśli klient nie został utworzony za pomocą deployment opcji, model właściwość w obiekcie options powinna zostać ustawiona z nazwą wdrożenia. Jednak operacje audio, takie jak audio.transcriptions.create wymagają utworzenia klienta z opcją deployment ustawioną na nazwę wdrożenia.

import { OpenAIClient } from "@azure/openai";
const endpoint = "Your Azure OpenAI resource endpoint";
const client = new OpenAIClient(endpoint, credential);

Jeśli nie zostanie ustawiona, wersja interfejsu API zostanie domyślnie ustawiona na ostatni znany przed wydaniem klienta. Klient nie jest również zablokowany do wdrożenia jednego modelu, co oznacza, że do każdej metody wymagającej tego musi być przekazana nazwa wdrożenia.

Różnice między interfejsami API

Klienci OpenAIClient i AzureOpenAI mają kluczowe różnice:

OpenAIClient Przedstawia operacje jako płaską listę metod, takich jak client.getChatCompletions. AzureOpenAI grupuje operacje w zagnieżdżonych grupach, takich jak client.chat.completions.create.
OpenAIClient używa innych nazw niż interfejs API usługi Azure OpenAI. Na przykład interfejs API używa konwencji snake_case, a klient — camelCase. AzureOpenAI używa tych samych nazw jak interfejs API Azure OpenAI.

Przykłady migracji

W poniższych sekcjach przedstawiono przykłady migracji z OpenAIClient do AzureOpenAI.

Ukończenie czatu

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

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

const result = await client.getChatCompletions(deploymentName, messages, { maxTokens: 100 });

Należy zwrócić uwagę na następujące kwestie:

Metoda getChatCompletions została zastąpiona chat.completions.create metodą .
Parametr messages jest teraz przekazywany w obiekcie options z właściwością messages .
Zmień nazwę właściwości na maxTokensmax_tokens i usuń deploymentName parametr . Ogólnie rzecz biorąc, nazwy właściwości w options obiekcie są takie same jak w interfejsie API Azure OpenAI. Interfejs API używa konwencji snake_case zamiast konwencji camelCase stosowanej w OpenAIClient. Ta konwencja nazewnictwa dotyczy wszystkich właściwości wszystkich żądań i odpowiedzi w AzureOpenAI kliencie.
Parametr deploymentName nie jest wymagany, jeśli klient został utworzony przy użyciu deployment opcji . Jeśli klient nie został utworzony za pomocą deployment opcji, model właściwość w obiekcie opcji należy ustawić na nazwę wdrożenia.

Ukończenie czatu przesyłania strumieniowego

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

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

const stream = await client.streamChatCompletions(deploymentName, messages, { maxTokens: 100 });

Azure na Twoich danych

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

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",
        }
      }
    }]
});

const azureSearchEndpoint = "Your Azure Search resource endpoint";
const azureSearchIndexName = "Your Azure Search index name";
const result = await client.getChatCompletions(deploymentName, messages, { azureExtensionOptions: { 
    data_sources: [{
      type: "azure_search",
      endpoint: azureSearchEndpoint,
      indexName: azureSearchIndexName,
      authentication: {
        type: "system_assigned_managed_identity",
      }
    }]
  } 
});

"@azure/openai/types" jest importowany, co dodaje do typów klientów definicje specyficzne dla Azure (na przykład data_sources).
Właściwość azureExtensionOptions została zastąpiona właściwością wewnętrzną data_sources .
Dodano właściwość parameters w celu opakowania parametrów rozszerzenia, które odzwierciedla schemat interfejsu API Azure OpenAI.
Właściwości przypadku wielbłąda zostały zastąpione właściwościami przypadku węża.

Transkrypcja audio

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

import { createReadStream } from "fs";

const result = await client.audio.transcriptions.create({
  model: '',
  file: createReadStream(audioFilePath),
});

import { readFile } from "fs/promises";

const audioFilePath = "path/to/audio/file";
const audio = await readFile(audioFilePath);
const result = await client.getAudioTranscription(deploymentName, audio);

Metoda getAudioTranscription została zastąpiona audio.transcriptions.create metodą .
Element AzureOpenAI musi być skonstruowany z opcją deployment ustawioną na nazwę wdrożenia, aby można było używać operacji audio, takich jak audio.transcriptions.create.
Właściwość model jest wymagana do ustawienia w obiekcie options, ale jej wartość nie jest używana w operacji, więc można ją ustawić na dowolną wartość.
Właściwość file akceptuje różne typy, w tym Buffer, fs.ReadaStreami Blob , ale w tym przykładzie plik jest przesyłany strumieniowo z dysku przy użyciu polecenia fs.createReadStream.

Tłumaczenie audio

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

import { createReadStream } from "fs";

const result = await client.audio.translations.create({
  model: '',
  file: createReadStream(audioFilePath),
});

import { readFile } from "fs/promises";

const audioFilePath = "path/to/audio/file";
const audio = await readFile(audioFilePath);
const result = await client.getAudioTranslation(deploymentName, audio);

Metoda getAudioTranslation została zastąpiona audio.translations.create metodą .
Wszystkie inne zmiany są takie same jak w przykładzie transkrypcji audio.

Osadzanie

W poniższym przykładzie pokazano, jak przeprowadzić migrację wywołania metody getEmbeddings.

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

const embeddings = await client.embeddings.create({ input, model: '' });

const embeddings = await client.getEmbeddings(deploymentName, input);

Metoda getEmbeddings została zastąpiona embeddings.create metodą .
Parametr input jest teraz przekazywany w obiekcie options z właściwością input .
Parametr deploymentName został usunięty. Parametr deploymentName nie jest wymagany, jeśli klient został utworzony przy użyciu deployment opcji . Jeśli klient nie został utworzony za pomocą deployment opcji, model właściwość w obiekcie opcji należy ustawić na nazwę wdrożenia.

Generowanie obrazu

W poniższym przykładzie pokazano, jak przeprowadzić migrację wywołania metody getImages.

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

  const results = await client.images.generate({ prompt, model: '', n, size });

const results = await client.getImages(deploymentName, prompt, { n, size });

Metoda getImages została zastąpiona images.generate metodą .
Parametr prompt jest teraz przekazywany w obiekcie options z właściwością prompt .
Parametr deploymentName został usunięty. Parametr deploymentName nie jest wymagany, jeśli klient został utworzony przy użyciu deployment opcji . Jeśli klient nie został utworzony za pomocą deployment opcji, model właściwość w obiekcie opcji należy ustawić na nazwę wdrożenia.

Filtr zawartości

Wyniki filtru zawartości są częścią typów odpowiedzi uzupełniania czatu w pliku OpenAIClient. Jednak AzureOpenAI nie ma bezpośredniego odpowiednika właściwości contentFilterResults w interfejsie ChatCompletion.Choice. Dostęp do wyników filtru zawartości można uzyskać, importując "@azure/openai/types" i korzystając z właściwości content_filter_results. W poniższym przykładzie pokazano, jak uzyskać dostęp do wyników filtru zawartości.

OpenAI JavaScript (nowy)
Azure OpenAI JavaScript (poprzedni)

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

const results = await client.getChatCompletions(deploymentName, messages);
for (const choice of results.choices) {
  if (!choice.contentFilterResults) {
    console.log("No content filter is found");
    return;
  }
  if (choice.contentFilterResults.error) {
    console.log(
      `Content filter ran into the error ${choice.contentFilterResults.error.code}: ${choice.contentFilterResults.error.message}`);
  }
  const { hate, sexual, selfHarm, violence } = choice.contentFilterResults;
  ...
}

Właściwości przypadku wielbłąda zostały zastąpione właściwościami przypadku węża.
"@azure/openai/types" jest importowany, co dodaje definicje specyficzne dla platformy Azure (na przykład content_filter_results) do typów klientów, zobacz sekcję Typy Azure, aby uzyskać więcej informacji.

Porównywanie typów

W poniższej tabeli omówiono kilka nazw typów z @azure/openai i ich najbliższe openai odpowiedniki. Różnice nazw ilustrują kilka wymienionych powyżej zmian. Ta tabela zawiera omówienie, a w poniższych sekcjach znajdują się bardziej szczegółowe informacje i przykłady kodu.

Stara nazwa typu	Najbliższy nowy typ	Typ symbolu	Zmień opis
`OpenAIClient`	`AzureOpenAI`	Klasa	Ta klasa zastępuje poprzednią i nie ma wspólnych metod. Zobacz sekcję `AzureOpenAI` poniżej.
`AudioResult`	`Transcription`/`Transcription`	Interfejs	W zależności od operacji wywoływania dwa interfejsy zastępują pierwszy z nich
`AudioResultFormat`	wbudowany typ unii właściwości `response_format`	Pseudonim	Nie istnieje
`AudioResultSimpleJson`	`Transcription`/`Transcription`	Interfejs	W zależności od operacji wywoływania dwa interfejsy zastępują pierwszy z nich
`AudioResultVerboseJson`	N/A	Interfejs
`AudioSegment`	N/A	Interfejs
`AudioTranscriptionTask`	N/A	Pseudonim
`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	Interfejsy i aliasy	Zobacz sekcję typy Azure poniżej
`AzureKeyCredential`	N/A	Klasa	Klucz interfejsu API można podać jako wartość ciągu
`ChatChoice`	`ChatCompletion.Choice`	Interfejs
`ChatChoiceLogProbabilityInfo`	`Logprobs`	Interfejs
`ChatCompletions`	`ChatCompletion` i `ChatCompletionChunk`	Interfejs
`ChatCompletionsFunctionToolCall`	`ChatCompletionMessageToolCall`	Interfejs
`ChatRequestFunctionMessage`	`ChatCompletionFunctionMessageParam`	Interfejs
`ChatRequestMessage`	`ChatCompletionMessageParam`	Interfejs
`ChatRequestMessageUnion`	`ChatCompletionMessageParam`
`ChatRequestSystemMessage`	`ChatCompletionSystemMessageParam`	Interfejs
`ChatRequestToolMessage`	`ChatCompletionToolMessageParam`	Interfejs
`ChatRequestUserMessage`	`ChatCompletionUserMessageParam`	Interfejs
`ChatResponseMessage`	`Delta` / `ChatCompletionMessage`	Interfejs
`ChatRole`	N/A	Pseudonim
`ChatTokenLogProbabilityInfo`	`TopLogprob`	Interfejs
`ChatTokenLogProbabilityResult`	`ChatCompletionTokenLogprob`	Interfejs
`Choice`	`Choice`	Interfejs
`Completions`	`Completion`	Interfejs
`CompletionsFinishReason`	N/A	Pseudonim
`CompletionsLogProbabilityModel`	`Logprobs`	Interfejs
`CompletionsUsage`	`CompletionUsage`	Interfejs
`EmbeddingItem`	`Embedding`	Interfejs
`Embeddings`	`CreateEmbeddingResponse`	Interfejs
`EmbeddingsUsage`	`CreateEmbeddingResponse.Usage`	Interfejs
`EventStream`	`Stream`	Interfejs
`FunctionCall`	`FunctionCall`	Interfejs
`FunctionCallPreset`	N/A	Pseudonim
`FunctionDefinition`	`Function`	Interfejs
`FunctionName`	N/A	Pseudonim
`GetAudioTranscriptionOptions`	`TranscriptionCreateParams`	Interfejs
`GetAudioTranslationOptions`	`TranslationCreateParams`	Interfejs
`GetChatCompletionsOptions`	`ChatCompletionCreateParamsNonStreaming` i `ChatCompletionCreateParamsStreaming`	Interfejs
`GetCompletionsOptions`	`CompletionCreateParams`	Interfejs
`GetEmbeddingsOptions`	`EmbeddingCreateParams`	Interfejs
`GetImagesOptions`	`ImageGenerateParams`	Interfejs
`ImageGenerationData`	`Image`	Interfejs
`ImageGenerationQuality`	N/A	Pseudonim
`ImageGenerationResponseFormat`	N/A	Pseudonim
`ImageGenerations`	`ImagesResponse`	Interfejs
`ImageGenerationStyle`	N/A	Pseudonim
`ImageSize`	N/A	Pseudonim
`MaxTokensFinishDetails`	N/A	Interfejs
`OpenAIClientOptions`	`AzureClientOptions`	Interfejs
`OpenAIError`	`OpenAIError`	Interfejs
`OpenAIKeyCredential`	N/A	Klasa
`StopFinishDetails`	N/A	Interfejs

typy Azure

AzureOpenAI łączy się z Azure OpenAI i może wywoływać wszystkie operacje dostępne w usłudze. Jednak typy żądań i odpowiedzi są dziedziczone z OpenAI i nie są jeszcze aktualizowane w celu odzwierciedlenia dodatkowych funkcji obsługiwanych wyłącznie przez usługę Azure OpenAI. Użytkownicy języka TypeScript będą musieli zaimportować "@azure/openai/types" z @azure/openai@2.0.0-beta.1, które scalą definicje specyficzne dla Azure z istniejącymi typami. Przykłady w sekcji Przykłady migracji pokazują, jak to zrobić.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-11