トレースによるアプリのデバッグと監視

生成AIアプリケーションに MLflow Tracingを計測可能にすると、その動作をデバッグし、パフォーマンスを理解し、入力と出力を観察するための強力なツールが得られます。 このガイドでは、Databricks 内で MLflow UI を効果的に使用し、これらの目的でノートブックの統合を活用する方法に焦点を当てています。

Databricks MLflow UI でのトレースの確認

キャプチャされたすべてのトレースは、 MLflow エクスペリメントに記録されます。 Databricks ワークスペースの MLflow UI からアクセスできます。

ヒント

トレースは、 MLFLOW_TRACKING_URI が databricksに設定されている場合、Databricks ワークスペース内のマネージド MLflow 追跡サービスによって格納され、提供されます。この本番環境対応のバックエンドでは、追加のホスティングは必要ありません。「 トレースを使用したエージェントのデプロイ」を参照してください。

1. エクスペリメントに移動します :トレースが記録されているエクスペリメント(例: mlflow.set_experiment("/Shared/my-genai-app-traces")によって設定されたもの)に移動します。
2. 「トレース」タブを開く :エクスペリメントビュー内で、「トレース」タブをクリックします。 これにより、そのエクスペリメントに記録されたすべてのトレースのリストが表示されます。

トレース リスト ビューについて

トレース・リストには、トレースの概要と、通常は次のものを含むソート可能な列が表示されます。

• トレース ID : 各トレースの一意の識別子。
• 要求 : トレースをトリガーした初期入力のプレビュー。
• 応答 : トレースの最終出力のプレビュー。
• セッション : セッション識別子 (指定されている場合)、関連するトレース (会話など) をグループ化します。
• ユーザー : ユーザー識別子 (指定されている場合)。
• 実行時間 : トレースが完了するまでにかかった合計時間。
• 要求時刻 : トレースが開始されたときのタイムスタンプ。
• 実行名 : トレースが MLflow 実行に関連付けられている場合、その名前がここに表示され、トレースがリンクされます。
• ソース : トレースの起点で、多くの場合、インストゥルメントされたライブラリまたはコンポーネント ( openai、 langchain、カスタムトレース名など) を示します。
• ステータス : トレースの現在のステータス ( OK、 ERROR、 IN_PROGRESSなど)。
• トレース名 : このトレースに割り当てられた特定の名前 (多くの場合、ルート スパンの名前)。
• 評価 : 評価タイプごとに個別の列 ( my_scorer、 professionalなど)。また、UI では、多くの場合、リストの上に概要セクションが表示され、現在表示されているトレース全体の集計された評価メトリクス (平均や合格/不合格率など) が表示されます。
• タグ : 個々のタグは列として表示できます (例: persona、 style)。タグのサマリー数も表示される場合があります。

トレースの検索とフィルタリング

UI には、関連するトレースを見つけて焦点を合わせる方法がいくつか用意されています。

• 検索バー (多くの場合、「リクエストによる評価の検索」などのラベルが付けられています): これにより、 Request (入力) フィールドの内容を検索してトレースをすばやく見つけることができます。

• Filters ドロップダウン : より構造化されたフィルタリングを行うには、"Filters" ドロップダウンを使用します。 これにより、通常、以下に基づいてクエリを作成できます。

  • 属性 : Request コンテンツ、 Session time、 Execution time、 Request timeなど。
  • 評価 : 評価の有無や特定の値 ( my_scorer や professionalなど) でフィルタリングします。
  • State、 Trace name、 Session、 User、Tags などの他のフィールド (tags.persona = 'expert'など) 。

• Sort ドロップダウン : "Sort" ドロップダウンを使用して、 Request time、 Execution timeなどのさまざまな列でトレースを並べ替えます。

• Columns ドロップダウン : トレース リストに表示する列 (特定のタグや評価メトリクスなど) をカスタマイズします。

プログラムによる高度なクエリと、UI で使用されるフィルター構文の理解については、 SDK を使用したトレースのクエリ ガイドを参照してください。

個々のトレースの探索

特定のトレースを深く掘り下げるには、リスト内の そのトレースの [Request Name] または [ Trace Name ] をクリックします。これにより、詳細なトレース ビューが開き、通常はいくつかのメイン パネルが表示されます。

1. トレースの内訳(左パネル):

   • このパネル (多くの場合、「トレースの内訳」というタイトル) は、 スパン階層 をツリー チャートまたはウォーターフォール チャートとして表示します。トレース内のすべての操作 (スパン)、親子関係、および実行順序と期間が表示されます。
   • この内訳から個々のスパンを選択して、特定の詳細を検査できます。

2. スパンの詳細(中央パネル):

   • [Trace] 内訳からスパンを選択すると、このパネルには詳細情報が表示され、通常は次のようなタブに整理されます。

     • チャット : チャットベースの LLM インタラクションの場合、このタブでは、多くの場合、会話フロー (ユーザー、アシスタント、ツール メッセージ) のレンダリング ビューが表示されます。

     

     • 入力/出力 : 操作に渡された生の入力データと、それが返した生の出力データを表示します。大きなコンテンツの場合は、「もっと見る」/「もっと見る」のトグルを使って、ビューを展開または折りたたむことができるかもしれません。

     

     • 属性 : スパンに固有のキーと値のメタデータ ( model 名、LLM 呼び出しの temperature 、取得者スパンの doc_uri など) を表示します。

     

     • イベント : エラーが発生したスパンの場合、このタブには通常、例外の詳細とスタック トレースが表示されます。ストリーミングスパンの場合、生成された個々のデータチャンクが表示される場合があります。

     • 一部の出力フィールドには、コンテンツが Markdown 形式の場合、未加工のビューとレンダリングされたビューを切り替えるための Markdown トグル がある場合もあります。

3. 評価(右パネル):

   • このパネルには、 トレース全体 または 現在選択されているスパン についてログに記録された評価 (ユーザーフィードバックまたは評価) が表示されます。
   • 重要なのは、このパネルには 多くの場合、「+ 新しい評価を追加」 ボタンが含まれているため、トレースをレビューしながら UI から直接新しいフィードバックや評価スコアを記録できることです。これは、手動のレビューとラベル付けのワークフローに非常に役立ちます。

   

Trace-Level 情報 : このビューでは、個々のスパンの詳細だけでなく、全体的なトレース情報にもアクセスできます。 これには、トレース・レベルのタグと、トレース全体に対してログに記録された評価 (特定のスパンまたはルート・スパンが選択されていない場合に [評価] パネルに表示されることが多い) が含まれ、 これは直接のユーザー・フィードバック または 体系的な評価から生成される場合があります。

一般的なデバッグと監視のシナリオ

MLflow Tracing UI を使用して、一般的なデバッグと監視のニーズに対処する方法を次に示します。

1. 低速トレース(レイテンシのボトルネック)の特定 :

   • トレースリストビューの場合 : [Sort] ドロップダウンを使用して、トレースを [Execution time] で降順にソートします。これにより、最も遅いトレースが一番上に表示されます。
   • 詳細トレース ビュー: 低速トレースを開いたら、[トレースの内訳] パネルを確認します。スパンのウォーターフォール表示は、最も時間がかかった操作を視覚的に強調表示し、アプリケーションのフロー内のレイテンシのボトルネックを特定するのに役立ちます。

   

2. 特定のユーザーからのトレースの検索 :

   • フィルターの使用 : 追跡したユーザー情報 があり、それがフィルターオプションとして利用可能な場合(例:「属性」または「フィルター」ドロップダウンの専用の「ユーザー」フィルターの下)、特定のユーザーIDを選択または入力できます。
   • 検索/タグの使用 : または、ユーザー ID がタグ ( mlflow.trace.userなど) として保存されている場合は、 tags.mlflow.trace.user = 'user_example_123'のようなクエリで検索バーを使用します。

   

