Migrazione alla libreria API JavaScript OpenAI 4.x (versione classica)

Si applica solo a:Portale di Foundry (versione classica). Questo articolo non è disponibile per il nuovo portale foundry. Altre informazioni sul nuovo portale.

Annotazioni

I collegamenti in questo articolo potrebbero aprire contenuto nella nuova documentazione di Microsoft Foundry anziché nella documentazione di Foundry (versione classica) visualizzata.

Importante

Per gli esempi di API più recenti, vedere l'articolo ciclo di vita dell'API.

Autenticazione del client

Esistono diversi modi per autenticare le richieste API per Azure OpenAI. È consigliabile usare token di Microsoft Entra ID. Per altre informazioni, vedere la documentazione Azure Identity.

Microsoft Entra ID

Esistono diversi modi per eseguire l'autenticazione con Azure OpenAI usando token di Microsoft Entra ID. Il modo predefinito consiste nell'usare la classe DefaultAzureCredential dal pacchetto @azure/identity, ma l'applicazione potrebbe usare una classe di credenziali diversa. Ai fini di questa guida, si presuppone che si stia usando la classe DefaultAzureCredential. È possibile creare credenziali come indicato di seguito:

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

Questo oggetto viene quindi passato al secondo argomento dei costruttori client OpenAIClient e AssistantsClient.

Per autenticare il client AzureOpenAI, tuttavia, è necessario usare la funzione getBearerTokenProvider dal pacchetto @azure/identity. Questa funzione crea un provider di token che AzureOpenAI usa internamente per ottenere i token per ogni richiesta. Il provider di token viene creato come segue:

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

azureADTokenProvider viene passato all'oggetto options durante la creazione del client AzureOpenAI.

(Altamente scoraggiato) Chiave API

Le chiavi API non sono consigliate per l'uso in produzione perché sono meno sicure di altri metodi di autenticazione. In precedenza, gli oggetti AzureKeyCredential venivano creati come indicato di seguito per autenticare OpenAIClient o AssistantsClient:

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

D’altra parte, è possibile eseguire l'autenticazione di AzureOpenAI con una chiave API impostando la variabile di ambiente AZURE_OPENAI_API_KEY o impostando la proprietà della stringa apiKey nell’oggetto Opzioni durante la creazione del client AzureOpenAI.

Importante

Utilizzare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente. Se si usa una chiave API, archiviarla in modo sicuro in Azure Key Vault. Per altre informazioni sull'uso sicuro delle chiavi API nelle app, vedere ChiaviAPI con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi di intelligenza artificiale, vedere Autorizzazione delle richieste a Servizi di Azure AI.

Costruzione del client

JavaScript OpenAI (nuovo)

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

L'endpoint della risorsa OpenAI Azure può essere specificato impostando l'opzione endpoint, ma può anche essere caricata dal client dalla variabile di ambiente AZURE_OPENAI_ENDPOINT. Questo è il modo consigliato per impostare l'endpoint perché consente al client di essere usato in ambienti differenti senza modificare il codice e anche per proteggere l'endpoint dall'esposizione nel codice.

Per specificare la versione dell'API, è necessario assicurarsi che il codice esistente non si interrompa tra le versioni dell'API di anteprima. Per altre informazioni sulle versioni Azure dell'API OpenAI, vedere la documentazione relativa al controllo delle versioni API. Inoltre, la proprietà deployment non è necessaria, ma è consigliabile impostarla. Dopo aver impostato deployment, viene usato come distribuzione predefinita per tutte le operazioni che lo richiedono. Se il client non è stato creato con l'opzione deployment, la proprietà model nell'oggetto opzione deve essere impostata con il nome della distribuzione. Tuttavia, le operazioni audio come audio.transcriptions.create richiedono che il client venga creato con l'opzione deployment impostata sul nome della distribuzione.

Azure OpenAI JavaScript (precedente)

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

Se non è impostata, per impostazione predefinita la versione dell'API è l'ultima nota prima del rilascio del client. Il client non è bloccato anche in una singola distribuzione del modello, vale a dire che il nome della distribuzione deve essere passato a ogni metodo che lo richiede.

