Azure AI Foundry SDK を使用して評価をオンラインで実行する方法

[アーティクル]
01/31/2025

重要

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

この記事では、Azure AI Foundry SDK を使用して、継続的な形でオンラインの評価を実行する方法について説明します。運用環境での評価は、アプリケーションが安全に性能を発揮し、高品質の結果が得られるようにするために不可欠です。ただし、アプリケーションをデプロイした後は、評価を止めるということではありません。運用環境では、ユーザーがアプリケーションに送信してくるクエリの種類など、さまざまな変化が起きるので、これが、アプリケーションのパフォーマンスに影響を与える可能性があります。運用環境の生成 AI アプリケーションにおいて高度な可観測性を維持するには、アプリケーションのデータをトレースして、継続的に評価することが重要です。そうすることで、アプリケーションの安全性、品質、パフォーマンスに対する信頼を維持できます。

オンライン評価のしくみ

このセクションでは、オンライン評価のしくみ、これが Azure Monitor Application Insights とどのように統合されるのか、また、生成 AI アプリケーションからのトレースデータに対する継続的な評価のためにこれをどう使用するかについて、確認ししていきます。

Application Insights へのトレースデータの送信をアプリケーションに装備した後は、このデータを継続的に評価するためのオンライン評価スケジュールを設定します。オンライン評価は、Azure AI コンピューティングを使用して、構成可能なエバリュエータのセットを継続的に実行するサービスです。 Azure AI Foundry SDK でオンライン評価スケジュールを設定し終えると、評価はカスタマイズ可能なスケジュールで実行されます。スケジュールされたジョブが実行されるたびに、次の手順が実行されます。

指定された Kusto (KQL) クエリを使用して、接続されている Application Insights リソースからのアプリケーショントレースデータをクエリします。
トレースデータに対して各エバリュエータを実行し、各メトリック (たとえば、"groundedness: 3") を計算します。
標準化されたセマンティック規則を使用して、評価スコアを各トレースに書き戻します。

Note

オンライン評価では、Azure AI Evaluation と同じメトリックがサポートされています。評価のしくみとサポートされている評価メトリックの詳細については、「Azure AI Evaluation SDK を使用して生成 AI アプリケーションを評価する」を参照してください。

たとえば、あなたの手元には、毎日多くの顧客からの質問を受け取るデプロイ済みのチャットアプリケーションがあるとしましょう。あなたは、アプリケーションの応答の品質を継続的に評価したいと考えています。オンライン評価のスケジュールは、毎日の繰り返し頻度で設定します。あなたは、Groundedness、Coherence、Fluency というエバリュエータを構成します。サービスは、毎日これらのメトリックの評価スコアを計算し、繰り返しの時間枠 (この例では過去 24 時間) の中で収集された各トレースに対応するデータを Application Insights に書き戻します。その後、データは各トレースからクエリを実行して、Azure AI Foundry と Azure Monitor Application Insights 内でアクセスできるようになります。

Application Insights 内の各トレースに書き戻される評価結果は、以下の規則に従います。評価メトリックごとに、一意のスパンが各トレースに追加されます。

プロパティ	Application Insights テーブル	特定の operation_ID のフィールド	例値
評価メトリック	traces、AppTraces	`customDimensions[“event.name”]`	`gen_ai.evaluation.relevance`
評価メトリックスコア	traces、AppTraces	`customDimensions[“gen_ai.evaluation.score”]`	`3`
評価メトリックコメント (該当する場合)	traces、AppTraces	`message`	`{“comment”: “I like the response”}`

オンライン評価のしくみと、これがどのように Azure Monitor Application Insights へ接続するかを理解できたので、次のステップはサービスの設定です。

オンライン評価を設定する

このセクションでは、デプロイされた生成 AI アプリケーションを継続的に監視するようにオンライン評価スケジュールを構成する方法を説明します。このような機能は、Azure AI Foundry SDK が Python API を介し提供しており、ローカル評価で使用できるすべての機能がサポートされています。以下の手順により、組み込みまたはカスタムのエバリュエータを使用する、データのオンライン評価スケジュールを送信します。

