チュートリアル: Semantic Kernel と Azure Container Apps でコード インタープリター セッションを使用する

Semantic Kernel は、Microsoft が大規模言語モデル (LLM) を使用する .NET、Python、Java 開発者向けに作成されたオープンソースの AI フレームワークです。 Semantic Kernel を使用して AI エージェントを構築すると、LLM はユーザー入力を解釈し、応答を生成します。 応答を生成するために数学的推論や象徴的推論を実行する必要がある場合、AI エージェントは往々にして苦戦します。 Azure Container Apps の動的セッションを Semantic Kernel と統合することで、特化したタスクの実行に使用できるコード インタープリターがエージェントに提供されます。

このチュートリアルでは、Web API で Semantic Kernel AI エージェントを実行する方法について説明します。 API はユーザー入力を受け付け、AI エージェントによって生成された応答を返します。 エージェントは、動的セッションでコード インタープリターを使用して計算を実行します。

Note

Azure Container Apps の動的セッションは現在プレビューの段階です。 詳細については、「プレビューの制限事項」を参照してください。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。
  • 持っていない場合は、無料で作成できます。
• Azure CLI をインストールします。
• Git.
• Python 3.10 以降。

Azure リソースを作成する

このクイック スタートのサンプル アプリでは、Azure OpenAI の LLM を使用します。 また、Azure Container Apps セッションを使用して、LLM によって生成されたコードを実行します。

1. Azure CLI を最新バージョンに更新します。

    az upgrade
   

2. Azure Container Apps 拡張機能が既にインストールされている場合はそれを削除し、セッション用のコマンドを含むプレビュー バージョンの Azure Container Apps 拡張機能をインストールします。

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Azure にサインインします。

   az login
   

4. このクイック スタートで使用する変数を設定します。

   RESOURCE_GROUP_NAME=aca-sessions-tutorial
   AZURE_OPENAI_LOCATION=swedencentral
   AZURE_OPENAI_NAME=<UNIQUE_OPEN_AI_NAME>
   SESSION_POOL_LOCATION=eastasia
   SESSION_POOL_NAME=code-interpreter-pool
   

   <UNIQUE_OPEN_AI_NAME> を一意の名前に置き換えて、Azure OpenAI アカウントを作成します。

5. リソース グループを作成します。

   az group create --name $RESOURCE_GROUP_NAME --location $SESSION_POOL_LOCATION
   

6. Azure OpenAI アカウントを作成します。

   az cognitiveservices account create \
       --name $AZURE_OPENAI_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $AZURE_OPENAI_LOCATION \
       --kind OpenAI \
       --sku s0 \
       --custom-domain $AZURE_OPENAI_NAME
   

7. Azure OpenAI アカウントで gpt-35-turbo という名前の GPT 3.5 Turbo モデル デプロイを作成します。

   az cognitiveservices account deployment create \
       --resource-group $RESOURCE_GROUP_NAME \
       --name $AZURE_OPENAI_NAME \
       --deployment-name gpt-35-turbo \
       --model-name gpt-35-turbo \
       --model-version "1106" \
       --model-format OpenAI \
       --sku-capacity "100" \
       --sku-name "Standard"
   

8. コード インタープリターのセッション プールを作成します。

   az containerapp sessionpool create \
       --name $SESSION_POOL_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --max-sessions 100 \
       --container-type PythonLTS \
       --cooldown-period 300
   

サンプル アプリをローカルで実行する

アプリを Azure Container Apps にデプロイする前に、ローカルで実行してテストすることができます。

アプリを複製する

1. Azure Container Apps セッション サンプル リポジトリを複製します。

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. サンプル アプリが含まれているディレクトリに移動します。

   cd container-apps-dynamic-sessions-samples/semantic-kernel-python-webapi
   

Configure the app

1. Python 仮想環境を作成し、アクティブ化します。

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

   別の Python バージョンを使用している場合は、コマンドの Python バージョンを変更します。 Python 3.10 以降を使用することをお勧めします。

   Note

   Windows を使用している場合は、.venv/bin/activate を .venv\Scripts\activate に置き換えます。

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

   python -m pip install -r requirements.txt
   

3. アプリを実行するには、環境変数を構成する必要があります。

   1. Azure OpenAI アカウント エンドポイントを取得します。

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.endpoint \
          --output tsv
      

   2. Azure Container Apps セッション プール管理エンドポイントを取得します。

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.poolManagementEndpoint \
          --output tsv
      

   3. サンプル アプリ ディレクトリのルート (main.py と同じ場所) に .env ファイルを作成します。 次の内容をファイルに追加します。

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      <AZURE_OPENAI_ENDPOINT> を Azure OpenAI アカウント エンドポイントに置き換え、<SESSION_POOL_MANAGEMENT_ENDPOINT> をセッション プール管理エンドポイントに置き換えます。