Differenze tra LE API

Esistono differenze principali tra i client OpenAIClient e AssistantsClient e il client AzureOpenAI:

• Le operazioni sono rappresentate come un elenco semplice di metodi in e OpenAIClientAssistantsClient, ad esempio client.getChatCompletions. In AzureOpenAIle operazioni sono raggruppate in gruppi annidati, ad esempio client.chat.completions.create.
• OpenAIClient e AssistantsClient rinominare molti dei nomi usati nell'API OpenAI Azure. Ad esempio, il case serpente viene usato nell'API, ma nel client viene usato il case camel. In AzureOpenAI i nomi vengono mantenuti uguali a quello dell'API OpenAI Azure.

Esempi di migrazione

Nelle sezioni seguenti vengono forniti esempi di come eseguire la migrazione da OpenAIClient e AssistantsClient a AzureOpenAI.

Completamenti della chat

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

Nota quanto segue:

• Il metodo getChatCompletions è stato sostituito dal metodo chat.completions.create.
• Il parametro messages viene ora passato nell'oggetto options con la proprietà messages.
• La proprietà maxTokens è stata rinominata in max_tokens e il parametro deploymentName è stato rimosso. In genere, i nomi delle proprietà nell'oggetto options sono uguali a quelli dell'API OpenAI di Azure, seguendo la convenzione snake case anziché la convenzione camel case usata nella AssistantsClient. Questo vale per tutte le proprietà in tutte le richieste e le risposte nel client AzureOpenAI.
• Il parametro deploymentName non è necessario se il client è stato creato con l'opzione deployment. Se il client non è stato creato con l'opzione deployment, la proprietà model nell'oggetto opzione deve essere impostata con il nome della distribuzione.

Completamento della chat in streaming

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

Azure sui tuoi dati

JavaScript OpenAI (nuovo)

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 (precedente)

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" viene importato che aggiunge definizioni specifiche di Azure (ad esempio, data_sources) ai tipi client.
• La proprietà azureExtensionOptions è stata sostituita con la proprietà interna data_sources.
• La proprietà parameters è stata aggiunta per eseguire il wrapping dei parametri dell'estensione, che rispecchia lo schema dell'API OpenAI Azure.
• Le proprietà del case Camel sono state sostituite con le proprietà del case serpente.

Trascrizione audio

JavaScript OpenAI (nuovo)

import { createReadStream } from "fs";

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

Azure OpenAI JavaScript (precedente)

import { readFile } from "fs/promises";

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

• Il metodo getAudioTranscription è stato sostituito dal metodo audio.transcriptions.create.
• AzureOpenAI deve essere costruito con l'opzione deployment impostata sul nome della distribuzione per usare operazioni audio come audio.transcriptions.create.
• La proprietà model deve essere impostata nell'oggetto options, ma il relativo valore non viene usato nell'operazione, quindi è possibile impostarlo su qualsiasi valore.
• La proprietà file accetta diversi tipi, tra cui Buffer, fs.ReadaStreame Blob, ma in questo esempio un file viene trasmesso dal disco usando fs.createReadStream.

Traduzione audio

JavaScript OpenAI (nuovo)

import { createReadStream } from "fs";

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

Azure OpenAI JavaScript (precedente)

import { readFile } from "fs/promises";

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

• Il metodo getAudioTranslation è stato sostituito dal metodo audio.translations.create.
• Tutte le altre modifiche sono le stesse dell'esempio di trascrizione audio.

Assistants

Negli esempi seguenti viene illustrato come eseguire la migrazione di alcuni metodi di AssistantsClient.

Creazione dell'assistente

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

• Il metodo createAssistant è stato sostituito dal metodo beta.assistants.create

Creazione di thread

Nell'esempio seguente viene illustrato come eseguire la migrazione della chiamata a un metodo createThread.

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

const assistantThread = await assistantsClient.createThread();

• Il metodo createThread è stato sostituito dal metodo beta.threads.create

Creazione messaggio

Nell'esempio seguente viene illustrato come eseguire la migrazione della chiamata a un metodo createMessage.

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

