トレースを使用してアプリをデバッグおよび監視する

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

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

キャプチャされたすべてのトレースは、MLflow 実験に記録されます。 Databricks ワークスペースの MLflow UI を使用してアクセスできます。

1. 実験に移動します。トレースが記録されている実験 (たとえば、 mlflow.set_experiment("/Shared/my-genai-app-traces")によって設定されたもの) に移動します。
2. [トレース] タブを開きます。実験ビューで、[トレース] タブをクリックします。これにより、その実験に記録されたすべてのトレースの一覧が表示されます。

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

トレース一覧にはトレースの概要が示され、通常は次のような列を並べ替えることができます。

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

トレースの検索とフィルター処理

UI には、関連するトレースを検索して重点を置くいくつかの方法が用意されています。

• 検索バー (多くの場合、"要求による評価の検索" などのラベルが付けられます): これにより、 Request (入力) フィールドの内容を検索してトレースをすばやく見つけることができます。
• [フィルター] ドロップダウン: より構造化されたフィルター処理を行うには、[フィルター] ドロップダウンを使用します。 これにより、通常、次に基づいてクエリを作成できます。
  • 属性: Request コンテンツ、 Session time、 Execution time、 Request timeなど。
  • 評価: my_scorerやprofessionalなどの評価の存在または特定の値でフィルターします。
  • State、Trace name、Session、User、Tagsなどのその他のフィールド (tags.persona = 'expert'など)。
• 並べ替えドロップダウン: [並べ替え] ドロップダウンを使用して、 Request time、 Execution timeなどのさまざまな列でトレースを並べ替えます。
• [列] ドロップダウン: 特定のタグや評価メトリックなど、トレース リストに表示される列をカスタマイズします。

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

個々の軌跡の探索

特定のトレースの詳細を調べるには、一覧の [要求 ] または [トレース名] をクリックします。 これにより、詳細なトレース ビューが開きます。通常、いくつかのメイン パネルがあります。

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

   • このパネル (多くの場合、"トレースの内訳") には、 スパン階層 がツリーまたはウォーターフォール グラフとして表示されます。 トレース内のすべての操作 (スパン)、その親子リレーションシップ、実行順序と実行時間が表示されます。
   • この内訳から個々のスパンを選択して、特定の詳細を調べることができます。

2. スパンの詳細 (センターパネル):

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

     • チャット: チャットベースの LLM 操作の場合、このタブには多くの場合、会話フロー (ユーザー、アシスタント、ツール メッセージ) の表示ビューが表示されます。

       

     • 入力/出力: 操作に渡された生の入力データと、返された未加工の出力データを表示します。 大きなコンテンツの場合、ビューを展開または折りたたむには、[See more]\(もっと見る\) /[See less]\(縮小表示\) トグルを使用できます。

       

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

       

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

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

3. 評価 (右側のパネル):

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

   

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

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

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

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

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

   

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

   • フィルターの使用: ユーザー情報を追跡 していて、フィルター オプションとして使用できる場合 ([フィルター] ドロップダウンの [属性] または専用の "ユーザー" フィルターなど) は、特定のユーザー ID を選択または入力できます。
   • 検索/タグの使用: または、ユーザー ID がタグ ( mlflow.trace.user など) として格納されている場合は、 tags.mlflow.trace.user = 'user_example_123'などのクエリで検索バーを使用します。

   

3. 障害 (エラー) のあるトレースの特定:

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

   

4. 否定的なフィードバックまたは問題 (不適切な応答など) を含むトレースの識別:

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

   

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

トレースのための Databricks Notebook の統合

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

しくみ

Databricks ノートブックで作業していて、MLflow Tracking URI が "databricks" に設定されている場合 (多くの場合、既定値であるか、 mlflow.set_tracking_uri("databricks")を使用して設定できます)、トレース UI をセルの出力に自動的に表示できます。

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

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

このノートブック内ビューには、メインの MLflow 実験 UI にあるのと同じ豊富な対話型トレース探索機能が用意されています。これにより、コンテキスト切り替えなしですばやく反復処理できます。

ノートブックの表示の制御

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

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

MLflow には、UI 以外に、プログラムでトレースを操作するための API が用意されています。

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

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

次のステップ

これらの推奨されるアクションとチュートリアルを使用して、体験を続けます。

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

リファレンス ガイド

このガイドで説明されている概念と機能の詳細なドキュメントを確認します。

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