Depurar sessões na Pesquisa de IA do Azure

Debug Sessions é um editor visual que trabalha com um conjunto de habilidades existente no portal do Azure, expondo a estrutura e o conteúdo de um único documento enriquecido à medida que é produzido por um indexador e conjunto de habilidades durante a sessão. Como você está trabalhando com um documento ao vivo, a sessão é interativa - você pode identificar erros, modificar e invocar a execução de habilidades e validar os resultados em tempo real. Se as alterações resolverem o problema, você poderá vinculá-las a um conjunto de habilidades publicado para aplicar as correções globalmente.

Este artigo explica os cenários suportados e como o editor está organizado. Guias e seções do editor descompactam diferentes camadas do conjunto de habilidades para que você possa examinar a estrutura do conjunto de habilidades, o fluxo e o conteúdo que ele gera em tempo de execução.

Cenários suportados

Use Debug Sessions para investigar e resolver problemas com:

• Habilidades incorporadas usadas para enriquecimento de IA, como OCR, análise de imagem, reconhecimento de entidade e extração de palavras-chave.

• Habilidades incorporadas usadas para vetorização integrada, com fragmentação de dados através de divisão de texto e vetorização através de uma habilidade de incorporação.

• Habilidades personalizadas usadas para integrar o processamento externo que você fornece.

Compare as seguintes imagens de sessão de depuração para os dois primeiros cenários. Para ambos os cenários, a área de superfície mostra a progressão de habilidades que geram ou transformam conteúdo no caminho do documento de origem para o índice de pesquisa. O fluxo inclui opções de mapeamento de índice e você pode rastrear as setas para seguir a trilha de processamento. O painel de detalhes à direita é sensível ao contexto. Ele mostra uma representação do documento enriquecido ou os detalhes de uma habilidade ou mapeamento.

A primeira imagem mostra um padrão para enriquecimento de IA aplicado. As habilidades podem ser executadas sequencialmente ou em paralelo se não houver dependências. Os mapeamentos de campo de saída enviam conteúdo enriquecido ou gerado de estruturas de dados na memória para campos em um índice.

A segunda imagem mostra um padrão típico de vetorização integrada. As habilidades para vetorização integrada geralmente incluem divisão de texto e uma habilidade de incorporação. Uma habilidade de Divisão de Texto divide um documento em páginas. Uma habilidade de incorporação fornece vetorização. Os mapeamentos de projeção controlam como os blocos de conteúdo são indexados. Esse conjunto de habilidades específico ignora o índice pai e cria um índice de conteúdo apenas fragmentado, usando metadados para identificar a origem do bloco.

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.

• Atualmente, a capacidade de selecionar qual documento depurar não está disponível. Esta limitação não é permanente e será levantada em breve. Neste momento, Debug Sessions seleciona o primeiro documento no contêiner ou pasta de dados de origem.

Como funciona uma sessão de depuração

Quando você inicia uma sessão, o serviço de pesquisa cria uma cópia do conjunto de habilidades, do indexador e de uma fonte de dados contendo um único documento usado para testar o conjunto de habilidades. Todo o estado da sessão é salvo em um novo contêiner de blob criado pelo serviço Azure AI Search em uma conta de Armazenamento do Azure que você fornece. O nome do contêiner gerado tem um prefixo de ms-az-cognitive-search-debugsession. O prefixo é necessário porque reduz a chance de exportar acidentalmente dados de sessão para outro contêiner em sua conta.

Uma cópia em cache do documento enriquecido e do conjunto de habilidades é carregada no editor visual para que você possa inspecionar o conteúdo e os metadados do documento enriquecido, com a capacidade de verificar cada nó do documento e editar qualquer aspeto da definição do conjunto de habilidades. Todas as alterações feitas dentro da sessão são armazenadas em cache. Essas alterações não afetarão o conjunto de habilidades publicadas, a menos que você as confirme. A confirmação de alterações substituirá o conjunto de habilidades de produção.

Se o pipeline de enriquecimento não tiver erros, uma sessão de depuração pode ser usada para enriquecer incrementalmente um documento, testar e validar cada alteração antes de confirmar as alterações.

Layout da sessão de depuração

O editor visual é organizado em uma área de superfície mostrando uma progressão de operações, começando com a quebra de documentos, seguida por habilidades, mapeamentos e um índice.

Selecione qualquer habilidade ou mapeamento, e um painel será aberto para o lado mostrando informações relevantes.

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.

Painel de detalhes de habilidades

O painel Detalhes da habilidade tem as seguintes seções:

• Iterações: mostra quantas vezes uma habilidade é executada. Você pode verificar as entradas e saídas de cada um.
• Configurações de habilidade: visualize ou edite a definição do conjunto de habilidades JSON.
• Erros e avisos: Mostra os erros ou avisos específicos para esta habilidade.

Painel de estrutura de dados enriquecido

O painel Estrutura de Dados Enriquecida desliza para o lado quando você seleciona o símbolo de seta azul mostrar ou ocultar. É uma representação legível por humanos do que o documento enriquecido contém. As capturas de tela anteriores neste artigo mostram exemplos da estrutura de dados enriquecida.

Próximos passos

Agora que você entende os elementos das sessões de depuração, inicie sua primeira sessão de depuração em um conjunto de habilidades existente.