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

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

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

前提条件

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

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

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

1. Microsoft Foundry にサインインします。 [新しいファウンドリー]切り替えがオフになっていることを確認します。 これらの手順は Foundry (クラシック) を参照します。

   

2. 次に何を行うかは、あなたのいる場所によって異なります。

   • 既存のプロジェクトがない場合: クイックスタート: Microsoft Foundry の概要に関するページの手順に従って、最初のプロジェクトを作成します。

   • プロジェクト内の場合は: プロジェクトの階層リンクを選択し、[新しいリソースの作成] を選択します。

     

   • プロジェクトに属していない場合: 右上の [新規作成] を選択して、新しい Foundry プロジェクトを作成します

     

3. AI ハブ リソースを選択し、[次へ] を選択します。

4. プロジェクトの 名前 を入力します。

5. ハブがある場合は、最近選択したハブが表示されます。

   • 複数のハブにアクセスできる場合は、ドロップダウンから別のハブを選択できます。

   • 新しいハブを作成する場合は、ドロップダウンから [ 新しいハブの作成 ] を選択します。

     

6. ハブがない場合は、既定のハブが自動的に作成されます。

7. を選択してを作成します。

モデルをデプロイする

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

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

1. 左側のウィンドウで、[ モデル カタログ] を選択します。

2. モデルの一覧から gpt-4o-mini モデルを選択します。 検索バーを使用して見つけることができます。

   

3. モデルの詳細ページで、[ このモデルを使用する] を選択します。

4. 既定の デプロイ名 のままにして、[ デプロイ] を選択します。 モデルが自分のリージョンで使用できない場合は、別のリージョンが選択され、プロジェクトに接続されます。 この場合は、[接続とデプロイ] を選択します。

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

Azure AI 検索サービスを作成する

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

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

Azure AI Search サービスが既にある場合は、 次のセクションに進みます。

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

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

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

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

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

1. Foundry でプロジェクトに移動し、左側のウィンドウから管理センターを選択します。

2. [接続されたリソース] セクションで、Azure AI 検索という種類の接続があるかどうかを調べます。

3. Azure AI Search 接続がある場合は、次の手順をスキップできます。

4. それ以外の場合は、[新しい接続] を選択し、次に [Azure AI 検索] を選択します。

5. オプションで Azure AI 検索サービスを見つけて、[接続を追加] を選択します。

6. [API キー] を [認証] に使用します。

   重要

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

7. [接続の追加] を選択します。

新しい Python 環境を作成する

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

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

必要に応じて Python をインストールする

Python 3.10 以降を使用しますが、少なくとも Python 3.9 が必要です。 適切なバージョンの Python がインストールされていない場合は、 VS Code Python チュートリアル の手順に従って、オペレーティング システムに 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 インタープリターが使用されます。

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

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

1. プロジェクト フォルダーに 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。

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

   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 プレイグラウンドのクイック スタートで作成した Foundry プロジェクト内で、接続文字列を見つけてください。 プロジェクトを開いて、[概要] ページで接続文字列を見つけます。 接続文字列をコピーして .env ファイルに貼り付けます。

  

• 検索インデックスがまだない場合は、AISEARCH_INDEX_NAME の値を "example-index" のままにします。 このチュートリアルのパート 2 では、この名前を使用してインデックスを作成します。 代わりに使用したい検索インデックスを以前に作成してある場合は、その検索インデックスの名前と一致するように値を更新します。

• モデルの名前をデプロイ時に変更した場合は、使用した名前と一致するように .env ファイル内の値を更新してください。

Azure CLI をインストールしてサインインする

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

ほとんどの場合、次のコマンドを使用して、ターミナルから 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 クライアント ライブラリ、 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 コストが発生しないようにするには、このチュートリアルで作成したリソースが不要になった場合は削除します。 リソースを管理するために、Azure portal を使用できます。

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

次のステップ

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