Tutorial: Depurar um conjunto de habilidades usando as Sessões de Depuração

Artigo
03/09/2024

Um conjunto de habilidades coordena as ações de habilidades que analisam, transformam ou criam conteúdo pesquisável. Frequentemente, a saída de uma habilidade torna-se a entrada de outra. Quando as entradas dependem das saídas, erros nas definições do conjunto de habilidades e associações de campo podem resultar na perda de operações e de dados.

As sessões de depuração são uma ferramenta do portal do Azure que fornece uma visualização holística de um conjunto de habilidades. Usando essa ferramenta, você pode fazer uma busca detalhada de etapas específicas para ver com facilidade onde uma ação pode estar falhando.

Neste artigo, use as Sessões de depuração para localizar e corrigir entradas e saídas ausentes. O tutorial é completo. Ele fornece dados de exemplo, um arquivo REST que cria objetos e instruções para depurar problemas no conjunto de habilidades.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

IA do Azure Search. Crie um serviço ou localize um serviço existente na assinatura atual. Você pode usar um serviço gratuito para este tutorial.
Uma conta de Armazenamento do Azure com Armazenamento de Blobs, usada para hospedar dados de exemplo e para persistir dados armazenados em cache criados durante uma sessão de depuração.
Visual Studio Code com um cliente REST.
PDFs de exemplo (testes clínicos).
Exemplo de arquivo debug-sessions.rest usado para criar o pipeline de enriquecimento.

Observação

Este tutorial também usa os Serviços de IA do Azure para detecção de idioma, reconhecimento de entidade e extração de frases-chave. Como a carga de trabalho é muito pequena, os Serviços de IA do Azure são acionados nos bastidores para fornecer processamento gratuito para até 20 transações. Isso significa que você pode concluir este exercício sem precisar criar um recurso faturável dos Serviços de IA do Azure.

Configurar os dados de exemplo

Esta seção cria o conjunto de dados de exemplo no Armazenamento de Blobs do Azure para que o indexador e o conjunto de habilidades tenham um conteúdo com o qual trabalhar.

Baixe dados de exemplo (clinical-trials-pdf-19) compostos por 19 arquivos.
Criar uma conta de armazenamento do Azure ou localizar uma conta.
- Escolha a mesma região da IA do Azure Search para evitar preços de largura de banda.
- Escolha o tipo de conta StorageV2 (uso geral V2).
Navegue até as páginas dos serviços de Armazenamento do Azure no portal e crie um contêiner de Blob. A melhor prática é especificar o nível de acesso "particular". Dê ao contêiner o nome clinicaltrialdataset.
No contêiner, selecione Carregar para carregar os arquivos de exemplo que você baixou e descompactou na primeira etapa.
No portal, copie a cadeia de conexão para o Armazenamento do Microsoft Azure. Obtenha a cadeia de conexão em Configurações>Chaves de acesso no portal.

Copiar uma chave e URL

As chamadas REST exigem o ponto de extremidade do serviço de pesquisa e uma chave de API em cada solicitação. Você pode obter esses valores no portal do Azure.

Entre no portal do Azure, navegue até a página Visão geral e copie a URL. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.
Em Configurações>Chaves, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas.

Uma chave de API válida estabelece a confiança, por solicitação, entre o aplicativo que envia a solicitação e o serviço de pesquisa que a está tratando.

Criar fonte de dados, conjunto de habilidades, índice e indexador

Nesta seção, crie um fluxo de trabalho "buggy" que você pode corrigir neste tutorial.

Inicie o Visual Studio Code e abra o arquivo debug-sessions.rest.
Forneça as seguintes variáveis: URL do serviço de pesquisa, chave de API de administrador de serviços de pesquisa, cadeia de conexão de armazenamento e o nome do contêiner de blob que armazena os PDFs.
Envie cada solicitação por sua vez. A criação do indexador leva vários minutos para ser concluída.
Feche o arquivo .

Verificar os resultados no portal

O código de exemplo cria intencionalmente um índice com bug como consequência de problemas ocorridos durante a execução do conjunto de habilidades. O problema é que o índice tem dados ausentes.

No portal do Azure, na página Visão geral do serviço de pesquisa, selecione a guia Índices.
Selecione clinical-trials.
Insira essa cadeia de caracteres de consulta JSON no modo de exibição JSON do Gerenciador de Pesquisa. Ele retorna campos para documentos específicos (identificados pelo campo exclusivo metadata_storage_path).
```
"select": "metadata_storage_path, organizations, locations",
"count"=true`
```
Execute a consulta. Você deve ver valores vazios para organizations e locations.

Esses campos devem ter sido populados por meio da habilidade de Reconhecimento de Entidade do conjunto de habilidades, usada para localizar organizações e locais em qualquer parte do conteúdo do blob. No próximo exercício, você depurará o conjunto de habilidades para determinar o que deu errado.

Outra maneira de investigar erros e avisos é por meio do portal do Azure.

Abra a guia Indexadores e selecione clinical-trials-idxr.

Observe que, embora o trabalho do indexador tenha sido bem-sucedido de modo geral, houve avisos.
Selecione Êxito para ver os avisos (se houvessem ocorrido erros na maior parte, o link de detalhes seria Falha). Você verá uma longa lista com todos os avisos emitidos pelo indexador.

Inicie a sessão de depuração

No painel de navegação à esquerda do serviço de pesquisa, em Gerenciamento de pesquisa, selecione Sessões de depuração.
Selecione + Adicionar sessão de depuração.
Dê um nome à sessão.
Conecte a sessão à sua conta de armazenamento. Crie um contêiner chamado "sessões de depuração". Você pode usar esse contêiner repetidamente para armazenar todos os dados da sessão de depuração.
Se você configurou uma conexão confiável entre a pesquisa e o armazenamento, selecione a identidade gerenciada pelo usuário ou a identidade do sistema para a conexão. Caso contrário, use o padrão (Nenhum).
No modelo do Indexador, forneça o nome do indexador. O indexador tem referências à fonte de dados, ao conjunto de habilidades e ao índice.
Aceite a opção de documento padrão para o primeiro documento na coleção. Uma sessão de depuração funciona apenas com um só documento. Você pode escolher qual documento deseja depurar ou simplesmente usar o primeiro.
Salve a sessão. Salvar a sessão iniciará o pipeline de enriquecimento, conforme definido pelo conjunto de habilidades para o documento selecionado.
Quando a sessão de depuração termina a inicialização, ela usa como padrão a guia Aprimoramentos de IA, destacando o Grafo de Habilidades. O Grafo de Habilidades fornece uma hierarquia visual do conjunto de habilidades e sua ordem de execução, sequencialmente e em paralelo.

Encontrar problemas com o conjunto de habilidades

Todos os problemas relatados pelo indexador podem ser encontrados na guia Erros/Avisos adjacente.

Observe que a guia Erros/Avisos fornecerá uma lista muito menor do que aquela exibida anteriormente, pois essa lista só detalha os erros de um documento. Assim como a lista exibida pelo indexador, você pode selecionar em uma mensagem de aviso e ver os detalhes desse aviso.

Selecione Erros/Avisos para examinar as notificações. Você deverá ver quatro:

"Não foi possível executar a habilidade porque uma ou mais entradas de habilidade eram inválidas. Entrada de habilidade necessária ausente. Nome: 'text', Source: '/document/content'."
"Não foi possível mapear o campo de saída 'locations' para o índice de pesquisa. Verifique a propriedade 'outputFieldMappings' do indexador. Valor ausente '/document/merged_content/locations'."
"Não foi possível mapear o campo de saída 'organizations' para o índice de pesquisa. Verifique a propriedade 'outputFieldMappings' do indexador. Valor ausente '/document/merged_content/organizations'."
"Habilidade executada, mas pode haver resultados inesperados porque uma ou mais entradas de habilidades eram inválidas. Entrada de habilidade opcional ausente. Nome: 'languageCode', Origem: '/document/languageCode'. Problemas de análise da linguagem de expressão: Valor ausente '/document/languageCode'."

Muitas habilidades têm um parâmetro "languageCode". Ao inspecionar a operação, você pode ver que essa entrada de código de idioma está faltando em EntityRecognitionSkill.#1, que é a mesma habilidade Reconhecimento de Entidade que está tendo problemas com as saídas 'locations' e 'organizations'.

Como as quatro notificações são sobre essa habilidade, a próxima etapa é depurá-la. Se possível, comece resolvendo primeiro os problemas de entrada antes de passar para os problemas de saída.

Corrigir os valores de entrada da habilidade ausente

Na guia Erros/Avisos, há duas entradas ausentes para uma operação rotulada EntityRecognitionSkill.#1. O detalhe do primeiro erro explica que uma entrada necessária para 'text' está ausente. O segundo indica um problema com um valor de entrada "/document/languageCode".

Em Enriquecimentos de IA>Grafo de Habilidades, selecione a habilidade rotulada No. 1 para exibir os detalhes dela no painel direito.
Selecione a guia Execuções e localize a entrada para "text".
Selecione o símbolo </> para abrir o Avaliador de Expressão. O resultado exibido para essa entrada não se parece com uma entrada de texto. Ele se parece com uma série de caracteres de nova linha \n \n\n\n\n em vez de texto. A falta de texto significa que nenhuma entidade pode ser identificada, portanto, esse documento não atende aos pré-requisitos da habilidade ou há outra entrada que deve ser usada em vez disso.
Alterne o painel esquerdo para Estrutura de Dados Enriquecidos e role para baixo na lista de nós de enriquecimento deste documento. Observe que o \n \n\n\n\n para "conteúdo" não tem nenhuma origem, mas um outro valor para "merged_content" tem uma saída OCR. Embora não haja nenhuma indicação, o conteúdo deste PDF parece ser um arquivo JPEG, conforme evidenciado pelo texto extraído e processado em "merged_content".
No painel direito, selecione Execuções para a habilidade nº 1 e abra o Avaliador de Expressão </> para a entrada "text".
Altere a expressão de /document/content para /document/merged_content e selecione Avaliar. Observe que o conteúdo agora é um trecho de texto e, portanto, acionável para reconhecimento de entidade.
Alterne para Editor de Habilidade JSON.
Na linha 16, em "entradas", altere /document/content para /document/merged_content.
```
 {
   "name": "text",
   "source": "/document/merged_content"
 },
