Databricksにデプロイされたエージェントのトレース
このページでは、本番運用トレースが自動的にキャプチャされるように、インストルメント化されたGenAI アプリケーションをDatabricksにデプロイする方法を示します。
トレースはMLflowエクスペリメントに記録され、随時表示されます。 オプションで、長期保存用に Delta テーブルを使用して保存します。デプロイメントとトレース ログのオプションを比較するには、 「トレースされたアプリをデプロイする」を参照してください。
Databricks の外部にデプロイされたアプリについては、 「Databricks の外部にデプロイされたトレース エージェント」を参照してください。
Agent Framework を使用したデプロイ (推奨)
Mosaic AI Agent Frameworkを通じて GenAI アプリケーションをデプロイすると、追加の構成なしで MLflow Tracing が自動的に機能します。トレースはエージェントのMLflowエクスペリメントに保存されます。
デプロイのステップ
まず、トレースの保存場所を設定します。
- 本番運用 モニタリングを使用してトレースをDeltaテーブルに保存する場合は、ワークスペースで有効になっていることを確認してください。
- アプリの本番運用トレースを格納するためのMLflowエクスペリメントを作成します。
次に、 Python ノートブックで、 MLflow Tracingを使用してエージェントをインストルメント化し、エージェントフレームワークを使用してエージェントをデプロイします。
- Python 環境に
mlflow[databricks]をインストールします。最新バージョンを使用します。 mlflow.set_experiment(...)を使用してMLflowエクスペリメントに接続します。- エージェントフレームワーク のオーサリングインターフェースを使用してエージェントのコードをラップします。エージェントコードで、自動または手動のインストルメンテーションを使用してMLflow Tracingを有効にします。
- エージェントを MLflow モデルとしてログに記録し、Unity Catalogに登録します。
mlflowがモデルの Python 依存関係にあり、ノートブック環境で使用されているのと同じパッケージ バージョンであることを確認します。agents.deploy(...)を使用して、Unity Catalog モデル (エージェント) をモデルサービング エンドポイントにデプロイします。
Databricks Gitフォルダーに保存されているノートブックからエージェントをデプロイしている場合、 MLflow 3 臨時トレースは当然機能しません。
嘔吐トレースを有効にするには、 agents.deploy()実行する前に、 mlflow.set_experiment()を使用してエクスペリメントをGitに関連付けられていないエクスペリメントに設定します。
エージェントからのトレースが、リアルタイムでMLflowエクスペリメントに表示される ようになります。
ノートブックの例
このノートブックでは、上記の展開ステップを示します。
Agent Framework と MLflow Tracing ノートブック
カスタム CPU サービングを使用してデプロイする (代替)
Agent Framework を使用できない場合は、代わりにカスタム CPU モデルサービングを使用してエージェントをデプロイします。
まず、トレースの保存場所を設定します。
- 本番運用 モニタリングを使用してトレースをDeltaテーブルに保存する場合は、ワークスペースで有効になっていることを確認してください。
- アプリの本番運用トレースを格納するためのMLflowエクスペリメントを作成します。
次に、 Python ノートブックで、 MLflow Tracingを使用してエージェントを計測可能にし、モデルサービング UI または API を使用してエージェントをデプロイします。
- 自動または手動のトレース インストルメンテーションを使用して、エージェントを MLflow モデルとしてログに記録します。
- モデルを CPU サービスにデプロイします。
- MLflowエクスペリメントへの
CAN_EDITアクセスを持つサービスプリンシパルまたはパーソナル アクセストークン(PAT)を提供します。 - CPU サービング エンドポイント ページで、[エンドポイントの編集] に移動します。トレースするデプロイされたモデルごとに、次の環境変数を追加します。
ENABLE_MLFLOW_TRACING=trueMLFLOW_EXPERIMENT_ID=<ID of the experiment you created>- サービスプリンシパルをプロビジョニングする場合は、
DATABRICKS_CLIENT_IDとDATABRICKS_CLIENT_SECRETを設定します。 PAT をプロビジョニングした場合は、DATABRICKS_HOSTを設定し、DATABRICKS_TOKENを設定します。
本番運用トレースを見る
MLflowエクスペリメント UI で本番運用トレースを表示します。 本番運用トレースは次を示します。
- ユーザーの問い合わせとエージェントの応答
- フィードバック（高評価/低評価、コメント）
- エラー率と障害パターン
- レイテンシーとパフォーマンスのメトリクス
- トークン消費
Delta テーブルへのログ トレース
オプションで、 MLflowエクスペリメントに加えて、トレースをDeltaテーブルに記録します。
- 本番運用監視テーブル( 推奨 ): トレースをDeltaテーブルに同期するジョブは、約 15 分ごとに実行されます。 これを機能させるためにモニタリング メトリクスを有効にする必要はありません。 トレースにはサイズ制限はありません。
- AI ゲートウェイ対応推論テーブル: モデルサービング エンドポイント ページで AI Gateway 設定を編集して有効にします。トレース・サイズの 制限 と、トレースをテーブルに同期する際の遅延に注意してください。
制限
MLflowエクスペリメントおよび 本番運用 モニタリング・テーブルへのトレースのログ記録には、トレースの数とピーク・ロードに制限があります。 エクスペリメントごとに 100K を超えるトレースを保存する必要がある場合、またはピーク負荷が 60 クエリ/秒 (QPS) >の場合は、 このフォームを使用して 増加をリクエストします。
次のステップ
- トレースにコンテキストを追加- リクエスト追跡、ユーザー セッション、環境データのメタデータを添付します。
- トークンの使用状況を追跡- コスト追跡のためにトークンの消費量を監視します。
- 本番運用モニタリング- スコアラーを使用してトレースを自動的に評価します。