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

[アーティクル]
12/18/2024

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

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

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

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

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

重要

この記事で "(プレビュー)" と付記されている項目は、現在、パブリックプレビュー段階です。このプレビューはサービスレベルアグリーメントなしで提供されており、運用環境ではお勧めしません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

前提条件

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

プロジェクトの作成

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

Azure AI Foundry のホーム ページに移動します。
[+ プロジェクトの作成] を選択します。
プロジェクトの名前を入力します。その他の設定は、すべて既定のままにします。
プロジェクトはハブに作成されます。 [新しいハブの作成] が表示されたら、それを選択して名前を指定します。 [次へ] を選択します。 ([新しいハブを作成] が表示されない場合、それは新しいハブが作成されているためです。)
[カスタマイズ] を選択して、ハブのプロパティを指定します。
[リージョン] を除き、任意の値を使用します。このチュートリアルシリーズのリージョンには、[米国東部 2] または [スウェーデン中部] のいずれかを使用することをお勧めします。
[次へ] を選択します。
[プロジェクトの作成] を選択します。

モデルをデプロイする

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

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

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

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

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

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

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

Note

Azure AI 検索サービスおよびその後の検索インデックスの作成には、関連コストがかかります。リソースを作成する前にコストを確認するには、作成ページで Azure AI 検索サービスの価格と価格レベルの詳細を確認できます。このチュートリアルでは、Basic 以上の価格レベルの使用をお勧めします。

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

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

ヒント

このチュートリアルシリーズでは、このステップでのみ Azure portal を使用します。残りの作業は、Azure AI Foundry ポータルまたはローカル開発環境で行います。

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

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

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

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

Azure AI Foundry でプロジェクトに移動し、左側のペインから [管理センター] を選択します。
[接続されたリソース] セクションで、Azure AI 検索という種類の接続があるかどうかを調べます。
Azure AI 検索接続がある場合は、次のセクションに進んでかまいません。
それ以外の場合は、[新しい接続] を選択し、次に [Azure AI 検索] を選択します。
オプションで Azure AI 検索サービスを見つけて、[接続を追加] を選択します。
[API キー] を [認証] に使用します。

重要

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

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

ユーザー資格情報を使用して Azure OpenAI Service を呼び出すことができるように、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 環境を作成する

このチュートリアルに必要なパッケージのインストールに使用される、新しい Python 環境を最初に作成する必要があります。グローバル Python インストールにパッケージをインストールしないでください。 Python パッケージをインストールするときは、常に仮想環境または conda 環境を使用する必要があります。そうしないと、Python のグローバルインストールが中断される場合があります。

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

Python 3.10 以降を使用することをお勧めしますが、少なくとも Python 3.8 が必要です。適切なバージョンの Python がインストールされていない場合は、オペレーティングシステムへの Python のインストールの最も簡単な方法として、VS Code 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 インタープリターを使用するということを意味します。

Note

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

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

azure-ai-projects (プレビュー) と azure-ai-inference (プレビュー) を、その他の必要なパッケージと共にインストールします。

最初に、requirements.txt という名前のファイルをプロジェクトフォルダー内に作成します。次のパッケージをこのファイルに追加します。
```
azure-ai-projects
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api
```
必要なパッケージをインストールします。
```
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 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 ファイル内の値を更新してください。

ヒント

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

警告

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

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

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

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

次のステップ

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

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

次の方法で共有

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

前提条件

プロジェクトの作成

モデルをデプロイする

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

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

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

新しい Python 環境を作成する

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

仮想環境を作成する

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

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

環境変数を構成する

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

プロジェクトの作成

モデルをデプロイする

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

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

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

新しい Python 環境を作成する

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

仮想環境を作成する

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

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

環境変数を構成する

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

次のステップ

フィードバック

その他のリソース

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