Migrando para a biblioteca de API JavaScript do OpenAI 4.x

A partir de junho de 2024, recomendamos migrar para a biblioteca JavaScript da API OpenAI 4.x, a versão mais recente da biblioteca oficial do cliente JavaScript do OpenAI, que dá suporte ao Azure OpenAI na versão 2022-12-01 e posteriores da API de Modelos Azure AI Foundry. Este artigo ajuda você a atualizar as alterações específicas para o OpenAI do Azure.

Autenticação do usuário

Há várias maneiras de autenticar solicitações de API no OpenAI do Azure. É altamente recomendável usar tokens do Microsoft Entra. Consulte a Documentação da Identidade do Azure para obter mais informações.

Microsoft Entra ID

Há várias maneiras de autenticar com o Azure OpenAI usando tokens de ID do Microsoft Entra. A maneira padrão é usar a classe DefaultAzureCredential do pacote @azure/identity, mas seu aplicativo pode estar usando uma classe de credencial diferente. Para os fins deste guia, presumimos que você esteja usando a classe DefaultAzureCredential. Uma credencial pode ser criada da seguinte maneira:

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

Em seguida, esse objeto é passado para o segundo argumento dos construtores OpenAIClient e AssistantsClient do cliente.

No entanto, para autenticar o cliente AzureOpenAI, precisamos usar a função getBearerTokenProvider do pacote @azure/identity. Essa função cria um provedor de token que usa AzureOpenAI 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://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

azureADTokenProvider é passado para o objeto de opções ao criar o AzureOpenAI cliente.

(Altamente Desencorajado) Chave de API

As chaves de API não são recomendadas para uso em produção porque são menos seguras do que outros métodos de autenticação. Anteriormente, objetos AzureKeyCredential eram criados da seguinte maneira para autenticar OpenAIClient ou AssistantsClient:

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

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

Importante

Use as chaves de API com cautela. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Azure Key Vault. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, confira Chaves de API com o Azure Key Vault.

Para obter mais informações sobre a segurança dos serviços de IA, veja Autenticar solicitações para serviços de IA do Azure.

Como construir o cliente

JavaScript do OpenAI (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 ponto de extremidade do recurso OpenAI do Azure pode ser especificado definindo a opção endpoint, mas também pode ser carregado pelo cliente da variável de ambienteAZURE_OPENAI_ENDPOINT. Essa é 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 proteger o ponto de extremidade de ser exposto no código.

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

JavaScript do OpenAI do Azure (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 usará como padrão a última conhecida antes da versão do cliente. O cliente também não está bloqueado para uma única implantação de modelo, o que significa que o nome da implantação deve ser passado para cada método que o exija.

Diferenças de API

Há diferenças importantes entre os clientes OpenAIClient e AssistantsClient e o cliente AzureOpenAI:

• As operações são representadas como uma lista simples de métodos em OpenAIClient e AssistantsClient, por exemplo client.getChatCompletions. Em AzureOpenAI, as operações são agrupadas em grupos aninhados, por exemplo client.chat.completions.create.
• OpenAIClient e AssistantsClient renomeiam muitos dos nomes usados na API OpenAI do Azure. Por exemplo, o caso snake é usado na API, mas o caso camel é usado no cliente. Em AzureOpenAI, os nomes são mantidos da mesma forma que na API openai do Azure.

Exemplos de migração

As seções a seguir fornecem exemplos de como migrar de OpenAIClient e AssistantsClient para AzureOpenAI.

Preenchimentos de chat

JavaScript do OpenAI (novo)

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

JavaScript do OpenAI do Azure (anterior)

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

Observe o seguinte:

• O método getChatCompletions foi substituído pelo método chat.completions.create.
• O parâmetro messages agora é passado no objeto opções com a propriedade messages.
• A propriedade maxTokens foi renomeada como max_tokens e o parâmetro deploymentName foi removido. Geralmente, os nomes das propriedades no objeto options são os mesmos da API OpenAI do Azure, seguindo a convenção snake_case em vez da convenção camelCase usada no AssistantsClient. Isso é verdadeiro para todas as propriedades em todas as solicitações e respostas no clienteAzureOpenAI.
• O parâmetro deploymentName não será necessário se o cliente tiver sido criado com a opção deployment. Se o cliente não tiver sido criado com a opção deployment, a propriedade model no objeto option deverá ser definida com o nome da implantação.

Conclusões de chat de streaming

JavaScript do OpenAI (novo)

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

JavaScript do OpenAI do Azure (anterior)

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

Azure nos seus dados

JavaScript do OpenAI (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",
        }
      }
    }]
});

