Aller au contenu principal
Dernière mise à jour le

Tutoriel : Suivre et analyser les utilisateurs et les environnements

Ouvrir dans Databricks

Ce tutoriel démontre comment ajouter du contexte aux traces afin de suivre et d'analyser les utilisateurs, les sessions et les déploiements.

  • Dans une application de chat simple, vous utiliserez mlflow.update_current_trace() pour ajouter des métadonnées et des balises personnalisées aux traces.
  • Pour analyser les traces, vous utiliserez mlflow.search_traces() pour extraire les traces pertinentes et calculer des statistiques pour les utilisateurs, les sessions, les environnements et les versions d'application.

Configuration de l'environnement​

Installez les packages requis :

  • mlflow[databricks]Utilisez la dernière version de MLflow pour obtenir davantage de fonctionnalités et d'améliorations.
  • openai: Cette application utilisera le client de l'API OpenAI pour appeler les modèles hébergés par Databricks.
Python
%pip install -qq --upgrade "mlflow[databricks]>=3.1.0" openai
dbutils.library.restartPython()

Créez une Experimentation MLflow. Si vous utilisez un Notebook Databricks, vous pouvez ignorer cette étape et utiliser l'Experimentation Notebook par default. Sinon, suivez le guide de démarrage rapide de la configuration de l'environnement pour créer l'Experimentation et vous connecter au serveur MLflow Tracking.

Définir et tracer votre application​

La simple application de chat ci-dessous appelle un modèle de fondation hébergé par Databricks pour répondre aux queries des utilisateurs.

Le traçage est effectué à l'aide de :

  • mlflow.openai.autolog() pour journaliser automatiquement les appels client OpenAI
  • @mlflow.trace pour tracer la logique d'application dans my_app()
  • mlflow.update_current_trace() pour ajouter du contexte aux traces dans my_app():
    • Contexte utilisateur et de session : des informations spécifiques à la query, telles que les ID utilisateur, peuvent être transmises à la logique d'application comme arguments.
    • Contexte de déploiement : Des informations spécifiques au déploiement, comme l'environnement ou la version de l'application, sont transmises à l'application via des variables d'environnement, ce qui simplifie les modifications de configuration entre les déploiements.

MLflow remplit automatiquement certaines métadonnées dans les traces, mais vous pouvez remplacer les valeurs default. Vous pouvez également définir des métadonnées personnalisées. L'exemple ci-dessous illustre les deux.

Python

import mlflow
import os
from databricks_openai import DatabricksOpenAI

mlflow.openai.autolog()

@mlflow.trace
def my_app(user_id: str, session_id: str, message: str) -> str:
    """Process a chat message with extra content logging for traces."""

    # Add user and session context to the current trace.
    # The @mlflow.trace decorator ensures there is an active trace.
    mlflow.update_current_trace(
        metadata={
            "mlflow.trace.user": user_id,
            "mlflow.trace.session": session_id,
        },
        tags={
          "query_category": "chat",  # Example of a custom tag
        },
    )

    app_environment = os.getenv("APP_ENVIRONMENT", "development")
    mlflow.update_current_trace(
        metadata={
            # Override automatically populated metadata
            "mlflow.source.type": app_environment,  # Override default LOCAL/NOTEBOOK
            # Add custom metadata
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
        }
    )

    # The trace will capture the execution time, inputs, outputs, and any errors
    # Your chat logic here
    response = chat_completion(message)
    return response


# Basic chat logic
def chat_completion(message: str) -> str:
    # Create an OpenAI client that is connected to Databricks-hosted LLMs
    client = DatabricksOpenAI()

    response = client.chat.completions.create(
        model="databricks-claude-sonnet-4",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant. Give brief, 1-2 sentence responses.",
            },
            {
                "role": "user",
                "content": message,
            },
        ]
    )
    return response.choices[0].message.content

La logique d’application ci-dessus prend l’utilisateur, la session et d’autres métadonnées comme arguments de fonction. Dans une application de production, l’implémentation peut extraire les métadonnées des en-têtes d’un objet de requête. Par exemple, si l’application est déployée en tant qu’ application Databricks, elle peut accéder aux en-têtes HTTP avec des métadonnées.

Ensuite, simulez quelques utilisateurs et sessions différents, chacun avec une ou plusieurs interactions de discussion. Définissez les informations de déploiement à l'aide de variables d'environnement.

Python
# Set environment variables to log deployment-specific metadata with traces.
os.environ["APP_ENVIRONMENT"] = "staging"
os.environ["APP_VERSION"] = "1.0.0"
os.environ["DEPLOYMENT_ID"] = "deployment-123"

# Run the chat completion with user and session context to generate example traces:
for session in range(2):
  # 2 chat interactions per session for this user
  result = my_app(
      user_id="user-123",
      session_id=f"session-abc-{session}",
      message="What is MLflow and how does it help with GenAI?"
  )
  result = my_app(
      user_id="user-123",
      session_id=f"session-abc-{session}",
      message="What is ML vs. AI?"
  )

os.environ["APP_VERSION"] = "1.1.0"
os.environ["DEPLOYMENT_ID"] = "deployment-456"

for session in range(2):
  # 1 chat interaction per session for this user
  result = my_app(
      user_id="user-456",
      session_id=f"session-def-{session}",
      message="What is MLflow and how does it help with machine learning?"
  )

Rechercher des traces​

Toutes les analyses ci-dessous sont basées sur l’utilisation de mlflow.search_traces() pour collecter les traces pertinentes à des fins d’analyse :

Python
import mlflow
traces = mlflow.search_traces()
traces

Chaque trace est annotée avec le contexte supplémentaire enregistré dans l'application, tel que les ID utilisateur :

