Migrace na knihovnu OpenAI Rozhraní JavaScript API 4.x (classic)

Platí jenom pro:Portál Foundry (Classic). Tento článek není k dispozici pro nový portál Foundry. Přečtěte si další informace o novém portálu.

Poznámka:

Odkazy v tomto článku můžou otevírat obsah v nové dokumentaci Microsoft Foundry místo dokumentace Foundry (classic), kterou si právě prohlížíte.

Důležité

Nejnovější příklady rozhraní API najdete v článku o životním cyklu rozhraní API.

Ověřování klienta

Existuje několik způsobů, jak ověřovat požadavky rozhraní API na Azure OpenAI. Důrazně doporučujeme používat tokeny Microsoft Entra ID. Další informace najdete v dokumentaci k identitě Azure.

Microsoft Entra ID

Existuje několik způsobů, jak se ověřit pomocí Azure OpenAI pomocí tokenů Microsoft Entra ID. Výchozím způsobem je použít třídu DefaultAzureCredential z balíčku @azure/identity, ale vaše aplikace může používat jinou třídu pověření. Pro účely této příručky předpokládáme, že používáte DefaultAzureCredential třídu. Přihlašovací údaje je možné vytvořit následujícím způsobem:

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

Předejte tento objekt druhému argumentu konstruktoru OpenAIClient .

K ověření klienta AzureOpenAI však musíme použít funkci getBearerTokenProvider z balíčku @azure/identity. Tato funkce vytvoří zprostředkovatele tokenů, který AzureOpenAI interně používá k získání tokenů pro každý požadavek. Zprostředkovatel tokenu se vytvoří následujícím způsobem:

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

azureADTokenProvider je předán objektu options při vytváření AzureOpenAI klienta.

(Důrazně nedoporučujeme) Klíč rozhraní API

Nepoužívejte klíče rozhraní API v produkčním prostředí, protože jsou méně zabezpečené než jiné metody ověřování. Dříve jste vytvořili AzureKeyCredential objekty následujícím způsobem pro ověření OpenAIClient:

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

Na druhou stranu AzureOpenAI může být ověřen pomocí API klíče nastavením proměnné prostředí AZURE_OPENAI_API_KEY nebo nastavením řetězcové vlastnosti apiKey v objektu možností při vytváření klienta AzureOpenAI.

Důležité

Používejte klíče rozhraní API s opatrností. Nezahrnujte klíč API přímo do svého kódu a nikdy ho nezveřejňujte veřejně. Pokud používáte klíč rozhraní API, bezpečně ho uložte do Azure Key Vault. Další informace o bezpečném používání klíčů API v aplikacích najdete v tématu KLÍČEAPI s Azure Key Vault.

Další informace o zabezpečení služeb AI najdete v tématu Ověření požadavků na služby 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);

Koncový bod prostředku Azure OpenAI lze zadat nastavením možnosti endpoint, ale klient ho může načíst také z proměnné prostředí AZURE_OPENAI_ENDPOINT. Jedná se o doporučený způsob nastavení koncového bodu, protože umožňuje klientovi používat v různých prostředích beze změny kódu a také ochranu koncového bodu před zveřejněním v kódu.

Je potřeba zadat verzi rozhraní API, která je nezbytná k zajištění toho, aby se stávající kód mezi verzemi rozhraní API ve verzi Preview nepřerušil. Další informace o verzích rozhraní API Azure OpenAI najdete v dokumentaci k správě verzí . Kromě toho se tato vlastnost nevyžaduje, deployment ale doporučuje se ji nastavit. Jakmile je deployment nastaveno, je použito jako výchozí nasazení pro všechny operace, které ho vyžadují. Pokud klient není vytvořen s deployment volbou, model vlastnost v objektu options by měla být nastavena na název nasazení. Zvukové operace, jako je audio.transcriptions.create, vyžadují vytvoření klienta s možností deployment nastavenou na název nasazení.

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

Pokud není nastavená, verze rozhraní API se nastaví na poslední známou verzi před vydáním klienta. Klient také není uzamčený na jedno nasazení modelu, což znamená, že název nasazení musí být předán každé metodě, která ji vyžaduje.

Rozdíly rozhraní API

Klienti AzureOpenAI a OpenAIClient se v klíčových ohledech liší:

OpenAIClient představuje operace jako plochý seznam metod, například client.getChatCompletions. AzureOpenAI seskupuje operace ve vnořených skupinách, například client.chat.completions.create.
OpenAIClientpoužívá jiné názvy než rozhraní API služby Azure OpenAI. Například rozhraní API používá snake_case, ale klient používá camelCase. AzureOpenAIpoužívá stejné názvy jako Azure rozhraní API OpenAI.

Příklady migrace

Následující části uvádějí příklady, jak migrovat z OpenAIClient do AzureOpenAI.

Dokončení chatu

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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

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

Je potřeba upozornit na následující:

Metoda getChatCompletions byla nahrazena metodou chat.completions.create .
Parametr messages je nyní předán jako vlastnost objektu messages options.
Přejmenujte vlastnost maxTokens na max_tokens a odeberte parametr deploymentName. Obecně platí, že názvy vlastností v objektu options jsou stejné jako v rozhraní AZURE OpenAI API. Rozhraní API používá snake_case místo konvence camelCase používané v OpenAIClient. Tato konvence vytváření názvů se vztahuje na všechny vlastnosti napříč všemi požadavky a odpověďmi v klientovi AzureOpenAI .
Parametr deploymentName není potřeba, pokud byl klient vytvořen s deployment možností. Pokud klient nebyl vytvořen s deployment možností, model vlastnost v objektu možností by měla být nastavena s názvem nasazení.

Streaming dokončování chatu

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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 vašich datech

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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" je importován, který do typů klientů přidává definice specifické pro Azure (například data_sources).
Vlastnost azureExtensionOptions byla nahrazena vnitřní data_sources vlastností.
Byla přidána vlastnost parameters pro zabalení parametrů rozšíření, která zrcadlí schéma rozhraní API Azure OpenAI.
Vlastnosti ve formátu camel case byly nahrazeny vlastnostmi ve formátu snake_case.

Přepis zvuku

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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 byla nahrazena metodou audio.transcriptions.create .
Musí být AzureOpenAI sestavena s volbou nastavenou na deployment implementaci, aby bylo možné používat zvukové operace, jako je audio.transcriptions.create.
Vlastnost model musí být nastavena v objektu možností, ale její hodnota se v operaci nepoužívá, takže ji můžete nastavit na libovolnou hodnotu.
Vlastnost file přijímá různé typy, včetně Buffer, fs.ReadaStreama Blob v tomto příkladu se soubor streamuje z disku pomocí fs.createReadStream.

Překlad zvuku

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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 byla nahrazena metodou audio.translations.create .
Všechny ostatní změny jsou stejné jako v příkladu přepisu zvuku.

Zakotvení

Následující příklad ukazuje, jak migrovat volání metody getEmbeddings.

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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

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

Metoda getEmbeddings byla nahrazena metodou embeddings.create .
Parametr input je nyní předán jako vlastnost objektu input options.
Parametr deploymentName byl odebrán. Parametr deploymentName není potřeba, pokud byl klient vytvořen s deployment možností. Pokud klient nebyl vytvořen s deployment možností, model vlastnost v objektu možností by měla být nastavena s názvem nasazení.

Generování obrázků

Následující příklad ukazuje, jak migrovat volání metody getImages.

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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

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

Metoda getImages byla nahrazena metodou images.generate .
Parametr prompt je nyní předán jako vlastnost objektu prompt options.
Parametr deploymentName byl odebrán. Parametr deploymentName není potřeba, pokud byl klient vytvořen s deployment možností. Pokud klient nebyl vytvořen s deployment možností, model vlastnost v objektu možností by měla být nastavena s názvem nasazení.

Filtr obsahu

