第5章学習環境とモデルを準備する

本章は初稿です。

本章の準備手順は公式資料を基にしています。Azure 資源の作成と SDK の実接続は、本教材では未検証です。

5.1 この章で学ぶこと

指示を書き始める前に、どこへ接続し、どのモデルを、誰の権限で使うかを決めます。接続先の誤り、認証の失敗、権限不足は、どれも「動かない」と見えますが、直す場所は異なります。

本章の到達点は、学習環境の構成表を埋め、次の章以降で利用する接続先と識別子を区別できることです。Azure を使わない場合も、同じ表を使って準備の関係を学べます。

5.2 準備するものの関係

図5-1 モデル、接続、権限、経路がそろって初めて呼び出せる。 矢印は準備の依存関係を表します。資源の配備順序を網羅した図ではありません。ネットワークの経路は第6章で詳しく学び、既存環境の設定を無断で変更しない前提で進めます。

準備するもの	記録する内容	避けること
学習環境	利用許可、費用の負担先、管理担当者	本番環境を練習用に変更する
Foundry プロジェクト	プロジェクト名とエンドポイント	別プロジェクトの設定を混ぜる
モデルのデプロイ	モデル、対応機能、デプロイの識別子	モデルの製品名を識別子と決めつける
呼び出し主体	認証方法と必要な操作権限	不明な権限不足を広い管理権限で回避する
開発環境	Python、SDK、関連パッケージの版	旧 API 世代のコードを混ぜる
ネットワーク	実行端末から接続できる経路	接続できない理由をすべて認証と考える

5.3 学習用プロジェクトとモデルを用意する

新しく資源を作る場合は、公式のリソース準備手順に従います。既存の学習環境を使う場合は、作成を繰り返さず、管理者に利用範囲を確認してください。公式手順は、プロジェクト、モデルのデプロイ、エージェント用のトレース接続を準備する流れを説明しています。[^resources]

最初は、テキストの Prompt エージェントと、後で扱う function calling に対応したモデルを一つ選びます。モデルやリージョンを固定した普遍的な推奨は置きません。自分の環境で利用できるか、必要な機能と容量があるかを確認します。

モデル名とデプロイ名は、画面上で同じ文字列になる場合もあります。それでも概念は別です。コードへ設定する値は、採用する API と公式例が要求するデプロイの識別子へ対応付けます。

5.4 エンドポイント、認証、認可を分ける

プロジェクトのエンドポイントは接続先です。公式クイックスタートの形式例は、https://<resource-name>.services.ai.azure.com/api/projects/<project-name> です。[^quickstart] 実際にはポータルで自分のプロジェクトの値を取得し、名前から推測して組み立てないようにします。

認証は「誰として呼ぶか」を確かめること、認可は「その主体に何を許すか」を決めることです。サインインできても、Agent の作成、モデルの利用、トレースの閲覧がすべて許されるとは限りません。

後の Python 例は DefaultAzureCredential を使います。これは利用可能な資格情報を探索するため、必ず想定した開発者アカウントになるとは限りません。[^credential-chains] 利用環境の認証方法を公式手順で確認し、環境変数などに別の主体の設定が残っていないかを確認します。資格情報そのものはログへ出しません。

5.5 SDK の例を読む準備をする

本教材の接続例は Python で示します。Azure へ接続しない学習では、コードの入力と出力を追うだけでも構いません。

参照した Prompt エージェントの公式手順は、Python で azure-ai-projects>=2.3.0 と、認証に使う azure-identity を利用しています。[^quickstart] インストール手順と対応する Python の版は、実施時の公式資料を確認してください。SDK の下限指定は、将来のすべての版で教材の例が動くことの保証ではありません。

実際に試す場合は、学習専用の作業ディレクトリと仮想環境を使い、解決されたパッケージの版を記録します。この文書リポジトリの依存パッケージへ、学習用 SDK を追加する必要はありません。

後の例で使う環境変数は次の三つです。PowerShell での設定例を示します。

powershell

$env:FOUNDRY_PROJECT_ENDPOINT = "ポータルで確認したプロジェクトのエンドポイント"
$env:FOUNDRY_MODEL_DEPLOYMENT = "利用するモデルのデプロイの識別子"
$env:FOUNDRY_AGENT_NAME = "自分専用の学習用エージェント名"

これらは値を置き換えるための例です。資格情報を設定する例ではありません。端末ごとの環境変数は、別のシェルや別のプロセスへ自動的に引き継がれるとは限らない点にも注意します。

5.6 小さな実習：構成表を完成させる

次の表を自分の環境で埋めます。机上学習の場合は、実際の値ではなく「どこから確認するか」を書きます。

項目	記録欄
プロジェクトと管理担当者	自分が利用してよい範囲
接続先	ポータルで確認したプロジェクトのエンドポイント
モデルとデプロイ	対応機能、リージョン、識別子
認証と必要な権限	呼び出し主体、Agent 作成・利用の許可
ネットワーク	公開接続か私設接続か、実行端末からの経路
トレース	Application Insights の接続と閲覧許可、記録する情報
実行環境	Python と SDK の版、参照した公式手順
費用と終了後の整理	予算、作成する資源、片付けを担当する人

トレースを閲覧するための権限は、Agent を呼び出す権限と別です。Application Insights の接続や閲覧許可が必要なことも、公式手順で確かめてください。[^resources]

5.7 確認課題

モデルの呼び出しが拒否されたとき、すぐにモデルを変更したり、管理者権限を付けたりしないでください。接続先、実際の呼び出し主体、対象操作の権限、ネットワーク制限のどこを確認するか説明します。

モデルの推論、検索、トレースの保存などには、それぞれ費用が発生し得ます。Cost Management の予算通知だけでは、資源の利用や消費は停止しません。[^budgets] 学習中の利用量を確認し、作成したものを記録します。片付けでは、共有モデルや共有プロジェクトを削除せず、自分が作成して削除を許可された対象だけを整理します。