```
Clique em Salvar no painel de Detalhes da Habilidade.
Selecione Executar no menu da janela da sessão. Isso iniciará outra execução do conjunto de habilidades usando o documento.
Depois que a execução da sessão de depuração for concluída, verifique a guia Erros/Avisos e ela mostrará que o erro de entrada de texto foi embora, mas os outros avisos permanecem. A próxima etapa é solucionar o aviso sobre "languageCode".
Selecione a guia Execuções e localize a entrada para "languageCode".
Selecione o símbolo </> para abrir o Avaliador de Expressão. Observe a confirmação de que a propriedade "languageCode" não é uma entrada válida.

Há duas maneiras de pesquisar esse erro. A primeira é examinar de onde a entrada é proveniente – qual habilidade na hierarquia deve produzir esse resultado? A guia Execuções no painel detalhes da habilidade deve exibir a origem da entrada. Se não houver nenhuma origem, isso indicará um erro de mapeamento de campo.

Na guia Execuções, verifique as ENTRADAS e localize "languageCode". Não há nenhuma fonte para essa entrada listada.
Alterne para o painel esquerdo para exibir a Estrutura de Dados Enriquecidos. Role para baixo na lista de nós de enriquecimento para este documento. Observe que não há nenhum nó "languageCode", mas há um para "idioma". Então, há um erro de digitação nas configurações de habilidade.
Ainda na Estrutura de Dados Enriquecidos, abra o Avaliador de Expressão </> para o nó "language" e copie a expressão /document/language.
No painel direito, selecione Configurações de Habilidade para a habilidade nº 1 e abra o Avaliador de Expressão </> para a entrada "languageCode".
Cole o novo valor, /document/language na caixa Expressão e selecione Avaliar. Ela deve exibir a entrada correta "en".
Clique em Salvar.
Selecione Executar.

Depois que a execução da sessão de depuração for concluída, verifique a guia Erros/Avisos e ela mostrará que todos os avisos de entrada desapareceram. Agora restam apenas os dois avisos sobre campos de saída para organizações e locais.

Corrigir valores de saída da habilidade ausente

As mensagens dizem para verificar a propriedade 'outputFieldMappings' do seu indexador, portanto, vamos começar por aí.

Vá para Grafo de Habilidades e selecione Mapeamentos de Campo de Saída. Os mapeamentos estão realmente corretos, mas normalmente você verificaria a definição do índice para garantir que os campos existam para "locais" e "organizações".
Se não houver nenhum problema com o índice, a próxima etapa é verificar as saídas de habilidades. Como antes, selecione a Estrutura de Dados Enriquecidos e role pelos nós para encontrar "locais" e "organizações". Observe que o pai é "content" em vez de "merged_content". O contexto está errado.
Volte para o Grafo de Habilidades e selecione a habilidade de reconhecimento de entidade.
Navegue para as Configurações de Habilidade para encontrar "context".
Clique duas vezes na configuração de "context" e edite-a para ler '/document/merged_content'.
Clique em Salvar.
Selecione Executar.

Todos os erros foram resolvidos.

Confirmar alterações no conjunto de habilidades

Quando a sessão de depuração foi iniciada, o serviço de pesquisa criou uma cópia do conjunto de habilidades. Isso foi feito para proteger o conjunto de habilidades original em seu serviço de pesquisa. Agora que você concluiu a depuração de seu conjunto de habilidades, as correções podem ser confirmadas (substituindo o conjunto de habilidades original).

Como alternativa, se não estiver pronto para confirmar as alterações, você poderá salvar a sessão de depuração e reabri-la mais tarde.

Selecione Confirmar alterações no menu principal das Sessões de depuração.
Selecione OK para confirmar que você deseja atualizar o conjunto de habilidades.
Feche a sessão de Depuração e abra Indexadores no painel de navegação esquerdo.
Selecione 'clinical-trials-idxr'.
Selecione Restaurar.
Selecione Executar.
Selecione Atualizar para mostrar o status dos comandos de redefinição e execução.

Quando o indexador terminar de ser executado, deverá haver uma marca de seleção verde e a palavra Êxito ao lado do carimbo de data/hora da última execução na guia de Histórico de execuções. Para garantir que as alterações tenham sido aplicadas:

No painel de navegação esquerdo, abra Índices.
Selecione o índice "clinical-trials" e, na guia Gerenciador de pesquisa, insira esta cadeia de caracteres de consulta: $select=metadata_storage_path, organizations, locations&$count=true para retornar campos para documentos específicos (identificados pelo campo metadata_storage_path exclusivo).
Selecione Pesquisar.

Os resultados devem mostrar que as organizações e locais agora estão preenchidos com os valores esperados.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, é uma boa ideia identificar, no final de um projeto, se você ainda precisa dos recursos criados. Recursos deixados em execução podem custar dinheiro. Você pode excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

O serviço gratuito é limitado a três índices, indexadores e fontes de dados. Você pode excluir itens individuais no portal para permanecer abaixo do limite.

Próximas etapas

Este tutorial abordou vários aspectos da definição e do processamento dos conjuntos de habilidades. Para saber mais sobre conceitos e fluxos de trabalho, confira seguintes os artigos: