Debug & Observe seu aplicativo com rastreamento
Quando o aplicativo GenAI é instrumentado com o MLflow Tracing, o senhor ganha ferramentas poderosas para depurar seu comportamento, entender seu desempenho e observar suas entradas e saídas. Este guia se concentra em como usar efetivamente a interface do usuário MLflow em Databricks e aproveitar a integração do Notebook para esses fins.
Revisão de rastreamentos na interface de usuário do Databricks MLflow
Todos os traços capturados são registrados em um MLflow Experiment. O senhor pode acessá-los por meio da UI MLflow em seu Databricks workspace.
- Navegue até seu experimento : Vá para o experimento em que seus traces são logs (por exemplo, aquele definido por
mlflow.set_experiment("/Shared/my-genai-app-traces")
). - Abra a guia "Traces": No experimento view, clique na guia "Traces" tab. Isso exibirá uma lista de todos os registros de rastreamento para esse experimento.
Entendendo a visualização da lista de traços
A lista de rastreamentos fornece uma visão geral de alto nível de seus rastreamentos, com colunas classificáveis que normalmente incluem:
- ID de rastreamento : o identificador exclusivo de cada rastreamento.
- Solicitação : uma prévia da entrada inicial que acionou o rastreamento.
- Resposta : Uma prévia da saída final do rastreamento.
- Sessão : o identificador da sessão, se fornecido, agrupando rastreamentos relacionados (por exemplo, em uma conversa).
- Usuário : O identificador do usuário, se fornecido.
- Tempo de execução : Tempo total necessário para a conclusão do rastreamento.
- Hora da solicitação : a data e hora em que o rastreamento foi iniciado.
- Nome da execução : se o rastreamento estiver associado a uma execução do MLflow, seu nome será exibido aqui, vinculando-os.
- Fonte : A origem do rastreamento, geralmente indicando a biblioteca ou o componente instrumentado (por exemplo,
openai
,langchain
, ou um nome de rastreamento personalizado). - Estado : O status atual do rastreamento (por exemplo,
OK
,ERROR
,IN_PROGRESS
). - Nome do rastreamento : o nome específico atribuído a esse rastreamento, geralmente o nome do intervalo raiz.
- Avaliações : colunas individuais para cada tipo de avaliação (por exemplo,
my_scorer
,professional
). A UI também costuma exibir uma seção de resumo acima da lista, mostrando métricas de avaliação agregadas (como médias ou taxas de aprovação/reprovação) nos traços visíveis no momento. - Tags : tags individuais podem ser exibidas como colunas (por exemplo,
persona
,style
). Uma contagem resumida de tags também pode estar presente.
Pesquisando e filtrando traços
A interface do usuário oferece várias maneiras de encontrar e focar em traços relevantes:
-
Barra de pesquisa (geralmente o rótulo "Avaliações de pesquisa por solicitação" ou similar): Isso permite que o senhor encontre rapidamente os rastros pesquisando o conteúdo do campo
Request
(input). -
Filtros : Para uma filtragem mais estruturada, use o "Filters" dropdown. Isso normalmente permite que você crie consultas com base em:
- Atributos : como conteúdo
Request
,Session time
,Execution time
ouRequest time
. - Avaliações : filtre pela presença ou valores específicos de avaliações, como
my_scorer
ouprofessional
. - Outros campos, como
State
,Trace name
,Session
,User
eTags
(por exemplo,tags.persona = 'expert'
).
- Atributos : como conteúdo
-
Menu suspenso Classificar : Use a opção "Sort" dropdown para ordenar os rastros por várias colunas, como
Request time
,Execution time
, etc. -
Menu suspenso Colunas : Personalize quais colunas são visíveis na lista de rastreamento, incluindo tags específicas ou métricas de avaliação.
Para obter informações sobre consultas programáticas avançadas e entender a sintaxe do filtro que a interface do usuário pode usar, consulte o guia Query traces via SDK.
Explorando um traço individual
Para se aprofundar em um rastreamento específico, clique em sua Solicitação ou Nome do Rastreamento na lista. Isso abre o rastreamento detalhado view, que normalmente tem alguns painéis principais:
-
Detalhamento do traço (painel esquerdo) :
- Esse painel (geralmente intitulado " Trace breakdown ") exibe a hierarquia de extensão como um gráfico de árvore ou cascata. Ele mostra todas as operações (spans) dentro do rastreamento, seus relacionamentos pai-filho e sua ordem de execução e duração.
- Você pode selecionar vãos individuais desse detalhamento para inspecionar seus detalhes específicos.
-
Detalhes da extensão (painel central) :
-
Quando um intervalo é selecionado no detalhamento do rastreamento, esse painel mostra suas informações detalhadas, geralmente organizadas em guias como
- Bate-papo : Para as interações do LLM que são baseadas em bate-papo, esse tab geralmente fornece um view renderizado do fluxo da conversa (usuário, assistente, mensagens da ferramenta).
- Entradas/Saídas : Exibe os dados brutos de entrada passados para as operações e os dados brutos de saída retornados. Para conteúdo grande, um botão de alternância "Ver mais" / "Ver menos" pode estar disponível para expandir ou recolher o view.
- Atributos : Mostra key-value metadata específico para a extensão (por exemplo,
model
name,temperature
para uma chamada LLM;doc_uri
para uma extensão retriever).
-
Eventos : Para os períodos que encontraram erros, esse tab normalmente mostra detalhes de exceção e rastreamentos de pilha. Para períodos de transmissão, ele pode mostrar blocos de dados individuais à medida que foram gerados.
-
Alguns campos de saída também podem ter um botão de alternância de Markdown para alternar entre a exibição bruta e a renderizada se o conteúdo estiver no formato Markdown.
-
-
Avaliações (painel direito) :
- Esse painel exibe todas as avaliações (feedback ou avaliações do usuário) que foram registradas para todo o rastreamento ou para o intervalo selecionado no momento .
- É importante ressaltar que esse painel geralmente inclui um botão "+ Add new assessment", permitindo que o senhor faça log novos feedbacks ou pontuações de avaliação diretamente da interface do usuário durante a revisão de um rastreamento. Isso é muito útil para revisão de manuais e rótulo fluxo de trabalho.
Informações em nível de traço : Além dos detalhes de cada vão, o site view também fornece acesso às informações gerais do traço. Isso inclui tags em nível de rastreamento e quaisquer registros de avaliações para todo o rastreamento (geralmente visíveis no painel Avaliações quando nenhum intervalo específico ou o intervalo raiz é selecionado), que podem se originar de feedback direto do usuário ou de avaliações sistemáticas.
Cenários comuns de depuração e observação
Veja como o senhor pode usar a UI MLflow Tracing para atender às necessidades comuns de depuração e observabilidade:
-
Identificação de traços lentos (gargalos de latência ):
- Na visualização Trace List (Lista de traços ): Use a opção "Sort" dropdown para classificar os rastreamentos por "Tempo de execução" em ordem decrescente. Isso trará os traços mais lentos para o topo.
- Na visualização Detailed Trace (Rastreamento detalhado ): Quando o senhor abrir um rastreamento lento, examine o painel "Trace breakdown". A exibição em cascata dos intervalos destacará visualmente as operações mais demoradas, ajudando o senhor a identificar os gargalos de latência no fluxo do aplicativo.
-
Encontrando rastros de um usuário específico :
- Uso de filtros : Se tiver rastreado as informações do usuário e elas estiverem disponíveis como opção de filtro (por exemplo, em "Attributes" ou em um filtro dedicado "User" em "Filters" dropdown), o senhor poderá selecionar ou inserir o ID do usuário específico.
- Usando pesquisa/tags : alternativamente, se os IDs de usuário forem armazenados como tags (por exemplo,
mlflow.trace.user
), use a barra de pesquisa com uma consulta comotags.mlflow.trace.user = 'user_example_123'
.
-
Localizando traços com falhas (erros) :
- Uso de filtros : Na seção "Filtros" dropdown, selecione o atributo
State
e escolhaERROR
para ver apenas os rastreamentos que falharam. - Na visualização Detailed Trace (Rastreamento detalhado ): Para um rastreamento de erro, selecione o intervalo marcado com um erro no detalhamento do rastreamento "" . Navegue até "Events" tab no painel Span Details para view a mensagem de exceção e o rastreamento de pilha, que são cruciais para diagnosticar a causa raiz da falha.
- Uso de filtros : Na seção "Filtros" dropdown, selecione o atributo
-
Identificação de traços com feedback negativo ou problemas (por exemplo, respostas incorretas) :
- Uso de filtros de avaliação : Se estiver coletando feedback do usuário ou executando avaliações que resultem em avaliações (por exemplo, um booleano
is_correct
ou um numéricorelevance_score
), os filtros "" dropdown podem permitir que o senhor filtre por esses nomes de avaliação e seus valores (por exemplo, filtre poris_correct = false
ourelevance_score < 0.5
). - Visualização de avaliações : Abra um rastreamento e verifique o painel "Assessments" (à direita no site detalhado view) ou as avaliações individuais do intervalo. Isso mostrará os comentários, as pontuações e as justificativas dos registros, ajudando o senhor a entender por que uma resposta foi marcada como de baixa qualidade.
- Uso de filtros de avaliação : Se estiver coletando feedback do usuário ou executando avaliações que resultem em avaliações (por exemplo, um booleano
Esses exemplos demonstram como as informações detalhadas capturadas pelo site MLflow Tracing, combinadas com os recursos de visualização e filtragem da interface do usuário, permitem que o senhor depure problemas com eficiência e observe o comportamento do aplicativo.
Integração do Databricks Notebook para Traces
MLflow Tracing oferece uma experiência perfeita no Databricks Notebook, permitindo que o senhor view rastreie diretamente como parte do seu fluxo de trabalho de desenvolvimento e experimentação.
A integração MLflow Tracing Databricks Notebook está disponível em MLflow 2.20 e acima.
Como funciona
Ao trabalhar em um notebook Databricks e o URI de acompanhamento MLflow estiver definido como "databricks"
(que geralmente é default ou pode ser definido por meio de mlflow.set_tracking_uri("databricks")
), a UI de rastreamento pode ser exibida automaticamente na saída de uma célula.
Isso normalmente ocorre quando:
- A execução do código de uma célula gera um rastreamento (por exemplo, chamando uma função decorada com
@mlflow.trace
ou uma chamada de biblioteca autoinstrumentada). - Você chama explicitamente
mlflow.search_traces()
e o resultado é exibido. - Um objeto
mlflow.entities.Trace
(por exemplo, demlflow.get_trace()
) é a última expressão em uma célula ou é passado paradisplay()
.
Esse notebook view oferece os mesmos recursos avançados e interativos de exploração de traços encontrados na interface de usuário principal do MLflow Experiments, ajudando o usuário a iterar mais rapidamente sem alternar o contexto.
Controle do site Notebook Display
- Para desativar a exibição automática de traços nas saídas de células do Notebook, o senhor pode executar:
mlflow.tracing.disable_notebook_display()
- Para reativá-lo , execute:
mlflow.tracing.enable_notebook_display()
Acesso e gerenciamento programáticos
Além da interface do usuário, o MLflow fornece APIs para interagir com os rastreamentos de forma programática:
- Consultar traços via SDK : Saiba como pesquisar, filtrar e recuperar o uso de dados de rastreamento Python para análise personalizada, criação de conjunto de dados de avaliação ou integração com outros sistemas.
- Excluir rastreamentos : entenda como remover rastreamentos com base em critérios específicos para o gerenciamento do ciclo de vida dos dados.
Ao combinar a exploração baseada em UI com o acesso programático, o senhor tem um kit de ferramentas abrangente para depurar seus aplicativos GenAI, entender seu comportamento e melhorar continuamente seu desempenho e qualidade.
Próximas etapas
Continue sua jornada com estas ações recomendadas e o tutorial.
- Consulta de traços via SDK - Pesquisa e análise programática de traços para fluxo de trabalho personalizado
- Use traces para melhorar a qualidade - Aproveite as percepções de traces para melhorar os aplicativos
- Criar conjunto de dados de avaliação - Converter traces em dados de teste para avaliação sistemática
Guia de referência
Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.
- Modelo de dados de rastreamento - Entenda a estrutura de rastreamento e extensão
- Excluir rastreamentos - Saiba mais sobre o gerenciamento do ciclo de vida do rastreamento
- Avaliações de registro - Mergulhe profundamente nos conceitos de feedback e avaliação