Migração para a biblioteca OpenAI API de JavaScript 4.x (clássica)

Aplica-se apenas a:Foundry (clássico) portal. Este artigo não está disponível para o novo portal da Foundry. Saiba mais sobre o novo portal.

Observação

Os links neste artigo podem abrir conteúdo na nova documentação do Microsoft Foundry em vez da documentação do Foundry (clássico) que está a ver agora.

Importante

Para os exemplos mais recentes de APIs, consulte o artigo sobre o ciclo de vida da API.

Autenticando o cliente

Existem várias formas de autenticar pedidos de API no Azure OpenAI. Recomendamos vivamente o uso de tokens Microsoft Entra ID. Consulte a documentação Azure Identidade para mais informações.

Microsoft Entra ID

Existem várias formas de autenticar com o Azure OpenAI usando tokens Microsoft Entra ID. A forma padrão é usar a classe DefaultAzureCredential do pacote @azure/identity, mas a tua aplicação pode estar a usar uma classe de credencial diferente. Para os fins deste guia, assumimos que você está usando a DefaultAzureCredential classe. Uma credencial pode ser criada da seguinte maneira:

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

Passe este objeto como segundo argumento do construtor OpenAIClient.

Para autenticar o cliente AzureOpenAI, no entanto, precisamos de usar a função getBearerTokenProvider do pacote @azure/identity. Essa função cria um provedor de token que AzureOpenAI usa internamente para obter tokens para cada solicitação. O provedor de token é criado da seguinte maneira:

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

azureADTokenProvider é passado para o objeto options ao criar o AzureOpenAI cliente.

Chave API (Altamente desencorajada)

Não uses chaves API em produção porque são menos seguras do que outros métodos de autenticação. Anteriormente, criou objetos AzureKeyCredential da seguinte forma para autenticar OpenAIClient:

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

Por outro lado, AzureOpenAI pode ser autenticado com uma chave de API, definindo a variável de ambiente AZURE_OPENAI_API_KEY ou definindo a propriedade de cadeia de caracteres apiKey no objeto de opções ao criar o cliente AzureOpenAI.

Importante

Use chaves de API com cuidado. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se usares uma chave API, guarda-a de forma segura no Azure Key Vault. Para mais informações sobre o uso seguro das chaves API nas suas aplicações, consulte chaves API com Azure Key Vault.

Para mais informações sobre a segurança dos serviços de IA, consulte Autenticar pedidos para Serviços de IA do Azure.

Construindo o cliente

OpenAI JavaScript (novo)

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

O endpoint do recurso Azure OpenAI pode ser especificado definindo a opção endpoint, mas também pode ser carregado pelo cliente a partir da variável de ambiente AZURE_OPENAI_ENDPOINT. Esta é a maneira recomendada de definir o ponto de extremidade porque permite que o cliente seja usado em ambientes diferentes sem alterar o código e também para proteger o ponto de extremidade de ser exposto no código.

A versão da API deve ser especificada, isso é necessário para garantir que o código existente não se quebre entre as versões da API de visualização. Consulte a documentação de versionamento da API para saber mais sobre as versões da API do Azure OpenAI. Além disso, a deployment propriedade não é necessária, mas recomenda-se que seja definida. Uma vez deployment definido, ele é usado como a implantação padrão para todas as operações que o exigem. Se o cliente não for criado com a deployment opção, a model propriedade no objeto de opções deverá ser definida com o nome da implantação. No entanto, operações de áudio como audio.transcriptions.create exigem que o cliente seja criado com a opção deployment definida para o nome da implantação.

Azure OpenAI JavaScript (anterior)

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

Se não estiver definida, a versão da API assume como padrão a última conhecida antes do lançamento do cliente. O cliente também não está limitado a uma única implantação de modelo, o que significa que o nome da implantação deve ser passado para cada método que o requer.

Diferenças da API

Os clientes OpenAIClient e AzureOpenAI têm diferenças principais:

• OpenAIClient apresenta as operações como uma lista plana de métodos, como client.getChatCompletions. AzureOpenAI agrupa operações em grupos aninhados, como client.chat.completions.create.
• OpenAIClient usa nomes diferentes da API do Azure OpenAI. Por exemplo, a API usa snake case, mas o cliente usa camel case. AzureOpenAIusa os mesmos nomes da API Azure OpenAI.

Exemplos de migração

As secções seguintes fornecem exemplos de como migrar de OpenAIClient para AzureOpenAI.

Finalizações de chat

OpenAI JavaScript (novo)

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

Azure OpenAI JavaScript (anterior)

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

Tenha em atenção o seguinte:

• O getChatCompletions método foi substituído pelo chat.completions.create método.
• O messages parâmetro agora é passado no objeto options com a propriedade messages.
• Renomeie a maxTokens propriedade para max_tokens e remova o deploymentName parâmetro. Geralmente, os nomes das propriedades no options objeto são os mesmos que na API do Azure OpenAI. A API utiliza snake_case em vez da convenção camelCase usada em OpenAIClient. Esta convenção de nomenclatura aplica-se a todas as propriedades em todos os pedidos e respostas do AzureOpenAI cliente.
• O deploymentName parâmetro não é necessário se o cliente foi criado com a deployment opção. Se o cliente não foi criado com a deployment opção, a model propriedade no objeto de opção deve ser definida com o nome da implantação.

Conclusão do bate-papo em streaming

OpenAI JavaScript (novo)

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

Azure OpenAI JavaScript (anterior)

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

Azure nos seus dados

OpenAI JavaScript (novo)

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 JavaScript (anterior)

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" é importado, o que adiciona definições específicas de Azure (por exemplo, data_sources) aos tipos de cliente.
• A azureExtensionOptions propriedade foi substituída pela propriedade interna data_sources .
• A propriedade parameters foi adicionada para envolver os parâmetros da extensão, que espelha o esquema da API Azure OpenAI.
• As propriedades da caixa do camelo foram substituídas pelas propriedades da caixa da cobra.

Transcrição de áudio

OpenAI JavaScript (novo)

import { createReadStream } from "fs";

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

Azure OpenAI JavaScript (anterior)

import { readFile } from "fs/promises";

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

• O getAudioTranscription método foi substituído pelo audio.transcriptions.create método.
• O AzureOpenAI tem que ser construído com a opção deployment definida para o nome da implantação para usar operações de áudio, como audio.transcriptions.create.
• A model propriedade deve ser definida no objeto options, mas seu valor não é usado na operação, então sinta-se à vontade para defini-la como qualquer valor.
• A file propriedade aceita vários tipos, incluindo Buffer, fs.ReadaStreame Blob mas neste exemplo, um arquivo é transmitido do disco usando fs.createReadStream.

Tradução áudio

OpenAI JavaScript (novo)

import { createReadStream } from "fs";

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

Azure OpenAI JavaScript (anterior)

import { readFile } from "fs/promises";

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

• O getAudioTranslation método foi substituído pelo audio.translations.create método.
• Todas as outras alterações são as mesmas do exemplo de transcrição de áudio.

Incorporações

O exemplo seguinte mostra como migrar a chamada do método getEmbeddings.

OpenAI JavaScript (novo)

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

Azure OpenAI JavaScript (anterior)

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

• O getEmbeddings método foi substituído pelo embeddings.create método.
• O input parâmetro agora é passado no objeto options com a propriedade input.
• O deploymentName parâmetro foi removido. O deploymentName parâmetro não é necessário se o cliente foi criado com a deployment opção. Se o cliente não foi criado com a deployment opção, a model propriedade no objeto de opção deve ser definida com o nome da implantação.

Geração de imagens

O exemplo seguinte mostra como migrar a chamada do método getImages.

OpenAI JavaScript (novo)

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

Azure OpenAI JavaScript (anterior)

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

• O getImages método foi substituído pelo images.generate método.
• O prompt parâmetro agora é passado no objeto options com a propriedade prompt.
• O deploymentName parâmetro foi removido. O deploymentName parâmetro não é necessário se o cliente foi criado com a deployment opção. Se o cliente não foi criado com a deployment opção, a model propriedade no objeto de opção deve ser definida com o nome da implantação.

Filtro de conteúdo

Os resultados do filtro de conteúdo são parte dos tipos de resposta de conclusão de chat em OpenAIClient. No entanto, AzureOpenAI não tem um equivalente direto à contentFilterResults propriedade na ChatCompletion.Choice interface. Os resultados do filtro de conteúdo podem ser acedidos importando "@azure/openai/types" e acedendo à propriedade content_filter_results. O exemplo seguinte mostra como acess aos resultados do filtro de conteúdo.

OpenAI JavaScript (novo)

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

Azure OpenAI JavaScript (anterior)

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

• As propriedades da caixa do camelo foram substituídas pelas propriedades da caixa da cobra.
• "@azure/openai/types" é importado, o que adiciona definições específicas de Azure (por exemplo, content_filter_results) aos tipos de cliente, consulte a secção Azure tipos para mais informações.

Comparando tipos

A tabela seguinte explora vários nomes de tipos a partir de @azure/openai e mostra o seu equivalente mais próximo openai. As diferenças de nomes ilustram várias das alterações acima mencionadas. Esta tabela fornece uma visão geral, e mais detalhes e exemplos de código são fornecidos nas seções a seguir.

Nome do tipo antigo	Tipo Novo Mais Próximo	Tipo de símbolo	Alterar a descrição
OpenAIClient	AzureOpenAI	Classe	Esta classe substitui a anterior e não tem métodos em comum com ela. Consulte a seção em AzureOpenAI abaixo.
AudioResult	Transcription/Transcription	Interfaz	Dependendo da operação de chamada, as duas interfaces substituem a anterior
AudioResultFormat	tipo de união inline da response_format propriedade	Alias	Não existe
AudioResultSimpleJson	Transcription/Transcription	Interfaz	Dependendo da operação de chamada, as duas interfaces substituem a anterior
AudioResultVerboseJson	N/A	Interfaz
AudioSegment	N/A	Interfaz
AudioTranscriptionTask	N/A	Alias
AzureChatEnhancementConfiguration, AzureChatEnhancements, AzureChatExtensionConfigurationUnion, AzureChatExtensionConfiguration, 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	Interfaces e aliases	Consulte a secção de tipos Azure abaixo
AzureKeyCredential	N/A	Classe	A chave da API pode ser fornecida como um valor de cadeia de caracteres
ChatChoice	ChatCompletion.Choice	Interfaz
ChatChoiceLogProbabilityInfo	Logprobs	Interfaz
ChatCompletions	ChatCompletion e ChatCompletionChunk	Interfaz
ChatCompletionsFunctionToolCall	ChatCompletionMessageToolCall	Interfaz
ChatRequestFunctionMessage	ChatCompletionFunctionMessageParam	Interfaz
ChatRequestMessage	ChatCompletionMessageParam	Interfaz
ChatRequestMessageUnion	ChatCompletionMessageParam
ChatRequestSystemMessage	ChatCompletionSystemMessageParam	Interfaz
ChatRequestToolMessage	ChatCompletionToolMessageParam	Interfaz
ChatRequestUserMessage	ChatCompletionUserMessageParam	Interfaz
ChatResponseMessage	Delta / ChatCompletionMessage	Interfaz
ChatRole	N/A	Alias
ChatTokenLogProbabilityInfo	TopLogprob	Interfaz
ChatTokenLogProbabilityResult	ChatCompletionTokenLogprob	Interfaz
Choice	Choice	Interfaz
Completions	Completion	Interfaz
CompletionsFinishReason	N/A	Alias
CompletionsLogProbabilityModel	Logprobs	Interfaz
CompletionsUsage	CompletionUsage	Interfaz
EmbeddingItem	Embedding	Interfaz
Embeddings	CreateEmbeddingResponse	Interfaz
EmbeddingsUsage	CreateEmbeddingResponse.Usage	Interfaz
EventStream	Stream	Interfaz
FunctionCall	FunctionCall	Interfaz
FunctionCallPreset	N/A	Alias
FunctionDefinition	Function	Interfaz
FunctionName	N/A	Alias
GetAudioTranscriptionOptions	TranscriptionCreateParams	Interfaz
GetAudioTranslationOptions	TranslationCreateParams	Interfaz
GetChatCompletionsOptions	ChatCompletionCreateParamsNonStreaming e ChatCompletionCreateParamsStreaming	Interfaz
GetCompletionsOptions	CompletionCreateParams	Interfaz
GetEmbeddingsOptions	EmbeddingCreateParams	Interfaz
GetImagesOptions	ImageGenerateParams	Interfaz
ImageGenerationData	Image	Interfaz
ImageGenerationQuality	N/A	Alias
ImageGenerationResponseFormat	N/A	Alias
ImageGenerations	ImagesResponse	Interfaz
ImageGenerationStyle	N/A	Alias
ImageSize	N/A	Alias
MaxTokensFinishDetails	N/A	Interfaz
OpenAIClientOptions	AzureClientOptions	Interfaz
OpenAIError	OpenAIError	Interfaz
OpenAIKeyCredential	N/A	Classe
StopFinishDetails	N/A	Interfaz

Tipos do Azure

AzureOpenAI liga-se à Azure OpenAI e pode chamar todas as operações disponíveis no serviço. No entanto, os tipos de pedidos e respostas são herdados do OpenAI e ainda não são atualizados para refletir as funcionalidades adicionais suportadas exclusivamente pelo serviço Azure OpenAI. Os utilizadores de TypeScript terão de importar "@azure/openai/types" de @azure/openai@2.0.0-beta.1, o que irá fundir definições específicas de Azure em tipos já existentes. Exemplos na secção Migração mostram como fazer isto.