Compartir a través de

Migración a la biblioteca de la API de JavaScript de OpenAI 4.x

A partir de junio de 2024, se recomienda migrar a la biblioteca de API de JavaScript de OpenAI 4.x, la versión más reciente de la biblioteca cliente oficial de JavaScript de OpenAI que admite Azure OpenAI en Azure AI Foundry Models API 2022-12-01 y versiones posteriores. Este artículo le ayuda a acelerar los cambios específicos de Azure OpenAI.

Autenticación del cliente

Hay varias maneras de autenticar solicitudes de API en Azure OpenAI. Se recomienda encarecidamente usar tokens de Microsoft Entra ID. Para obtener más información, consulte la documentación de Azure Identity.

Microsoft Entra ID

Hay varias maneras de autenticarse con Azure OpenAI mediante tokens de identificador de Microsoft Entra. La manera predeterminada es usar la clase DefaultAzureCredential del paquete @azure/identity, pero la aplicación podría estar usando otra clase de credenciales. Para los fines de esta guía, se supone que usa la clase DefaultAzureCredential. Se puede crear una credencial de la siguiente manera:

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

A continuación, este objeto se pasa al segundo argumento de los constructores de cliente OpenAIClient y AssistantsClient.

Sin embargo, para autenticar el cliente AzureOpenAI, es necesario usar la función getBearerTokenProvider desde el paquete @azure/identity. Esta función crea un proveedor de tokens que AzureOpenAI usa internamente para obtener tokens para cada solicitud. El proveedor de tokens se crea de la siguiente manera:

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

azureADTokenProvider se pasa al objeto options al crear el cliente AzureOpenAI.

(Muy desaconsejado) Clave de API

Las claves de API no se recomiendan para su uso en producción porque son menos seguras que otros métodos de autenticación. Anteriormente, los objetos AzureKeyCredential se crearon de la siguiente manera para autenticar OpenAIClient o AssistantsClient:

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

Por otro lado, AzureOpenAI se puede autenticar con una clave de API estableciendo la variable de entorno AZURE_OPENAI_API_KEY o estableciendo la propiedad de cadena apiKey en el objeto de opciones al crear el cliente de AzureOpenAI.

Importante

Use las claves de API con precaución. No incluya la clave de API directamente en el código ni la exponga nunca públicamente. Si está usando una clave de API, guárdela de forma segura en la instancia de Azure Key Vault. Para más información sobre cómo utilizar las claves de API de forma segura en sus aplicaciones, consulte Claves de API con Azure Key Vault.

Para más información acerca de la seguridad de los servicios de AI, consulte Autenticación de solicitudes a los servicios de Azure AI.

Construcción del cliente

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

El punto de conexión del recurso de Azure OpenAI se puede especificar estableciendo la opción endpoint, pero el cliente también puede cargarlo desde la variable de entorno AZURE_OPENAI_ENDPOINT. Esta es la manera recomendada de establecer el punto de conexión porque permite que el cliente se use en entornos diferentes sin cambiar el código y también para proteger el punto de conexión de exponerse en el código.

Es necesario especificar la versión de la API para asegurarse de que el código existente no se interrumpa entre las versiones preliminares de la API. Consulte la documentación de control de versiones de la API para más información sobre las versiones de la API de Azure OpenAI. Además, la propiedad deployment no es necesaria, pero se recomienda establecerla. Una vez que se establece deployment, se usa como implementación predeterminada para todas las operaciones que lo requieren. Si el cliente no se crea con la opción deployment, la propiedad model del objeto options debe establecerse con el nombre de la implementación. Sin embargo, las operaciones de audio como audio.transcriptions.create requieren que el cliente se cree con la opción deployment establecida en el nombre de la implementación.

Diferencias entre las API

Hay diferencias clave entre los clientes OpenAIClient y AssistantsClient y el cliente AzureOpenAI:

  • Las operaciones se representan como una lista plana de métodos en OpenAIClient y AssistantsClient, por ejemplo, client.getChatCompletions. En AzureOpenAI, las operaciones se agrupan en grupos anidados, por ejemplo, client.chat.completions.create.
  • OpenAIClient y AssistantsClient renombran muchos de los nombres usados en la API de Azure OpenAI. Por ejemplo, en la API se usa camelCase, pero en el cliente se usa snakeCase. En AzureOpenAI, los nombres se mantienen iguales que en la API de Azure OpenAI.

Ejemplos de migración

En las secciones siguientes se proporcionan ejemplos de cómo migrar de OpenAIClient y AssistantsClient a AzureOpenAI.

Finalizaciones de chat

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

