GenAI アプリケーションでユーザーとセッションを追跡すると、ユーザーの動作を理解したり、会話フローを分析したり、パーソナル化を改善したりするための重要なコンテキストが提供されます。 MLflow には、トレースをユーザーに関連付け、セッションにグループ化するための組み込みのサポートが用意されています。
[前提条件]
環境に基づいて適切なインストール方法を選択します。
生産
運用環境の展開の場合は、 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 には、セッションとユーザー追跡用の 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を使用すると、トレースの作成後にこれらの識別子が不変になります
運用 Web アプリケーションの例
運用アプリケーションでは、通常、ユーザー、セッション、およびその他のコンテキスト情報を同時に追跡します。 この例は、トレースを使用した運用環境の監視ガイドからのものであり、環境とコンテキストの追跡ガイドに示されているような、環境およびデプロイのコンテキストも組み込んでいます。
import mlflow
import os
from fastapi import FastAPI, Request, HTTPException # HTTPException might be needed depending on full app logic
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
def handle_chat(request: Request, chat_request: ChatRequest):
# Retrieve all context from request headers
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,
}
)
# --- 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?"}'
この例では、コンテキスト追跡とキャプチャに対する統一されたアプローチを示します。
- ユーザー情報:
X-User-IDヘッダーから、mlflow.trace.userメタデータとしてログに記録されます。 - セッション情報:
X-Session-IDヘッダーから、mlflow.trace.sessionメタデータとしてログに記録されます。
データのクエリと分析
MLflow UI の使用
次の検索クエリを使用して、MLflow UI のトレースをフィルター処理します。
# Find all traces for a specific user
metadata.`mlflow.trace.user` = 'user-123'
# Find all traces in a session
metadata.`mlflow.trace.session` = 'session-abc-456'
# Find traces for a user within a specific session
metadata.`mlflow.trace.user` = 'user-123' AND metadata.`mlflow.trace.session` = 'session-abc-456'
プログラムによる分析
MLflow SDK を使用して、ユーザーとセッションのデータをプログラムで分析します。 これにより、カスタム分析の構築、レポートの生成、大規模なユーザー動作パターンの監視を行うことができます。
from mlflow.client import MlflowClient
client = MlflowClient()
# Analyze user behavior
def analyze_user_behavior(user_id: str, experiment_id: str):
"""Analyze a specific user's interaction patterns."""
# Search for all traces from a specific user
user_traces = client.search_traces(
experiment_ids=[experiment_id],
filter_string=f"metadata.`mlflow.trace.user` = '{user_id}'",
max_results=1000
)
# Calculate key metrics
total_interactions = len(user_traces)
unique_sessions = len(set(t.info.metadata.get("mlflow.trace.session", "") for t in user_traces))
avg_response_time = sum(t.info.execution_time_ms for t in user_traces) / total_interactions
return {
"total_interactions": total_interactions,
"unique_sessions": unique_sessions,
"avg_response_time": avg_response_time
}
# Analyze session flow
def analyze_session_flow(session_id: str, experiment_id: str):
"""Analyze conversation flow within a session."""
# Get all traces from a session, ordered chronologically
session_traces = client.search_traces(
experiment_ids=[experiment_id],
filter_string=f"metadata.`mlflow.trace.session` = '{session_id}'",
order_by=["timestamp ASC"]
)
# Build a timeline of the conversation
conversation_turns = []
for i, trace in enumerate(session_traces):
conversation_turns.append({
"turn": i + 1,
"timestamp": trace.info.timestamp,
"duration_ms": trace.info.execution_time_ms,
"status": trace.info.status
})
return conversation_turns
主な機能:
- ユーザー動作分析 - ユーザー ごとの対話頻度、セッション数、およびパフォーマンス メトリックを追跡する
- セッション フロー分析 - 会話のタイムラインを再構築して複数ターンの相互作用を理解する
- 柔軟なフィルター処理 - MLflow の検索構文を使用して、メタデータ フィールドの任意の組み合わせでトレースにクエリを実行する
- スケーラブルな分析 - 大量のトレースをプログラムで処理して大規模な分析情報を得る
- エクスポート可能なデータ - 結果を DataFrame に簡単に変換したり、さらに分析するためにエクスポートしたりできます
ベスト プラクティス
- 一貫性のある ID 形式 - ユーザー ID とセッション ID に標準化された形式を使用する
- セッション境界 - セッション の開始と終了の明確な規則を定義する
- メタデータ エンリッチメント - ユーザー セグメントやセッションの種類などの追加のコンテキストを追加する
- 要求追跡と組み合わせる - ユーザー/セッション データを要求 ID とリンクして完全な追跡可能性を実現する
- 定期的な分析 - ユーザーの動作とセッション パターンを監視するようにダッシュボードを設定する
他の MLflow 機能との統合
ユーザーとセッションの追跡は、他の MLflow 機能とシームレスに統合されます。
- 評価 - さまざまなユーザー セグメント間で品質メトリックを比較し、改善する領域を特定する
- 運用環境の監視 - ユーザー コーホートまたはセッションの種類別にパフォーマンス パターンを追跡する
- フィードバック収集 - 品質分析のためにユーザーフィードバックを特定のセッションに関連付ける
- 評価データセットの構築 - 特定のユーザー セッションからターゲット データセットを作成する
実稼働に関する考慮事項
包括的な運用環境の実装については、次の トレースを使用した運用環境の可観測性 に関するガイドを参照してください。
- 運用環境でのユーザーとセッションの追跡の設定
- セッション ID と要求 ID を組み合わせて完全な追跡可能性を実現する
- セッション全体のフィードバック収集の実装
- 大量のセッション管理のベスト プラクティス
次のステップ
これらの推奨されるアクションとチュートリアルを使用して、体験を続けます。
- 環境とコンテキストの追跡 - デプロイと環境のメタデータをトレースに追加する
- ユーザー フィードバックの収集 - ユーザー からの品質信号をキャプチャする
リファレンス ガイド
このガイドで説明されている概念と機能の詳細なドキュメントを確認します。
- トレース データ モデル - メタデータ、タグ、トレース構造を理解する
- SDK を使用したトレースのクエリ - 高度なクエリ手法について説明します
- 運用監視の概念 - 監視パターンを調べる