Depurar um conjunto de habilidades de Pesquisa de IA do Azure no portal do Azure

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

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

Para obter informações básicas sobre como uma sessão de depuração funciona, consulte Depurar sessões no Azure AI Search. Para praticar um fluxo de trabalho de depuração com um documento de exemplo, consulte Tutorial: Sessões de depuração.

Pré-requisitos

• Um serviço Azure AI Search. Recomendamos usar uma identidade gerenciada atribuída pelo sistema e atribuições de função que permitam que a Pesquisa de IA do Azure escreva no Armazenamento do 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 da 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 utilizador dos Serviços Cognitivos na conta multisserviço do Azure AI utilizada pelo conjunto de competências.

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

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

Limitações

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

• Indexador do SharePoint Online.

• Azure Cosmos DB para indexador MongoDB.

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

• Para a API SQL do Azure Cosmos DB, se uma coleção particionada não foi 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 Azure. Conforme indicado nos pré-requisitos, você pode usar uma identidade gerenciada pelo sistema ou especificar uma cadeia de conexão de acesso total 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.

Criar uma sessão de depuração

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

2. No menu à esquerda, selecione Sessões de depuração de gerenciamento>de pesquisa.

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 o ajudará a lembrar de qual conjunto de habilidades, indexador e fonte de dados se trata a sessão de depuração.

5. No modelo Indexador, selecione o indexador que orienta o conjunto de habilidades que você deseja depurar. Cópias do indexador e do conjunto de habilidades são usadas para inicializar a sessão.

6. Em Conta de armazenamento, localize 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 anteriormente permissões de Colaborador de Dados de Blob de Armazenamento à identidade gerenciada pelo sistema do serviço de pesquisa.

8. Selecione Guardar.

   • O Azure AI Search cria um contêiner de blob no Armazenamento do 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. Você pode fazer modificações na configuração inicial e substituir quaisquer padrões.

10. Em Cadeia de conexão de armazenamento, você pode especificar a cadeia de conexão ou alterar a conta de armazenamento.

11. Em Documento a depurar, escolha o primeiro documento no índice ou selecione um documento específico. Se você selecionar um documento específico, dependendo da fonte de dados, será solicitado um URI ou um ID de linha.

    Se o documento específico for um blob, forneça o URI de blob. Você pode encontrar o URI na página de propriedades do blob no portal.

    

12. Opcionalmente, em Configurações do indexador, especifique as configurações de execução do indexador usadas para criar a sessão. As configurações devem espelhar as configurações usadas pelo indexador real. Todas as opções de indexador especificadas em uma sessão de depuração não têm efeito sobre o indexador em si.

13. Se você fez alterações, selecione Salvar sessão, seguido por Executar.

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

Uma sessão de depuração pode ser cancelada durante a execução usando o botão Cancelar . Se você pressionar o botão Cancelar, deverá ser capaz de analisar os resultados parciais.

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

Comece 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 são limitados a um documento. Você pode trabalhar nessa lista, fazer as alterações e retornar à 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 pode ser específico desse documento. Você pode escolher um documento diferente para confirmar se os erros e avisos são generalizados ou específicos de um único documento.

Selecione Erros ou Avisos para obter uma lista de problemas.

Como prática recomendada, resolva problemas com entradas antes de passar para saídas.

Para provar se uma modificação resolve um erro, siga estes passos:

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

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

3. Volte para Erros ou Avisospara ver se a contagem é reduzida.

Ver conteúdo enriquecido ou gerado

Os pipelines de enriquecimento de IA extraem ou inferem informações e estrutura de documentos de origem, criando um documento enriquecido no processo. Um documento enriquecido é criado pela primeira vez durante a quebra do documento e preenchido com um nó raiz (/document), além de nós para qualquer conteúdo que é retirado diretamente da fonte de dados, como metadados e a chave do documento. Mais nós são criados por habilidades durante a execução de habilidades, onde 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ões. Você pode passar o mouse sobre os links para exibir cada valor de entrada ou saída na árvore de documentos enriquecida. Para visualizar a entrada ou 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 enriquecida. No entanto, se você selecionar uma habilidade ou um mapeamento, o detalhe será sobre esse objeto.

   

2. Selecione uma habilidade.

   

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

   

Verificar mapeamentos de índice

Se as habilidades produzirem resultados, mas o índice de pesquisa estiver vazio, verifique os mapeamentos de campo. Os mapeamentos de campo especificam como o conteúdo sai do pipeline e entra em um índice de pesquisa.

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

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

• Os 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 Sintaxe do caminho do nó de enriquecimento.

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

Este exemplo mostra os detalhes de um mapeamento de projeção. Você pode 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 para configuração e conteúdo. Se uma habilidade não produzir saída, pode estar faltando uma propriedade ou parâmetro, 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 porque o erro dirá o que está errado, mas não como corrigi-lo. Para obter ajuda com o contexto e a sintaxe de entrada, consulte Enriquecimentos de referência em um conjunto de habilidades do Azure AI Search. Para obter ajuda com mensagens individuais, consulte Solução de 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 superfície de trabalho. O painel Detalhes da habilidade é aberto à direita.

2. Edite uma definição de habilidade usando as Configurações de habilidade. Você pode editar o JSON diretamente.

3. Verifique a sintaxe do caminho para referenciar nós em uma árvore de enriquecimento. A seguir estão alguns dos caminhos de entrada mais comuns:

   • /document/content para pedaços de texto. Este nó é preenchido a partir da propriedade content do blob.
   • /document/merged_content para pedaços de texto em frigideiras que incluem a habilidade de mesclagem de texto.
   • /document/normalized_images/* para texto reconhecido ou inferido a partir de imagens.

Depurar uma habilidade personalizada localmente

As habilidades personalizadas podem ser mais difíceis de depurar 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 sua habilidade de API Web personalizada, sessão de depuração, Visual Studio Code e ngrok ou Tunnelmole. Essa técnica funciona com habilidades personalizadas que são executadas no Azure Functions ou em qualquer outra estrutura da Web executada localmente (por exemplo, FastAPI).

Obter um URL público

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

Usar Tunnelmole

Tunnelmole é uma ferramenta de tunelamento de código aberto que pode criar uma URL pública que encaminha solicitações para sua máquina local através de um túnel.

1. Instale 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: Instale usando npm. Ou se você não tiver o NodeJS instalado, baixe o arquivo .exe pré-compilado para Windows e coloque-o em algum lugar no seu PATH.

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

   tmole 7071
   

   Você verá uma resposta parecida com esta:

   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 sua máquina local, que é a porta padrão onde as funções do Azure são expostas.

Use ngrok

O ngrok é um aplicativo popular, de código fechado e multiplataforma que pode criar um URL de encapsulamento ou encaminhamento, para que as solicitações da Internet cheguem à sua máquina local. Use ngrok para encaminhar solicitações de um pipeline de enriquecimento em seu serviço de pesquisa para sua máquina para permitir a depuração local.

1. Instale o ngrok.

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

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

   ngrok http 7071 
   

   Nota

   Por padrão, as funções do Azure são expostas em 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. O URL de encaminhamento é gerado aleatoriamente.

   

Configurar no portal do Azure

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

Você pode editar a definição de habilidade na seção Configurações de habilidade do painel Detalhes da habilidade.

Teste o seu código

Neste ponto, novas solicitações de sua sessão de depuração agora devem ser enviadas para sua Função do Azure local. Você pode usar pontos de interrupção em seu código do Visual Studio para depurar seu código ou executar passo a passo.

Próximos passos

Agora que você entende o layout e os recursos do editor visual Debug Sessions, experimente o tutorial para uma experiência prática.

Tutorial: Explore sessões de depuração