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.

Requisitos

Instale o pacote apropriado para rastreamento 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.

Implementação

Para adicionar metadados e tags aos rastreamentos:

1. Acompanhe o andamento da sua candidatura. Na maioria das vezes, você usará o decorador @mlflow.trace para rastrear funções automaticamente.
2. Durante a execução do seu aplicativo, chame mlflow.update_current_trace() para adicionar contexto aos rastreamentos usando tags ou metadata. Após a conclusão do seu aplicativo e um rastreamento ser registrado, tags são mutáveis, mas metadata são imutáveis no rastreamento de logs.

Python

import mlflow
mlflow.update_current_trace(
    metadata={
        "mlflow.trace.user": user_id,
        "mlflow.trace.session": session_id,
    },
    tags={
        "query_category": "chat",  # Example of a custom tag
    },
)

Para acessar metadados e tags em logs de rastreamento, use os campos metadata e tags no DataFrame Pandas retornado por mlflow.search_traces() ou use os campos Trace.info.trace_metadata e Trace.info.tags dos objetos Trace .

Consulte o tutorial: Rastrear e analisar usuários e ambientes para obter um tutorial completo.

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.

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.

Para metadados de implantação, como ambientes e versões, seu aplicativo geralmente deve extrair os metadados da variável de ambiente, em vez de tê-los codificados diretamente no aplicativo. variável de ambiente simplifica o processo de implantação. Por exemplo:

Python

import mlflow
import os

# In your application logic
mlflow.update_current_trace(
    metadata={
        "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default
    }
)

nota

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

Metadados preenchidos automaticamente

O MLflow define automaticamente determinados campos de metadados padrão com base no seu ambiente de execução.

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. Por exemplo, substitua o valor do ambiente de execução 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.
	mlflow.sourceRun	O ID de execução da execução de origem que gerou o rastreamento.	Definido automaticamente para o ID de execução da execução de origem que gerou o rastreamento.
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() .

Adicionar metadados personalizados

Você usa a chave personalizada metadata para capturar qualquer outro contexto específico do aplicativo. Por exemplo, você pode querer anexar informações como:

• Versão do aplicativo
• ID de implantação
• Região de implantação
• sinalizadores de recurso

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

• Tutorial: Rastrear e analisar usuários e ambientes - Veja um exemplo completo de como adicionar metadados de usuário, sessão, ambiente e versão do aplicativo aos rastreamentos.
• Pesquise rastros programaticamente - Saiba mais sobre como usar mlflow.search_traces().
• Analisar vestígios - Veja exemplos de análise de vestígios.