Note

評価がサポートされているのは、AI 支援のリスクと安全性メトリックと同じリージョンにおいてだけです。

前提条件

環境と必要なリソースに対する認証を設定するには、以下の前提条件の手順を実行します。

Azure サブスクリプション。
評価がサポートされているリージョン内のリソースグループ。
同じリソースグループとリージョン内の新しいユーザー割り当てマネージド ID。 clientId をメモしておきます。これは後で必要になります。
同じリソースグループとリージョン内の Azure AI ハブ。
このハブ内の Azure AI プロジェクト。「Azure AI Foundry ポータルでのプロジェクトの作成」を参照してください。
Azure Monitor Application Insights リソース。
Azure portal でハブページに移動し、Application Insights リソースを追加します。「Azure Application Insights と Azure Container Registry の更新」を参照してください。
Azure OpenAI デプロイと、gpt-4 など、chat completion をサポートする GPT モデル。
Azure AI プロジェクトで Connection String オブジェクトを簡単に作成するための AIProjectClient。プロジェクトの [概要] ページの [プロジェクトの詳細] でプロジェクトの接続文字列を取得できます。
Azure portal で Application Insights リソースに移動し、[アクセス制御 (IAM)] タブを使用して、先ほど作成したユーザー割り当てマネージド ID に Log Analytics Contributor ロールを追加します。
ユーザー割り当てマネージド ID をプロジェクトにアタッチします。
Azure portal で Azure AI サービスに移動し、[アクセス制御 (IAM)] タブを使用して、先ほど作成したユーザー割り当てマネージド ID に Cognitive Services OpenAI Contributor ロールを追加します。

インストールの指示

ユーザー資格情報を使用して 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 仮想環境を終了し、必要に応じて、それを後で再アクティブ化できます。

また、conda を使用して新しい Python 環境を作成することもできます。

conda create -n online-evaluation
conda activate online-evaluation

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

pip install azure-identity azure-ai-projects azure-ai-ml

ヒント

コード内に組み込まれたエバリュエータのエバリュエータ ID をフェッチする、コードファーストなエクスペリエンスを希望する場合は、オプションとして pip install azure-ai-evaluation を使用することもできます。これを行う方法については、「エバリュエータライブラリからのエバリュエータの指定」を参照してください。

生成 AI アプリケーションのトレースを設定する

オンライン評価を設定する前に、まず生成型 AI アプリケーションのトレースの設定が済んでいることを確認します。

トレースデータでのサービス名の使用

Application Insights で一意の ID を通じてアプリケーションを特定するには、トレースデータ内でサービス名の OpenTelemetry プロパティを使用できます。これは、複数のアプリケーションから同じ Application Insights リソースにデータをログしており、それらを区別したい場合に特に便利です。たとえば、あなたの手元には、App-1 と App-2 という 2 つのアプリケーションがあり、同じ Application Insights リソースにデータをログするようにトレースが構成されているとしましょう。 App-1 が Relevance によって、App-2 が Groundedness によって継続的に評価されるように設定したい場合があるかもしれません。サービス名を使用することで、オンライン評価の構成内でアプリケーションを区別することができます。

サービス名プロパティを設定するには、こちらの手順 (「リソースが異なる複数のトレーサープロバイダーの使用」を参照) に従って、アプリケーションコード内で直接これを実行することができます。または、アプリをデプロイする前に環境変数 OTEL_SERVICE_NAME を設定することもできます。サービス名の使用の詳細については、「OTEL 環境変数」および「サービスリソースのセマンティック規則」を参照してください。

サービス名を使用して、生成 AI アプリケーション間を区別する方法の詳細については、トレースを参照してください。

Application Insights 内に保存されているトレースデータのクエリを実行する