• Il metodo createMessage è stato sostituito dal metodo beta.threads.messages.create.
• La specifica del messaggio è stata spostata da un elenco di parametri a un oggetto.

Runs

Per eseguire un assistente in un thread, il metodo createRun viene usato per creare un'operazione e quindi viene usato un loop per interrogare lo stato dell'operazione fino a raggiungere uno stato terminale. Nell'esempio seguente viene illustrato come eseguire la migrazione della creazione e del polling dell'esecuzione.

JavaScript OpenAI (nuovo)

Questo codice può essere migrato e semplificato usando il metodo createAndPoll, che crea un'esecuzione ed esegue il polling fino a quando non si trova in uno stato terminale.

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

Azure OpenAI JavaScript (precedente)

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"

• Il metodo createRun è stato sostituito dai metodi beta.threads.runs.create e createAndPoll.
• Il metodo createAndPoll viene usato per creare un'esecuzione ed eseguirne il polling fino a quando non si trova in uno stato terminale.

Elaborazione dei risultati dell'esecuzione

JavaScript OpenAI (nuovo)

È possibile scorrere le pagine usando il for await loop.

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

Azure OpenAI JavaScript (precedente)

Senza paging, i risultati devono essere accessibili manualmente alla pagina tramite la proprietà data dell'oggetto risposta. Ad esempio, l'accesso alla prima pagina può essere eseguito come segue:

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

Incorporamenti

Nell'esempio seguente viene illustrato come eseguire la migrazione della chiamata a un metodo getEmbeddings.

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

• Il metodo getEmbeddings è stato sostituito dal metodo embeddings.create.
• Il parametro input viene ora passato nell'oggetto options con la proprietà input.
• Il parametro deploymentName è stato rimosso. Il parametro deploymentName non è necessario se il client è stato creato con l'opzione deployment. Se il client non è stato creato con l'opzione deployment, la proprietà model nell'oggetto opzione deve essere impostata con il nome della distribuzione.

Generazione di immagini

Nell'esempio seguente viene illustrato come eseguire la migrazione della chiamata a un metodo getImages.

JavaScript OpenAI (nuovo)

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

Azure OpenAI JavaScript (precedente)

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

• Il metodo getImages è stato sostituito dal metodo images.generate.
• Il parametro prompt viene ora passato nell'oggetto options con la proprietà prompt.
• Il parametro deploymentName è stato rimosso. Il parametro deploymentName non è necessario se il client è stato creato con l'opzione deployment. Se il client non è stato creato con l'opzione deployment, la proprietà model nell'oggetto opzione deve essere impostata con il nome della distribuzione.

Filtro di contenuto

I risultati del filtro del contenuto fanno parte dei tipi di risposta di completamento della chat in OpenAIClient. Tuttavia, AzureOpenAI non ha un equivalente diretto alla proprietà contentFilterResults nell'interfaccia ChatCompletion.Choice. È possibile accedere ai risultati del filtro contenuto importando "@azure/openai/types" e accedendo alla proprietà content_filter_results. Nell'esempio seguente viene illustrato come accedere ai risultati del filtro dei contenuti.

JavaScript OpenAI (nuovo)

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 (precedente)

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

• Le proprietà del case Camel sono state sostituite con le proprietà del case serpente.
• "@azure/openai/types" viene importato che aggiunge definizioni specifiche Azure (ad esempio, content_filter_results) ai tipi client, vedere la sezione Azure types per altre informazioni.

Confronto tra tipi

Nella tabella seguente vengono esaminati diversi nomi di tipo da @azure/openai e vengono visualizzati i relativi openai equivalenti più vicini. Le differenze tra i nomi illustrano diverse modifiche indicate in precedenza. Questa tabella offre una panoramica e altri dettagli e esempi di codice sono disponibili nelle sezioni seguenti.

