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:

Production

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.

Development

Para ambientes de desenvolvimento, instale o pacote completo do MLflow com os extras do Databricks:

Bash

pip install --upgrade "mlflow[databricks]>=3.1"

O pacote completo do mlflow[databricks] inclui todos os recursos necessários para o desenvolvimento local e a experimentação no Databricks.

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

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

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 de Adicionar metadados e feedback do usuário aos rastreamentos e também incorpora o ambiente e o contexto de implantação, conforme mostrado no exemplo de aplicativo web de produção:

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:

• Avaliação - Compare as métricas de qualidade em diferentes segmentos de usuários para identificar áreas de melhoria
• Monitoramento da produção - Acompanhe os padrões de desempenho por grupos de usuários ou tipos de sessão
• Coleta de feedback - Associe o feedback do usuário a sessões específicas para análise de qualidade
• Criação do conjunto de dados de avaliação - Crie um conjunto de dados direcionado a partir de sessões de usuários específicos

Considerações de produção

Para uma implementação abrangente da produção, consulte Adicionar metadados e feedback do usuário aos rastreamentos, 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

• Implantar agentes com rastreamento - Entender os rastreamentos de registro na produção
• Monitore ambientes e contexto - Adicione metadados de implantação e ambiente aos rastreamentos
• Colete feedback do usuário - Capture sinais de qualidade dos usuários

referências de recursos

Para obter detalhes sobre os conceitos e recursos deste guia, consulte:

• Modelo de dados de rastreamento - Entenda metadados, tags e estrutura de rastreamento
• Traços de consulta via SDK - Aprenda técnicas avançadas de consulta
• Conceitos de monitoramento da produção - Explorar padrões de monitoramento