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

  • Artigo

No Azure AI Search, 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.

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

Neste artigo, use Debug Sessions 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

  • Azure AI Search. Crie um serviço ou encontre um serviço existente na sua subscrição atual. Você pode usar um serviço gratuito para este tutorial. A camada gratuita não fornece suporte de identidade gerenciada para um serviço Azure AI Search. Você deve usar chaves para conexões com o Armazenamento do Azure.

  • Conta de Armazenamento do Azure com armazenamento de Blob, usada para hospedar dados de exemplo e para persistir dados armazenados em cache criados durante uma sessão de depuração. Se estiver a utilizar um serviço de pesquisa gratuito, a conta de armazenamento tem de ter chaves de acesso partilhadas ativadas e tem de permitir o acesso à rede pública.

  • Código do Visual Studio com um cliente REST.

  • Exemplos de PDFs (ensaios clínicos).

  • Exemplo de arquivo debug-sessions.rest usado para criar o pipeline de enriquecimento.

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

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 pode ser obtida 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 ).

    "search": "*",
"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. No modelo Indexador, forneça o nome do indexador. O indexador tem referências à fonte de dados, ao conjunto de habilidades e ao índice.

  5. Selecione a conta de armazenamento.

  6. Salve a sessão.

    Captura de ecrã da página de definição de sessão de depuração.

  7. Uma sessão de depuração é aberta na página de configurações. Você pode fazer modificações na configuração inicial e substituir quaisquer padrões. Uma sessão de depuração só funciona com um único documento. O padrão é aceitar o primeiro documento da coleção como base de suas sessões de depuração. Você pode escolher um documento específico para depurar fornecendo seu URI no Armazenamento do Azure.

  8. Quando a sessão de depuração terminar de inicializar, você verá um fluxo de trabalho de habilidades com mapeamentos e um índice de pesquisa. A estrutura de dados do documento enriquecida aparece em um painel de detalhes ao lado. Nós o excluímos da captura de tela a seguir para que você pudesse ver mais do fluxo de trabalho.

    Captura de tela do editor visual Debug Session.

Encontre problemas com o conjunto de habilidades

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

Observe que o número de erros e avisos é uma lista muito menor do que a exibida anteriormente, porque 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 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 linguagem 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

  1. Na superfície de trabalho, selecione a habilidade que está relatando os avisos. Neste tutorial, é a habilidade de reconhecimento de entidade.

  2. O painel Detalhes da habilidade é aberto à direita com seções para iterações e suas respetivas entradas e saídas, configurações de habilidade para a definição JSON da habilidade e mensagens para quaisquer erros e avisos que essa habilidade esteja emitindo.

    Captura de tela do painel de detalhes da habilidade.

  3. Passe o cursor sobre cada entrada (ou selecione uma entrada) para mostrar os valores no avaliador de expressão. Observe que 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 da entrada de habilidade mostrando valores nulos.

  4. Volte para Estrutura de dados enriquecida e revise os nós de enriquecimento para este 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. Volte para a habilidade e selecione Configurações do conjunto de habilidades para abrir a definição JSON.

  6. Altere a expressão de /document/content para /document/merged_contente, em seguida, selecione Guardar. Observe que o aviso não está mais listado.

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

  7. Selecione Executar no menu da janela da sessão. Isso inicia outra execução do conjunto de habilidades usando o documento.

  8. Quando a execução da sessão de depuração for concluída, observe que a contagem de avisos foi reduzida em um. Os avisos mostram que o erro de entrada de texto desapareceu, mas os outros avisos permanecem. O próximo passo é abordar o aviso sobre o valor /document/languageCodeausente ou vazio.

    Captura de ecrã de erros e avisos atualizados.

  9. Selecione a habilidade e passe o mouse sobre /document/languageCode. O valor dessa entrada é null, o que não é uma entrada válida.

  10. Como na edição anterior, comece revisando a estrutura de dados enriquecida para obter evidências de seus nós. 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.

  11. Copie a expressão /document/language.

  12. No painel Detalhes da habilidade, selecione Configurações de habilidade para a habilidade #1 e cole o novo valor, /document/language.

  13. Selecione Guardar.

  14. Selecione Executar.

  15. Após a conclusão da execução da sessão de depuração, você pode verificar os resultados no painel de detalhes Habilidades. Ao passar o mouse sobre /document/language, você deve ver en como o valor no avaliador de expressão.

Observe que 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. Selecione Mapeamentos de campo de saída na superfície de trabalho. Observe que os mapeamentos de campo de saída estão faltando.

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

  2. Como primeiro passo, confirme se o índice de pesquisa tem os campos esperados. Neste caso, o índice tem campos para "locais" e "organizações".

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

  4. Volte para o painel de detalhes Habilidades para a habilidade de reconhecimento de entidade.

  5. Em Configurações de habilidade, mude context para document/merged_content. Neste ponto, você deve ter três modificações na definição de habilidade ao todo.

    Captura de tela da definição de habilidade com todas as modificações indicadas.

  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. Selecione Pesquisar.

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: