次の方法で共有

OpenAI JavaScript API ライブラリ 4.x への移行

2024 年 6 月の時点で、Azure AI Foundry Models API バージョン 2022-12-01 以降で Azure OpenAI をサポートする公式の OpenAI JavaScript クライアント ライブラリの最新バージョンである OpenAI JavaScript API ライブラリ 4.x に移行することをお勧めします。 この記事では、Azure OpenAI に固有の変更内容を紹介します。

クライアントの認証

Azure OpenAI に対する API 要求の認証を行うには、さまざまな方法があります。 Microsoft Entra ID のトークンを使用することをお勧めします。 詳細については、Azure Identity のドキュメントを参照してください。

マイクロソフト エントラ ID

Microsoft Entra ID トークンを使用して Azure OpenAI で認証するには、いくつかの方法があります。 既定の方法では DefaultAzureCredential パッケージの @azure/identity クラスを使用しますが、実際のアプリケーションでは別の資格情報クラスが使用されることもあります。 このガイドでは、DefaultAzureCredential クラスを使用することを前提とします。 資格情報は次の方法で作成できます。

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

このオブジェクトが、OpenAIClient と AssistantsClient のクライアント コンストラクターの 2 番目の引数に渡されます。

ただし、AzureOpenAI クライアントの認証を行うには、getBearerTokenProvider パッケージの @azure/identity 関数を使用する必要があります。 この関数によってトークン プロバイダーが作成され、これが AzureOpenAI の内部で各要求のトークンを取得するために使用されます。 トークン プロバイダーの作成方法は次のとおりです。

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

azureADTokenProvider は AzureOpenAI クライアントの作成時にオプション オブジェクトに渡されます。

(推奨されません) API キー

API キーは、他の認証方法よりも安全性が低いため、運用環境での使用はお勧めしません。 以前は、AzureKeyCredential オブジェクトは、OpenAIClient または AssistantsClient を認証するために次のように作成されていました。

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

一方、AzureOpenAI は、AZURE_OPENAI_API_KEY 環境変数を設定するか、apiKey クライアントの作成時にオプション オブジェクトに AzureOpenAI 文字列プロパティを設定することで、API キーを使用して認証できます。

重要

API キーは慎重に使用してください。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。 API キーを使用する場合は、Azure Key Vault に安全に保存します。 アプリで API キーを安全に使用する方法の詳細については、Azure Key Vault を使用した API キーに関する記事を参照してください。

AI サービスのセキュリティの詳細については、「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);

Azure OpenAI リソースのエンドポイントは、endpoint オプションを設定するという方法で指定できますが、クライアントが環境変数 AZURE_OPENAI_ENDPOINTから読み込むこともできます。 エンドポイントを設定するにはこの方法をお勧めします。その理由は、コードを変更しなくてもクライアントをさまざまな環境で使用できるようになることと、エンドポイントがコード内で公開されないよう保護できることです。

API バージョンの指定は必須です。これが必要であるのは、プレビュー API バージョン間で既存のコードの動作に支障が生じることがないようにするためです。 Azure OpenAI API のバージョンの詳細については、API のバージョン管理に関するドキュメントを参照してください。 また、deployment プロパティは必須ではありませんが、設定することをお勧めします。 deployment が設定済みのときは、これを必要とするすべての操作の既定のデプロイとして使用されます。 クライアントの作成時に deployment オプションが指定されない場合は、オプション オブジェクト内の model プロパティでデプロイ名が設定されている必要があります。 ただし、オーディオ操作 (たとえば audio.transcriptions.create) を行うには、クライアントの作成時に deployment オプションがデプロイ名に設定されていることが必要です。

API の相違点

OpenAIClient および AssistantsClient のクライアントと AzureOpenAI クライアントとの間の主な違いは次のとおりです。

  • OpenAIClient と AssistantsClient のどちらも、操作はメソッドのフラット リストとして表現されます (たとえば client.getChatCompletions)。 AzureOpenAI では、操作は入れ子のグループとしてグループ化されます (たとえば client.chat.completions.create)。
  • OpenAIClient と AssistantsClient Azure OpenAI API で使用される多くの名前の名前を変更します。 たとえば、API ではスネーク ケースが使用されますが、クライアントではキャメル ケースが使用されます。 AzureOpenAIでは、名前は Azure OpenAI API と同じまま保持されます。

移行の例

以降のセクションでは、OpenAIClient と AssistantsClient から AzureOpenAI に移行する方法の例を示します。

チャット入力候補

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

次の点に注意してください。

  • getChatCompletions メソッドは chat.completions.create メソッドで置き換えられました。
  • messages パラメーターはオプション オブジェクト内で messages プロパティを使用して渡されるようになりました。
  • maxTokens プロパティの名前が max_tokens に変更され、deploymentName パラメーターが削除されました。 一般に、 options オブジェクトのプロパティの名前は Azure OpenAI API と同じです。これは、 AssistantsClientで使用されるキャメル ケース規則ではなく、スネーク ケース規則に従っています。 これは、AzureOpenAI クライアント内のすべての要求と応答のすべてのプロパティに当てはまります。
  • deploymentName パラメーターは、クライアントが deployment オプションを指定して作成された場合は必要ありません。 クライアントの作成時に deployment オプションが指定されなかった場合は、オプション オブジェクト内の model プロパティでデプロイ名が設定されている必要があります。

チャット補完のストリーミング

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

Azure On Your Data

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 OpenAI API のスキーマが反映されます。
  • キャメル ケースのプロパティはスネーク ケースのプロパティで置き換えられました。

オーディオ文字起こし

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 メソッドで置き換えられました。
  • その他の変更はすべて、オーディオ文字起こしの例と同じです。

アシスタント

以降の例では、AssistantsClient のメソッドのいくつかの移行方法を示します。

アシスタント作成

const options = ...;
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);
  • createAssistant メソッドは beta.assistants.create メソッドで置き換えられました。

スレッドの作成

次の例では、createThread メソッド呼び出しを移行する方法を示します。

const assistantThread = await assistantsClient.beta.threads.create();
  • createThread メソッドは beta.threads.create メソッドで置き換えられました。

メッセージ作成

次の例では、createMessage メソッド呼び出しを移行する方法を示します。

const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);
  • createMessage メソッドは beta.threads.messages.create メソッドで置き換えられました。
  • メッセージ指定がパラメーター リストからオブジェクトに移動しました。

実行

アシスタントをスレッドに対して実行するには、createRun メソッドを使用して実行を作成してから、ループを使用してその実行の状態のポーリングを終了状態になるまで繰り返します。 次の例では、実行の作成とポーリングを移行する方法を示します。

このコードは、createAndPoll メソッドを使用して移行するとともに単純化できます。このメソッドによって実行が作成され、その実行のポーリングが終了状態になるまで行われます。

const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
  • createRun メソッドは beta.threads.runs.create メソッドと createAndPoll メソッドで置き換えられました。
  • createAndPoll メソッドは、実行を作成してその実行のポーリングを終了状態になるまで行うために使用されます。

実行の結果を処理する

for await ループを使用して、ページを順にループ処理できます。

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

埋め込み

次の例では、getEmbeddings メソッド呼び出しを移行する方法を示します。

const embeddings = await client.embeddings.create({ input, model: '' });
  • getEmbeddings メソッドは embeddings.create メソッドで置き換えられました。
  • input パラメーターはオプション オブジェクト内で input プロパティを使用して渡されるようになりました。
  • deploymentName パラメーターは削除されました。 deploymentName パラメーターは、クライアントが deployment オプションを指定して作成された場合は必要ありません。 クライアントの作成時に deployment オプションが指定されなかった場合は、オプション オブジェクト内の model プロパティでデプロイ名が設定されている必要があります。

イメージの生成

次の例では、getImages メソッド呼び出しを移行する方法を示します。

  const results = await client.images.generate({ prompt, model: '', n, size });
  • getImages メソッドは images.generate メソッドで置き換えられました。
  • prompt パラメーターはオプション オブジェクト内で 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;
  ...
}
  • キャメル ケースのプロパティはスネーク ケースのプロパティで置き換えられました。
  • "@azure/openai/types" がインポートされ、これによって Azure 固有の定義 (たとえば content_filter_results) がクライアントの型に追加されます。詳細については、「Azure の型」セクションを参照してください。

型の比較

次の表は、@azure/openai のさまざまな型名と、openai での最も等価に近い型をまとめたものです。 名前の違いには、前述のさまざまな変更が現れています。 この表の内容は概要であり、詳細とコード サンプルはその後のセクションで示します。

以前の型名 最も近い新しい型 シンボル型 変更の説明
OpenAIClient AzureOpenAI クラス このクラスは以前のクラスを置き換えるものですが、共通するメソッドはありません。 後述の AzureOpenAI のセクションを参照してください。
AudioResult Transcription/Transcription インターフェイス 呼び出し操作に応じて、この 2 つのインターフェイスが以前のインターフェイスを置き換えます。
AudioResultFormat response_format プロパティのインライン ユニオン型 エイリアス 存在しない
AudioResultSimpleJson Transcription/Transcription インターフェイス 呼び出し操作に応じて、この 2 つのインターフェイスが以前のインターフェイスを置き換えます。
AudioResultVerboseJson 該当なし インターフェイス
AudioSegment 該当なし インターフェイス
AudioTranscriptionTask 該当なし エイリアス
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 該当なし インターフェイスとエイリアス 後の「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 Service のみでサポートされている追加機能を反映する更新はまだ行われていません。 TypeScript を使用する場合は、"@azure/openai/types" を @azure/openai@2.0.0-beta.1 からインポートして Azure 固有の定義を既存の型にマージする必要があります。 「移行の例」セクションの例で、これを行う方法を示しています。

次のステップ