Azure AI Foundry SDK を使用して AI エージェントをトレースする (プレビュー)

この記事では、監視とデバッグを強化するために、OpenTelemetry と Azure Monitor を使用して Azure AI Foundry SDK を使用してエージェントのトレースをインストルメント化する方法について説明します。

作業を開始する前の主要な概念の概要を次に示します。

設定

Azure AI Foundry を使用してチャットの完了またはエージェントを構築する場合は、次をインストールします。

pip install azure-ai-projects azure-identity

トレースをインストルメント化するには、次のインストルメンテーション ライブラリをインストールする必要があります。

pip install azure-monitor-opentelemetry opentelemetry-sdk

Azure AI Foundry でトレースを表示するには、Application Insights リソースを Azure AI Foundry プロジェクトに接続する必要があります。

1. Azure AI Foundry ポータルの左側のナビゲーション ウィンドウで[ トレース ]に移動します。
2. まだお持ちでない場合は、新しい Application Insights リソースを作成します。
3. リソースを AI Foundry プロジェクトに接続します。

コードでトレースをインストルメント化する

チャット メッセージの内容をトレースするには、 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 環境変数を true に設定します (大文字と小文字は区別されません)。 これには個人データが含まれている可能性があることに注意してください。 詳細については、Python 用 Azure Core Tracing OpenTelemetry クライアント ライブラリに関するページを参照してください。

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

AIProjectClientを使用した Azure AI プロジェクトの認証と接続から始めて、OpenTelemetry トレースを使用してエージェントのインストルメント化を開始しましょう。

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

次に、プロジェクトに接続されている Application Insights リソースから接続文字列を取得し、テレメトリを Azure Monitor に送信するように OTLP エクスポーターを設定します。

from azure.monitor.opentelemetry import configure_azure_monitor
connection_string = project_client.telemetry.get_connection_string()

if not connection_string:
    print("Application Insights is not enabled. Enable by going to Tracing in your Azure AI Foundry project.")
    exit()

configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

次に、Azure AI プロジェクトでエージェントとユーザー メッセージを作成して実行するコードをトレースして、トラブルシューティングまたは監視の詳細な手順を確認できます。

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

エージェントを実行したら、 Azure AI Foundry ポータルでトレースの表示を開始できます。

トレースをローカルでログに記録する

アスパイア ダッシュボードまたは別の OpenTelemetry 互換バックエンドに接続するには、OpenTelemetry Protocol (OTLP) エクスポーターをインストールします。 これにより、トレースをコンソールに出力したり、アスパイア ダッシュボードなどのローカル ビューアーを使用したりできます。

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

次に、アプリケーションのトレースを構成します。

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

enable_telemetryを使用してテレメトリの収集を開始します。

from azure.ai.projects import enable_telemetry
enable_telemetry(destination=sys.stdout)

# Logging to an OTLP endpoint, change the destination to
# enable_telemetry(destination="http://localhost:4317")

# Start tracing
from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.create_run(thread_id=thread.id, agent_id=agent.id)

カスタム関数をトレースする

カスタム関数をトレースするには、OpenTelemetry SDK を使用してコードをインストルメント化します。

1. トレーサー プロバイダーを設定する: スパンを管理および作成するためにトレーサー プロバイダーを初期化します。
2. スパンを作成する: トレースするコードをスパンでラップします。 各スパンは作業単位を表し、入れ子にしてトレース ツリーを形成できます。
3. 属性の追加: トレース データのコンテキストを増やすために、属性を使用してスパンを強化します。
4. エクスポーターを構成する: 分析と視覚化のためにバックエンドにトレース データを送信します。

カスタム関数のトレースの例を次に示します。

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

詳細な手順と高度な使用方法については、OpenTelemetry のドキュメントを参照してください。

トレースにユーザー フィードバックを添付する

Azure AI Foundry ポータルでユーザー フィードバックをトレースにアタッチして視覚化するには、OpenTelemetry のセマンティック規則を使用して、アプリケーションをインストルメント化して、トレースとログ ユーザー フィードバックを有効にすることができます。

応答 ID またはスレッド ID を使用して、フィードバック トレースをそれぞれのチャット要求トレースと関連付けることで、Azure AI Foundry ポータルでこれらのトレースを表示および管理できます。 OpenTelemetry の仕様により、標準化され、エンリッチされたトレース データが使用でき、それを Azure AI Foundry ポータルで分析してパフォーマンスを最適化し、ユーザー エクスペリエンス分析情報を得ることができます。 このアプローチは、OpenTelemetry を最大限に活用して、アプリケーションの監視を強化するのに役立ちます。

ユーザーフィードバックをログに記録するには、次の形式に従います。

ユーザーが GenAI モデルの応答に対する反応を提供した場合にのみ、ユーザー フィードバック評価イベントをキャプチャできます。 可能な場合は、そのような応答を記述する GenAI スパンの親になる必要があります。

ユーザー フィードバック イベント本文には、次の構造があります。

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

Application Insights で一意の ID を使用してサービスを特定するには、トレース データ内のサービス名 OpenTelemetry プロパティを使用できます。 これは、複数のアプリケーションから同じ Application Insights リソースにデータをログに記録していて、それらを区別する場合に便利です。

たとえば、 App-1 と App-2 という 2 つのアプリケーションがあり、同じ Application Insights リソースにデータをログ記録するようにトレースが構成されているとします。 関連性によって継続的に評価されるように App-1 を設定し、関連性によって継続的に評価されるように App-2 を設定したい場合があります。 サービス名を使用して、AI Foundry Portal でアプリケーションを監視するときに Application でフィルター処理できます。

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

特定のサービス名のトレース データのクエリを実行するには、cloud_roleName プロパティのクエリを実行します。

| where cloud_RoleName == "service_name"

Langchain のトレースを有効にする

OpenTelemetry-instrumentation-langchain に従って、OpenTelemetry 標準に従う Langchain のトレースを有効にすることができます。 Langchain のトレースを有効にするには、pip のようにパッケージ マネージャーを使用してパッケージ opentelemetry-instrumentation-langchain をインストールします。

pip install opentelemetry-instrumentation-langchain

必要なパッケージがインストールされたら、コードでトレースのインストルメント化を簡単に開始できます。

Azure AI Foundry ポータルでトレースを表示する

プロジェクトで、 Tracing に移動して、必要に応じてトレースをフィルター処理します。

トレースを選択すると、アプリケーションの応答を観察しながら、各スパンをステップ実行し、問題を特定できます。 これは、アプリケーションの問題をデバッグして特定するのに役立ちます。

Azure Monitor でトレースを表示する

前述のコード スニペットを使用してトレースをログした場合は、すべて Azure Monitor Application Insights でトレースを表示するように設定されています。 [データ ソースの管理] から Application Insights で開き [エンドツーエンドのトランザクションの詳細ビュー] を使用してさらに調査できます。

Azure AI 推論トレースを Azure Monitor に送信し、Azure Monitor リソースを作成する方法の詳細については、Azure Monitor OpenTelemetry のドキュメントを参照してください。

関連コンテンツ

• Python サンプルには、同期および非同期クライアントを使用してトレースするための完全に実行可能な Python コードが含まれています。
• コンソール トレースを使用したサンプル エージェント
• Azure Monitor を使用したサンプル エージェント
• JavaScript サンプルには、同期および非同期クライアントを使用してトレースするための完全に実行可能な JavaScript コードが含まれています。
• C# サンプルには、同期および非同期メソッドを使用して推論を実行するための完全に実行可能な C# コードが含まれています。