JavaScript do OpenAI do Azure (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 do Azure (por exemplo, data_sources) aos tipos de cliente.
• A propriedade azureExtensionOptions foi substituída pela propriedade interna data_sources.
• A parameters propriedade foi adicionada para encapsular os parâmetros da extensão, que espelha o esquema da API openai do Azure.
• As propriedades do caso camel foram substituídas por propriedades de casos de cobra.

Transcrição de áudio

JavaScript do OpenAI (novo)

import { createReadStream } from "fs";

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

JavaScript do OpenAI do Azure (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 método getAudioTranscription foi substituído pelo método audio.transcriptions.create.
• O AzureOpenAI deve ser construído com a opção deployment definida como o nome da implantação para usar operações de áudio, como audio.transcriptions.create.
• A propriedade model é necessária para ser definida no objeto de opções, mas seu valor não é usado na operação, portanto, fique à vontade para defini-la como qualquer valor.
• A propriedade file aceita vários tipos, incluindo Buffer, fs.ReadaStream e Blob mas, nesse exemplo, um arquivo é transmitido do disco usando fs.createReadStream.

Tradução de áudio

JavaScript do OpenAI (novo)

import { createReadStream } from "fs";

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

JavaScript do OpenAI do Azure (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 método getAudioTranslation foi substituído pelo método audio.translations.create.
• Todas as outras alterações são as mesmas do exemplo de transcrição de áudio.

Assistentes

Os exemplos a seguir mostram como migrar alguns dos métodos AssistantsClient.

Criação do Assistente

JavaScript do OpenAI (novo)

const options = ...;
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);

JavaScript do OpenAI do Azure (anterior)

const options = {
  model: azureOpenAIDeployment,
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" }],
};
const assistantResponse = await assistantsClient.createAssistant(options);

• O método createAssistant foi substituído pelo método beta.assistants.create

Criação de Thread

O exemplo a seguir mostra como migrar a chamada de método createThread.

JavaScript do OpenAI (novo)

const assistantThread = await assistantsClient.beta.threads.create();

JavaScript do OpenAI do Azure (anterior)

const assistantThread = await assistantsClient.createThread();

• O método createThread foi substituído pelo método beta.threads.create

Criação de Mensagem

O exemplo a seguir mostra como migrar a chamada de método createMessage.

JavaScript do OpenAI (novo)

const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);

JavaScript do OpenAI do Azure (anterior)

const threadResponse = await assistantsClient.createMessage(
  assistantThread.id,
  role,
  message
);

• O método createMessage foi substituído pelo método beta.threads.messages.create.
• A especificação da mensagem foi movida de uma lista de parâmetros para um objeto.

Execuções

Para executar um assistente em um thread, o método createRun é usado para criar uma execução e, em seguida, um loop é usado para sondar o status de execução até que ele esteja em um estado terminal. O exemplo a seguir mostra como migrar a criação e a sondagem da execução.

JavaScript do OpenAI (novo)

Esse código pode ser migrado e simplificado usando o método createAndPoll, que cria uma execução e o sonda até estar em um estado terminal.

const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);

JavaScript do OpenAI do Azure (anterior)

let runResponse = await assistantsClient.createRun(assistantThread.id, {
  assistantId: assistantResponse.id,
});

