トレースにコンテキストを追加する

トレースにコンテキストを追加すると、実行の詳細を追跡し、ユーザーの動作を分析し、環境全体の問題をデバッグし、アプリケーションのパフォーマンスを監視できるようになります。MLflow は、一般的なコンテキストタイプに対して標準化されたメタデータフィールドを提供し、さらにアプリケーション固有のカスタムメタデータを柔軟に追加することもできます。

要件

環境に応じて、トレースに適切なパッケージをインストールします。

Production
Development

本番運用デプロイの場合は、 mlflow-tracingパッケージをインストールします。

Bash
pip install --upgrade mlflow-tracing

mlflow-tracingパッケージは、最小限の依存関係と優れたパフォーマンス特性を備えた本番運用向けに最適化されています。

開発環境では、Databricks の追加機能を含む完全な MLflow パッケージをインストールします。

Bash
pip install --upgrade "mlflow[databricks]>=3.1"

完全なmlflow[databricks]パッケージには、Databricks でのローカル開発と実験に必要なすべての機能が含まれています。

注記

コンテキストトラッキングには MLflow 3 が必要です。MLflow 2.x は、パフォーマンスの制限と本番運用での使用に不可欠な機能が欠落しているため、サポートされていません。

実装

トレースにメタデータとタグを追加するには:

アプリケーションを追跡します。最も一般的には、関数を自動的にトレースするには@mlflow.traceデコレータを使用します。
アプリケーションの実行中に、 mlflow.update_current_trace()を呼び出して、 tagsまたはmetadataを使用してトレースにコンテキストを追加します。アプリケーションが完了し、トレースがログに記録された後、ログに記録されたトレースではtagsは変更可能になりますが、 metadataは変更できません。

Python
import mlflow
mlflow.update_current_trace(
    metadata={
        "mlflow.trace.user": user_id,
        "mlflow.trace.session": session_id,
    },
    tags={
        "query_category": "chat",  # Example of a custom tag
    },
)

トレースTrace.info.tags Traceログ内のメタデータとタグにアクセスするには、metadata tagsPandasDataFramemlflow.search_traces()によって返されるTrace.info.trace_metadata のフィールドとフィールドを使用するか、オブジェクトのフィールドとフィールドを使用します。

完全なチュートリアルについては、「チュートリアル: ユーザーと環境のトレースと分析」を参照してください。

コンテキストメタデータの種類

本番運用アプリケーションは、複数のコンテキストを同時に追跡する必要があります。 MLflow には、重要なコンテキスト情報を取得するための標準化されたメタデータフィールドがあります。

コンテキストタイプ	ユースケース	MLflowフィールド
クライアントリクエストID	エンドツーエンドのデバッグのために、トレースを特定のクライアントリクエストまたは API 呼び出しにリンクします。	`TraceInfo` パラメーター `client_request_id`
ユーザーセッションID	複数ターンの会話のトレースをグループ化して、会話の流れ全体を分析できます。	`mlflow.trace.session` メタデータ
ユーザーID	パーソナライゼーション、コホート分析、ユーザー固有のデバッグのために、トレースを特定のユーザーに関連付けます。	`mlflow.trace.user` メタデータ
環境データ	デプロイメントコンテキスト (環境、バージョン、リージョン) を追跡して、さまざまなデプロイメント間での運用上の知識とデバッグを実現します。	自動メタデータとカスタムメタデータ
カスタムメタデータ	組織、検索、フィルタリングのトレースにアプリケーション固有のメタデータを追加する	（メタデータキー）

ユーザーとセッションを追跡する

生成AI アプリケーションでユーザーとセッションを追跡すると、ユーザーの行動を理解し、会話フローを分析し、パーソナライゼーションを改善するための重要なコンテキストが提供されます。

ユーザーとセッションを追跡する理由は何ですか?

ユーザーとセッションの追跡により、強力な分析と改善が可能になります。

ユーザー行動分析 - さまざまなユーザーがアプリケーションとどのようにやり取りするかを理解する
会話フローの追跡 - 複数ターンの会話とコンテキストの保持を分析
パーソナライゼーション知見 - ユーザー固有のエクスペリエンスを改善するためのパターンを特定する
ユーザーごとの品質 - さまざまなユーザーセグメントにわたるパフォーマンスメトリクスを追跡
セッションの継続性 - 複数のインタラクションにわたってコンテキストを維持する

ユーザーとセッションの標準メタデータフィールド

MLflow は、セッションとユーザーの追跡用に 2 つの標準メタデータフィールドを提供します。

mlflow.trace.user - トレースを特定のユーザーに関連付ける
mlflow.trace.session - 複数ターンの会話に属するトレースをグループ化します

これらの標準メタデータフィールドを使用すると、MLflow によって UI でのフィルタリングとグループ化が自動的に有効になります。タグとは異なり、メタデータはトレースが記録されると更新できないため、ユーザー ID やセッション ID などの不変の識別子に最適です。

環境とバージョンを追跡する

生成AI アプリケーションの実行環境とアプリケーションバージョンを追跡することで、コードに関連するパフォーマンスと品質の問題をデバッグできます。このメタデータにより、次のことが可能になります。

以下のフェーズ固有の環境: development、staging、および production
アプリのバージョン間での パフォーマンス/品質の追跡 とレグレッションの検出
問題発生時の 根本原因分析の迅速化

環境やバージョンなどのデプロイメントメタデータの場合、通常、アプリケーションはメタデータをアプリケーションにハードコードするのではなく、環境変数からメタデータを抽出する必要があります。環境変数により、デプロイメントプロセスが簡素化されます。例えば：

Python
import mlflow
import os

# In your application logic
mlflow.update_current_trace(
    metadata={
        "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default
    }
)

注記

バージョン管理の仕組みの包括的な概要については、「バージョン追跡」を参照してください。

自動的に入力されたメタデータ

MLflow は、実行環境に基づいて特定の標準メタデータフィールドを自動的に設定します。

mlflow.update_current_trace()を使用して、自動的に入力されるメタデータフィールドをオーバーライドできます。これは、自動検出が要件を満たさない場合に役立ちます。たとえば、 mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"})を使用して実行環境の値をオーバーライドします。

カテゴリー	メタデータフィールド	説明	自動設定ロジック
実行環境	`mlflow.source.name`	トレースを生成したエントリポイントまたはスクリプト。	Pythonスクリプトのファイル名、 Databricks /Jupyter ノートブックのノートブック名が自動的に入力されます。
	`mlflow.source.git.commit`	Git コミットハッシュ。	Git リポジトリから実行すると、コミットハッシュが自動的に検出され、入力されます。
	`mlflow.source.git.branch`	Git ブランチ。	Git リポジトリから実行すると、現在のブランチ名が自動的に検出され、入力されます。
	`mlflow.source.git.repoURL`	Git リポジトリの URL。	Git リポジトリから実行すると、リポジトリ URL が自動的に検出され、入力されます。
	`mlflow.source.type`	実行環境をキャプチャします。	Jupyter または Databricks ノートブックで実行している場合は自動的に`NOTEBOOK`に設定され、ローカル Python スクリプトを実行している場合は`LOCAL` 、それ以外の場合は`UNKNOWN` (自動検出) に設定されます。デプロイされたアプリでは、環境に応じてこの変数を更新することをお勧めします (例: `PRODUCTION` 、 `STAGING`など)。
	`mlflow.sourceRun`	トレースを生成したソース実行の実行 ID。	トレースを生成したソース実行の実行 ID に自動的に設定されます。
アプリケーションバージョン	`metadata.mlflow.modelId`	MLflowログモデルID。	環境変数`MLFLOW_ACTIVE_MODEL_ID`のモデル ID 値または`mlflow.set_active_model()`関数によって設定されたモデル ID に自動的に設定されます。

カスタムメタデータを追加する

その他のアプリケーション固有のコンテキストをキャプチャするには、カスタムmetadataキーを使用します。たとえば、次のような情報を添付することができます。

アプリケーションバージョン
デプロイメントID
展開地域
機能フラグ

ベストプラクティス

一貫したID形式 - アプリケーション全体でユーザーIDとセッションIDに標準化された形式を使用します
セッションの境界 - セッションの開始と終了の明確なルールを定義する
環境変数 - ハードコーディングされた値ではなく、環境変数からメタデータを入力します。
コンテキストタイプを組み合わせる - ユーザー、セッション、環境のコンテキストをまとめて追跡し、完全なトレーサビリティを実現します。
定期的な分析 - ユーザーの行動、セッションパターン、バージョンのパフォーマンスを監視するためのダッシュボードを設定します
デフォルトを慎重に上書きする - 必要な場合にのみ、自動的に入力されたメタデータを上書きします

次のステップ

チュートリアル: ユーザーと環境のトレースと分析- ユーザー、セッション、環境、アプリバージョンのメタデータをトレースに追加する完全な例を参照してください。
プログラムでトレースを検索する- mlflow.search_traces()使用について詳しく学習します。
トレースの分析- トレース分析の例を参照してください。

要件​

実装​

コンテキストメタデータの種類​

ユーザーとセッションを追跡する​

ユーザーとセッションを追跡する理由は何ですか?​

ユーザーとセッションの標準メタデータフィールド​

環境とバージョンを追跡する​

自動的に入力されたメタデータ​

カスタムメタデータを追加する​

ベストプラクティス​

次のステップ​

要件

実装