Adicionar contexto aos rastreamentos

Adicionar contexto aos rastreamentos permite acompanhar detalhes da execução, analisar o comportamento do usuário, depurar problemas em diferentes ambientes e monitorar o desempenho do aplicativo. O MLflow fornece campos de metadados padronizados para tipos de contexto comuns, além da flexibilidade para adicionar metadados personalizados específicos para sua aplicação.

Pré-requisitos

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

Production

Para implantações em 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 mlflow[databricks] inclui todos os recursos necessários para desenvolvimento local e experimentação no Databricks.

nota

MLflow 3 é necessário para acompanhamento do contexto. MLflow 2.x não é suportado devido a limitações de desempenho e à falta de recursos essenciais para uso em produção.

Tipos de metadados de contexto

Aplicações de produção precisam rastrear vários elementos contextuais simultaneamente. MLflow padronizou campos de metadados para capturar informações contextuais importantes:

Tipo de contexto	Casos de uso	Campo MLflow
ID da solicitação do cliente	Vincule rastreamentos a solicitações de clientes ou chamadas de API específicas para depuração de ponta a ponta.	TraceInfo Parâmetro client_request_id
ID da sessão do usuário	Agrupe registros de conversas com várias interações, permitindo analisar todo o fluxo da conversa.	mlflow.trace.session Metadados
ID do usuário	Associe rastros a usuários específicos para personalização, análise de coorte e depuração específica do usuário.	mlflow.trace.user Metadados
Dados ambientais	Acompanhe o contexto de implantação (ambiente, versão, região) para fins operacionais e descubra diferentes implantações.	metadados automáticos e metadados personalizados
Metadados personalizados	Adicione metadados específicos do aplicativo para rastreamentos de organização, pesquisa e filtragem.	(sua chave de metadados)

Rastrear usuários e sessões

Acompanhar usuários e sessões em seu aplicativo GenAI fornece um contexto essencial para entender o comportamento do usuário, analisar fluxos de conversação e aprimorar a personalização.

Por que rastrear usuários e sessões?

O acompanhamento de usuários e sessões 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 - Analise conversas com múltiplas interações e a retenção do contexto.
3. Personalização - Identificar padrões para aprimorar 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 - Manter o contexto em múltiplas interações.

Campos de metadados padrão para usuários e sessões

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

• mlflow.trace.user - Associa rastros a usuários específicos
• mlflow.trace.session - Agrupamentos de registros pertencentes a conversas com múltiplas interações

Ao usar esses campos de metadados padrão, o MLflow habilita automaticamente a filtragem e o agrupamento na interface do usuário. Diferentemente tags, os metadados não podem ser atualizados depois que o rastreamento é registrado, tornando-os 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 principais:

• 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 após a criação do rastreamento.

Acompanhe os ambientes e versões.

Acompanhar o ambiente de execução e a versão do aplicativo GenAI permite depurar problemas de desempenho e qualidade relacionados ao código. Esses metadados permitem:

• Análise específica do ambiente em development, staging e production
• acompanhamento de desempenho/qualidade e detecção de regressão entre versões de aplicativos
• Análise de causa raiz mais rápida quando ocorrem problemas.

nota

Para uma visão geral completa de como funciona o versionamento, consulte Acompanhamento de versões.

Metadados preenchidos automaticamente

Esses campos de metadados padrão são capturados automaticamente pelo MLflow com base no seu ambiente de execução.

importante

Se a lógica de captura automática não atender aos seus requisitos, você pode substituir manualmente esses metadados preenchidos automaticamente usando mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"}).

Categoria	Campo de metadados	Descrição	Lógica de configuração automática
Ambiente de execução	mlflow.source.name	O ponto de entrada ou script que gerou o rastreamento.	Preenchido automaticamente com o nome do arquivo para scripts Python e o nome do Notebook para Databricks/Jupyter Notebook.
	mlflow.source.git.commit	Hash do commit do Git.	Se for executado a partir de um repositório Git , o hash commit é automaticamente detectado e preenchido.
	mlflow.source.git.branch	Ramificação Git.	Se a execução ocorrer a partir de um repositório Git , o nome da branch atual será detectado e preenchido automaticamente.
	mlflow.source.git.repoURL	URL repo Git .	Se for executado a partir de um repositório Git , a URL do repositório é automaticamente detectada e preenchida.
	mlflow.source.type	Captura o ambiente de execução.	Definido automaticamente como NOTEBOOK se estiver sendo executado no Jupyter ou Databricks Notebook, LOCAL se estiver executando um script Python local, caso contrário, UNKNOWN (detectado automaticamente). Em seu aplicativo implantado, sugerimos atualizar esta variável com base no ambiente, por exemplo, PRODUCTION, STAGING, etc.
Versão do aplicativo	metadata.mlflow.modelId	ID do modelo registrado no MLflow.	Definido automaticamente para o valor do ID do modelo na variável de ambiente MLFLOW_ACTIVE_MODEL_ID ou para o ID do modelo definido através da função mlflow.set_active_model() .

Personalizando metadados preenchidos automaticamente

Você pode substituir qualquer um dos campos de metadados preenchidos automaticamente usando mlflow.update_current_trace(). Isso é útil quando a detecção automática não atende às suas necessidades ou quando você deseja adicionar contexto adicional:

Python

import mlflow
import os

# We suggest populating metadata from environment variables rather than hard coding the values

@mlflow.trace
def my_app(user_question: str) -> dict:
    # Override automatically populated metadata and add custom context
    mlflow.update_current_trace(
        metadata={
            # Use any of the keys from above
            "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default LOCAL/NOTEBOOK
        }
    )

    # Application logic

    return {"response": user_question + "!!"}

my_app("test")

Adicionar metadados personalizados

Você pode anexar metadados personalizados para capturar qualquer contexto específico do aplicativo. Por exemplo, você pode querer anexar informações como:

• app_version: por exemplo, "1.0.0" (da variável de ambiente APP_VERSION )
• deployment_id: por exemplo, "deploy-abc-123" (da variável de ambiente DEPLOYMENT_ID )
• region: por exemplo, "us-east-1" (da variável de ambiente REGION )
• (Outros metadados personalizados, como sinalizadores de recurso, também podem ser adicionados)

Python

import mlflow
import os

# We suggest populating metadata from environment variables rather than hard coding the values

@mlflow.trace
def my_app(user_question: str) -> dict:
    # Add custom context
    mlflow.update_current_trace(
        metadata={
            # Use any key
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
            "region": os.getenv("REGION", "us-east-1")
        }
    )

    # Application logic

    return {"response": user_question + "!!"}

my_app("test")

Exemplo de aplicação web de produção

Em aplicações de produção, normalmente você monitora o contexto do usuário, da sessão e do ambiente simultaneamente. O exemplo FastAPI a seguir demonstra como capturar todos os tipos de contexto em conjunto:

Python

import mlflow
import os
from fastapi import FastAPI, Request
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 decorator
def handle_chat(request: Request, chat_request: ChatRequest):
    # Retrieve all context from request headers
    client_request_id = request.headers.get("X-Request-ID")
    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,
            # Override automatically populated environment metadata
            "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default LOCAL/NOTEBOOK
            # Add custom environment metadata
            "environment": "production",
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
            "region": os.getenv("REGION", "us-east-1"),
            # Add custom tags
            "my_custom_tag": "custom tag value",
        }
    )

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

Este exemplo demonstra uma abordagem unificada para o acompanhamento contextual, capturando:

• ID da solicitação do cliente : A partir do cabeçalho X-Request-ID , registra usando o parâmetro client_request_id .
• Informações do usuário : no cabeçalho X-User-ID , registra como metadados mlflow.trace.user .
• Informações da sessão : no cabeçalho X-Session-ID , registra como metadados mlflow.trace.session .
• Contexto do ambiente : A partir de variáveis de ambiente e detecção automática, com opções de sobrescrita para configurações de produção.
• Versão do aplicativo : obtida da variável de ambiente APP_VERSION .
• Detalhes da implantação : Metadados personalizados para o ID da implantação e região.

Melhores práticas

1. Formatos de ID consistentes - Utilize formatos padronizados para IDs de usuário e de sessão em todo o seu aplicativo.
2. Limites da sessão - Defina regras claras para quando as sessões começam e terminam.
3. variável de ambiente - Preencher metadados da variável de ambiente em vez de valores codificados
4. Combine tipos de contexto - Rastreie o contexto do usuário, da sessão e do ambiente em conjunto para obter rastreabilidade completa.
5. Análise regular – Configure painéis para monitorar o comportamento do usuário, padrões de sessão e desempenho da versão
6. Substitua os valores padrão com cuidado - Substitua os metadados preenchidos automaticamente somente quando necessário.

Próximos passos

Depois de adicionar os metadados do usuário e da sessão, você poderá:

• Pesquise e filtre rastros - Consulte rastros usando os metadados de contexto que você adicionou.
• Analisar a atividade do usuário - Padrões prontos para produção para analisar o comportamento do usuário