トレースにコンテキストを追加する
トレースにコンテキストを追加すると、実行の詳細を追跡し、ユーザーの動作を分析し、環境全体の問題をデバッグし、アプリケーションのパフォーマンスを監視できるようになります。MLflow は、一般的なコンテキスト タイプに対して標準化されたメタデータ フィールドを提供し、さらにアプリケーション固有のカスタム メタデータを柔軟に追加することもできます。
前提条件
環境に応じて適切なインストール方法を選択してください。
- Production
- Development
本番運用デプロイの場合は、 mlflow-tracingパッケージをインストールします。
pip install --upgrade mlflow-tracing
mlflow-tracingパッケージは、最小限の依存関係と優れたパフォーマンス特性を備えた本番運用向けに最適化されています。
開発環境では、Databricks の追加機能を含む完全な MLflow パッケージをインストールします。
pip install --upgrade "mlflow[databricks]>=3.1"
完全なmlflow[databricks]パッケージには、Databricks でのローカル開発と実験に必要なすべての機能が含まれています。
コンテキスト トラッキングには MLflow 3 が必要です。MLflow 2.x は、パフォーマンスの制限と本番運用での使用に不可欠な機能が欠落しているため、サポートされていません。
コンテキストメタデータの種類
本番運用アプリケーションは、複数のコンテキストを同時に追跡する必要があります。 MLflow には、重要なコンテキスト情報を取得するための標準化されたメタデータ フィールドがあります。
コンテキストタイプ | ユースケース | MLflowフィールド |
|---|---|---|
クライアントリクエストID | エンドツーエンドのデバッグのために、トレースを特定のクライアント リクエストまたは API 呼び出しにリンクします。 | |
ユーザーセッションID | 複数ターンの会話のトレースをグループ化して、会話の流れ全体を分析できます。 | |
ユーザーID | パーソナライゼーション、コホート分析、ユーザー固有のデバッグのために、トレースを特定のユーザーに関連付けます。 | |
環境データ | デプロイメントコンテキスト (環境、バージョン、リージョン) を追跡して、さまざまなデプロイメント間での運用上の知識とデバッグを実現します。 | 自動メタデータとカスタムメタデータ |
カスタムメタデータ | 組織、検索、フィルタリングのトレースにアプリケーション固有のメタデータを追加する | （メタデータキー） |
ユーザーとセッションを追跡する
生成AI アプリケーションでユーザーとセッションを追跡すると、ユーザーの行動を理解し、会話フローを分析し、パーソナライゼーションを改善するための重要なコンテキストが提供されます。
ユーザーとセッションを追跡する理由は何ですか?
ユーザーとセッションの追跡により、強力な分析と改善が可能になります。
- ユーザー行動分析 - さまざまなユーザーがアプリケーションとどのようにやり取りするかを理解する
- 会話フローの追跡 - 複数ターンの会話とコンテキストの保持を分析
- パーソナライゼーション 知見 - ユーザー固有のエクスペリエンスを改善するためのパターンを特定する
- ユーザーごとの品質 - さまざまなユーザーセグメントにわたるパフォーマンスメトリクスを追跡
- セッションの継続性 - 複数のインタラクションにわたってコンテキストを維持する
ユーザーとセッションの標準メタデータフィールド
MLflow は、セッションとユーザーの追跡用に 2 つの標準メタデータ フィールドを提供します。
mlflow.trace.user- トレースを特定のユーザーに関連付けるmlflow.trace.session- 複数ターンの会話に属するトレースをグループ化します
これらの標準メタデータ フィールドを使用すると、MLflow によって UI でのフィルタリングとグループ化が自動的に有効になります。タグとは異なり、メタデータはトレースが記録されると更新できないため、ユーザー ID やセッション ID などの不変の識別子に最適です。
基本的な実装
アプリケーションにユーザーとセッションの追跡を追加する方法は次のとおりです。
import mlflow
@mlflow.trace
def chat_completion(user_id: str, session_id: str, message: str):
"""Process a chat message with user and session tracking."""
# Add user and session context to the current trace
# The @mlflow.trace decorator ensures there's an active trace
mlflow.update_current_trace(
metadata={
"mlflow.trace.user": user_id, # Links this trace to a specific user
"mlflow.trace.session": session_id, # Groups this trace with others in the same conversation
}
)
# The trace will capture the execution time, inputs, outputs, and any errors
# Your chat logic here
response = generate_response(message)
return response
# Example usage in a chat application
def handle_user_message(request):
# Extract user and session IDs from your application's context
# These IDs should be consistent across all interactions
return chat_completion(
user_id=request.user_id, # e.g., "user-123" - unique identifier for the user
session_id=request.session_id, # e.g., "session-abc-456" - groups related messages
message=request.message
)
# Placeholder chat logic
def generate_response(message: str) -> str:
"""Your chat logic here"""
return "Placeholder response"
# Run the chat completion with user and session context
result = chat_completion(
user_id="user-123",
session_id="session-abc-456",
message="What is MLflow and how does it help with machine learning?"
)
要点:
@mlflow.traceデコレータは関数実行のトレースを自動的に作成しますmlflow.update_current_trace()ユーザー ID とセッション ID をメタデータとしてアクティブ トレースに追加しますmetadata使用すると、トレースが作成された後にこれらの識別子が不変になることが保証されます。
環境とバージョンを追跡する
生成AI アプリケーションの実行環境とアプリケーションバージョンを追跡することで、コードに関連するパフォーマンスと品質の問題をデバッグできます。このメタデータにより、次のことが可能になります。
- 以下のフェーズ固有の環境:
development、staging、およびproduction - アプリのバージョン間での パフォーマンス/品質の追跡 とレグレッションの検出
- 問題発生時の 根本原因分析の迅速化
バージョン管理の仕組みの包括的な概要については、 「バージョン追跡」を参照してください。
自動的に入力されたメタデータ
これらの標準メタデータ フィールドは、実行環境に基づいて MLflow によって自動的にキャプチャされます。
自動キャプチャ ロジックが要件を満たさない場合は、 mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"})を使用して、自動的に入力されたこれらのメタデータを手動で上書きできます。
カテゴリー | メタデータフィールド | 説明 | 自動設定ロジック |
|---|---|---|---|
実行環境 |
| トレースを生成したエントリ ポイントまたはスクリプト。 | Pythonスクリプトのファイル名、 Databricks /Jupyter ノートブックのノートブック名が自動的に入力されます。 |
| Git コミット ハッシュ。 | Git リポジトリから実行すると、コミット ハッシュが自動的に検出され、入力されます。 | |
| Git ブランチ。 | Git リポジトリから実行すると、現在のブランチ名が自動的に検出され、入力されます。 | |
| Git リポジトリの URL。 | Git リポジトリから実行すると、リポジトリ URL が自動的に検出され、入力されます。 | |
| 実行環境をキャプチャします。 | Jupyter または Databricks ノートブックで実行している場合は自動的に | |
アプリケーションバージョン |
| MLflowログモデルID。 | 環境変数 |
自動的に入力されるメタデータのカスタマイズ
mlflow.update_current_trace()を使用して、自動的に入力されるメタデータ フィールドをオーバーライドできます。これは、自動検出が要件を満たさない場合や、追加のコンテキストを追加したい場合に役立ちます。
import mlflow
import os
# We suggest populating metadata from environment variables rather than hard coding the values
@mlflow.trace
def my_app(user_question: str) -> dict:
# Override automatically populated metadata and add custom context
mlflow.update_current_trace(
metadata={
# Use any of the keys from above
"mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"), # Override default LOCAL/NOTEBOOK
}
)
# Application logic
return {"response": user_question + "!!"}
my_app("test")
カスタムメタデータを追加する
カスタム メタデータ を添付して、アプリケーション固有のコンテキストをキャプチャできます。たとえば、次のような情報を添付することができます。
app_version: 例:"1.0.0"(APP_VERSION環境変数から)deployment_id: 例:"deploy-abc-123"(DEPLOYMENT_ID環境変数から)region: 例:"us-east-1"(REGION環境変数から)- （機能フラグなどの他のカスタムメタデータも追加できます）
import mlflow
import os
# We suggest populating metadata from environment variables rather than hard coding the values
@mlflow.trace
def my_app(user_question: str) -> dict:
# Add custom context
mlflow.update_current_trace(
metadata={
# Use any key
"app_version": os.getenv("APP_VERSION", "1.0.0"),
"deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
"region": os.getenv("REGION", "us-east-1")
}
)
# Application logic
return {"response": user_question + "!!"}
my_app("test")
本番運用 Web アプリケーションの例
本番運用アプリケーションでは、通常、ユーザー、セッション、環境のコンテキストを同時に追跡します。 次の FastAPI の例は、すべてのコンテキスト タイプをまとめてキャプチャする方法を示しています。
import mlflow
import os
from fastapi import FastAPI, Request
from pydantic import BaseModel
# Initialize FastAPI app
app = FastAPI()
class ChatRequest(BaseModel):
message: str
@mlflow.trace # Ensure @mlflow.trace is the outermost decorator
@app.post("/chat") # FastAPI decorator should be inner decorator
def handle_chat(request: Request, chat_request: ChatRequest):
# Retrieve all context from request headers
client_request_id = request.headers.get("X-Request-ID")
session_id = request.headers.get("X-Session-ID")
user_id = request.headers.get("X-User-ID")
# Update the current trace with all context and environment metadata
# The @mlflow.trace decorator ensures an active trace is available
mlflow.update_current_trace(
client_request_id=client_request_id,
metadata={
# Session context - groups traces from multi-turn conversations
"mlflow.trace.session": session_id,
# User context - associates traces with specific users
"mlflow.trace.user": user_id,
# Override automatically populated environment metadata
"mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"), # Override default LOCAL/NOTEBOOK
# Add custom environment metadata
"environment": "production",
"app_version": os.getenv("APP_VERSION", "1.0.0"),
"deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
"region": os.getenv("REGION", "us-east-1"),
# Add custom tags
"my_custom_tag": "custom tag value",
}
)
# --- Your application logic for processing the chat message ---
# For example, calling a language model with context
# response_text = my_llm_call(
# message=chat_request.message,
# session_id=session_id,
# user_id=user_id
# )
response_text = f"Processed message: '{chat_request.message}'"
# --- End of application logic ---
# Return response
return {
"response": response_text
}
# To run this example (requires uvicorn and fastapi):
# uvicorn your_file_name:app --reload
#
# Example curl request with context headers:
# curl -X POST "http://127.0.0.1:8000/chat" \
# -H "Content-Type: application/json" \
# -H "X-Request-ID: req-abc-123-xyz-789" \
# -H "X-Session-ID: session-def-456-uvw-012" \
# -H "X-User-ID: user-jane-doe-12345" \
# -d '{"message": "What is my account balance?"}'
この例では、コンテキスト トラッキング、キャプチャに対する統一されたアプローチを示します。
- クライアント リクエスト ID :
X-Request-IDヘッダーから、client_request_id問題を使用して記録されます。 - ユーザー情報 :
X-User-IDヘッダーから、mlflow.trace.userメタデータとして記録されます。 - セッション情報 :
X-Session-IDヘッダーから、mlflow.trace.sessionメタデータとして記録されます。 - 環境コンテキスト : 環境変数と自動検出から、本番運用設定のオーバーライドを含みます。
- アプリケーション バージョン :
APP_VERSION環境変数から。 - デプロイメントの詳細 : デプロイメント ID とリージョンのカスタム メタデータ。
ベストプラクティス
- 一貫したID形式 - アプリケーション全体でユーザーIDとセッションIDに標準化された形式を使用します
- セッションの境界 - セッションの開始と終了の明確なルールを定義する
- 環境変数 - ハードコーディングされた値ではなく、環境変数からメタデータを入力します。
- コンテキスト タイプを組み合わせる - ユーザー、セッション、環境のコンテキストをまとめて追跡し、完全なトレーサビリティを実現します。
- 定期的な分析 - ユーザーの行動、セッションパターン、バージョンのパフォーマンスを監視するためのダッシュボードを設定します
- デフォルトを慎重に上書きする - 必要な場合にのみ、自動的に入力されたメタデータを上書きします
次のステップ
ユーザーとセッションのメタデータを追加したら、次のことが可能になります。
- トレースの検索とフィルタリング- 追加したコンテキスト メタデータを使用してトレースをクエリします
- ユーザー アクティビティの分析- ユーザーの行動を分析するための本番運用対応パターン