Výsledky filtru obsahu jsou součástí typů odpovědí na dokončení chatu v OpenAIClient. AzureOpenAI Nemá však přímý ekvivalent vlastnosti contentFilterResults v ChatCompletion.Choice rozhraní. K výsledkům filtru obsahu se dostanete importem "@azure/openai/types" a přístupem k vlastnosti content_filter_results. Následující příklad ukazuje, jak přistupovat k výsledkům filtrování obsahu.

OpenAI JavaScript (nový)
Azure OpenAI JavaScript (předchozí)

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

Vlastnosti ve formátu camel case byly nahrazeny vlastnostmi ve formátu snake_case.
"@azure/openai/types" je importován, který přidává definice specifické pro Azure (například content_filter_results) do typů klientů, další informace najdete v části typy Azure.

Porovnání typů

Následující tabulka zkoumá několik názvů typů z @azure/openai a zobrazuje jejich nejbližší openai ekvivalent. Rozdíly v názvech ilustrují několik výše uvedených změn. Tato tabulka obsahuje přehled a další podrobnosti a ukázky kódu najdete v následujících částech.

Starý název typu	Nejbližší nový typ	Typ symbolu	Změna popisu
`OpenAIClient`	`AzureOpenAI`	Class	Tato třída nahrazuje bývalou třídu a nemá s ní společné žádné metody. Další informace naleznete v části `AzureOpenAI` níže.
`AudioResult`	`Transcription`/`Transcription`	Rozhraní	V závislosti na volající operaci nahradí obě rozhraní první rozhraní.
`AudioResultFormat`	typ sloučení inline vlastnosti `response_format`	Alias	Neexistuje
`AudioResultSimpleJson`	`Transcription`/`Transcription`	Rozhraní	V závislosti na volající operaci nahradí obě rozhraní první rozhraní.
`AudioResultVerboseJson`	N/A	Rozhraní
`AudioSegment`	N/A	Rozhraní
`AudioTranscriptionTask`	N/A	Alias
`AzureChatEnhancementConfiguration`, `AzureChatEnhancements`, `AzureChatExtensionConfiguration`, `AzureChatExtensionConfigurationUnionAzureChatExtensionDataSourceResponseCitationAzureChatExtensionsMessageContextAzureChatExtensionTypeAzureChatGroundingEnhancementConfigurationAzureChatOCREnhancementConfigurationAzureCosmosDBChatExtensionConfigurationAzureCosmosDBFieldMappingOptionsAzureExtensionsOptionsAzureGroundingEnhancementAzureGroundingEnhancementCoordinatePointAzureGroundingEnhancementLineAzureGroundingEnhancementLineSpanAzureMachineLearningIndexChatExtensionConfigurationAzureSearchChatExtensionConfigurationAzureSearchIndexFieldMappingOptionsAzureSearchQueryTypeContentFilterBlocklistIdResultContentFilterCitedDetectionResultContentFilterDetectionResultContentFilterErrorResultsContentFilterResultContentFilterResultDetailsForPromptContentFilterResultsForChoiceContentFilterSeverityContentFilterResultsForPromptContentFilterSuccessResultDetailsForPromptContentFilterSuccessResultsForChoiceElasticsearchChatExtensionConfigurationElasticsearchIndexFieldMappingOptionsElasticsearchQueryTypeImageGenerationContentFilterResultsImageGenerationPromptFilterResultsOnYourDataAccessTokenAuthenticationOptionsOnYourDataApiKeyAuthenticationOptionsOnYourDataAuthenticationOptionsOnYourDataAuthenticationOptionsUnionOnYourDataConnectionStringAuthenticationOptionsOnYourDataDeploymentNameVectorizationSourceOnYourDataEncodedApiKeyAuthenticationOptionsOnYourDataEndpointVectorizationSourceOnYourDataKeyAndKeyIdAuthenticationOptionsOnYourDataModelIdVectorizationSourceOnYourDataSystemAssignedManagedIdentityAuthenticationOptionsOnYourDataUserAssignedManagedIdentityAuthenticationOptionsOnYourDataVectorizationSourceOnYourDataVectorizationSourceTypeOnYourDataVectorizationSourceUnionPineconeChatExtensionConfigurationPineconeFieldMappingOptions`	N/A	Rozhraní a aliasy	Viz sekci typů Azure níže.
`AzureKeyCredential`	N/A	Class	Klíč rozhraní API je možné zadat jako řetězcovou hodnotu.
`ChatChoice`	`ChatCompletion.Choice`	Rozhraní
`ChatChoiceLogProbabilityInfo`	`Logprobs`	Rozhraní
`ChatCompletions`	`ChatCompletion` a `ChatCompletionChunk`	Rozhraní
`ChatCompletionsFunctionToolCall`	`ChatCompletionMessageToolCall`	Rozhraní
`ChatRequestFunctionMessage`	`ChatCompletionFunctionMessageParam`	Rozhraní
`ChatRequestMessage`	`ChatCompletionMessageParam`	Rozhraní
`ChatRequestMessageUnion`	`ChatCompletionMessageParam`
`ChatRequestSystemMessage`	`ChatCompletionSystemMessageParam`	Rozhraní
`ChatRequestToolMessage`	`ChatCompletionToolMessageParam`	Rozhraní
`ChatRequestUserMessage`	`ChatCompletionUserMessageParam`	Rozhraní
`ChatResponseMessage`	`Delta` / `ChatCompletionMessage`	Rozhraní
`ChatRole`	N/A	Alias
`ChatTokenLogProbabilityInfo`	`TopLogprob`	Rozhraní
`ChatTokenLogProbabilityResult`	`ChatCompletionTokenLogprob`	Rozhraní
`Choice`	`Choice`	Rozhraní
`Completions`	`Completion`	Rozhraní
`CompletionsFinishReason`	N/A	Alias
`CompletionsLogProbabilityModel`	`Logprobs`	Rozhraní
`CompletionsUsage`	`CompletionUsage`	Rozhraní
`EmbeddingItem`	`Embedding`	Rozhraní
`Embeddings`	`CreateEmbeddingResponse`	Rozhraní
`EmbeddingsUsage`	`CreateEmbeddingResponse.Usage`	Rozhraní
`EventStream`	`Stream`	Rozhraní
`FunctionCall`	`FunctionCall`	Rozhraní
`FunctionCallPreset`	N/A	Alias
`FunctionDefinition`	`Function`	Rozhraní
`FunctionName`	N/A	Alias
`GetAudioTranscriptionOptions`	`TranscriptionCreateParams`	Rozhraní
`GetAudioTranslationOptions`	`TranslationCreateParams`	Rozhraní
`GetChatCompletionsOptions`	`ChatCompletionCreateParamsNonStreaming` a `ChatCompletionCreateParamsStreaming`	Rozhraní
`GetCompletionsOptions`	`CompletionCreateParams`	Rozhraní
`GetEmbeddingsOptions`	`EmbeddingCreateParams`	Rozhraní
`GetImagesOptions`	`ImageGenerateParams`	Rozhraní
`ImageGenerationData`	`Image`	Rozhraní
`ImageGenerationQuality`	N/A	Alias
`ImageGenerationResponseFormat`	N/A	Alias
`ImageGenerations`	`ImagesResponse`	Rozhraní
`ImageGenerationStyle`	N/A	Alias
`ImageSize`	N/A	Alias
`MaxTokensFinishDetails`	N/A	Rozhraní
`OpenAIClientOptions`	`AzureClientOptions`	Rozhraní
`OpenAIError`	`OpenAIError`	Rozhraní
`OpenAIKeyCredential`	N/A	Class
`StopFinishDetails`	N/A	Rozhraní

typy Azure

AzureOpenAI se připojí k Azure OpenAI a může vyvolávat všechny operace dostupné ve službě. Typy požadavků a odpovědí se však dědí z OpenAI a ještě se neaktualizují tak, aby odrážely další funkce podporované výhradně službou Azure OpenAI. Uživatelé TypeScriptu budou muset importovat "@azure/openai/types" z @azure/openai@2.0.0-beta.1, které sloučí definice specifické pro Azure do existujících typů. Příklady v sekci příkladů migrace ukazují, jak to udělat.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-11