チュートリアル: パート 1 - Microsoft Foundry SDK (クラシック) を使用してカスタムナレッジ取得 (RAG) アプリを構築するためのプロジェクトと開発環境を設定する

注

このドキュメントでは、 Microsoft Foundry (クラシック) ポータルを参照します。

🔍 新しいポータルの詳細については、Microsoft Foundry (新しい) ドキュメントを参照してください。

このチュートリアルでは、Microsoft Foundry SDK を使用してカスタムナレッジ取得 (RAG) チャットアプリを構築するために必要なリソースを設定します。これは、3 部構成のチュートリアルシリーズのパート 1 です。ここでリソースを作成し、パート 2 でアプリをビルドし、パート 3 で評価します。このパートでは、次のことを行います。

プロジェクトを作成する
Azure AI Search インデックスを作成する
Azure CLIをインストールしてサインインする
Pythonとパッケージをインストールする
モデルをプロジェクトにデプロイする
環境変数を構成する

他のチュートリアルまたはクイックスタートを完了した場合は、このチュートリアルに必要なリソースの一部を既に作成している可能性があります。その場合は、これらの手順をスキップしてください。

[前提条件]

Important

この記事では、ハブベースのプロジェクトのレガシサポートを提供します。 Foundry プロジェクトでは機能しません。「自分が持っているプロジェクトの種類を確認する方法」を参照してください。

SDK の互換性に関する注意: コード例には、特定の Microsoft Foundry SDK バージョンが必要です。互換性の問題が発生した場合は、ハブベースから Foundry プロジェクトへの移行を検討してください。

アクティブなサブスクリプションと Owner または Contributor ロールが割り当てられているAzure アカウント。お持ちでない場合は、無料のアカウントを作成してください。
Microsoft Foundry: プロジェクトを作成するための所有者または共同作成者ロール。

ハブベースのプロジェクトを作成する

Microsoft Foundry でハブベースのプロジェクトを作成するには、次の手順に従います。

Microsoft Foundry にサインインします。 「New Foundry」トグルがオフになっていることを確認します。 これらの手順は Foundry (クラシック) を参照します。
次に何を行うかは、あなたのいる場所によって異なります。
- 既存のプロジェクトがない場合は、「クイックスタート: Microsoft Foundry の概要」の手順に従って、最初のプロジェクトを作成します。
- プロジェクト内の場合は: プロジェクトの階層リンクを選択し、[新しいリソースの作成] を選択します。
- プロジェクトに含まれていない場合: 右上の [ 新規作成 ] を選択して新しい Foundry プロジェクトを作成します
AI ハブリソースを選択し、[次へ] を選択します。
プロジェクトの名前を入力します。
ハブがある場合は、最近選択したハブが表示されます。
- 複数のハブにアクセスできる場合は、ドロップダウンから別のハブを選択できます。
- 新しいハブを作成する場合は、ドロップダウンから [ 新しいハブの作成 ] を選択します。
ハブがない場合は、既定のハブが自動的に作成されます。
を選択してを作成します。

モデルをデプロイする

RAG ベースのチャットアプリを構築するには、Azure OpenAI チャットモデル (gpt-4o-mini) と Azure OpenAI 埋め込みモデル (text-embedding-ada-002) の 2 つのモデルが必要です。各モデルに対してこの一連の手順を使用して、これらのモデルを Foundry プロジェクトにデプロイします。

次の手順では、Foundry ポータルモデルカタログからリアルタイムエンドポイントにモデルをデプロイします。

ヒント

Microsoft Foundry ポータルで左側のウィンドウをカスタマイズできるため、次の手順とは異なる項目が表示される場合があります。探しているものが表示されない場合は、左側のペインの下部にある… もっと見るを選択してください。

左側のウィンドウで、[ モデルカタログ] を選択します。
モデルの一覧から gpt-4o-mini モデルを選択します。検索バーを使用して見つけることができます。
モデルの詳細ページで、[ このモデルを使用する] を選択します。
既定の デプロイ名 のままにして、[ デプロイ] を選択します。モデルが自分のリージョンで使用できない場合は、別のリージョンが選択され、プロジェクトに接続されます。この場合は、[接続とデプロイ] を選択します。

gpt-4o-mini をデプロイした後に、このステップを繰り返して text-embedding-ada-002 モデルをデプロイします。

Azure AI Search サービスを作成する

このアプリケーションの目的は、カスタムデータ内のモデル応答を固定することです。検索インデックスは、ユーザーの質問に基づいて関連するドキュメントを取得します。

検索インデックスを作成するには、Azure AI Search サービスと接続が必要です。

注

Azure AI Search サービス以降の検索インデックスを作成すると、コストが発生します。リソースを作成する前にコストを確認するには、Azure AI Search サービスの作成ページで価格と価格レベルを確認してください。このチュートリアルでは、 Basic 以上の価格レベルを使用します。

既にAzure AI Search サービスがある場合は、next セクションに移動します。

それ以外の場合は、Azure ポータルを使用してAzure AI Search サービスを作成します。

ヒント

この手順は、このチュートリアルシリーズで Azure ポータルを使用する唯一の時間です。残りの作業は Foundry ポータルまたはローカル開発環境で行います。

Azure ポータルでAzure AI Search サービスを作成します。
リソースグループとインスタンスの詳細を選択します。このページで価格と価格レベルを確認してください。このチュートリアルでは、 Basic 以上の価格レベルを使用します。
ウィザードを続行し、[レビューと割り当て] を選択してリソースを作成します。
推定コストを含め、Azure AI Search サービスの詳細を確認します。
Create を選択して、Azure AI Search サービスを作成します。

Azure AI Searchをプロジェクトに接続する

プロジェクトに既にAzure AI Search接続がある場合は、Azure CLIをインストールしてサインインします。

Foundry ポータルで、Azure AI Search接続されているリソースを確認します。

Foundry でプロジェクトに移動し、左側のウィンドウから管理センターを選択します。
Connected resources セクションで、Azure AI Search の種類の接続があるかどうかを確認します。
Azure AI Search接続がある場合は、次の手順をスキップできます。
それ以外の場合は、[新しい接続] を選択し、Azure AI Search を選択します。
オプションでAzure AI Search サービスを見つけて、接続の追加を選択します。
[API キー] を [認証] に使用します。

Important

API キー オプションは、運用環境では推奨されません。推奨される方法は、Microsoft Entra ID 認証です。これには、Search Index Data Contributor ロールと Search Service Contributor ロール (前提条件で構成) が必要です。詳細については、「ロールを使用してAzure AI Searchに接続するを参照してください。このチュートリアルでは、迅速に作業を進める場合は 、API キー を使用できます。運用環境にデプロイする前に、Entra ID に切り替えます。
[接続の追加] を選択します。

新しいPython環境を作成する

任意の IDE で、プロジェクト用の新しいフォルダーを作成します。そのフォルダーでターミナルウィンドウを開きます。

まず、新しいPython環境を作成します。グローバル Python インストールにはパッケージをインストールしないでください。 Python パッケージをインストールするときは、必ず仮想環境または conda 環境を使用してください。それ以外の場合は、Pythonのグローバルインストールを中断できます。

必要に応じて、Pythonをインストールします

Python 3.10 以降を使用しますが、少なくとも Python 3.9 が必要です。適切なバージョンのPythonがインストールされていない場合は、VS Code Python Tutorialの指示に従って、オペレーティングシステムにPythonをインストールする最も簡単な方法を確認してください。

仮想環境を作成する

Python 3.10 以降が既にインストールされている場合は、次のコマンドを使用して仮想環境を作成します。

py -3 -m venv .venv
.venv\scripts\activate

python3 -m venv .venv
source .venv/bin/activate

python3 -m venv .venv
source .venv/bin/activate

Python環境をアクティブ化すると、コマンドラインから python または pip を実行すると、アプリケーションの .venv フォルダーにあるPython インタープリターが使用されます。

注

deactivate コマンドを使用して、Python仮想環境を終了します。必要に応じて、後で再アクティブ化できます。

パッケージをインストールする

必要なパッケージをインストールします。