3. 失敗(エラー)のあるトレースの検索 :

   • フィルタの使用 : [フィルタ] ドロップダウンで State 属性を選択し、[ ERROR ] を選択すると、失敗したトレースのみが表示されます。
   • 詳細トレース ビュー: エラー トレースの場合は、[トレースの内訳] でエラーとマークされたスパンを選択します。[Span Details] パネルの [Events] タブに移動して、障害の根本原因を診断するために重要な例外メッセージとスタック トレースを表示します。

   

4. 否定的なフィードバックや問題(誤った回答など)のあるトレースの特定 :

   • 評価フィルターの使用 : ユーザー フィードバックを収集し たり、評価につながる評価を実行したりする場合 (ブール is_correct や数値 relevance_scoreなど)、"Filters" ドロップダウンを使用すると、これらの評価名とその値 ( is_correct = false や relevance_score < 0.5のフィルターなど) でフィルター処理できる場合があります。
   • 評価の表示 : トレースを開き、[評価] パネル (詳細ビューの右側) または個々のスパン評価を確認します。これにより、ログに記録されたフィードバック、スコア、根拠が表示され、応答が低品質としてマークされた理由を理解するのに役立ちます。

   

これらの例は、 MLflow Tracingによってキャプチャされた詳細な情報と UI の表示およびフィルタリング機能を組み合わせることで、問題を効率的にデバッグし、アプリケーションの動作を観察する方法を示しています。

Databricks ノートブックとトレースの統合

MLflow Tracing は、 Databricks ノートブック内でシームレスなエクスペリエンスを提供し、開発および実験ワークフローの一部としてトレースを直接表示できます。

注記

MLflow Tracing Databricksノートブックの統合は、MLflow 2.20以降で利用できます。

仕組み

Databricksノートブックで作業し、MLflowトラッキングURIが"databricks"に設定されている場合(多くの場合、デフォルトまたはmlflow.set_tracking_uri("databricks")を介して設定できます)、トレースUIをセルの出力に自動的に表示できます。

これは通常、次の場合に発生します。

1. セルのコード実行では、トレースが生成されます (たとえば、 @mlflow.trace で修飾された関数や 自動インストゥルメントされたライブラリ呼び出しを呼び出すことによって)。
2. 明示的にmlflow.search_traces()を呼び出すと、結果が表示されます。
3. mlflow.entities.Trace オブジェクト (例: frommlflow.get_trace() はセル内の最後の式であるか、display()に渡されます。

このノートブック内ビューは、メインの MLflow エクスペリメント UI にあるのと同じリッチでインタラクティブなトレース探索機能を提供し、コンテキストを切り替えることなく迅速に反復処理するのに役立ちます。

ノートブックの表示を制御する

• ノートブックのセル出力でのトレースの自動表示 を無効に するには、次のコマンドを実行します mlflow.tracing.disable_notebook_display()
• 再度 有効に するには、次のコマンドを実行します mlflow.tracing.enable_notebook_display()

プログラムによるアクセスと管理

UI 以外にも、 MLflow はプログラムでトレースを操作するための APIs を提供します。

• SDK によるトレースのクエリ : Python を使用してトレースデータを検索、フィルタリング、取得し、カスタム分析、評価データセットの構築、または他のシステムとの統合を行う方法を学びます。
• トレースの削除 : データ ライフサイクル管理の特定の基準に基づいてトレースを削除する方法を理解します。

UI ベースの探索とプログラムによるアクセスを組み合わせることで、生成AI アプリケーションのデバッグ、その動作の理解、パフォーマンスと品質の継続的な改善のための包括的なツールキットが得られます。

次のステップ

これらの推奨アクションとチュートリアルで旅を続けてください。

• SDKによるトレースのクエリ - カスタムワークフローのトレースをプログラムで検索および分析します
• トレースによる品質向上 - トレースの知見をアプリケーション改善に活用
• 評価データセットの構築 - トレースをテストデータに変換して体系的に評価します

リファレンスガイド

このガイドで説明されている概念と機能の詳細なドキュメントをご覧ください。

• トレーシング・データ・モデル - トレースとスパン構造の理解
• トレースの削除 - トレースのライフサイクル管理について学習します。
• ログ評価 - フィードバックと評価の概念について詳しく説明します