Pular para o conteúdo principal

Rastreie as sessões & dos usuários

O acompanhamento de usuários e sessões em seu aplicativo GenAI fornece um contexto essencial para entender o comportamento do usuário, analisar os fluxos de conversa e melhorar a personalização. MLflow oferece suporte integrado para associar traços a usuários e agrupá-los em sessões.

Pré-requisitos​

Escolha o método de instalação apropriado com base no seu ambiente:

Para implementações de produção, instale o pacote mlflow-tracing:

Bash
pip install --upgrade mlflow-tracing

O pacote mlflow-tracing é otimizado para uso em produção com dependências mínimas e melhores características de desempenho.

nota

MLflow 3 é necessário para o acompanhamento do usuário e da sessão. MLflow O 2.x não é compatível devido a limitações de desempenho e à falta de recursos essenciais para uso em produção.

Por que rastrear usuários e sessões?​

O acompanhamento do usuário e da sessão permite análises e melhorias poderosas:

  1. Análise do comportamento do usuário - Entenda como diferentes usuários interagem com seu aplicativo
  2. Acompanhamento do fluxo de conversação - Analise conversas com vários turnos e retenção de contexto
  3. Percepções de personalização - Identificar padrões para melhorar as experiências específicas do usuário
  4. Qualidade por usuário - Acompanhe as métricas de desempenho em diferentes segmentos de usuários
  5. Continuidade da sessão - mantenha o contexto em várias interações

Campos de metadados padrão do MLflow​

MLflow fornece dois campos de metadados padrão para acompanhamento da sessão e do usuário:

  • mlflow.trace.user - Associa rastreamentos a usuários específicos
  • mlflow.trace.session - Traços de grupos pertencentes a conversas de vários turnos

Quando o senhor usa esses campos de metadados padrão, o MLflow ativa automaticamente a filtragem e o agrupamento na interface do usuário. Ao contrário das tags, os metadados não podem ser atualizados depois que o rastreamento é registrado, o que os torna ideais para identificadores imutáveis, como IDs de usuário e de sessão.

Implementação básica​

Veja como adicionar acompanhamento de usuário e sessão ao seu aplicativo:

Python
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
        }
    )

    # Your chat logic here
    # The trace will capture the execution time, inputs, outputs, and any errors
    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
    )

pontos-chave:

  • O decorador @mlflow.trace cria automaticamente um rastreamento para a execução da função
  • mlflow.update_current_trace() adiciona o ID do usuário e o ID da sessão como metadados ao rastreamento ativo
  • O uso de metadata garante que esses identificadores sejam imutáveis quando o rastreamento for criado

Exemplo de aplicativo web de produção​

Nos aplicativos de produção, o usuário, a sessão e outras informações contextuais são normalmente rastreadas simultaneamente. O exemplo a seguir foi adaptado do nosso guia Production Observability with Tracing e também incorpora o ambiente e o contexto de implantação, conforme mostrado no guia Track Environments & Context:

Python
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?"}'

Esse exemplo demonstra uma abordagem unificada para o acompanhamento do contexto, capturando:

  • Informações do usuário : Do cabeçalho X-User-ID, registros como metadados mlflow.trace.user.
  • Informações sobre a sessão : Do cabeçalho X-Session-ID, registros como metadados mlflow.trace.session.

Consultando e analisando dados​

Usando a interface de usuário do MLflow​

Filtre os rastreamentos na interface do usuário do MLflow usando essas consultas de pesquisa:

# 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'

Análise programática​

Use o MLflow SDK para analisar os dados do usuário e da sessão de forma programática. Isso permite que o senhor crie análises personalizadas, gere relatórios e monitore os padrões de comportamento do usuário em escala.

Python
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

principais recursos:

  • Análise do comportamento do usuário - Acompanhe a frequência de interação, a contagem de sessões e o desempenho métrico por usuário
  • Análise do fluxo da sessão - Reconstrua as linhas do tempo da conversa para entender as interações de várias voltas
  • Filtragem flexível - Use a sintaxe de pesquisa do MLflow para consultar traços por qualquer combinação de campos de metadados
  • Análise escalonável - Processe milhares de traços de forma programática para percepções de grande escala
  • Dados prontos para exportação - Os resultados podem ser facilmente convertidos em DataFrames ou exportados para análise posterior

Melhores práticas​

  1. Formatos de ID consistentes - Use formatos padronizados para IDs de usuário e sessão
  2. Limites da sessão - Defina regras claras para quando as sessões começam e terminam
  3. Enriquecimento de metadados - Adicione contexto adicional, como segmentos de usuário ou tipos de sessão
  4. Combine com o acompanhamento de solicitações - Vincule dados de usuário/sessão com IDs de solicitações para rastreabilidade completa
  5. Análise regular - Configure painéis de controle para monitorar o comportamento do usuário e os padrões de sessão

Integração com outros MLflow recurso​

O acompanhamento de usuários e sessões integra-se perfeitamente a outros recursos do site MLflow:

Considerações de produção​

Para uma implementação abrangente de produção, consulte nosso guia sobre observabilidade de produção com rastreamento, que abrange:

  • Configuração do acompanhamento de usuários e sessões em ambientes de produção
  • Combinando IDs de sessão com IDs de solicitação para total rastreabilidade
  • Implementando a coleta de feedback para sessões inteiras
  • Práticas recomendadas para gerenciamento de sessões de alto volume

Próximas etapas​

Continue sua jornada com estas ações recomendadas e o tutorial.

Guia de referência​

Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.

Última atualização em