Pular para o conteúdo principal

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.

  1. 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")).
  2. 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.

Visualização da lista de traços

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 ou Request time.
    • Avaliações : filtre pela presença ou valores específicos de avaliações, como my_scorer ou professional.
    • Outros campos, como State, Trace name, Session, User e Tags (por exemplo, tags.persona = 'expert').
  • 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.

Filtro de lista de rastreamento

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:

Visão geral do Trace Detail

  1. 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.
  2. 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).

      Guia Chat de detalhes do span

      • 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.

      Guia IO de detalhes do intervalo

      • 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).

      Aba Atributos de detalhes do intervalo

      • 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.

  3. 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.

    Trace Detail Adicionar avaliação

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:

  1. 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.

    Identificando a interface de usuário de traços l

  2. 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 como tags.mlflow.trace.user = 'user_example_123'.

    UI de localização de traços de usuário

  3. Localizando traços com falhas (erros) :

    • Uso de filtros : Na seção "Filtros" dropdown, selecione o atributo State e escolha ERROR 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.

    Localizando a interface de usuário do Error Traces

  4. 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érico relevance_score), os filtros "" dropdown podem permitir que o senhor filtre por esses nomes de avaliação e seus valores (por exemplo, filtre por is_correct = false ou relevance_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.

    Identificação da interface de usuário de feedback negativo

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.

nota

A integração MLflow Tracing Databricks Notebook está disponível em MLflow 2.20 e acima.

Databricks Notebook Rastrear UI

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:

  1. 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).
  2. Você chama explicitamente mlflow.search_traces() e o resultado é exibido.
  3. Um objeto mlflow.entities.Trace (por exemplo, de mlflow.get_trace()) é a última expressão em uma célula ou é passado para display().

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.

Guia de referência

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