Python
first_trace = traces.iloc[0]
first_trace.trace_metadata['mlflow.trace.user']
Output
'user-456'

Analysez le comportement des utilisateurs​

Premièrement, analysez le comportement d'un utilisateur spécifique.

Python
import pandas as pd
import time

def analyze_user_behavior(user_id: str, days: int = 7):
    """Analyze activity patterns for a specific user."""

    cutoff_ms = int((time.time() - days * 86400) * 1000)

    traces = mlflow.search_traces(
        filter_string=f"metadata.`mlflow.trace.user` = '{user_id}' AND "
                      f"trace.timestamp_ms > {cutoff_ms}",
        order_by=["trace.timestamp_ms DESC"],
    )

    if len(traces) == 0:
        print(f"No activity found for user {user_id}")
        return

    # Calculate key metrics
    total_interactions = len(traces)
    unique_sessions = set(row.trace_metadata.get("mlflow.trace.session", "") for index, row in traces.iterrows())
    unique_sessions.discard("")

    print(f"User {user_id} Activity Report ({days} days)")
    print("=" * 50)
    print(f"Total interactions: {total_interactions}")
    print(f"Unique sessions: {len(unique_sessions)}")

    # Daily activity
    traces['date'] = pd.to_datetime(traces['request_time'], unit='ms').dt.date
    daily_activity = traces.groupby('date').size()
    print(f"\nDaily activity:")
    print(daily_activity.to_string())

    # Query categories
    query_categories = traces['tags'].apply(lambda tags: tags.get('query_category'))
    unique_categories = set(query_categories.dropna())
    category_counts = query_categories.value_counts()
    print(f"\nQuery categories:")
    print(category_counts.to_string())

    # Performance stats
    print(f"\nPerformance:")
    print(f"Average response time: {traces['execution_duration'].mean():.1f}ms")
    print(f"Error rate: {(traces['state'] == 'ERROR').mean() * 100:.1f}%")

    return traces
Python
analyze_user_behavior(user_id="user-123")
Output
User user-123 Activity Report (7 days)
==================================================
Total interactions: 4
Unique sessions: 2

Daily activity:
date
2025-12-12    4

Query categories:
tags
chat    4

Performance:
Average response time: 2177.5ms
Error rate: 0.0%

Analyser le flux de session​

Un utilisateur peut interagir avec votre application pour des conversations à plusieurs tours. L'analyse de la session tour par tour peut aider à illustrer l'expérience de l'utilisateur. Ci-dessous, les tours de conversation sont classés à l'aide des Timestamp de trace.

Python
def analyze_session_flow(session_id: str):
    """Analyze conversation flow within a session."""

    # Get all traces from a session, ordered chronologically
    session_traces = mlflow.search_traces(
        filter_string=f"metadata.`mlflow.trace.session` = '{session_id}'",
        order_by=["timestamp ASC"]
    )

    # Build a timeline of the conversation
    conversation_turns = []
    for index, row in session_traces.iterrows():
        conversation_turns.append({
            "turn": index + 1,
            "timestamp": int(row.request_time),
            "duration_ms": int(row.execution_duration),
            "status": str(row.state),
            "response": row.response,
        })

    return conversation_turns
Python
analyze_session_flow(session_id="session-abc-0")
Output
[{'turn': 1,
  'timestamp': 1765560306051,
  'duration_ms': 2570,
  'status': 'OK',
  'response': 'MLflow is an open-source platform for managing the machine learning lifecycle, including experiment tracking, model packaging, and deployment. For GenAI, it helps by providing tools to track experiments with large language models, manage model versions, log prompts and responses, and deploy AI models at scale while maintaining reproducibility and governance.'},
 {'turn': 2,
  'timestamp': 1765560308943,
  'duration_ms': 2644,
  'status': 'OK',
  'response': 'AI (Artificial Intelligence) is the broader field focused on creating machines that can perform tasks requiring human-like intelligence, while ML (Machine Learning) is a subset of AI that specifically uses algorithms to learn patterns from data without being explicitly programmed for each task. Think of AI as the goal and ML as one of the main methods to achieve it.'}]

Analyser les environnements et les versions​

Les métadonnées de déploiement telles que la version de l’environnement ou de l’application peuvent être analysées de manière similaire aux utilisateurs et aux sessions. L'analyse des déploiements peut aider à suivre les améliorations ou les dégradations en matière de qualité, de latence ou d'autres métriques importantes à mesure que vous itérez sur votre application.

Python
traces = mlflow.search_traces()

traces['app_version'] = traces['trace_metadata'].apply(lambda meta: meta.get('app_version'))
traces['user_id'] = traces['trace_metadata'].apply(lambda meta: meta.get('mlflow.trace.user'))
traces['app_environment'] = traces['trace_metadata'].apply(lambda meta: meta.get('mlflow.source.type'))

interactions_per_version = traces.groupby('app_version').size()
print(f"Interactions per app version:")
print(interactions_per_version.to_string())

users_per_version = traces.groupby('app_version')['user_id'].nunique()
print(f"\nDistinct users per app version:")
print(users_per_version.to_string())

interactions_per_environment = traces.groupby('app_environment').size()
print(f"\nInteractions per app environment:")
print(interactions_per_environment.to_string())
Output
Interactions per app version:
app_version
1.0.0    4
1.1.0    4

Distinct users per app version:
app_version
1.0.0    1
1.1.0    1

Interactions per app environment:
app_environment
staging    8

Étapes suivantes​

Exemple de Notebook​

Tutoriel : Suivre et analyser les utilisateurs et les environnements

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks
Sur cette page