Tutorial: Depurar um conjunto de competências com as Sessões de Depuração

  • Artigo

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

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 detalhar etapas específicas para ver facilmente onde uma ação pode estar caindo.

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

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

Pré-requisitos

Nota

Este tutorial também usa os serviços de IA do Azure para deteçã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 aproveitados nos bastidores para processamento gratuito de até 20 transações. Isso significa que você pode concluir este exercício sem precisar criar um recurso faturável de 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 conteúdo para trabalhar.

  1. Download de dados de amostra (clinical-trials-pdf-19), consistindo em 19 arquivos.

  2. Crie uma conta de armazenamento do Azure ou localize uma conta existente.

    • Escolha a mesma região que o Azure AI Search para evitar cobranças de largura de banda.

    • Escolha o tipo de conta StorageV2 (V2 de uso geral).

  3. Navegue até as páginas de 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 "privado". Atribua um nome ao seu contentor clinicaltrialdataset.

  4. No contêiner, selecione Carregar para carregar os arquivos de exemplo baixados e descompactados na primeira etapa.

  5. Enquanto estiver no portal, copie a cadeia de conexão para o Armazenamento do Azure. Você pode obter a cadeia de conexão em Configurações>de Chaves de Acesso no portal.

Copiar uma chave e um 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.

  1. Entre no portal do Azure, navegue até a página Visão geral e copie a URL. Um ponto final de exemplo poderá ser parecido com https://mydemo.search.windows.net.

  2. Em Teclas de Configurações>, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Existem duas chaves de administração intercambiáveis. Copie qualquer uma delas.

    Captura de ecrã do URL e das chaves de API no portal do Azure.

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

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

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

  1. Inicie o Visual Studio Code e abra o debug-sessions.rest arquivo.

  2. Forneça as seguintes variáveis: URL do serviço de pesquisa, chave da API de administração dos serviços de pesquisa, cadeia de conexão de armazenamento e o nome do contêiner de blob que armazena os PDFs.

  3. Envie cada pedido por vez. A criação do indexador leva vários minutos para ser concluída.

  4. Feche o arquivo.

Consulte os resultados no portal

O código de exemplo cria intencionalmente um índice de bugs como consequência de problemas que ocorreram durante a execução do conjunto de habilidades. O problema é que faltam dados no índice.

  1. No portal do Azure, na página Visão geral do serviço de pesquisa, selecione a guia Índices.

  2. Selecione ensaios clínicos.

  3. Insira essa cadeia de caracteres de consulta JSON na visualização JSON do explorador de pesquisa. Ele retorna campos para documentos específicos (identificados pelo campo exclusivo metadata_storage_path ).

    "select": "metadata_storage_path, organizations, locations",
