Перенос в библиотеку OpenAI JavaScript API 4.x (классическая версия)

Применяется только к:Портал Foundry (классический). Эта статья недоступна для нового портала Foundry. Дополнительные сведения о новом портале.

Замечание

Ссылки в этой статье могут открывать содержимое в новой документации Microsoft Foundry вместо классической документации Foundry, которую вы просматриваете в данный момент.

Это важно

Последние примеры API см. в статье жизненного цикла API.

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

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

Microsoft Entra ID

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

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

Передайте этот объект второму аргументу конструктора OpenAIClient .

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

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

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

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

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

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

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

Это важно

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

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

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

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

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

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

Различия API

Клиенты AzureOpenAI и OpenAIClient имеют ключевые различия:

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

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

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

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

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

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

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

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

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

Azure для ваших данных

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 было добавлено для упаковки параметров расширения, которое отражает схему Azure API OpenAI.
  • Свойства в верблюжем регистре были заменены свойствами в формате snake case.

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

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.

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

import { createReadStream } from "fs";

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

Встраивания

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

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

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

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

  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. В следующем примере показано, как получить доступ к результатам фильтрации контента.

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;
  ...
}
  • Свойства в верблюжем регистре были заменены свойствами в формате snake case.
  • "@azure/openai/types" импортируется, что добавляет определения Azure, (например, content_filter_results) к клиентским типам, см. в разделе Типы Azure дополнительные сведения.

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

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

Старое имя типа Ближайший новый тип Тип символа Описание изменения
OpenAIClient AzureOpenAI Класс Этот класс заменяет предыдущий и не имеет общих методов. См. раздел о AzureOpenAI ниже.
AudioResult Transcription/Transcription Интерфейс В зависимости от операции вызова, два интерфейса заменяют прежний интерфейс.
AudioResultFormat тип встроенного объединения свойства response_format псевдоним Он не существует
AudioResultSimpleJson Transcription/Transcription Интерфейс В зависимости от операции вызова, два интерфейса заменяют прежний интерфейс.
AudioResultVerboseJson N/A Интерфейс
AudioSegment N/A Интерфейс
AudioTranscriptionTask N/A псевдоним
AzureChatEnhancementConfiguration, ContentFilterSuccessResultDetailsForPrompt, 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, 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 Интерфейсы и псевдонимы См. раздел типов Azure ниже
AzureKeyCredential N/A Класс Ключ 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 N/A псевдоним
ChatTokenLogProbabilityInfo TopLogprob Интерфейс
ChatTokenLogProbabilityResult ChatCompletionTokenLogprob Интерфейс
Choice Choice Интерфейс
Completions Completion Интерфейс
CompletionsFinishReason N/A псевдоним
CompletionsLogProbabilityModel Logprobs Интерфейс
CompletionsUsage CompletionUsage Интерфейс
EmbeddingItem Embedding Интерфейс
Embeddings CreateEmbeddingResponse Интерфейс
EmbeddingsUsage CreateEmbeddingResponse.Usage Интерфейс
EventStream Stream Интерфейс
FunctionCall FunctionCall Интерфейс
FunctionCallPreset N/A псевдоним
FunctionDefinition Function Интерфейс
FunctionName N/A псевдоним
GetAudioTranscriptionOptions TranscriptionCreateParams Интерфейс
GetAudioTranslationOptions TranslationCreateParams Интерфейс
GetChatCompletionsOptions ChatCompletionCreateParamsNonStreaming и ChatCompletionCreateParamsStreaming. Интерфейс
GetCompletionsOptions CompletionCreateParams Интерфейс
GetEmbeddingsOptions EmbeddingCreateParams Интерфейс
GetImagesOptions ImageGenerateParams Интерфейс
ImageGenerationData Image Интерфейс
ImageGenerationQuality N/A псевдоним
ImageGenerationResponseFormat N/A псевдоним
ImageGenerations ImagesResponse Интерфейс
ImageGenerationStyle N/A псевдоним
ImageSize N/A псевдоним
MaxTokensFinishDetails N/A Интерфейс
OpenAIClientOptions AzureClientOptions Интерфейс
OpenAIError OpenAIError Интерфейс
OpenAIKeyCredential N/A Класс
StopFinishDetails N/A Интерфейс

Типы Azure

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

  • Последнее обновление: