トレースを使用したエージェントのデプロイ
MLflow Tracing は、MLflow UI で表示したり、テーブルとして分析したりできる実行の詳細をキャプチャすることで、本番運用 gen AI エージェントとアプリに包括的な可観測性を提供します。
Databricks は、 フルマネージド、本番対応の MLflow 追跡サービス すべてのワークスペースで。 追跡 URI を databricks
に設定すると、トレースは Databricks によって安全に格納および提供され、デプロイまたは運用する個別のトレース データベースやサーバーはありません。
本番運用トレースの仕組み:
-
アプリは、API 呼び出しごとにトレースを生成 します。アプリは、モデルサービング (このガイド) で実行される場合もあれば、 外部アプリケーションである場合もあります。
-
トレースは 、リアルタイムで Databricks MLflow 追跡サーバーのエクスペリメントに記録され、 オプションで Delta テーブルに記録されます。
- 開発には、エクスペリメント MLflow に記録されたトレースを使用します。
- 本番運用の場合は、エクスペリメント ロギングやDeltaテーブルへのロギングMLflowを使用します。
-
UI、本番運用 モニタリング 、またはカスタム評価を使用して 、トレースを分析および監視 します。MLflow
Agent Framework を使用したデプロイ (推奨)
Mosaic AIAgent Framework を介してでインストルメント化されたMLflow Tracing 生成 AI アプリケーションまたはエージェントをデプロイすると、追加の設定なしで自動的にMLflow Tracing 機能します。これは推奨されるデプロイ方法です。トレースは、エージェントのエクスペリメント MLflow に自動的に保存されます。 オプションで、本番運用 モニタリングを使用してトレースをDeltaテーブルにコピーすることもできます。
本番運用 トレースは、Databricksの内部または外部にデプロイされた第 AI 世代アプリで機能します。このセクションでは、 Databricks モデルサービングを使用してデプロイされたアプリをトレースします。 外部にデプロイされたアプリについては、「 Databricks の外部にデプロイされたエージェントのトレース」を参照してください。
デプロイのステップ
まず、トレースの保存場所を設定します。
- 本番運用 モニタリングを使用してトレースをDeltaテーブルに保存する場合は、ワークスペースで有効になっていることを確認してください。
- アプリの本番運用トレースを格納するためのMLflowエクスペリメントを作成します。
次に、 Python ノートブックで、 MLflow Tracingを使用してエージェントをインストルメント化し、エージェントフレームワークを使用してエージェントをデプロイします。
- Python 環境に
mlflow[databricks]
をインストールします。最新バージョンを使用します。 mlflow.set_experiment(...)
を使用してMLflowエクスペリメントに接続します。- エージェントフレームワーク のオーサリングインターフェースを使用してエージェントのコードをラップします。エージェントコードで、自動または手動のインストルメンテーションを使用してMLflow Tracingを有効にします。
- エージェントを MLflow モデルとしてログに記録し、登録する Unity Catalogに .
mlflow
がモデルの Python 依存関係にあり、ノートブック環境で使用されているのと同じパッケージ バージョンであることを確認します。agents.deploy(...)
を使用して、Unity Catalog モデル (エージェント) をモデルサービング エンドポイントにデプロイします。
エージェントからのトレースが、リアルタイムの エクスペリメント MLflow に表示される ようになりました。
ノートブックの例
次のノートブックでは、上記の手順を使用して、Agent Framework を使用して単純な生成 AI アプリをデプロイし、 MLflow エクスペリメントにトレースをログに記録する例を示します。
Agent Framework and MLflow Tracing ノートブック
カスタム CPU サービングを使用してデプロイする (代替)
Agent Framework を使用してエージェントをデプロイできない場合、このセクションでは、カスタム CPU モデルサービングを使用して Databricks にエージェントをデプロイする方法について説明します。それ以外の場合は、 次のセクションに進んでください。
まず、トレースの保存場所を設定します。
- 本番運用 モニタリングを使用してトレースをDeltaテーブルに保存する場合は、ワークスペースで有効になっていることを確認してください。
- アプリの本番運用トレースを格納するためのMLflowエクスペリメントを作成します。
次に、 Python ノートブックで、 MLflow Tracingを使用してエージェントをインストルメント化し、モデルサービング UI または APIs を使用してエージェントをデプロイします。
- エージェントを MLflow モデルとしてログに記録します。エージェントコードで、自動または手動のインストルメンテーションを使用してMLflow Tracingを有効にします。エージェントのコードで、自動または手動のインストルメンテーションを使用してトレースが有効になっていることを確認します
- モデルを CPU サービスにデプロイします。
- プロビジョニングは、MLflowエクスペリメントへの
CAN_EDIT
アクセスを持つサービスプリンシパルまたはPersonal アクセストークン(PAT)です。 - CPU サービング エンドポイント ページで、[エンドポイントの編集] に移動します。トレースするデプロイされたモデルごとに、次の環境変数を追加します。
ENABLE_MLFLOW_TRACING=true
MLFLOW_EXPERIMENT_ID=<ID of the experiment you created>
- サービスプリンシパルをプロビジョニングする場合は、
DATABRICKS_CLIENT_ID
とDATABRICKS_CLIENT_SECRET
を設定します。 PAT をプロビジョニングした場合は、DATABRICKS_HOST
を設定し、DATABRICKS_TOKEN
を設定します。
本番運用トレースを見る
エージェントがデプロイされると、開発のトレースと同様に、 MLflow エクスペリメント UI でそのトレースを表示できます。 これらの本番運用トレースは、次のことへの貴重な知見を提供します。
- 実際のユーザーのクエリとエージェントの応答 - ユーザーが何を尋ねているか、エージェントがどのように応答するかを正確に確認します
- Quality 知見 from user feedback - 本番運用トレースに添付された親指を上げたり下げたりする評価やコメントなどのフィードバックを表示
- エラー率と失敗パターン - エージェントがいつ、なぜ失敗するのかを特定する
- 行動パターン - ユーザーがエージェントとどのようにやり取りするかを理解し、改善の機会を特定します
- レーテンシーとパフォーマンスメトリクス - 本番運用におけるレスポンスタイムとシステムパフォーマンスの監視
- リソースの使用状況とコスト - トークンの消費と関連コストを追跡する
Delta テーブルへのログ トレース
エージェントがデプロイされたら、オプションで、MLflowエクスペリメントに加えて、トレースをDeltaテーブルに記録できます。このログは、次の 2 つの方法でサポートされます。
- 本番運用 モニタリング テーブル ( 推奨 ): MLflow エクスペリメントの [モニタリング ] タブに移動し、Unity Catalogスキーマを選択することで有効にします。トレースを Delta テーブルに同期するジョブは、~15分ごとに実行します。 これを機能させるために、監視メトリクスを有効にする必要はありません。 トレースにはサイズ制限はありません。
- AI ゲートウェイ対応推論テーブル: モデルサービング エンドポイント ページで AI Gateway 設定を編集して有効にします。トレース・サイズの 制限 と、トレースをテーブルに同期する際の遅延に注意してください。
トレースにメタデータを追加する
基本的なトレースが機能したら、メタデータまたはコンテキストを追加して、 デバッグ そして 知見。 MLflow には、次のような重要なコンテキスト情報をキャプチャするための標準化されたタグと属性が用意されています。
- 要求の追跡 - エンドツーエンドのデバッグのためにトレースを特定の API 呼び出しにリンクします
- ユーザーセッション - ユーザージャーニーを理解するために、関連するインタラクションをグループ化します
- 環境データ - 各トレースを生成したデプロイ、バージョン、またはリージョンを追跡します
- ユーザーフィードバック - 品質評価を収集し、特定のインタラクションにリンクします
「 メタデータとユーザー フィードバックをトレースに追加する」で開始します。
トークンの使用状況とコストを追跡する
開発と本番運用の両方で、MLflow TracingLLM呼び出しのトークン使用量を追跡でき、コストにコンピュートできます。トレースでは、 LLM プロバイダ APIsから返されたトークン数を使用します。
MLflow Tracing は、OpenAI クライアントを介して呼び出される Databricks 基盤モデル APIs、OpenAI、 LangChain、LangGraph などの他の多くのLLMプロバイダーのトークン使用状況追跡をネイティブにサポートしています。その後、次の例のように、トークンの使用状況をプログラムで照会できます。
# Get aggregated token usage (if available)
token_usage = trace.info.token_usage
if token_usage:
print(f"Input tokens: {token_usage.get('input_tokens')}")
print(f"Output tokens: {token_usage.get('output_tokens')}")
print(f"Total tokens: {token_usage.get('total_tokens')}")
詳細については、「 トークンの使用情報 」を参照してください。
MLflow Tracing では、特定のエージェントまたはアプリケーションをインストゥルメントできます。 AIプラットフォーム全体でのモニタリングの使用のために、 AI Gateway は共有配信エンドポイントのガバナンスを提供します。プラットフォーム レベルのトークン使用量をシステムテーブルにログに記録するには、「AI Gateway 使用状況の追跡」を参照してください。
これらのトークン数を使用して、 LLM プロバイダーの価格スケジュールに基づいてコストをコンピュートできます。 多くのプロバイダーは、入力トークンと出力トークンに対して異なるレートを請求することに注意してください。
制限
エクスペリメント MLflow および 本番運用 モニタリング・テーブルへのトレースのログ記録には、トレースの数とピーク・ロードに制限があります。 エクスペリメントごとに 100K を超えるトレースを保存する必要がある場合、またはピーク負荷が 60 クエリ/秒 (QPS) >の場合は、 このフォームを使用して 増加をリクエストします。
次のステップ
- ユーザーまたはセッション ID、カスタム タグ、ユーザー フィードバックなどのメタデータをトレースに追加して、 デバッグ と 知見
- スコアラー、評価データセット、本番運用 モニタリングを使用してエージェントを評価および監視 する
機能参照
このガイドの概念と機能の詳細については、以下を参照してください。
- デプロイメントの詳細のトレース - デプロイメント・オプションのトレースの詳細
- トレースデータモデル - トレース、スパン、および属性の詳細
- ログ評価 - フィードバックの保存方法と使用方法を理解する