Kusto 照会言語 (KQL) を使用すると、継続的なオンライン評価で使用するための生成 AI アプリケーションのトレースデータを、Application Insights からクエリすることができます。 Azure AI Tracing パッケージを使用して生成 AI アプリケーションをトレースするのであれば、次の Kusto クエリを使用できます。

重要

オンライン評価サービスで使用される KQL クエリは、operation_Id、operation_ParentId、および gen_ai_response_id の列を出力する必要があります。さらに、各エバリュエータにはそれ独自の入力データ要件があります。 KQL クエリは、エバリュエータ自体への入力として使用するために、これらの列を出力する必要があります。エバリュエータのデータ要件の一覧については、「組み込みエバリュエータのデータ要件」を参照してください。

let gen_ai_spans = (
    dependencies
    | where isnotnull(customDimensions["gen_ai.system"])
    | extend response_id = tostring(customDimensions["gen_ai.response.id"])
    | project id, operation_Id, operation_ParentId, timestamp, response_id
);
let gen_ai_events = (
    traces
    | where message in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
        or tostring(customDimensions["event.name"]) in ("gen_ai.choice", "gen_ai.user.message", "gen_ai.system.message")
    | project 
        id = operation_ParentId, 
        operation_Id, 
        operation_ParentId, 
        user_input = iff(
            message == "gen_ai.user.message" or tostring(customDimensions["event.name"]) == "gen_ai.user.message", 
            parse_json(iff(message == "gen_ai.user.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        system = iff(
            message == "gen_ai.system.message" or tostring(customDimensions["event.name"]) == "gen_ai.system.message", 
            parse_json(iff(message == "gen_ai.system.message", tostring(customDimensions["gen_ai.event.content"]), message)).content, 
            ""
        ), 
        llm_response = iff(
            message == "gen_ai.choice", 
            parse_json(tostring(parse_json(tostring(customDimensions["gen_ai.event.content"])).message)).content, 
            iff(tostring(customDimensions["event.name"]) == "gen_ai.choice", parse_json(parse_json(message).message).content, "")
        )
    | summarize 
        operation_ParentId = any(operation_ParentId), 
        Input = maxif(user_input, user_input != ""), 
        System = maxif(system, system != ""), 
        Output = maxif(llm_response, llm_response != "") 
    by operation_Id, id
);
gen_ai_spans
| join kind=inner (gen_ai_events) on id, operation_Id
| project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id

生成 AI アプリケーション内で、OTEL_SERVICE_NAME 環境変数を使用してサービス名を設定している場合は、Kusto (KQL) クエリに次の行を追加することで、オンライン評価スケジュール内で cloud_RoleName をクエリできます。

| where cloud_RoleName == "service_name"

必要に応じて、Kusto クエリで sample 演算子または take 演算子を使用することで、クエリがトレースのサブセットのみを返すようにすることができます。大規模な AI 支援の評価はコストがかかる可能性があるため、このアプローチは、データのランダムなサンプル (または n 個のトレース) のみを評価することによってコストを制御するのに役立ちます。

Azure AI Project SDK を使用してオンライン評価を設定する

Python API を介して Azure AI Project SDK を使用することで、オンライン評価のスケジュールされたジョブを送信することができます。パフォーマンスおよび品質 (AI 支援) エバリュエータを使用したオンライン評価の設定方法については、以下のスクリプトで確認できます。サポートされているエバリュエータの完全な一覧については、「Azure AI Evaluation SDK を使用した評価」を参照してください。カスタムエバリュエータの使用方法については、「カスタムエバリュエータ」を参照してください。

まずは、以下のように必要なパッケージをインポートし、必要な変数を構成します。

from azure.ai.projects import AIProjectClient 
from azure.identity import DefaultAzureCredential 
from azure.ai.projects.models import ( 
    ApplicationInsightsConfiguration,
    EvaluatorConfiguration,
    EvaluationSchedule,
    RecurrenceTrigger,
)
from azure.ai.evaluation import CoherenceEvaluator 

# This sample includes the setup for an online evaluation schedule using the Azure AI Project SDK and Azure AI Evaluation SDK
# The schedule is configured to run daily over the collected trace data while running two evaluators: CoherenceEvaluator and RelevanceEvaluator
# This sample can be modified to fit your application's requirements

# Name of your online evaluation schedule
SAMPLE_NAME = "online_eval_name"

# Connection string to your Azure AI Foundry project
# Currently, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
PROJECT_CONNECTION_STRING = "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"

# Your Application Insights resource ID
APPLICATION_INSIGHTS_RESOURCE_ID = "appinsights_resource_id"

# Kusto Query Language (KQL) query to query data from Application Insights resource
# This query is compatible with data logged by the Azure AI Inferencing Tracing SDK (linked in documentation)
# You can modify it depending on your data schema
# The KQL query must output these required columns: operation_ID, operation_ParentID, and gen_ai_response_id
# You can choose which other columns to output as required by the evaluators you are using
KUSTO_QUERY = "let gen_ai_spans=(dependencies | where isnotnull(customDimensions[\"gen_ai.system\"]) | extend response_id = tostring(customDimensions[\"gen_ai.response.id\"]) | project id, operation_Id, operation_ParentId, timestamp, response_id); let gen_ai_events=(traces | where message in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") or tostring(customDimensions[\"event.name\"]) in (\"gen_ai.choice\", \"gen_ai.user.message\", \"gen_ai.system.message\") | project id= operation_ParentId, operation_Id, operation_ParentId, user_input = iff(message == \"gen_ai.user.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.user.message\", parse_json(iff(message == \"gen_ai.user.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), system = iff(message == \"gen_ai.system.message\" or tostring(customDimensions[\"event.name\"]) == \"gen_ai.system.message\", parse_json(iff(message == \"gen_ai.system.message\", tostring(customDimensions[\"gen_ai.event.content\"]), message)).content, \"\"), llm_response = iff(message == \"gen_ai.choice\", parse_json(tostring(parse_json(tostring(customDimensions[\"gen_ai.event.content\"])).message)).content, iff(tostring(customDimensions[\"event.name\"]) == \"gen_ai.choice\", parse_json(parse_json(message).message).content, \"\")) | summarize operation_ParentId = any(operation_ParentId), Input = maxif(user_input, user_input != \"\"), System = maxif(system, system != \"\"), Output = maxif(llm_response, llm_response != \"\") by operation_Id, id); gen_ai_spans | join kind=inner (gen_ai_events) on id, operation_Id | project Input, System, Output, operation_Id, operation_ParentId, gen_ai_response_id = response_id"

次に、オンライン評価スケジュールの実行に使用するクライアントと Azure OpenAI GPT デプロイ (GPT-4 など) を定義します。また、Application Insights リソースへの接続も行います。

# Connect to your Azure AI Foundry Project
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=PROJECT_CONNECTION_STRING
)

# Connect to your Application Insights resource 
app_insights_config = ApplicationInsightsConfiguration(
    resource_id=APPLICATION_INSIGHTS_RESOURCE_ID,
    query=KUSTO_QUERY
)

# Connect to your Azure OpenAI Service resource. You must use a GPT model deployment for this example.
deployment_name = "gpt-4"
api_version = "2024-08-01-preview"

# This is your Azure OpenAI Service connection name, which can be found in your Azure AI Foundry project under the 'Models + Endpoints' tab.
default_connection = project_client.connections._get_connection(
    "aoai_connection_name"
)

model_config = {
    "azure_deployment": deployment_name,
    "api_version": api_version,
    "type": "azure_openai",
    "azure_endpoint": default_connection.properties["target"]
}

次に、以下のように使用したいエバリュエータを構成します。

# RelevanceEvaluator
# id for each evaluator can be found in your Azure AI Foundry registry - please see documentation for more information
# init_params is the configuration for the model to use to perform the evaluation
# data_mapping is used to map the output columns of your query to the names required by the evaluator
relevance_evaluator_config = EvaluatorConfiguration(
    id="azureml://registries/azureml-staging/models/Relevance-Evaluator/versions/4",
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

# CoherenceEvaluator
coherence_evaluator_config = EvaluatorConfiguration(
    id=CoherenceEvaluator.id,
    init_params={"model_config": model_config},
    data_mapping={"query": "${data.Input}", "response": "${data.Output}"}
)

最後に、以下のように繰り返しを定義し、スケジュールを作成します。

注: Application Insights リソースに対してオンライン評価スケジュールを認証するためのユーザー割り当てマネージド ID は、前提条件の手順において作成済みです。 EvaluationSchedule クラスの properties パラメーターの AzureMSIClientId は、この ID の clientId です。

# Frequency to run the schedule
recurrence_trigger = RecurrenceTrigger(frequency="day", interval=1)

# Dictionary of evaluators
evaluators = {
    "relevance": relevance_evaluator_config,
    "coherence" : coherence_evaluator_config
}

name = SAMPLE_NAME
description = f"{SAMPLE_NAME} description"
# AzureMSIClientId is the clientID of the User-assigned managed identity created during set-up - see documentation for how to find it
properties = {"AzureMSIClientId": "your_client_id"}

# Configure the online evaluation schedule
evaluation_schedule = EvaluationSchedule(
    data=app_insights_config,
    evaluators=evaluators,
    trigger=recurrence_trigger,
    description=description,
    properties=properties)

# Create the online evaluation schedule 
created_evaluation_schedule = project_client.evaluations.create_or_replace_schedule(name, evaluation_schedule)
print(f"Successfully submitted the online evaluation schedule creation request - {created_evaluation_schedule.name}, currently in {created_evaluation_schedule.provisioning_state} state.")

オンライン評価スケジュールに関する操作を実行する

オンライン評価の構成スクリプトに次のコードを追加することで、オンライン評価スケジュールの取得、一覧表示、無効化を行うことができます。

警告: オンライン評価スケジュールの作成と get_schedule() API の実行の間には、短い待機時間 (約 30 秒以内) を設けてください。

オンライン評価スケジュールを取得します。

name = "<my-online-evaluation-name>"
get_evaluation_schedule = project_client.evaluations.get_schedule(name)

すべてのオンライン評価スケジュールを一覧表示します。

count = 0
for evaluation_schedule in project_client.evaluations.list_schedule():
    count += 1
        print(f"{count}. {evaluation_schedule.name} "
        f"[IsEnabled: {evaluation_schedule.is_enabled}]")
        print(f"Total evaluation schedules: {count}")

オンライン評価スケジュールを無効化 (論理的に削除) します。

name = "<my-online-evaluation-name>"
project_client.evaluations.disable_schedule(name)

次の方法で共有

Azure AI Foundry SDK を使用して評価をオンラインで実行する方法

オンライン評価のしくみ

オンライン評価を設定する

前提条件

インストールの指示

新しい Python 環境を作成する

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

仮想環境を作成する

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

生成 AI アプリケーションのトレースを設定する

トレースデータでのサービス名の使用

Application Insights 内に保存されているトレースデータのクエリを実行する

Azure AI Project SDK を使用してオンライン評価を設定する

オンライン評価スケジュールに関する操作を実行する

フィードバック

その他のリソース

次の方法で共有

Azure AI Foundry SDK を使用して評価をオンラインで実行する方法

オンライン評価のしくみ

オンライン評価を設定する

前提条件

インストールの指示

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

新しい Python 環境を作成する

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

仮想環境を作成する

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

生成 AI アプリケーションのトレースを設定する

トレース データでのサービス名の使用

Application Insights 内に保存されているトレース データのクエリを実行する

Azure AI Project SDK を使用してオンライン評価を設定する

オンライン評価スケジュールに関する操作を実行する

関連するコンテンツ

フィードバック

その他のリソース

トレースデータでのサービス名の使用

Application Insights 内に保存されているトレースデータのクエリを実行する