Tutorial: Corrigir um conjunto de habilidades usando sessões de depuração

Artigo
09/03/2024

Na Pesquisa de IA do Azure, 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 que é executado na Pesquisa de IA do Azure. 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. O nível gratuito não fornece suporte à identidade gerenciada para um serviço da Pesquisa de IA do Azure. Você precisa usar chaves para as conexões com o Armazenamento do Microsoft Azure.
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. Se você estiver usando um serviço de pesquisa gratuito, a conta de armazenamento precisará ter as chaves de acesso compartilhadas habilitadas e permitir o acesso à rede pública.
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.
Crie uma conta de Armazenamento do Azure ou localize uma existente.
- 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

Este tutorial usa chaves de API para autenticação e autorização. Você precisa do ponto de extremidade do serviço de pesquisa e de uma chave de API, que você pode obter 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).
```
"search": "*",
"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.
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.
Selecione a conta de armazenamento.
Salve a sessão.
Uma sessão de depuração é aberta na página de configurações. Você pode fazer modificações na configuração inicial e substituir todos os padrões. Uma sessão de depuração funciona apenas com um só documento. O padrão é aceitar o primeiro documento da coleção como a base para as suas sessões de depuração. Você pode escolher um documento específico para depurar fornecendo seu URI no Armazenamento do Microsoft Azure.
Quando a sessão de depuração terminar de inicializar, você deverá ver um fluxo de trabalho de habilidades, com mapeamentos e um índice de pesquisa. A estrutura de dados enriquecida do documento aparece em um painel de detalhes na lateral. Foi excluída da captura de tela a seguir para que você possa ver o fluxo de trabalho mais completo.

Encontrar problemas com o conjunto de habilidades

Todos os problemas relatados pelo indexador são indicados como Erros e Avisos.

Observe que o número de erros e avisos é muito menor do que o exibido anteriormente porque essa lista detalha apenas os erros de um único documento. Assim como a lista exibida pelo indexador, você pode selecionar em uma mensagem de aviso e ver os detalhes desse aviso.

Selecione Avisos para ler 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ê poderá ver que essa entrada de código de idioma está faltando em EntityRecognitionSkill.#1, que é a mesma habilidade de reconhecimento de entidade que está tendo problemas com as saídas "locais" e "organizações".

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 superfície de trabalho, selecione a habilidade que está reportando os avisos. Neste tutorial, trata-se da habilidade de reconhecimento de entidade.
O painel de detalhes "Habilidade" se abre do lado direito, com seções para iterações e suas respectivas entradas e saídas, configurações de habilidade para a definição da habilidade em JSON e as mensagens de quaisquer erros e avisos que essa habilidade estiver emitindo.
Passe o mouse sobre cada entrada (ou selecione uma entrada) para mostrar os valores no Avaliador de expressões. Observe que 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.
Volte para a Estrutura de dados enriquecida e examine os nós de enriquecimento desse 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".
Volte para a habilidade e selecione Configurações do conjunto de Habilidades para abrir a definição em JSON.
Altere a expressão de /document/content para /document/merged_content e, a seguir, selecione Salvar. Observe que o aviso não está mais listado.
Selecione Executar no menu da janela da sessão. Isso dará início a outra execução do conjunto de habilidades usando o documento.
Assim que a execução da sessão de depuração terminar, observe que o número de avisos tem um a menos. Os avisos mostram que o erro de entrada de texto desapareceu, mas os outros avisos permanecem. A próxima etapa é abordar o aviso sobre o valor /document/languageCode, ausente ou vazio.
Selecione a habilidade e passe o mouse sobre /document/languageCode. O valor dessa entrada é nulo, o que não é uma entrada válida.
Assim como ocorre com o problema anterior, comece por examinar a Estrutura de dados enriquecida para obter evidências sobre seus nós. 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.
Copie a expressão /document/language.
No painel de detalhes "Habilidade", selecione Configurações da Habilidade para a habilidade n.º 1 e cole o novo valor, /document/language.
Selecione Salvar.
Selecione Executar.
Após a conclusão da execução da sessão de depuração, você poderá verificar os resultados no painel de detalhes "Habilidades". Ao passar o mouse sobre /document/languageo mouse, você deverá ver en como o valor do Avaliador de expressões.

Observe que os avisos sobre a 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í.

Selecione Mapeamentos do Campo de Saída na superfície de trabalho. Observe que os mapeamentos de campo de saída estão ausentes.
Como uma primeira etapa, confirme se o índice de pesquisa inclui os campos esperados. Nesse caso, o índice terá os campos "locais" e "organizações".
Se não houver nenhum problema com o índice, a próxima etapa é verificar as saídas de habilidades. Como você fez antes, selecione a Estrutura de dados enriquecida 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.
Alterne novamente para o painel de detalhes "Habilidades" da habilidade de reconhecimento de entidade.
Em Configurações da Habilidade, altere context para document/merged_content. Nesta altura, você deverá ter um total de três modificações na definição da habilidade.
Selecione 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:

Compartilhar via