do {
  await new Promise((r) => setTimeout(r, 500));
  runResponse = await assistantsClient.getRun(
    assistantThread.id,
    runResponse.id
  );
} while (
  runResponse.status === "queued" ||
  runResponse.status === "in_progress"

• O método createRun foi substituído pelos métodos beta.threads.runs.create e createAndPoll.
• O método createAndPoll é usado para criar uma execução e sondar até que ele esteja em um estado terminal.

Resultados da Execução de Processamento

JavaScript do OpenAI (novo)

As páginas podem ser executadas em loop usando o loop for await.

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

JavaScript do OpenAI do Azure (anterior)

Sem paginação, os resultados tinham que ser acessados manualmente página por página usando a propriedade data do objeto de resposta. Por exemplo, o acesso à primeira página pode ser feito da seguinte maneira:

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

Inserções

O exemplo a seguir mostra como migrar a chamada de método getEmbeddings.

JavaScript do OpenAI (novo)

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

JavaScript do OpenAI do Azure (anterior)

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

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

Geração de imagem

O exemplo a seguir mostra como migrar a chamada de método getImages.

JavaScript do OpenAI (novo)

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

JavaScript do OpenAI do Azure (anterior)

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

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

Filtro de conteúdo

Os resultados do filtro de conteúdo fazem parte dos tipos de resposta de conclusões de chat em OpenAIClient. No entanto, AzureOpenAI não tem um equivalente direto à propriedade contentFilterResults na interface ChatCompletion.Choice. Os resultados do filtro de conteúdo podem ser acessados importando "@azure/openai/types" e acessando a propriedadecontent_filter_results. O exemplo a seguir mostra como acessar os resultados do filtro de conteúdo.

JavaScript do OpenAI (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;
  ...
}

JavaScript do OpenAI do Azure (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 do caso camel foram substituídas por propriedades de casos de cobra.
• "@azure/openai/types" é importado, o que adiciona definições específicas do Azure (por exemplo, content_filter_results) aos tipos de cliente, consulte a seção deTipos do Azure para obter mais informações.

Comparando Tipos

A tabela a seguir explora vários nomes de tipo de @azure/openai e mostra seu openai equivalente mais próximo. As diferenças de nomes ilustram várias das alterações mencionadas acima. 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	Novo Tipo Mais Próximo	Tipo de Símbolo	Descrição das alterações
OpenAIClient	AzureOpenAI	Classe	Essa classe substitui a primeira e não tem métodos em comum com ela. Consulte a seção no AzureOpenAI abaixo.
AudioResult	Transcription/Transcription	Interfase	Dependendo da operação de chamada, as duas interfaces substituem a anterior
AudioResultFormat	tipo de união embutida da propriedade response_format	Apelido	Não existe
AudioResultSimpleJson	Transcription/Transcription	Interfase	Dependendo da operação de chamada, as duas interfaces substituem a anterior
AudioResultVerboseJson	N/D	Interfase
AudioSegment	N/D	Interfase
AudioTranscriptionTask	N/D	Apelido
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/D	Interfaces e Aliases	Consulte a seção Tipos do Azure abaixo
AzureKeyCredential	N/D	Classe	A chave de API pode ser fornecida como um valor de cadeia de caracteres
ChatChoice	ChatCompletion.Choice	Interfase
ChatChoiceLogProbabilityInfo	Logprobs	Interfase
ChatCompletions	ChatCompletion e ChatCompletionChunk	Interfase
ChatCompletionsFunctionToolCall	ChatCompletionMessageToolCall	Interfase
ChatRequestFunctionMessage	ChatCompletionFunctionMessageParam	Interfase
ChatRequestMessage	ChatCompletionMessageParam	Interfase
ChatRequestMessageUnion	ChatCompletionMessageParam
ChatRequestSystemMessage	ChatCompletionSystemMessageParam	Interfase
ChatRequestToolMessage	ChatCompletionToolMessageParam	Interfase
ChatRequestUserMessage	ChatCompletionUserMessageParam	Interfase
ChatResponseMessage	Delta / ChatCompletionMessage	Interfase
ChatRole	N/D	Apelido
ChatTokenLogProbabilityInfo	TopLogprob	Interfase
ChatTokenLogProbabilityResult	ChatCompletionTokenLogprob	Interfase
Choice	Choice	Interfase
Completions	Completion	Interfase
CompletionsFinishReason	N/D	Apelido
CompletionsLogProbabilityModel	Logprobs	Interfase
CompletionsUsage	CompletionUsage	Interfase
EmbeddingItem	Embedding	Interfase
Embeddings	CreateEmbeddingResponse	Interfase
EmbeddingsUsage	CreateEmbeddingResponse.Usage	Interfase
EventStream	Stream	Interfase
FunctionCall	FunctionCall	Interfase
FunctionCallPreset	N/D	Apelido
FunctionDefinition	Function	Interfase
FunctionName	N/D	Apelido
GetAudioTranscriptionOptions	TranscriptionCreateParams	Interfase
GetAudioTranslationOptions	TranslationCreateParams	Interfase
GetChatCompletionsOptions	ChatCompletionCreateParamsNonStreaming e ChatCompletionCreateParamsStreaming	Interfase
GetCompletionsOptions	CompletionCreateParams	Interfase
GetEmbeddingsOptions	EmbeddingCreateParams	Interfase
GetImagesOptions	ImageGenerateParams	Interfase
ImageGenerationData	Image	Interfase
ImageGenerationQuality	N/D	Apelido
ImageGenerationResponseFormat	N/D	Apelido
ImageGenerations	ImagesResponse	Interfase
ImageGenerationStyle	N/D	Apelido
ImageSize	N/D	Apelido
MaxTokensFinishDetails	N/D	Interfase
OpenAIClientOptions	AzureClientOptions	Interfase
OpenAIError	OpenAIError	Interfase
OpenAIKeyCredential	N/D	Classe
StopFinishDetails	N/D	Interfase

Tipos do Azure

AzureOpenAI conecta-se ao Azure OpenAI e pode chamar todas as operações disponíveis no serviço. No entanto, os tipos de solicitações e respostas são herdados e OpenAI ainda não são atualizados para refletir os recursos adicionais compatíveis exclusivamente com o serviço OpenAI do Azure. Os usuários do TypeScript precisarão importar "@azure/openai/types" de @azure/openai@2.0.0-beta.1 o que irá mesclar definições específicas do Azure em tipos existentes. Os exemplos na seção Exemplos de Migração mostram como fazer isso.

Próximas etapas

• Assistentes do OpenAI do Azure