Прочитать на английском

Поделиться через

Переход на библиотеку API JavaScript OpenAI 4.x

  • Статья

По состоянию на июнь 2024 г. мы рекомендуем перенести библиотеку API OpenAI JavaScript версии 4.x, последнюю версию официальной клиентской библиотеки OpenAI JavaScript, которая поддерживает версию API Службы OpenAI и более поздних версий 2022-12-01 . Эта статья поможет вам ускорить изменения, относящиеся к Azure OpenAI.

Проверка подлинности клиента

Существует несколько способов проверки подлинности запросов API в Azure OpenAI. Настоятельно рекомендуется использовать маркеры идентификатора Microsoft Entra. Дополнительные сведения см. в документации по удостоверению Azure.

Microsoft Entra ID

Существует несколько способов проверки подлинности в службе Azure OpenAI с помощью маркеров идентификатора Microsoft Entra. По умолчанию используется DefaultAzureCredential класс из @azure/identity пакета, но приложение может использовать другой класс учетных данных. В целях этого руководства предполагается, что вы используете DefaultAzureCredential класс. Учетные данные можно создать следующим образом:

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

Затем этот объект передается второму аргументу OpenAIClient конструкторов и AssistantsClient клиентских конструкторов.

Однако для проверки подлинности AzureOpenAI клиента необходимо использовать getBearerTokenProvider функцию из @azure/identity пакета. Эта функция создает поставщик токенов, который AzureOpenAI используется внутренне для получения маркеров для каждого запроса. Поставщик токенов создается следующим образом:

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

azureADTokenProvider передается объекту options при создании AzureOpenAI клиента.

(очень не рекомендуется) Ключ API

Ключи API не рекомендуется использовать в рабочей среде, так как они менее безопасны, чем другие методы проверки подлинности. Ранее объекты были созданы следующим образом для AzureKeyCredential проверки подлинности OpenAIClient или AssistantsClient:

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

С другой стороны, можно пройти проверку подлинности с помощью ключа API, AzureOpenAI задав переменную среды или задав AZURE_OPENAI_API_KEYapiKey строковое свойство в объекте параметров при создании AzureOpenAI клиента.

Важно!

Используйте ключи API с осторожностью. Не включайте ключ API непосредственно в код и никогда не публикуйте его. Если вы используете ключ API, сохраните его безопасно в Azure Key Vault. Дополнительные сведения об использовании ключей API безопасно в приложениях см. в разделе "Ключи API" с помощью Azure Key Vault.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

Создание клиента

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

Конечную точку ресурса Azure OpenAI можно указать, задав endpoint параметр, но его также можно загрузить клиентом из переменной AZURE_OPENAI_ENDPOINTсреды. Это рекомендуемый способ задать конечную точку, так как он позволяет клиенту использоваться в разных средах, не изменяя код, а также защищать конечную точку от предоставления в коде.

Необходимо указать версию API, чтобы убедиться, что существующий код не прерывается между версиями API предварительной версии. Дополнительные сведения о версиях API OpenAI см. в документации по использованию версий API Azure. Кроме того, свойство не требуется, deployment но рекомендуется задать его. После deployment установки он используется в качестве развертывания по умолчанию для всех операций, требующих его. Если клиент не создан с deployment параметром, model свойство в объекте options должно быть задано с именем развертывания. Однако для таких операций аудио, как audio.transcriptions.create требование создания клиента с заданным параметром deployment имени развертывания.

Отличия между API

Существуют ключевые различия между клиентами OpenAIClient и AssistantsClient клиентами AzureOpenAI :

  • Операции представлены как плоский список методов в обоих OpenAIClient и AssistantsClient, например client.getChatCompletions. Например AzureOpenAI, client.chat.completions.createоперации группируются в вложенных группах.
  • OpenAIClient и AssistantsClient переименуйте многие имена, используемые в API службы Azure OpenAI. Например, в API используется случай змеи, но в клиенте используется случай верблюда. Имена AzureOpenAIхранятся так же, как и в API службы Azure OpenAI.

Примеры миграции

В следующих разделах приведены примеры миграции из и AssistantsClient в OpenAIClientAzureOpenAI.

Завершение чата

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

Обратите внимание на следующее:

  • Метод getChatCompletions был заменен методом chat.completions.create .
  • Теперь messages параметр передается в объекте options с свойством messages .
  • maxTokens Свойство было переименовано max_tokens в и deploymentName параметр был удален. Как правило, имена свойств в options объекте совпадают с API службы Azure OpenAI, следуя соглашению о случае змеи, а не соглашению о регистре верблюда, используемом в соглашении AssistantsClient. Это верно для всех свойств во всех запросах и ответах клиента AzureOpenAI .
  • Параметр deploymentName не требуется, если клиент был создан с параметром deployment . Если клиент не был создан с deployment параметром, model свойство в объекте параметра должно быть задано с именем развертывания.

Завершение потокового чата

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

Azure On Your Data

TypeScript 
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" импортируется, который добавляет определения azure (например, data_sources) в типы клиентов.
  • Свойство azureExtensionOptions было заменено внутренним data_sources свойством.
  • Свойство parameters было добавлено для упаковки параметров расширения, которое отражает схему API службы Azure OpenAI.
  • Свойства дела верблюда были заменены свойствами регистра змеи.

Транскрибирование звука

TypeScript 
import { createReadStream } from "fs";

const result = await client.audio.transcriptions.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • Метод getAudioTranscription был заменен методом audio.transcriptions.create .
  • Необходимо AzureOpenAI создать с deployment помощью параметра, заданного для имени развертывания, чтобы использовать такие звуковые операции, как audio.transcriptions.create.
  • Свойство model должно быть задано в объекте параметров, но его значение не используется в операции, поэтому вы можете настроить его в любом значении.
  • Свойство file принимает различные типы, включая Buffer, fs.ReadaStreamи Blob в этом примере файл передается из диска с помощью fs.createReadStream.

Перевод звука

TypeScript 
import { createReadStream } from "fs";

const result = await client.audio.translations.create({
  model: '',
  file: createReadStream(audioFilePath),
});
  • Метод getAudioTranslation был заменен методом audio.translations.create .
  • Все остальные изменения совпадают с примером транскрибирования звука.

Помощники

В следующих примерах показано, как перенести некоторые AssistantsClient методы.

Создание помощника

TypeScript 
const options = ...;
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);
  • Метод createAssistant был заменен методом beta.assistants.create

Создание потока

В следующем примере показано, как перенести createThread вызов метода.

TypeScript 
const assistantThread = await assistantsClient.beta.threads.create();
  • Метод createThread был заменен методом beta.threads.create

Создание сообщения

В следующем примере показано, как перенести createMessage вызов метода.

TypeScript 
const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);
  • Метод createMessage был заменен методом beta.threads.messages.create .
  • Спецификация сообщения была перемещена из списка параметров в объект.

Запуски

Для запуска помощника в потоке createRun метод используется для создания запуска, а затем цикл используется для опроса состояния выполнения до тех пор, пока он не находится в состоянии терминала. В следующем примере показано, как перенести создание и опрос запуска.

Этот код можно перенести и упростить с помощью createAndPoll метода, который создает запуск и опрашивает его до тех пор, пока он не находится в состоянии терминала.

TypeScript 
const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
  • Метод createRun был заменен методом и createAndPoll методамиbeta.threads.runs.create.
  • Метод createAndPoll используется для создания запуска и опроса его до тех пор, пока он не находится в состоянии терминала.

Обработка результатов выполнения

Страницы можно прокрутить с помощью for await цикла.

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

Внедрение

В следующем примере показано, как перенести getEmbeddings вызов метода.

TypeScript 
const embeddings = await client.embeddings.create({ input, model: '' });
  • Метод getEmbeddings был заменен методом embeddings.create .
  • Теперь input параметр передается в объекте options с свойством input .
  • Параметр deploymentName удален. Параметр deploymentName не требуется, если клиент был создан с параметром deployment . Если клиент не был создан с deployment параметром, model свойство в объекте параметра должно быть задано с именем развертывания.

Генерирование изображений

В следующем примере показано, как перенести getImages вызов метода.

TypeScript 
  const results = await client.images.generate({ prompt, model: '', n, size });
  • Метод getImages был заменен методом images.generate .
  • Теперь prompt параметр передается в объекте options с свойством prompt .
  • Параметр deploymentName удален. Параметр deploymentName не требуется, если клиент был создан с параметром deployment . Если клиент не был создан с deployment параметром, model свойство в объекте параметра должно быть задано с именем развертывания.

Фильтр содержимого

Результаты фильтра содержимого являются частью типов ответов завершения чата.OpenAIClient AzureOpenAI Однако не имеет прямого эквивалента contentFilterResults свойству в интерфейсеChatCompletion.Choice. Результаты фильтра содержимого можно получить, импортируя "@azure/openai/types" и доступ к свойству content_filter_results . В следующем примере показано, как получить доступ к результатам фильтра содержимого.

TypeScript 
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/types" импортируется, который добавляет определения azure (например, content_filter_results) в типы клиентов, см . в разделе типов Azure для получения дополнительных сведений.

Сравнение типов

В следующей таблице рассматриваются несколько имен типов из @azure/openai и отображаются их ближайшие openai эквиваленты. Различия имен иллюстрируют несколько указанных выше изменений. Эта таблица содержит общие сведения, а также дополнительные сведения и примеры кода приведены в следующих разделах.

Старое имя типа Ближайший новый тип Тип символа Описание изменения
OpenAIClient AzureOpenAI Класс Этот класс заменяет бывший и не имеет общих методов. См. раздел о AzureOpenAI ниже.
AudioResult Transcription/Transcription Интерфейс В зависимости от операции вызова два интерфейса заменяют ранее
AudioResultFormat встроенный response_format тип объединения свойства Псевдоним Он не существует
AudioResultSimpleJson Transcription/Transcription Интерфейс В зависимости от операции вызова два интерфейса заменяют ранее
AudioResultVerboseJson Н/П Интерфейс
AudioSegment Н/П Интерфейс
AudioTranscriptionTask Н/П Псевдоним
AzureChatEnhancementConfiguration ContentFilterSuccessResultDetailsForPrompt, AzureChatEnhancementsAzureChatExtensionConfigurationAzureChatExtensionConfigurationUnionAzureChatExtensionDataSourceResponseCitationAzureChatExtensionsMessageContextAzureChatExtensionTypeAzureChatGroundingEnhancementConfigurationAzureChatOCREnhancementConfigurationAzureCosmosDBChatExtensionConfigurationAzureCosmosDBFieldMappingOptionsAzureExtensionsOptionsAzureGroundingEnhancementAzureGroundingEnhancementCoordinatePointAzureGroundingEnhancementLineAzureGroundingEnhancementLineSpanAzureMachineLearningIndexChatExtensionConfigurationAzureSearchChatExtensionConfigurationAzureSearchIndexFieldMappingOptionsAzureSearchQueryTypeContentFilterBlocklistIdResultContentFilterCitedDetectionResultContentFilterDetectionResultContentFilterErrorResultsContentFilterResultContentFilterResultDetailsForPromptContentFilterResultsForChoiceContentFilterSeverityContentFilterResultsForPromptContentFilterSuccessResultsForChoiceElasticsearchChatExtensionConfigurationElasticsearchIndexFieldMappingOptionsElasticsearchQueryTypeImageGenerationContentFilterResultsImageGenerationPromptFilterResultsOnYourDataAccessTokenAuthenticationOptionsOnYourDataApiKeyAuthenticationOptionsOnYourDataAuthenticationOptionsOnYourDataAuthenticationOptionsUnionOnYourDataConnectionStringAuthenticationOptionsOnYourDataDeploymentNameVectorizationSourceOnYourDataEncodedApiKeyAuthenticationOptionsOnYourDataEndpointVectorizationSourceOnYourDataKeyAndKeyIdAuthenticationOptionsOnYourDataModelIdVectorizationSourceOnYourDataSystemAssignedManagedIdentityAuthenticationOptionsOnYourDataUserAssignedManagedIdentityAuthenticationOptionsOnYourDataVectorizationSourceOnYourDataVectorizationSourceTypeOnYourDataVectorizationSourceUnionPineconeChatExtensionConfigurationPineconeFieldMappingOptions Н/П Интерфейсы и псевдонимы См. раздел "Типы Azure" ниже
AzureKeyCredential Н/П Класс Ключ API можно указать в виде строкового значения.
ChatChoice ChatCompletion.Choice Интерфейс
ChatChoiceLogProbabilityInfo Logprobs Интерфейс
ChatCompletions ChatCompletion и ChatCompletionChunk. Интерфейс
ChatCompletionsFunctionToolCall ChatCompletionMessageToolCall Интерфейс
ChatRequestFunctionMessage ChatCompletionFunctionMessageParam Интерфейс
ChatRequestMessage ChatCompletionMessageParam Интерфейс
ChatRequestMessageUnion ChatCompletionMessageParam
ChatRequestSystemMessage ChatCompletionSystemMessageParam Интерфейс
ChatRequestToolMessage ChatCompletionToolMessageParam Интерфейс
ChatRequestUserMessage ChatCompletionUserMessageParam Интерфейс
ChatResponseMessage Delta / ChatCompletionMessage Интерфейс
ChatRole Н/П Псевдоним
ChatTokenLogProbabilityInfo TopLogprob Интерфейс
ChatTokenLogProbabilityResult ChatCompletionTokenLogprob Интерфейс
Choice Choice Интерфейс
Completions Completion Интерфейс
CompletionsFinishReason Н/П Псевдоним
CompletionsLogProbabilityModel Logprobs Интерфейс
CompletionsUsage CompletionUsage Интерфейс
EmbeddingItem Embedding Интерфейс
Embeddings CreateEmbeddingResponse Интерфейс
EmbeddingsUsage CreateEmbeddingResponse.Usage Интерфейс
EventStream Stream Интерфейс
FunctionCall FunctionCall Интерфейс
FunctionCallPreset Н/П Псевдоним
FunctionDefinition Function Интерфейс
FunctionName Н/П Псевдоним
GetAudioTranscriptionOptions TranscriptionCreateParams Интерфейс
GetAudioTranslationOptions TranslationCreateParams Интерфейс
GetChatCompletionsOptions ChatCompletionCreateParamsNonStreaming и ChatCompletionCreateParamsStreaming. Интерфейс
GetCompletionsOptions CompletionCreateParams Интерфейс
GetEmbeddingsOptions EmbeddingCreateParams Интерфейс
GetImagesOptions ImageGenerateParams Интерфейс
ImageGenerationData Image Интерфейс
ImageGenerationQuality Н/П Псевдоним
ImageGenerationResponseFormat Н/П Псевдоним
ImageGenerations ImagesResponse Интерфейс
ImageGenerationStyle Н/П Псевдоним
ImageSize Н/П Псевдоним
MaxTokensFinishDetails Н/П Интерфейс
OpenAIClientOptions AzureClientOptions Интерфейс
OpenAIError OpenAIError Интерфейс
OpenAIKeyCredential Н/П Класс
StopFinishDetails Н/П Интерфейс

Типы Azure

AzureOpenAI подключается к службе Azure OpenAI и может вызывать все операции, доступные в службе. Однако типы запросов и ответов наследуются от OpenAI и еще не обновляются, чтобы отразить дополнительные функции, поддерживаемые исключительно службой Azure OpenAI. Пользователям TypeScript потребуется импортировать данные "@azure/openai/types" , из @azure/openai@2.0.0-beta.1 которых будут объединяться определения, относящиеся к Azure, в существующие типы. Примеры в разделе "Примеры миграции " показывают, как это сделать.

Следующие шаги