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

このチュートリアルでは、 Azure AI Foundry SDK (およびその他のライブラリ) を使用して、Contoso Trek という小売企業のチャット アプリを構築、構成、評価します。 この小売会社は、キャンプ用品とアウトドア衣類を専門としています。 このチャット アプリは、製品とサービスに関する質問に答えます。 たとえば、このチャット アプリは、"最も防水性が高いテントはどれですか?" や "寒い天候に最適な寝袋は何ですか?" などの質問に答えることができます。

このチュートリアルは 3 部構成のチュートリアルのパート 1 です。 このパート 1 では、パート 2 でコードを書いてパート 3 でチャット アプリを評価するための準備を整えます。 このパートでは、次のことを行います。

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

このチュートリアルは 3 部構成のチュートリアルのパート 1 です。

前提条件

• アクティブなサブスクリプションを持つ Azure アカウント。 お持ちでない場合は、無料のアカウントを作成してください。

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

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

1. Azure AI Foundry にサインインします。

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

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

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

     

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

     

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

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

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

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

   • 新しく作成する場合は、[新しいハブの作成] を選択し、名前を指定します。

     

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

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

モデルをデプロイする

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

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

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

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

   

3. モデルの詳細ページで、[デプロイ] を選択します。

   

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

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

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

このアプリケーションの目標は、モデルの応答をカスタム データにグラウンディングさせることです。 検索インデックスは、ユーザーの質問に基づいて、関連するドキュメントを取得するために使用されます。

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

既に Azure AI 検索サービスがある場合は、次のセクションまでスキップして構いません。

そうでなければ、Azure portal を使用して Azure AI 検索サービスを作成できます。

1. Azure portal で Azure AI 検索サービスを作成します。
2. リソース グループとインスタンスの詳細を選択します。 このページでは、価格と価格レベルの詳細を確認できます。
3. ウィザードを続行し、[レビューと割り当て] を選択してリソースを作成します。
4. 推定コストなど、Azure AI 検索サービスの詳細を確認します。
5. [作成] を選択して Azure AI 検索サービスを作成します。

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

Azure AI 検索接続が既にプロジェクト内にある場合は、「Azure CLI のインストールとサインイン」に進んでかまいません。

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

1. Azure AI Foundry でプロジェクトに移動し、左側のペインから [管理センター] を選択します。

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

3. Azure AI 検索接続がある場合は、次のセクションに進んでかまいません。

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

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

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

   重要

   API キー オプションは、運用環境では推奨されません。 推奨される Microsoft Entra ID 認証オプションを選択して使用するには、Azure AI Search サービスのアクセス制御も構成する必要があります。 検索インデックス データ共同作成者と検索サービス共同作成者のロールをユーザー アカウントに割り当てます。 詳細については、「ロールを使用して Azure AI 検索に接続する」および「Azure AI Foundry ポータルでのロールベースのアクセス制御」を参照してください。

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
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

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

   pip install -r requirements.txt
   

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

作業用のフォルダーを作成します。 このフォルダーの中に config.py という名前のファイルを作成します。 このヘルパー スクリプトは、このチュートリアル シリーズ内の次の 2 つのパートで使用されます。 次のコードを追加します。

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

環境変数を構成する

コードから Azure AI 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"

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

  

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

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

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

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

ほとんどの場合、次のコマンドを使用して、ターミナルから 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 スクリプトも実行できるように、このターミナル ウィンドウを開いたままにしておきます。

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

不要な Azure コストが発生しないように、このチュートリアルで作成したリソースが不要になったら削除してください。 リソースを管理するために、Azure portal を使用できます。

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

次のステップ

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