Azure AI 推論 SDK を使用してアプリケーションをトレースする方法

重要

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

この記事では、Python、JavaScript、または C# のいずれかを選択して、Azure AI 推論 SDK でアプリケーションをトレースする方法について説明します。 Azure AI 推論クライアント ライブラリは、OpenTelemetry を使用したトレースのサポートを提供します。

アプリケーションでトレースを有効にする

前提条件

• Azure サブスクリプション。
• Azure AI プロジェクト。「Azure AI Foundry ポータルでプロジェクトを作成する」を参照してください。
• Azure AI モデル推論 API をサポートする AI モデルが Azure AI Foundry を介してデプロイされていること。
• Python を使用している場合は、pip を含む Python 3.8 以降がインストールされている必要があります。
• JavaScript を使用している場合は、サポートされる環境は Node.js の LTS バージョンです。

インストール

Python

pip のように、パッケージ マネージャーを使用してパッケージ azure-ai-inference をインストールします。

  pip install azure-ai-inference[opentelemetry] 

監視バックエンドにテレメトリを送信するための Azure Core OpenTelemetry Tracing プラグイン、OpenTelemetry、OTLP エクスポーターをインストールします。 Python に必要なパッケージをインストールするには、次の pip コマンドを使用します。

pip install opentelemetry 

pip install opentelemetry-exporter-otlp 

Python 用 Azure AI 推論 SDK と監視の詳細については、Python 用推論 SDK を使用したトレースに関するページを参照してください。

JavaScript

npm を使用して JavaScript 用のパッケージ @azure-rest/ai-inference をインストールします。

    npm install @azure-rest/ai-inference

JavaScript 用 Azure AI 推論 SDK と監視の詳細については、JavaScript 用推論 SDK を使用したトレースに関するページを参照してください。

C#

NuGet を使って、.NET 用 Azure AI 推論クライアント ライブラリをインストールします。

    dotnet add package Azure.AI.Inference --prerelease

C# 用 Azure AI 推論 SDK と監視の詳細については、C# 用推論 SDK を使用したトレースに関するページを参照してください。

詳細については、推論 SDK リファレンスを参照してください。

構成

Python

ユース ケースに従って、次の構成設定を追加する必要があります。

• プロンプトと完了の内容をキャプチャするには、AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 環境変数を true に設定します (大文字と小文字は区別されません)。 既定では、プロンプト、入力候補、関数名、パラメーター、または出力は記録されません。

• Azure SDK トレースを有効にするには、AZURE_SDK_TRACING_IMPLEMENTATION 環境変数を opentelemetry に設定します。 または、次のスニペットを使用してコード内で構成することもできます。

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

  詳細については、Python 用 Azure Core Tracing OpenTelemetry クライアント ライブラリに関するページを参照してください。

JavaScript

インストルメンテーションは、ストリーミングなしのチャット入力候補でのみサポートされます。 インストルメンテーションを有効にするには、エクスポーターを登録する必要があります。 コンソール エクスポーターを追加する方法の例を次に示します。

コンソール エクスポーター:

import { ConsoleSpanExporter, NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node"; 

const provider = new NodeTracerProvider(); 

provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); 

provider.register(); 

C#

OpenTelemetry を使用した分散トレースとメトリックは、実験モードの Azure AI 推論でサポートされており、次のいずれかの手順で有効にすることができます。

• AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE 環境変数を true に設定する。
• アプリケーション コードで、Azure.Experimental.EnableActivitySource コンテキストスイッチを true に設定する。

インストルメンテーションを有効にする

Python

最後の手順は、次のコード スニペットを使用して Azure AI 推論インストルメンテーションを有効にすることです。

from azure.ai.inference.tracing import AIInferenceInstrumentor 

# Instrument AI Inference API 

AIInferenceInstrumentor().instrument() 

また、インストルメントを無効化する呼び出しを使用して、Azure AI 推論 API のインストルメントを無効にすることも可能です。 この呼び出しの後、インストルメントが再度呼び出されるまで、トレースは Azure AI 推論 API で出力されなくなります。

AIInferenceInstrumentor().uninstrument() 

JavaScript

Azure SDK のインストルメンテーションを使用するには、@azure/core-tracing から @azure-rest/ai-inference などの依存関係をインポートする前にインストルメンテーションを登録する必要があります。

import { registerInstrumentations } from "@opentelemetry/instrumentation"; 

import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk"; 


registerInstrumentations({ 

  instrumentations: [createAzureSdkInstrumentation()], 

}); 

import ModelClient from "@azure-rest/ai-inference"; 

チャット入力候補の呼び出しを行うときは、アクティブなトレース コンテキストに tracingOptions を含める必要があります。

import { context } from "@opentelemetry/api"; 

client.path("/chat/completions").post({ 

      body: {...}, 

      tracingOptions: { tracingContext: context.active() } 

}); 

C#

OpenTelemetry を構成し、Azure AI 推論トレースを有効にするには、次の手順に従います。

1. OpenTelemetry パッケージをインストールする: HTTP トレースとメトリックのインストルメンテーションおよび、コンソールと OTLP エクスポーター用に次の依存関係をインストールします。

      dotnet add package OpenTelemetry.Instrumentation.Http 
   
      dotnet add package OpenTelemetry.Exporter.Console 
   
      dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol 
   

2. 実験用 Azure SDK の監視を有効にする: 実験用 Azure SDK の監視を有効にするようにコンテキスト スイッチを設定します。

      AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); 
   

3. コンテンツの記録を有効にする: 既定では、インストルメンテーションはコンテンツなしでチャット メッセージをキャプチャします。 コンテンツの記録を有効にするには、次のコンテキスト スイッチを設定します。

    AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);
   

4. トレーサー プロバイダーの構成: トレースとメトリックをコンソールとローカル OTLP の宛先に必要に応じてエクスポートするように、トレーサー プロバイダーを構成します。

独自の関数のトレース

独自のカスタム関数をトレースするには、OpenTelemetry を利用できます。OpenTelemetry SDK を使用してコードをインストルメント化する必要があります。 これには、トレーサー プロバイダーの設定と、トレースするコードのスパンの作成が含まれます。 各スパンは作業単位を表し、入れ子にしてトレース ツリーを形成できます。 スパンに属性を追加して、追加のコンテキストでトレース データをエンリッチすることができます。 インストルメント化されたら、分析と視覚化のためにトレース データをバックエンドに送信するようにエクスポーターを構成します。 詳細な手順と高度な使用方法については、OpenTelemetry のドキュメントを参照してください。 これにより、カスタム関数のパフォーマンスを監視し、その実行に関する分析情報を得ることができます。

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

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

関連するコンテンツ

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