Tenga en cuenta lo siguiente:

  • El método getChatCompletions se ha reemplazado por el método chat.completions.create.
  • El parámetro messages ahora se pasa en el objeto options con la propiedad messages.
  • Se ha cambiado el nombre de la propiedad de maxTokens a max_tokens y se ha quitado el parámetro deploymentName. Por lo general, los nombres de las propiedades en el objeto options son los mismos que en la API de Azure OpenAI, siguiendo la convención de snake case en lugar de la convención de camel case utilizada en AssistantsClient. Esto es cierto para todas las propiedades de todas las solicitudes y respuestas del cliente AzureOpenAI.
  • El parámetro deploymentName no es necesario si el cliente se creó con la opción deployment. Si el cliente no se creó con la opción deployment, la propiedad model del objeto option debe establecerse con el nombre de la implementación.

Finalizaciones de chat en streaming

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

Azure en los datos

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" se importa, lo que agrega definiciones específicas de Azure (por ejemplo, data_sources) a los tipos de cliente.
  • La propiedad azureExtensionOptions se ha reemplazado por la propiedad data_sources interna.
  • La parameters propiedad se ha agregado para encapsular los parámetros de la extensión, que refleja el esquema de la API de Azure OpenAI.
  • Las propiedades de camelCase se han reemplazado por propiedades de snakeCase.

Transcripción de audio

import { createReadStream } from "fs";

const result = await client.audio.transcriptions.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • El método getAudioTranscription se ha reemplazado por el método audio.transcriptions.create.
  • El AzureOpenAI debe construirse con la opción deployment establecida en el nombre de la implementación para poder usar operaciones de audio como audio.transcriptions.create.
  • Se requiere que la propiedad model se establezca en el objeto options, pero su valor no se usa en la operación, así que siéntase libre de establecerla en cualquier valor.
  • La propiedad file acepta varios tipos, como Buffer, fs.ReadaStream y Blob, pero en este ejemplo, un archivo se transmite desde el disco mediante fs.createReadStream.

Traducción de audio

import { createReadStream } from "fs";

const result = await client.audio.translations.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • El método getAudioTranslation se ha reemplazado por el método audio.translations.create.
  • Todos los demás cambios son los mismos que en el ejemplo de transcripción de audio.

Asistentes

En los siguientes ejemplos se muestra cómo migrar algunos de los métodos AssistantsClient.

Creación del asistente

const options = ...;
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);
  • El método createAssistant se ha reemplazado por el método beta.assistants.create

Creación de subprocesos

En el siguiente ejemplo se muestra cómo migrar la llamada al método createThread.

const assistantThread = await assistantsClient.beta.threads.create();
  • El método createThread se ha reemplazado por el método beta.threads.create

Creación de mensajes

En el siguiente ejemplo se muestra cómo migrar la llamada al método createMessage.

const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);
  • El método createMessage se ha reemplazado por el método beta.threads.messages.create.
  • La especificación del mensaje se ha movido de una lista de parámetros a un objeto.

Ejecuciones

Para ejecutar un asistente en un subproceso, el método createRun se usa para crear una ejecución y, a continuación, se usa un bucle para sondear el estado de ejecución hasta que se encuentra en un estado terminal. En el siguiente ejemplo se muestra cómo migrar la creación y el sondeo de ejecución.

Este código se puede migrar y simplificar mediante el método createAndPoll, que crea una ejecución y sondea hasta que se encuentra en un estado terminal.

const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
  • El método createRun se ha reemplazado por los métodos beta.threads.runs.create y createAndPoll.
  • El método createAndPoll se usa para crear una ejecución y sondearla hasta que se encuentra en un estado terminal.

Procesamiento de resultados de ejecución

Las páginas se pueden recorrer mediante el bucle for await.

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

Inserciones

En el siguiente ejemplo se muestra cómo migrar la llamada al método getEmbeddings.

const embeddings = await client.embeddings.create({ input, model: '' });
  • El método getEmbeddings se ha reemplazado por el método embeddings.create.
  • El parámetro input ahora se pasa en el objeto options con la propiedad input.
  • El parámetro deploymentName se ha quitado. El parámetro deploymentName no es necesario si el cliente se creó con la opción deployment. Si el cliente no se creó con la opción deployment, la propiedad model del objeto option debe establecerse con el nombre de la implementación.

Generación de imágenes

En el siguiente ejemplo se muestra cómo migrar la llamada al método getImages.

  const results = await client.images.generate({ prompt, model: '', n, size });
  • El método getImages se ha reemplazado por el método images.generate.
  • El parámetro prompt ahora se pasa en el objeto options con la propiedad prompt.
  • El parámetro deploymentName se ha quitado. El parámetro deploymentName no es necesario si el cliente se creó con la opción deployment. Si el cliente no se creó con la opción deployment, la propiedad model del objeto option debe establecerse con el nombre de la implementación.

Filtro de contenido