"count"=true`

  4. Executar a consulta. Você deve ver valores vazios para organizations e locations.

    Esses campos devem ter sido preenchidos por meio da habilidade de Reconhecimento de Entidade do conjunto de habilidades, usada para detetar organizações e locais em qualquer lugar dentro 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.

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

    Observe que, embora o trabalho do indexador tenha sido bem-sucedido no geral, houve avisos.

  2. Selecione Êxito para visualizar os avisos (se houvesse principalmente erros, o link de detalhes seria Falha). Você verá uma longa lista de todos os avisos emitidos pelo indexador.

    Captura de ecrã dos avisos de visualização.

Inicie sua sessão de depuração

  1. No painel de navegação esquerdo do serviço de pesquisa, em Gerenciamento de pesquisa, selecione Depurar sessões.

  2. Selecione + Adicionar sessão de depuração.

  3. Dê um nome à sessão.

  4. Conecte a sessão à sua conta de armazenamento. Crie um contêiner chamado "debug sessions". Você pode usar esse contêiner repetidamente para armazenar todos os dados da sessão de depuração.

  5. Se você configurou uma conexão confiável entre pesquisa e 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).

  6. No modelo Indexador, forneça o nome do indexador. O indexador tem referências à fonte de dados, ao conjunto de habilidades e ao índice.

  7. Aceite a opção de documento padrão para o primeiro documento da coleção. Uma sessão de depuração só funciona com um único documento. Você pode escolher qual documento depurar ou apenas usar o primeiro.

  8. Salve a sessão. Salvar a sessão iniciará o pipeline de enriquecimento conforme definido pelo conjunto de habilidades para o documento selecionado.

    Captura de tela da configuração de uma nova sessão de depuração.

  9. Quando a sessão de depuração terminar de inicializar, a sessão assume como padrão a guia AI Enrichments , destacando o Skill Graph. O Gráfico de Habilidades fornece uma hierarquia visual do conjunto de habilidades e sua ordem de execução sequencial e em paralelo.

    Captura de tela do editor visual Debug Session.

Encontre problemas com o conjunto de habilidades

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

Captura de ecrã do separador erros e avisos.

Observe que a guia Erros/Avisos fornecerá uma lista muito menor do que a exibida anteriormente, pois essa lista está apenas detalhando os erros de um único documento. Como a lista exibida pelo indexador, você pode selecionar uma mensagem de aviso e ver os detalhes desse aviso.

Selecione Erros/Avisos para rever as notificações. Você deve ver quatro:

  • "Não foi possível executar habilidade porque uma ou mais entradas de habilidade eram inválidas. Falta a entrada de habilidades necessárias. Nome: 'texto', Fonte: '/documento/conteúdo'."

  • "Não foi possível mapear 'locais' do campo de saída para pesquisar o índice. Verifique a propriedade 'outputFieldMappings' do seu indexador. Valor em falta '/document/merged_content/locations'."

  • "Não foi possível mapear 'organizações' do campo de saída para pesquisar o índice. Verifique a propriedade 'outputFieldMappings' do seu indexador. Valor em falta '/document/merged_content/organizations'."

  • "Habilidade executada, mas pode ter resultados inesperados porque uma ou mais entradas de habilidade foram inválidas. A entrada de habilidades opcionais está faltando. Nome: 'languageCode', Fonte: '/document/languageCode'. Problemas de análise de 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á ausente do EntityRecognitionSkill.#1, que é a mesma habilidade de Reconhecimento de Entidade que está tendo problemas com a saída 'locais' e 'organizações'.

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

Corrigir valores de entrada de habilidade ausentes

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

  1. No AI Enrichments>Skill Graph, selecione a habilidade rotulada # 1 para exibir seus detalhes no painel direito.

  2. Selecione a guia Execuções e localize a entrada para "texto".

  3. Selecione o <símbolo /> para abrir o Avaliador de Expressões. O resultado exibido para essa entrada não se parece com uma entrada de texto. Parece uma série de novos caracteres \n \n\n\n\n de linha em vez de texto. A falta de texto significa que nenhuma entidade pode ser identificada, então ou este documento não atende aos pré-requisitos da habilidade, ou há outra entrada que deve ser usada em vez disso.

    Captura de tela do Avaliador de Expressão para a entrada de texto.

  4. Alterne o painel esquerdo para Estrutura de Dados Enriquecida e role para baixo a lista de nós de enriquecimento deste documento. Observe que o \n \n\n\n\n para "conteúdo" não tem fonte de origem, mas outro valor para "merged_content" tem saída OCR. Embora não haja indicação, o conteúdo deste PDF parece ser um arquivo JPEG, como evidenciado pelo texto extraído e processado em "merged_content".

    Captura de tela da estrutura de dados enriquecida.

  5. No painel direito, selecione Execuções para a habilidade #1 e abra o Avaliador <de Expressão /> para a entrada "texto".

  6. Altere a expressão de /document/content para /document/merged_contente, em seguida, selecione Avaliar. Observe que o conteúdo agora é um pedaço de texto e, portanto, acionável para reconhecimento de entidade.

    Captura de tela do Avaliador de Expressão para entrada de merged_content fixa.

  7. Mude para o Editor JSON de Habilidades.

  8. Na linha 16, em "entradas", mude /document/content para /document/merged_content.

     {
   "name": "text",
   "source": "/document/merged_content"
 },

  9. Selecione Salvar no painel Detalhes da habilidade.

    Captura de tela do comando Salvar para obter detalhes do conjunto de habilidades.

  10. Selecione Executar no menu da janela da sessão. Isso dará início a outra execução do conjunto de habilidades usando o documento.

  11. Quando a execução da sessão de depuração for concluída, verifique a guia Erros/Avisos e ela mostrará que o erro para entrada de texto desapareceu, mas os outros avisos permanecem. O próximo passo é abordar o aviso sobre "languageCode".

    Captura de ecrã de erros e avisos atualizados.

  12. Selecione a guia Execuções e localize a entrada para "languageCode".

  13. Selecione o <símbolo /> para abrir o Avaliador de Expressões. Observe a confirmação de que a propriedade "languageCode" não é uma entrada válida.

    Captura de tela do Avaliador de Expressão para a entrada de idioma.

Há duas maneiras de pesquisar esse erro. A primeira é olhar para a origem do input - que habilidade na hierarquia deve produzir esse resultado? A guia Execuções no painel de detalhes da habilidade deve exibir a origem da entrada. Se não houver nenhuma fonte, isso indica um erro de mapeamento de campo.

  1. Na guia Execuções, verifique o INPUTS e encontre "languageCode". Não há nenhuma fonte para esta entrada listada.

  2. Alterne o painel esquerdo para Estrutura de dados enriquecida. Role para baixo a lista de nós de enriquecimento deste documento. Observe que não há um nó "languageCode", mas há um para "language". Então, há um erro de digitação nas configurações de habilidade.

    Captura de ecrã da Estrutura de Dados Enriquecida, com a linguagem realçada.

  3. Ainda na Estrutura de Dados Enriquecida, abra o Avaliador< de Expressão /> para o nó "linguagem" e copie a expressão/document/language.

  4. No painel direito, selecione Configurações de habilidade para a habilidade #1 e abra o Avaliador< de Expressão /> para a entrada "languageCode".

  5. Cole o novo valor /document/language na caixa Expressão e selecione Avaliar. Ele deve exibir a entrada correta "en".

  6. Selecione Guardar.

  7. Selecione Executar.

Após a conclusão da execução da sessão de depuração, 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 de habilidade ausentes

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

  1. Vá para Skill Graph e selecione Output Field Mappings. 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".

    Captura de tela dos mapeamentos de campo de saída.

  2. Se não houver nenhum problema com o índice, o próximo passo é verificar os resultados das habilidades. Como antes, selecione a Estrutura de Dados Enriquecida e role os nós para encontrar "locais" e "organizações". Observe que o pai é "conteúdo" em vez de "merged_content". O contexto está errado.

    Captura de tela da estrutura de dados enriquecida com contexto errado.

  3. Volte para o Skill Graph e selecione a habilidade de reconhecimento de entidade.

  4. Navegue pelas Configurações de habilidade para encontrar o "contexto".

    Captura de tela da correção de contexto na configuração de habilidades.

  5. Clique duas vezes na configuração para "contexto" e edite-a para ler '/document/merged_content'.

  6. Selecione Guardar.

  7. Selecione Executar.

Todos os erros foram resolvidos.

Confirmar alterações no conjunto de competências

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ê terminou de depurar seu conjunto de habilidades, as correções podem ser confirmadas (substituir o conjunto de habilidades original).

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

  1. Selecione Confirmar alterações no menu principal Depurar sessões.

  2. Selecione OK para confirmar que deseja atualizar seu conjunto de habilidades.

  3. Feche a sessão de depuração e abra Indexadores no painel de navegação esquerdo.

  4. Selecione 'clinical-trials-idxr'.

  5. Selecione Repor.

  6. Selecione Executar.

  7. Selecione Atualizar para mostrar o status dos comandos de redefinição e execução.

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

  1. No painel de navegação esquerdo, abra Índices.

  2. Selecione o índice 'ensaios clínicos' e, no separador Explorador de pesquisa, introduza esta cadeia de consulta: $select=metadata_storage_path, organizations, locations&$count=true para devolver campos para documentos específicos (identificados pelo campo exclusivo metadata_storage_path ).

  3. Selecionar Pesquisa.

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

Clean up resources (Limpar recursos)

Ao trabalhar na sua própria subscrição, recomendamos que verifique, depois de concluir um projeto, se ainda vai precisar dos recursos que criou. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no portal, usando o link Todos os recursos ou Grupos de recursos no painel de navegação esquerdo.

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

Próximos passos

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