プロジェクトフォルダーに requirements.txt という名前のファイルを作成します。次のパッケージをこのファイルに追加します。
```
azure-ai-projects==1.0.0b10
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api
```
参照: Azure AI Projects クライアントライブラリ、azure-ai-inference、python-dotenv。
必要なパッケージをインストールします。
```
pip install -r requirements.txt
```

環境変数を構成する

コードから Microsoft Foundry Models の Azure OpenAI を呼び出すには、プロジェクト接続文字列が必要です。このクイックスタートでは、この値を .env ファイルに保存します。このファイルには、アプリケーションで読み取ることができる環境変数が記録されています。

.env ファイルを作成し、次のコードを貼り付けます。

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

Foundry playground クイックスタートであなたが作成した Foundry プロジェクトで connection string を見つけます。プロジェクトを開き、Overview ページでconnection stringを見つけます。 connection stringをコピーし、.env ファイルに貼り付けます。
検索インデックスがまだない場合は、AISEARCH_INDEX_NAME の値を "example-index" のままにします。このチュートリアルのパート 2 では、この名前を使用してインデックスを作成します。代わりに使用したい検索インデックスを以前に作成してある場合は、その検索インデックスの名前と一致するように値を更新します。
モデルの名前をデプロイ時に変更した場合は、使用した名前と一致するように .env ファイル内の値を更新してください。

ヒント

VS Code で作業している場合は、.env ファイルでの変更を保存した後に、ターミナルウィンドウを閉じて再度開いてください。

Warnung

誤って git リポジトリにチェックインされることがないように、お使いの .env が .gitignore ファイルの中にあることを確認してください。

Azure CLIをインストールし、ローカル開発環境からサインインして、ユーザー資格情報を使用して Microsoft Foundry Models で OpenAI Azure呼び出すことができるようにします。

ほとんどの場合、次のコマンドを使用してターミナルからAzure CLIをインストールできます。

winget install -e --id Microsoft.AzureCLI

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

brew update && brew install azure-cli

これらのコマンドが特定のオペレーティングシステムまたはセットアップで機能しない場合は>Azure CLI

Azure CLIをインストールしたら、az login コマンドを使用してサインインし、ブラウザーを使用してサインインします。

az login

または、デバイスコードを使用してブラウザー経由で手動でサインインすることもできます。

az login --use-device-code

サインインしたら、このターミナルウィンドウを開いたままにして、ここから Python スクリプトを実行します。

セットアップを確認する

クイックテストを実行して、環境が正しく設定されていることを確認します。

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

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

"Setup successful!" が表示された場合は、Azure資格情報と SDK が正しく構成されています。

ヒント

このチュートリアルでは、AZURE AI Projects SDK バージョン 1.0.0b10 が必要です。上記の SDK バージョンは、互換性の確認に役立ちます。別のバージョンがある場合は、 from_connection_string() メソッドを使用できない可能性があります。必要なバージョンをインストールするには、 pip install azure-ai-projects==1.0.0b10を実行します。

参照: Azure AI Projects クライアントライブラリ、DefaultAzureCredential。

ヘルパースクリプトを作成する

作業用のフォルダーを作成します。このフォルダーに config.py という名前のファイルを作成します。このヘルパースクリプトは、チュートリアルシリーズの次の 2 つの部分で使用します。このスクリプトは環境変数を読み込み、Azure AI Projects クライアントを初期化します。次のコードを追加します。

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

参照: AIProjectClient、 DefaultAzureCredential、 load_dotenv。

注

このスクリプトでは、まだインストールしていないパッケージ (azure.monitor.opentelemetry) も使用します。このパッケージは、チュートリアルシリーズの次の部でインストールします。

リソースをクリーンアップする

不要なAzureコストが発生しないようにするには、このチュートリアルで作成したリソースが不要になった場合は削除します。リソースを管理するには、Azure ポータルを使用します。

ただし、このチュートリアルシリーズの次のパートでチャットアプリを作成する場合は、まだ削除しないでください。

次のステップ

このチュートリアルでは、Azure AI SDK を使用してカスタムチャットアプリを構築するために必要なすべてのものを設定します。このチュートリアルシリーズ内の次のパートで、カスタムアプリを構築します。

パート 2: Azure AI SDK を使用してカスタムチャットアプリを構築する

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-10