4. アプリは、Azure サービスへの認証に DefaultAzureCredential を使用します。 ローカル コンピューターでは、現在の Azure CLI ログイン資格情報が使用されます。 アプリがモデル エンドポイントにアクセスするには、Azure OpenAI アカウントの Cognitive Services OpenAI ユーザー ロールを自分自身に付与し、アプリがセッション プールにアクセスするには、セッション プールの Azure ContainerApps Session Executor ロールを自分自身に付与する必要があります。

   1. Azure CLI ユーザー名を取得します。

      az account show --query user.name --output tsv
      

   2. 次のコマンドを実行して、Azure OpenAI アカウントのリソース ID を取得します。

      az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   3. Azure OpenAI アカウントの Azure CLI ユーザーに Cognitive Services OpenAI ユーザー ロールを割り当てます。

      az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
      

      <CLI_USERNAME> を Azure CLI のユーザー名に置き換え、<AZURE_OPENAI_RESOURCE_ID> を Azure OpenAI アカウントのリソース ID に置き換えます。

   4. 次のコマンドを実行して、セッション プールのリソース ID を取得します。

      az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   5. その ID を使用して、Azure ContainerApps Session Executor ロールをセッション プールの Azure CLI ユーザーに割り当てます。

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      <CLI_USERNAME> を Azure CLI のユーザー名に置き換え、<SESSION_POOL_RESOURCE_ID> をセッション プールのリソース ID に置き換えます。

アプリを実行する

サンプル アプリを実行する前に、エディターで main.py を開き、コードを確認します。 アプリは FastAPI を使用して、クエリ文字列でユーザー メッセージを受け付ける Web API を作成します。

次のコード行は、SessionsPythonTool をインスタンス化し、Semantic Kernel エージェントに提供します。

sessions_tool = SessionsPythonTool(
    pool_management_endpoint,
    auth_callback=auth_callback_factory("https://dynamicsessions.io/.default"),
)
kernel.add_plugin(sessions_tool, "SessionsTool")

計算を実行する必要がある場合、カーネルは SessionsPythonTool 内のコード インタープリターを使用してコードを実行します。 このコードは、セッション プール内のセッションで実行されます。 既定では、ツールをインスタンス化するときにランダムなセッション識別子が生成されます。 カーネルは、このツールを使用して複数の Python コード スニペットを実行する場合、同じセッションを使用します。 各エンド ユーザーが確実に一意のセッションを持つようにするために、ユーザーごとに個別のカーネルとツールを使用します。

SessionsPythonTool は、semantic-kernel パッケージのバージョン 0.9.8b1 以降で使用できます。

1. サンプル アプリを実行します。

   fastapi dev main.py
   

2. ブラウザーを開き、 http://localhost:8000/docs に移動します。 サンプル アプリの Swagger UI が表示されます。

3. /chat エンドポイントを展開して、[試してみる] を選択します。

4. message フィールドに「What time is it right now?」と入力し、[実行] を選択します。

   エージェントは現在の時刻を応答で返します。 ターミナルには、エージェントが現在の時刻を取得するための Python コードを生成し、そのコードをコード インタープリター セッションで実行したことを示すログが表示されます。

5. アプリを停止するには、ターミナルに「Ctrl+C」と入力します。

オプション: サンプル アプリを Azure Container Apps にデプロイする

FastAPI アプリを Azure Container Apps にデプロイするには、コンテナー イメージを作成し、それをコンテナー レジストリにプッシュする必要があります。 その後、イメージを Azure Container Apps にデプロイできます。 az containerapp up コマンドは、これらの手順を 1 つのコマンドに結合します。

その後、アプリのマネージド ID を構成し、そのマネージド ID に Azure OpenAI とセッション プールにアクセスするための適切なロールを割り当てる必要があります。

1. Container Apps 環境とアプリ名の変数を設定します。

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. アプリをビルドして Azure Container Apps にデプロイします。

   az containerapp up \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --environment $ENVIRONMENT_NAME \
       --env-vars "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>" \
       --source .
   

   <OPEN_AI_ENDPOINT> を Azure OpenAI アカウント エンドポイントに置き換え、<SESSION_POOL_MANAGMENT_ENDPOINT> をセッション プール管理エンドポイントに置き換えます。

3. アプリのシステム割り当てマネージド ID を有効にします。

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

4. アプリが Azure OpenAI とセッション プールにアクセスするには、マネージド ID に適切なロールを割り当てる必要があります。

   1. マネージド ID のプリンシパル ID を取得します。

      az containerapp show \
          --name $CONTAINER_APP_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query identity.principalId \
          --output tsv
      

   2. セッション プールのリソース ID を取得します。

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   3. マネージド ID にセッション プールの Azure ContainerApps Session Executor ロールと Contributor ロールを割り当てます。

      次のコマンドを実行する前に、<PRINCIPAL_ID> と <SESSION_POOL_RESOURCE_ID> を前の手順で取得した値に置き換えます。

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      
      az role assignment create \
          --role "Contributor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

   4. Azure OpenAI アカウントのリソース ID を取得します。

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   5. マネージド ID に Azure OpenAI アカウントの Cognitive Services OpenAI User ロールを割り当てます。

      次のコマンドを実行する前に、<PRINCIPAL_ID> と <AZURE_OPENAI_RESOURCE_ID> を前の手順で取得した値に置き換えます。

      az role assignment create \
          --role "Cognitive Services OpenAI User" \
          --assignee <PRINCIPAL_ID> \
          --scope <AZURE_OPENAI_RESOURCE_ID>
      

5. アプリの完全修飾ドメイン名 (FQDN) を取得します。

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. ブラウザーを開いて https://<FQDN>/docs にアクセスし、デプロイされたアプリをテストします。

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

リソースを使い終えたら、料金が発生しないようにそれらのリソースを削除することができます。

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

次のステップ

コード インタープリター セッション