Los resultados del filtro de contenido forman parte de los tipos de respuesta de finalizaciones de chat en OpenAIClient. Sin embargo, AzureOpenAI no tiene un equivalente directo a la propiedad contentFilterResults en la interfaz ChatCompletion.Choice. Se puede acceder a los resultados del filtro de contenido importando "@azure/openai/types" y accediendo a la propiedad content_filter_results. En el siguiente ejemplo se muestra cómo acceder a los resultados del filtro de contenido.

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;
  ...
}
  • Las propiedades de camelCase se han reemplazado por propiedades de snakeCase.
  • "@azure/openai/types" se importa, que agrega definiciones específicas de Azure (por ejemplo, content_filter_results) a los tipos de cliente, consulte la sección tipos de Azure para obtener más información.

Comparación de tipos

En la siguiente tabla se exploran varios nombres de tipo de @azure/openai y se muestran sus equivalentes openai más cercanos. Las diferencias de nombres muestran varios de los cambios mencionados anteriormente. En esta tabla se proporciona información general y se proporcionan más detalles y ejemplos de código en las siguientes secciones.

Nombre de tipo anterior Nuevo tipo más cercano Tipo de símbolo Descripción del cambio
OpenAIClient AzureOpenAI Clase Esta clase reemplaza la anterior y no tiene ningún método en común con ella. Consulte la sección sobre AzureOpenAI siguiente.
AudioResult Transcription/Transcription Interfaz En función de la operación de llamada, las dos interfaces reemplazan a la anterior
AudioResultFormat Tipo de unión insertada de la propiedad response_format Alias (Nombre ficticio) No existe
AudioResultSimpleJson Transcription/Transcription Interfaz En función de la operación de llamada, las dos interfaces reemplazan a la anterior
AudioResultVerboseJson N/D Interfaz
AudioSegment N/D Interfaz
AudioTranscriptionTask N/D Alias (Nombre ficticio)
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 y alias Consulte la sección Tipos de Azure a continuación
AzureKeyCredential N/D Clase La clave de API se puede proporcionar como un valor de cadena
ChatChoice ChatCompletion.Choice Interfaz
ChatChoiceLogProbabilityInfo Logprobs Interfaz
ChatCompletions ChatCompletion y 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/D Alias (Nombre ficticio)
ChatTokenLogProbabilityInfo TopLogprob Interfaz
ChatTokenLogProbabilityResult ChatCompletionTokenLogprob Interfaz
Choice Choice Interfaz
Completions Completion Interfaz
CompletionsFinishReason N/D Alias (Nombre ficticio)
CompletionsLogProbabilityModel Logprobs Interfaz
CompletionsUsage CompletionUsage Interfaz
EmbeddingItem Embedding Interfaz
Embeddings CreateEmbeddingResponse Interfaz
EmbeddingsUsage CreateEmbeddingResponse.Usage Interfaz
EventStream Stream Interfaz
FunctionCall FunctionCall Interfaz
FunctionCallPreset N/D Alias (Nombre ficticio)
FunctionDefinition Function Interfaz
FunctionName N/D Alias (Nombre ficticio)
GetAudioTranscriptionOptions TranscriptionCreateParams Interfaz
GetAudioTranslationOptions TranslationCreateParams Interfaz
GetChatCompletionsOptions ChatCompletionCreateParamsNonStreaming y ChatCompletionCreateParamsStreaming Interfaz
GetCompletionsOptions CompletionCreateParams Interfaz
GetEmbeddingsOptions EmbeddingCreateParams Interfaz
GetImagesOptions ImageGenerateParams Interfaz
ImageGenerationData Image Interfaz
ImageGenerationQuality N/D Alias (Nombre ficticio)
ImageGenerationResponseFormat N/D Alias (Nombre ficticio)
ImageGenerations ImagesResponse Interfaz
ImageGenerationStyle N/D Alias (Nombre ficticio)
ImageSize N/D Alias (Nombre ficticio)
MaxTokensFinishDetails N/D Interfaz
OpenAIClientOptions AzureClientOptions Interfaz
OpenAIError OpenAIError Interfaz
OpenAIKeyCredential N/D Clase
StopFinishDetails N/D Interfaz

Tipos de Azure

AzureOpenAI se conecta con Azure OpenAI y puede hacer llamadas a todas las operaciones disponibles en el servicio. Sin embargo, los tipos de las solicitudes y respuestas se heredan del OpenAI y aún no se actualizan para reflejar las características adicionales admitidas exclusivamente por el servicio Azure OpenAI. Los usuarios de TypeScript deberán importar "@azure/openai/types" desde @azure/openai@2.0.0-beta.1 que combinarán definiciones específicas de Azure en tipos existentes. Los ejemplos de la sección Ejemplos de migración muestran cómo hacerlo.

Pasos siguientes