プロンプト フロー SDK を使用してアプリケーションをトレースする方法 | Azure AI Studio
重要
この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
トレースは、エージェント、AutoGen、取得拡張生成 (RAG) ユース ケースなどの生成 AI アプリケーションの実行プロセスを開発者が深く理解できるようにする強力なツールです。 アプリケーション内の各ノードの入力と出力など、実行フローの詳細なビューが提供されます。 この基本的な情報は、複雑なアプリケーションのデバッグやパフォーマンスの最適化を行う際に重要です。
より多くの開発者が、Langchain、Semantic Kernel、OpenAI、各種のエージェントなどのさまざまなフレームワークを使用して LLM ベースのアプリケーションを作成しています。 プロンプト フロー SDK を使用したトレースでは、LLM ベースのアプリケーションの可視性が向上し、トラブルシューティングが簡素化され、開発、イテレーション、運用の監視を効果的にサポートできます。 AI Studio でのトレースは OpenTelemetry 仕様に従い、任意の AI アプリケーションの内部実行の詳細をキャプチャして視覚化し、全体的な開発エクスペリエンスを向上します。
エンタープライズ レベルのクラウド プラットフォームでの AI Studio トレースの利点
さらに、エンタープライズ レベルのクラウド プラットフォームである AI Studio で永続的なローカル テストを提供し、コラボレーション、永続化、テスト履歴管理を大幅に強化しました。
トレースを使用すると、次のことができます。
- 履歴テストを保持して追跡するためのクラウドベースの場所を設定します。
- テスト結果を簡単に抽出して視覚化し、さまざまなテスト ケースの出力を比較します。
- 人間のフィードバック、データ キュレーションなど、後で使用するために以前のテスト資産を再利用します。
- 将来のリソース使用率の向上を促進します。
- アプリケーションを簡単にデバッグして最適化します。 LLM アプリケーション シナリオのデバッグを開始するには、LLM アプリケーションを使用したトレースの説明を参照してください。
- RAG アプリケーションでの取得プロセスと生成プロセスを分析します。
- マルチエージェントのシナリオでマルチエージェントの相互作用を観察します。 マルチエージェント シナリオでのトレースの概要については、AutoGen を使用したトレースの説明を参照してください。
アプリケーションのトレースをログに記録して表示する
AI Studio には、トレース ビューをドリルダウンしてデバッグおよび監視しながら、LLM アプリケーションのテストと評価をログに記録し管理するためのトレース機能が用意されています。
現在のアプリケーション機能のトレースは、プロンプト フローのオープンソース パッケージに実装され、OpenTelemetry 仕様に従って、使用するフレームワークに関係なく、ユーザーが LLM 呼び出しまたは関数、および LangChain や AutoGen などの LLM フレームワークをトレースできるようにします。
アプリケーションでトレースを有効にする
コード優先 - プロンプト フローでトレースするためにコードに注釈が付いていることを確認します。
- プロンプト フローのインストール: promptflow-tracing が必要です
- アプリケーション コードのインストルメント化:
@traceとstart_trace()を使用します。 - ローカルでのトレースのテストと表示
プロンプト フローでのトレースの詳細については、このプロンプト フローのドキュメントを参照してください。
トレースを AI Studio に記録する
トレース先を設定する
既定では、トレースはログに記録され、ローカル環境で表示されます。 クラウドの AI Studio でログに記録するには、trace destination を指定した AI Studio プロジェクトに設定する必要があります。
次の手順を参照して、トレース先を AI Studio プロジェクトに設定できます。
まず、Azure CLI がインストールされ、ログイン済みであることを確認します。
az login
次のコマンドを実行してトレース先を設定します。 <your_subscription_id>、<your_resourcegroup_name>、<your_studio_project_name> を、特定のサブスクリプション ID、リソース グループ名、AI Studio プロジェクト名に置き換えます。
pf config set trace.destination=azureml://subscriptions/<your_subscription_id>/resourcegroups/<your_resourcegroup_name>/providers/Microsoft.MachineLearningServices/workspaces/<your_studio_project_name>
Note
米国西部 3 (westus3) リージョンはトレースをサポートしていません。
コレクション
コレクションは、関連付けられたトレースのグループです。 AI Studio では、これらのコレクションとその内部トレースが管理され、[コレクション] タブの [トレース] モジュールに格納されます。
AI Studio でプロジェクトに移動します。
左側のウィンドウで、[トレース] を選択します。 [コレクション] タブが表示されます。コレクションの一覧には、独自のコレクションのみが表示されます。 この例では、コレクションはまだありません。
[コレクション] タブには、作成したすべてのコレクションの包括的な一覧が表示されます。 名前、実行場所、最終更新時刻、作成時刻など、各コレクションの重要なメタデータが表示されます。
- 実行場所: アプリケーションがローカルで実行されるか、クラウドで実行されるかを示します。 クラウド コレクションは、特定のプロンプト フロー クラウド作成テスト履歴と生成されたトレースに関連付けられています。 この場合、コレクション名はプロンプト フローの表示名と同じです。
- 更新日: 新しいトレースがコレクションに記録された最新の時刻を表示します。 既定では、コレクションは更新された時刻に基づいて降順に並べ替えられます。
- 作成日: コレクションが最初に作成された時刻。
コレクションの名前を選択すると、そのコレクション内のすべてのトレースの一覧にアクセスできます。 トレースのサブセットのみを他のユーザーと共有できます。 詳細については、共有トレースの説明を参照してください。
トレースをログに記録するときは、コレクション名を指定して、他の関連トレースとグループ化することができます。 トレースをより適切に編成するために、複数のコレクションを作成できます。 トレースのログ記録時にコレクション名が指定されていない場合、既定ではプロジェクト フォルダー名または既定のコレクションが使用されます。
コレクションをカスタマイズする
トレースをより適切に編成するために、トレースのログ記録時にカスタム コレクション名を指定できます。
独自のアプリケーションをトレースしている場合は、コード内の start_trace() 関数でコレクション名を設定できます。
from promptflow.tracing import start_trace, trace
@trace
def my_function(input: str) -> str:
output = input + "Hello World!"
return output
my_function("This is my function")
start_trace(collection="my_custom_collection")
コレクションのカスタマイズの詳細については、トレースのチュートリアルとプロンプト フロー コマンドの説明を参照してください。
トレースを表示する
まず、前の手順を完了して、クラウド内のトレースを表示する必要があります。
次に、Python スクリプトを直接実行します。 正常に実行されると、クラウド トレース リンクが出力に表示されます。 次のように表示されます。
Starting prompt flow service...
...
You can view the traces in cloud from AI Studio: https://ai.azure.com/projecttrace/detail/....
URL を選択して、クラウド ポータルのトレース詳細ページに移動します。 このページは、ローカル トレース ビューに似ています。
トレース詳細ビューには、アプリケーション内の操作の包括的で構造化された概要が表示されます。
トレースの詳細ビューについて
トレース ビューの右上隅には、次の情報が表示されます。
- トレース名: これは、アプリケーションのエントリ関数名を表すルート スパン名と同じです。
- 状態: "完了" または "失敗" のいずれかです。
- 合計期間: テスト実行の合計期間です。 カーソルを合わせると、開始時刻と終了時刻が表示されます。
- 合計トークン数: テストの合計トークン コストです。 マウス ポインターを合わせると、プロンプト トークンと完了したトークンが表示されます。
- 作成時刻: トレースが作成された時刻。
左側には、階層ツリー構造が表示されます。 この構造体は、関数呼び出しのシーケンスを示しています。 各関数呼び出しのメタデータはスパンに編成されます。 これらのスパンはツリーのような構造でリンクされ、実行のシーケンスを示します。
プロンプト フロー SDK では、LLM、関数、埋め込み、取得、フローなど、いくつかのスパンの種類を定義しました。 指定された属性とイベントに実行情報を含むスパンは、システムによって自動的に作成されます。
各スパンでは、次の情報を表示できます。
- 関数名: 既定では、これはコードで定義されている関数の名前です。 ただし、Open Telemetry を使用して定義した、カスタマイズされたスパン名にすることもできます。
- 期間: 関数が実行された期間を表します。 カーソルを合わせると、開始時刻と終了時刻が表示されます。
- LLM 呼び出しのトークン: これは LLM 呼び出しのトークン コストです。 マウス ポインターを合わせると、プロンプト トークンと完了したトークンが表示されます。
特定のスパンを選択すると、その関連する詳細情報を右側に表示するように切り替えられます。 この情報には、入力、出力、生の JSON、ログ、例外が含まれます。これは、アプリケーションの監視とデバッグに不可欠です。
LLM スパンの場合は、明確な会話ビューが提供されます。 これには、システム プロンプト、ユーザー プロンプト、アシスタント応答が含まれます。 この情報は、LLM 中間自動呼び出し内での会話のフローと対話を理解できるようにするため、マルチエージェントの場合に特に重要です。
[raw JSON]\(生の JSON\) タブを選択して、スパンの JSON データを表示できます。 この形式は、デバッグとトラブルシューティングに関しては、開発者により適している可能性があります。
トレースの共有
プロジェクトのアクセス許可を持つ他のユーザーとトレースを共有する場合は、トレースの詳細ページの右隅にある [共有] ボタンを選択すると、他のユーザーと共有するためにページ リンクがコピーされます。
Note
共有されたトレースは読み取り専用であり、プロジェクト権限を持つユーザーのみがリンクを介して表示できます。