Tutorial: Rastrear e analisar utilizadores e ambientes

Abrir a versão desta página do bloco de notas

Este tutorial demonstra como adicionar contexto a traços para rastrear e analisar utilizadores, sessões e implementações.

Numa simples aplicação de chat, vais usar mlflow.update_current_trace() para adicionar metadados e etiquetas personalizadas aos rastreios.
Para analisar rastos, irá utilizar mlflow.search_traces() para extrair rastos relevantes e calcular estatísticas para utilizadores, sessões, ambientes e versões da aplicação.

Configuração do ambiente

Instalar pacotes necessários:

mlflow[databricks]: Use a versão mais recente do MLflow para obter mais recursos e melhorias.
openai: Este aplicativo usará o cliente OpenAI API para chamar modelos hospedados pelo Databricks.

%pip install -qq --upgrade "mlflow[databricks]>=3.1.0" openai
dbutils.library.restartPython()

Crie um experimento MLflow. Se estiver a utilizar um bloco de notas Databricks, pode ignorar este passo e utilizar a experiência predefinida do bloco de notas. Caso contrário, siga o início rápido de configuração do ambiente para criar o experimento e conectar-se ao servidor MLflow Tracking.

Defina e rastreie a sua aplicação

A aplicação de chat simples abaixo chama um modelo fundamental alojado no Databricks para responder a perguntas dos utilizadores.

O rastreio é feito usando:

mlflow.openai.autolog() para registar automaticamente chamadas de clientes do OpenAI
@mlflow.trace para traçar a lógica de aplicação em my_app()
mlflow.update_current_trace() Para adicionar contexto aos rastros dentro de my_app():
- Contexto do utilizador e da sessão: Informação específica da consulta, como IDs de utilizador, pode ser passada à lógica da aplicação como argumentos.
- Contexto de implementação: Informações específicas da implementação, como o ambiente ou a versão da aplicação, são passadas para a aplicação através de variáveis de ambiente, o que simplifica as alterações de configuração entre implementações.

O MLflow preenche automaticamente alguns metadados nos traços, mas podes sobrescrever os valores predefinidos. Também pode definir metadados personalizados. O exemplo abaixo demonstra ambos.


import mlflow
import os
from databricks.sdk import WorkspaceClient

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
    w = WorkspaceClient()
    client = w.serving_endpoints.get_open_ai_client()

    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

A lógica de aplicação acima aceita os metadados de utilizador, sessão e outros como argumentos de função. Numa aplicação de produção, a implementação pode extrair metadados de cabeçalhos num objeto de pedido. Por exemplo, se a aplicação for implementada como uma aplicação Databricks, então a aplicação pode aceder a cabeçalhos HTTP com metadados.

De seguida, simule vários utilizadores e sessões diferentes, cada uma com uma ou mais interações de chat. Defina a informação de implementação usando variáveis de ambiente.

# 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?"
  )

Registos de pesquisa

Todas as análises abaixo baseiam-se na utilização de mlflow.search_traces() para recolher pistas relevantes para análise.

import mlflow
traces = mlflow.search_traces()
traces

Cada traço é anotado com o contexto adicional registado na aplicação, como IDs de utilizador:

first_trace = traces.iloc[0]
first_trace.trace_metadata['mlflow.trace.user']

'user-456'

Analisar o comportamento do utilizador

Primeiro, analise o comportamento de um utilizador específico.

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

analyze_user_behavior(user_id="user-123")

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%

Analisar o fluxo da sessão

Um utilizador pode interagir com a sua aplicação para conversas com múltiplos turnos. Analisar a sessão passo a lado pode ajudar a ilustrar a experiência do utilizador. Abaixo, os turnos de conversa estão organizados usando carimbos de rastreio.

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

analyze_session_flow(session_id="session-abc-0")

[{'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.'}]

Analisar ambientes e versões

Metadados de implementação, como o ambiente ou a versão da aplicação, podem ser analisados de forma semelhante aos utilizadores e sessões. Analisar implementações pode ajudar a acompanhar melhorias ou degradações na qualidade, latência ou outras métricas importantes à medida que itera na sua aplicação.

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())

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

Próximos passos

Adicione contexto aos traços - Saiba mais sobre como adicionar metadados e etiquetas personalizados aos traços.
Procurar rastros programaticamente - Saiba mais sobre a utilização de mlflow.search_traces().
Analisar traços - Veja outros exemplos de análise de traços.

Exemplo de bloco de notas

Tutorial: Rastrear e analisar utilizadores e ambientes

Obter bloco de notas

Feedback

Esta página foi útil?

Last updated on 2025-12-19

Partilhar via

Tutorial: Rastrear e analisar utilizadores e ambientes

Configuração do ambiente

Defina e rastreie a sua aplicação

Registos de pesquisa

Analisar o comportamento do utilizador

Analisar o fluxo da sessão

Analisar ambientes e versões

Próximos passos

Exemplo de bloco de notas

Tutorial: Rastrear e analisar utilizadores e ambientes

Feedback

Recursos adicionais