Nome di tipo precedente	Nuovo tipo più vicino	Tipo di simbolo	Descrizione delle modifiche
OpenAIClient	AzureOpenAI	Classe	Questa classe sostituisce il precedente e non ha metodi in comune con esso. Vedere la sezione su AzureOpenAI di seguito.
AudioResult	Transcription/Transcription	Interfaccia	A seconda dell'operazione chiamante, le due interfacce sostituiscono quella precedente
AudioResultFormat	tipo di unione inline della proprietà response_format	Alias	Non esiste
AudioResultSimpleJson	Transcription/Transcription	Interfaccia	A seconda dell'operazione chiamante, le due interfacce sostituiscono quella precedente
AudioResultVerboseJson	N/A	Interfaccia
AudioSegment	N/A	Interfaccia
AudioTranscriptionTask	N/A	Alias
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	Interfacce e alias	Vedere la sezione tipi di Azure di seguito
AzureKeyCredential	N/A	Classe	La chiave API può essere fornita come valore stringa
ChatChoice	ChatCompletion.Choice	Interfaccia
ChatChoiceLogProbabilityInfo	Logprobs	Interfaccia
ChatCompletions	ChatCompletion e ChatCompletionChunk	Interfaccia
ChatCompletionsFunctionToolCall	ChatCompletionMessageToolCall	Interfaccia
ChatRequestFunctionMessage	ChatCompletionFunctionMessageParam	Interfaccia
ChatRequestMessage	ChatCompletionMessageParam	Interfaccia
ChatRequestMessageUnion	ChatCompletionMessageParam
ChatRequestSystemMessage	ChatCompletionSystemMessageParam	Interfaccia
ChatRequestToolMessage	ChatCompletionToolMessageParam	Interfaccia
ChatRequestUserMessage	ChatCompletionUserMessageParam	Interfaccia
ChatResponseMessage	Delta / ChatCompletionMessage	Interfaccia
ChatRole	N/A	Alias
ChatTokenLogProbabilityInfo	TopLogprob	Interfaccia
ChatTokenLogProbabilityResult	ChatCompletionTokenLogprob	Interfaccia
Choice	Choice	Interfaccia
Completions	Completion	Interfaccia
CompletionsFinishReason	N/A	Alias
CompletionsLogProbabilityModel	Logprobs	Interfaccia
CompletionsUsage	CompletionUsage	Interfaccia
EmbeddingItem	Embedding	Interfaccia
Embeddings	CreateEmbeddingResponse	Interfaccia
EmbeddingsUsage	CreateEmbeddingResponse.Usage	Interfaccia
EventStream	Stream	Interfaccia
FunctionCall	FunctionCall	Interfaccia
FunctionCallPreset	N/A	Alias
FunctionDefinition	Function	Interfaccia
FunctionName	N/A	Alias
GetAudioTranscriptionOptions	TranscriptionCreateParams	Interfaccia
GetAudioTranslationOptions	TranslationCreateParams	Interfaccia
GetChatCompletionsOptions	ChatCompletionCreateParamsNonStreaming e ChatCompletionCreateParamsStreaming	Interfaccia
GetCompletionsOptions	CompletionCreateParams	Interfaccia
GetEmbeddingsOptions	EmbeddingCreateParams	Interfaccia
GetImagesOptions	ImageGenerateParams	Interfaccia
ImageGenerationData	Image	Interfaccia
ImageGenerationQuality	N/A	Alias
ImageGenerationResponseFormat	N/A	Alias
ImageGenerations	ImagesResponse	Interfaccia
ImageGenerationStyle	N/A	Alias
ImageSize	N/A	Alias
MaxTokensFinishDetails	N/A	Interfaccia
OpenAIClientOptions	AzureClientOptions	Interfaccia
OpenAIError	OpenAIError	Interfaccia
OpenAIKeyCredential	N/A	Classe
StopFinishDetails	N/A	Interfaccia

tipi di Azure

AzureOpenAI si connette al Azure OpenAI e può chiamare tutte le operazioni disponibili nel servizio. Tuttavia, i tipi di richieste e risposte vengono ereditati dal OpenAI e non vengono ancora aggiornati per riflettere le funzionalità aggiuntive supportate esclusivamente dal servizio OpenAI Azure. Gli utenti typeScript dovranno importare "@azure/openai/types" da @azure/openai@2.0.0-beta.1 che unisce definizioni specifiche di Azure in tipi esistenti. Esempi nella sezione Esempi di migrazione illustrano come farlo.

Passaggi successivi

• Assistenti OpenAI di Azure