Depurar um conjunto de habilidades da IA do Azure Search no portal do Azure

Inicie uma sessão de depuração baseada no portal para identificar e resolver erros, validar alterações e enviar alterações para um conjunto de habilidades existente no seu serviço IA do Azure Search.

Uma sessão de depuração é um indexador em cache e uma execução de qualificação, com escopo para um único documento, que você pode usar para editar e testar alterações de qualificação de forma interativa. Quando terminar de depurar, você poderá salvar as alterações no conjunto de habilidades.

Para obter informações sobre como funciona uma sessão de depuração, consulte Sessões de depuração na Pesquisa de IA do Azure. Para praticar um fluxo de trabalho de depuração com um documento de exemplo, confira Tutorial: sessões de depuração.

Pré-requisitos

• Um serviço do Azure AI Search. É recomendável usar uma identidade gerenciada atribuída pelo sistema e atribuições de função que permitem que a Pesquisa de IA do Azure escreva no Armazenamento do Microsoft Azure e chame os recursos de IA do Azure usados no conjunto de habilidades.

• Uma conta de armazenamento do Azure usada para salvar o estado de sessão.

• Um pipeline de enriquecimento existente, incluindo uma fonte de dados, um conjunto de habilidades, um indexador e um índice.

• Para atribuições de função, a identidade do serviço de pesquisa deve ter:

  • Permissões de Usuário dos Serviços Cognitivos na conta multisserviços de IA do Azure usada pelo conjunto de habilidades.

  • Permissões de Colaborador de Dados de Blobs de Armazenamento no Armazenamento do Microsoft Azure. Caso contrário, planeje usar uma cadeia de conexão de acesso completo para a conexão da sessão de depuração com o Armazenamento do Microsoft Azure.

• Se a conta de Armazenamento do Microsoft Azure estiver por trás de um firewall, configure-a para permitir acesso de serviço de pesquisa.

Limitações

As sessões de depuração funcionam com todas as fontes de dados do indexador geralmente disponíveis e com a maioria das fontes de dados de visualização, com as seguintes exceções:

• Indexador do SharePoint Online.

• Indexador do Azure Cosmos DB for MongoDB.

• Para o Azure Cosmos DB for NoSQL, se uma linha falhar durante o índice e não houver metadados correspondentes, pode ser que a sessão de depuração não escolha a linha correta.

• Para a API do SQL do Azure Cosmos DB, se uma coleção particionada não tiver sido particionada anteriormente, a sessão de depuração não encontrará o documento.

• Para habilidades personalizadas, não há suporte para uma identidade gerenciada atribuída pelo usuário para uma conexão de sessão de depuração com o Armazenamento do Microsoft Azure. Conforme indicado nos pré-requisitos, você pode usar uma identidade gerenciada pelo sistema ou especificar uma cadeia de conexão de acesso completo que inclua uma chave. Para obter mais informações, consulte Conectar um serviço de pesquisa a outros recursos do Azure usando uma identidade gerenciada.

• Atualmente, a capacidade de selecionar qual documento depurar não está disponível. Essa limitação não é permanente e será suspensa em breve. Nesse momento, as Sessões de Depuração selecionam o primeiro documento no contêiner ou pasta de dados de origem.

Criar uma sessão de depuração

1. Entre no portal do Azure e localize o serviço de pesquisa.

2. No menu esquerdo, selecione Gerenciamento de pesquisa>Sessões de depuração.

3. Na barra de ações na parte superior, selecione Adicionar sessão de depuração.

   

4. Em Nome da sessão de depuração, forneça um nome que ajudará você a se lembrar de qual conjunto de habilidades, do indexador e da fonte de dados sobre a sessão de depuração.

5. Em Modelo do indexador, selecione o indexador que orienta o conjunto de habilidades que você deseja depurar. As cópias do indexador e do conjunto de habilidades são usadas para inicializar a sessão.

6. Em Conta de armazenamento, encontre uma conta de armazenamento de uso geral para armazenar em cache a sessão de depuração.

7. Selecione Autenticar usando identidade gerenciada se você atribuiu permissões de Colaborador de Dados de Blob de Armazenamento anteriormente à identidade gerenciada pelo sistema do serviço de pesquisa.

8. Selecione Salvar.

   • A Pesquisa de IA do Azure cria um contêiner de blob no Armazenamento do Microsoft Azure chamado ms-az-cognitive-search-debugsession.
   • Dentro desse contêiner, ele cria uma pasta usando o nome que você forneceu para o nome da sessão.
   • Ele inicia sua sessão de depuração.

9. Uma sessão de depuração é aberta na página de configurações. É possível fazer modificações na configuração inicial e substituir os padrões.

10. Na Cadeia de conexão de armazenamento, é possível especificar a cadeia de conexão ou alterar a conta de armazenamento.

11. Opcionalmente, em Configurações do indexador, especifique quaisquer configurações de execução do indexador usadas para criar a sessão. As configurações devem espelhar as definições usadas pelo indexador real. As opções do indexador que você especificar em uma sessão de depuração não terão efeito no indexador em si.

12. Caso tenha feito alterações, selecione Salvar sessão, seguido de Executar.

A sessão de depuração começa com a execução do indexador e do conjunto de habilidades no documento selecionado. O conteúdo e os metadados do documento ficam visíveis e disponíveis na sessão.

Uma sessão de depuração pode ser cancelada enquanto está em execução por meio do botão Cancelar. Se você apertar o botão Cancelar, poderá analisar os resultados parciais.

Espera-se que uma sessão de depuração leve mais tempo para ser executada do que o indexador, pois ela passa por processamento extra.

Iniciar com erros e avisos

O histórico de execução do indexador no portal fornece a lista completa de erros e avisos para todos os documentos. Em uma sessão de depuração, os erros e avisos estão limitados a um documento. É possível trabalhar nessa lista, fazer suas alterações e, em seguida, voltar até a lista para verificar se os problemas foram resolvidos.

Lembre-se de que uma sessão de depuração é baseada em um documento de todo o índice. Se uma entrada ou saída parecer errada, o problema poderá ser específico para esse documento. É possível escolher um documento diferente para confirmar se erros e avisos são generalizados ou específicos para um único documento.

Selecione Erros ou Avisos para uma lista de problemas.

Uma melhor prática a ser seguida é resolver os problemas com as entradas antes de passar para as saídas.

Para verificar se uma modificação resolve um erro, siga estas etapas:

1. Selecione Salvar no painel de detalhes de habilidade para preservar as alterações.

2. Selecione Executar na janela de sessão para invocar a execução do conjunto de habilidades usando a definição modificada.

3. Volte para Erros ou Avisos para visualizar se a contagem foi reduzida.

Exibir conteúdo enriquecido ou gerado

Os pipelines de enriquecimento de IA extraem ou inferem informações e estruturas de documentos de origem, criando um documento aprimorado no processo. Um documento enriquecido é criado durante a quebra de documento e preenchido com um nó raiz (/document) e nós para qualquer conteúdo diretamente extraído da fonte de dados, como uma chave de documento e metadados. Mai nós são criados por habilidades durante a execução delas, em que cada saída de habilidade adiciona um novo nó à árvore de enriquecimento.

Todo o conteúdo criado ou usado por um conjunto de habilidades aparece no Avaliador de Expressão. É possível passar o mouse sobre os links para exibir cada valor de entrada ou saída na árvore de documentos enriquecida. Para exibir a entrada ou a saída de cada habilidade, siga estas etapas:

1. Em uma sessão de depuração, expanda a seta azul para exibir detalhes sensíveis ao contexto. Por padrão, o detalhe é a estrutura de dados do documento enriquecido. No entanto, caso selecione uma habilidade ou um mapeamento, o detalhe será sobre esse objeto.

   

2. Selecione uma habilidade.

   

3. Siga os links para detalhar ainda mais o processamento de habilidades. Por exemplo, a captura de tela a seguir mostra a saída da primeira iteração da habilidade de Divisão de Texto.

   

Verificar mapeamentos de índice

Se as habilidades produzirem a saída, mas o índice de pesquisa estiver vazio, verifique os mapeamentos de campo. Os mapeamentos de campo especificam como o conteúdo é movido para fora do pipeline e para um índice de pesquisa.

Selecione uma das opções de mapeamento e expanda a exibição de detalhes para examinar as definições de origem e de destino.

• Os Mapeamentos de projeção são encontrados em conjuntos de habilidades que fornecem vetorização integrada, como as habilidades criadas pelo assistente de importação e vetorização de dados. Esses mapeamentos determinam mapeamentos de campo pai-filho (parte) e se um índice secundário é criado apenas para o conteúdo em partes

• Mapeamentos de campo de saída são encontrados em indexadores e são usados quando conjuntos de habilidades invocam habilidades internas ou personalizadas. Esses mapeamentos são usados para definir o caminho de dados de um nó na árvore de enriquecimento para um campo no índice de pesquisa. Para obter mais informações sobre caminhos, consulte a sintaxe do caminho do nó de enriquecimento.

• Mapeamentos de campo são encontrados em definições de indexador e estabelecem o caminho de dados do conteúdo bruto na fonte de dados e um campo no índice. Também é possível usar mapeamentos de campo para adicionar etapas de codificação e decodificação.

Este exemplo mostra os detalhes de um mapeamento de projeção. É possível editar o JSON para corrigir quaisquer problemas de mapeamento.

Editar definições de habilidade

Se os mapeamentos de campo estiverem corretos, verifique as habilidades individuais de configuração e conteúdo. Se uma habilidade não produzir a saída, pode ser que esteja faltando uma propriedade ou um parâmetro, o que pode ser determinado por meio de mensagens de erro e validação.

Outros problemas, como um contexto inválido ou uma expressão de entrada, podem ser mais difíceis de resolver, pois o erro informará o que está errado, mas não como corrigir isso. Para obter ajuda com a sintaxe de contexto e de entrada, consulte Enriquecimentos de referência em um conjunto de habilidades da Pesquisa de IA do Azure. Para obter ajuda com mensagens individuais, confira Solucionar problemas de erros e avisos comuns do indexador.

As etapas a seguir mostram como obter informações sobre uma habilidade.

1. Selecione uma habilidade na área de trabalho. O painel de detalhes de Habilidades é aberto à direita.

2. Edite uma definição de habilidade usando Configurações de Habilidade. É possível editar o JSON diretamente.

3. Verifique a sintaxe do caminho para fazer referência a nós em uma árvore de enriquecimento. Confira alguns dos caminhos de entrada mais comuns:

   • /document/content para partes de texto. Esse nó é preenchido a partir da propriedade conteúdo do blob.
   • /document/merged_content para partes de texto em conjuntos de habilidade que incluem a habilidade de Mesclagem de Texto.
   • /document/normalized_images/* para textos reconhecidos ou inferidos a partir de imagens.

Depurar uma habilidade personalizada localmente

As habilidades personalizadas podem ser mais difíceis de serem depuradas porque o código é executado externamente, portanto, a sessão de depuração não pode ser usada para depurá-las. Esta seção descreve como depurar localmente a habilidade de API da Web Personalizada, a sessão de depuração, o Visual Studio Code e ngrok ou Tunnelmole. Essa técnica funciona com habilidades personalizadas que são executadas em Azure Functions ou qualquer outro Web Framework executado localmente (por exemplo, FastAPI).

Obter uma URL pública

Esta seção descreve duas abordagens para obter um URL público para uma habilidade personalizada.

Usar o Tunnelmole

Tunnelmole é uma ferramenta de túnel de software livre que pode criar uma URL pública que encaminha solicitações para seu computador local por meio de um túnel.

1. Instalar o Tunnelmole:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: Instalar usando o npm. Ou se você não tiver o NodeJS instalado, baixe o arquivo .exe pré-compilado para Windows e coloque-o em algum lugar em seu caminho.

2. Execute este comando para criar um novo túnel:

   tmole 7071
   

   Você deverá ver um resultado parecido com este:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   No exemplo anterior, https://m5hdpb-ip-49-183-170-144.tunnelmole.net encaminha para a porta 7071 em seu computador local, que é a porta padrão em que as funções do Azure são expostas.

Usar o ngrok

O ngrok é um aplicativo multiplataforma popular e de código fechado que pode criar uma URL de túnel ou encaminhamento para que as solicitações da Internet cheguem ao computador local. Use o ngrok para encaminhar solicitações de um pipeline de enriquecimento em seu serviço de pesquisa para seu computador para permitir a depuração local.

1. Instale o ngrok.

2. Abra um terminal e acesse a pasta com o executável ngrok.

3. Execute o ngrok com o seguinte comando para criar um novo túnel:

   ngrok http 7071 
   

   Observação

   Por padrão, Azure Functions são expostos no 7071. Outras ferramentas e configurações podem exigir que você forneça uma porta diferente.

4. Quando o ngrok for iniciado, copie e salve a URL de encaminhamento público para a próxima etapa. A URL de encaminhamento é gerada aleatoriamente.

   

Configurar no portal do Azure

Após ter um URL público para sua habilidade personalizada, modifique o URI de Habilidade de API Web Personalizada em uma sessão de depuração para chamar o URL de encaminhamento do tunnelmole ou do ngrok. Certifique-se de acrescentar "/api/FunctionName" ao usar o Azure Function para executar o código do conjunto de habilidades.

É possível editar a definição de habilidade na seção Configurações de habilidade do painel de detalhes de Habilidade.

Testar seu código

Neste ponto, novas solicitações de sua sessão de depuração agora devem ser enviadas para o Azure Function local. É possível usar pontos de interrupção em seu Visual Studio Code para depurar seu código ou executar passo a passo.

Próximas etapas

Agora que você entende como funciona o layout e os recursos do editor visual de Sessões de Depuração, experimente o tutorial para uma experiência prática.

Tutorial: explorar sessões de depuração