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

  • Artigo

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 publicado 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 suas alterações 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 pipeline de enriquecimento existente, incluindo uma fonte de dados, um conjunto de habilidades, um indexador e um índice.

  • Uma atribuição de função de Colaborador no serviço de pesquisa.

  • Uma conta de Armazenamento do Azure, usada para salvar o estado da sessão.

  • Uma atribuição de função de Colaborador de Dados de Blob de Armazenamento no Armazenamento do Azure se você estiver usando uma identidade gerenciada pelo sistema. 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. A lista a seguir observa as exceções:

  • O Azure Cosmos DB para MongoDB não é suportado no momento.

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

O portal não suporta criptografia de chave gerenciada pelo cliente (CMK), o que significa que experiências de portal como sessões de depuração não podem ter cadeias de conexão criptografadas por CMK ou outros metadados criptografados. Se o serviço de pesquisa estiver configurado para imposição de CMK, as sessões de depuração não funcionarão.

Criar uma sessão de depuração

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

  2. Na página de navegação esquerda, selecione Depurar sessões.

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

    Captura de tela dos comandos de sessões de depuração na página do portal.

  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. Em Conexão de armazenamento, localize uma conta de armazenamento de uso geral para armazenar em cache a sessão de depuração. Você será solicitado a selecionar e, opcionalmente, criar um contêiner de blob no Armazenamento de Blob ou no Azure Data Lake Storage Gen2. Você pode reutilizar o mesmo contêiner para todas as sessões de depuração subsequentes criadas. Um nome de contêiner útil pode ser "cognitive-search-debug-sessions".

  6. Em Autenticação de identidade gerenciada, escolha Nenhum se a conexão com o Armazenamento do Azure não usar uma identidade gerenciada. Caso contrário, escolha a identidade gerenciada à qual você concedeu permissões de Colaborador de Dados de Blob de Armazenamento .

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

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

    Captura de tela da propriedade URI no armazenamento de blob.

  9. 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 imitar 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.

  10. Sua configuração deve ser semelhante a esta captura de tela. Selecione Salvar sessão para começar.

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

A sessão de depuração começa executando o indexador e o conjunto de habilidades no documento selecionado. O conteúdo do documento e os metadados criados estarão visíveis e 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 serão limitados a um documento. Você trabalhará nessa lista, fará suas alterações e retornará à lista para verificar se os problemas foram resolvidos.

Para visualizar as mensagens, selecione uma habilidade no AI Enrichment Skill Graph e, em seguida, selecione Erros/Avisos no painel de detalhes.>

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/Avisos para ver se a contagem é reduzida. A lista não será atualizada até que você abra a guia.

Exibir conteúdo de nós de enriquecimento

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.

Os documentos enriquecidos são internos, mas uma sessão de depuração dá acesso ao conteúdo produzido durante a execução de habilidades. Para visualizar o conteúdo ou a saída de cada habilidade, siga estas etapas:

  1. Comece com as visualizações padrão: AI enriquecimento > Skill Graph, com o tipo de gráfico definido como Dependency Graph.

  2. Selecione uma habilidade.

  3. No painel de detalhes à direita, selecione Execuções, selecione uma SAÍDA e abra o Avaliador de Expressões (</>) para exibir a expressão e seu resultado.

    Captura de tela de uma execução de habilidade mostrando valores de saída.

  4. Como alternativa, abra a Estrutura de Dados Enriquecida de enriquecimento > de IA para rolar a lista de nós para baixo. A lista inclui nós potenciais e reais, com uma coluna para saída e outra coluna que indica o objeto upstream usado para produzir a saída.

    Captura de ecrã do documento enriquecido a mostrar valores de saída.

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. No Gráfico de habilidades de enriquecimento de > IA, selecione uma habilidade. O painel Detalhes da Habilidade é aberto à direita.

  2. Edite uma definição de habilidade usando qualquer uma das abordagens:

    • Configurações de habilidade se você preferir um editor visual
    • Skill JSON Editor para editar o documento 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.

Verificar mapeamentos de campo

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.

  1. Comece com as visualizações padrão: AI enriquecimento > Skill Graph, com o tipo de gráfico definido como Dependency Graph.

  2. Selecione Mapeamentos de campo na parte superior. Você deve encontrar pelo menos a chave do documento que identifica e associa exclusivamente cada documento de pesquisa no índice de pesquisa com seu documento de origem na fonte de dados.

    Se você estiver importando conteúdo bruto diretamente da fonte de dados, ignorando o enriquecimento, deverá encontrar esses campos em Mapeamentos de Campo.

  3. Selecione Mapeamentos de campo de saída na parte inferior do gráfico. Aqui você encontrará mapeamentos de saídas de habilidades para campos de destino no índice de pesquisa. A menos que você tenha usado o assistente Importar Dados, os mapeamentos de campo de saída são definidos manualmente e podem estar incompletos ou digitados incorretamente.

    Verifique se os campos em Mapeamentos de Campo de Saída existem no índice de pesquisa conforme especificado, verificando a sintaxe do caminho do nó de enriquecimento e ortografia.

    Captura de tela do nó Mapeamentos de Campo de Saída e detalhes.

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

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

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

    Screenshot do terminal ngrok.

Configurar no portal do Azure

Na sessão de depuração, modifique o URI de habilidade da API Web personalizada 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 no portal.

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