エンドポイントと SDK を選択する

  • 7 分

Microsoft Foundry は、生成型 AI チャット アプリケーションを開発するための柔軟性を提供します。 開発を開始する前に、使用可能なオプションと、使用するオプションを決定する方法を理解しておくことが重要です。 アプリケーションの開発に関するいくつかの考慮事項を次に示します。

  • エンドポイント: Microsoft Foundry プロジェクトには、クライアント アプリケーションからプロジェクト資産に接続して使用できる 2 つのエンドポイント (モデルのデプロイなど) が用意されています。 各プロジェクトには、 Project エンドポイント と Azure OpenAI エンドポイントの両方があります。
  • クライアント SDK: 選択したエンドポイントに応じて、 Microsoft Foundry SDK または OpenAI SDK を使用して生成 AI チャット アプリケーションを開発できます。 どちらの SDK でも、モデルにプロンプトを送信できる OpenAI API 互換クライアント オブジェクトがサポートされていますが、各 SDK で使用できる特定の機能にはいくつかの違いがあります。
  • 認証: 使用するエンドポイントと SDK に応じて、資産へのアクセスを許可するために、Foundry によってクライアント アプリケーションを認証する方法は複数あります。 一般に、運用アプリケーションでは Microsoft Entra ID 認証を使用する必要があります。これには、特定の ID のコンテキストでアプリケーションを実行する必要があります。ただし、一部のシナリオでは 、キーベース または トークンベースの 認証を使用することもできます。
  • チャット API: OpenAI クライアント API は、 ChatCompletions と Responses という 2 つのチャット API をサポート しています。 ほとんどの新しい開発プロジェクトでは Responses API が推奨されますが、 ChatCompletions API は、多くの生成 AI モデルとプラットフォーム間で十分に確立され、互換性があります。

まず、使用可能なエンドポイント、クライアント SDK、認証方法を検討してみましょう。応答と ChatCompletions API については後で説明します。

Foundry SDK とプロジェクト エンドポイントの使用

Microsoft Foundry SDK は、REST API と言語固有のクライアント ライブラリを使用して、プロジェクト内のリソースへのプログラムによるアクセスを提供します。含む：

注

このモジュールでは、一般的なタスクに Python コード例を使用します。 優先言語での同等のコードについては、言語固有の SDK ドキュメントを参照してください。 各 SDK は個別に開発および保守されるため、一部の機能は実装の異なる段階にある場合があります。

SDK のインストール

Python で Azure AI Projects ライブラリを使用するには、PyPI から azure-ai-projects パッケージをサポート パッケージと共にインストールします。

pip install azure-ai-projects azure-identity openai

注

Foundry SDK を使用してチャット アプリケーションを開発する場合は、OpenAI SDK パッケージもインポートする必要があります。Foundry SDK のチャット クライアント機能は OpenAI SDK から派生します。

プロジェクト エンドポイントへの接続

各 Foundry projectには、foundry ポータルの project Overview ページ (https://ai.azure.com) で見つけることができる一意のエンドポイントがあります。

project エンドポイントは、次の形式に従います。

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

AIProjectClient オブジェクトを作成するには、次のエンドポイントを使用します。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

注

このコードでは、既定のAzure資格情報を使用して認証します。 この認証を有効にするには、azure-identity パッケージをインストールする必要があります (前のインストール コマンドを参照)。

ヒント

projectを正常にaccessするには、認証されたAzure セッションでコードを実行する必要があります。 たとえば、Azure CLI az login コマンドを使用して、コードを実行する前にサインインできます。

プロジェクト クライアント (AIProjectClient) は、OpenAI に相当するものがない Foundry ネイティブ操作へのアクセスを提供します。 project クライアントを使用して、次の手順を実行します。

  • リソース接続を取得する
  • プロジェクト構成にアクセスする
  • トレースを有効にする
  • データセットとインデックスを管理する

チャット クライアントの作成

Foundry プロジェクト内のモデルとチャットするには、OpenAI と互換性のあるクライアント オブジェクトが必要です。 次のように、プロジェクト クライアントの get_openai_client() メソッドを使用して取得できます。

openai_client = project_client.get_openai_client(api_version="2024-10-21")

その後、このチャット クライアント オブジェクトを使用して、モデルにプロンプトを送信し、応答を返すことができます。

Azure OpenAI エンドポイントでの OpenAI SDK の使用

OpenAI SDK は、OpenAI API を呼び出すための公式のクライアント ライブラリです。 HTTP 要求、認証、再試行、応答解析を処理します。 この SDK は、同じパターンを使用して、OpenAI でホストされるモデル、Azure OpenAI デプロイ、Foundry モデルと連携します。

SDK のインストール

Python で OpenAI ライブラリを使用するには、サポート パッケージと共に PyPI から openai パッケージをインストールします。

pip install openai azure-identity

注

トークン ベースの認証を使用して Microsoft Entra ID 資格情報を使用してエンドポイントに接続する場合は、 Azure ID パッケージが必要です。

Azure OpenAI エンドポイントへの接続

各 Foundry プロジェクトには、の Foundry ポータルにあるプロジェクトの https://ai.azure.com] ページで確認できる Azure OpenAI エンドポイントが含まれています。

Azure OpenAI エンドポイントは、次の形式に従います。

https://{resource-name}.openai.azure.com/openai/v1

エンドポイントと Azure 資格情報を使用して OpenAI クライアントを作成します。

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Microsoft Entra ID (推奨) に加えて、API キーまたは環境変数を使用して認証できます。

API キー認証:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Important

API キーは慎重に使用してください。 Azure Key Vault に安全に格納し、コードに直接含めてはいけません。

環境変数:

OPENAI_BASE_URLとOPENAI_API_KEY環境変数を設定すると、クライアントはそれらを自動的に使用します。

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

認証方法に関係なく、 OpenAI クライアントはモデル推論操作を処理します。 次の場合に使用します。

  • Responses API を使用した応答の生成
  • チャットの完了と画像の生成
  • Foundry ダイレクト モデルへのアクセス (Azure OpenAI 以外のモデル)

AzureOpenAI クライアント オブジェクトの使用

通常、 OpenAI クライアント オブジェクトを使用して、Azure OpenAI v1 エンドポイントを介してモデルとチャットする必要があります。 ただし、特定のバージョンの Azure OpenAI API の機能を使用する必要がある場合は、 AzureOpenAI クライアント オブジェクトを作成することもできます。 AzureOpenAI クライアント オブジェクトを作成するには、次のように API バージョンと Azure エンドポイントを指定する必要があります。

import os
from openai import AzureOpenAI
    
openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Foundry SDK と OpenAI SDK の選択

Microsoft Foundry では、AI アプリケーションを構築するための 2 つの方法がサポートされています。 それぞれが異なる目的を果たし、それぞれの用途を理解することは、適切なソリューションを構築するのに役立ちます。

Foundry SDK を使用するタイミング

アプリケーションで Foundry 固有の機能が必要な場合は、Foundry SDK を使用します。

  • AI エージェントを構築および管理するための Foundry Agent Service
  • ツールの呼び出しと承認 のワークフロー
  • AI 応答をテストおよび検証するためのクラウド評価
  • アプリケーションの動作を監視するためのトレースと可観測性
  • Foundry ダイレクト モデル (モデル カタログから利用できる Azure OpenAI 以外のモデル)
  • プロジェクトメタデータ、接続、ガバナンス 機能

エージェント、評価、または Foundry 固有の機能を使用してアプリを構築する場合は、Foundry SDK をお勧めします。

OpenAI SDK を使用するタイミング

OpenAI API との最大の互換性が必要な場合は、OpenAI SDK を使用します。

  • 既存のコードとツールに対する OpenAI API の完全な互換性
  • OpenAI デプロイと Azure OpenAI デプロイ間の移植性
  • チャットの完了、応答、画像 API
  • Foundry 固有の概念への最小限の依存関係

OpenAI SDK は、既存の OpenAI コードを最小限の変更で動作させるモデル推論ワークロードに最適です。 ただし、このアプローチでは、エージェントや評価などの Foundry 固有の機能は提供されません。

Microsoft Foundry を使用すると、AI アプリケーションの構築方法を柔軟に行えます。 エージェント、評価、トレース、接続などのプロジェクト レベルの機能が必要な場合は、foundry SDK を AIProjectClient と共に使用します。 OpenAI SDK は、OpenAI の最大互換性を備えた単純なモデル推論が必要な場合に使用します。 どちらの SDK も Foundry プロジェクト エンドポイントで動作するため、アプリケーションで必要に応じてそれらを組み合わせることができます。 また、同じアプリケーション (プロジェクト機能用 Foundry SDK とモデル推論用の OpenAI SDK) の両方の SDK を一緒に使用することもできます。