Sessões de Depuração 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. As guias e seções do editor desdobram várias camadas do conjunto de competências, permitindo que você examine a estrutura, o fluxo e o conteúdo gerado durante a 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 das sessões de depuração para os cenários um e dois. 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 criado pelo pipeline, ou os detalhes de uma competência ou de um mapeamento.

A primeira imagem mostra um padrão para enriquecimento de IA aplicado (sem vetores). As habilidades podem ser executadas sequencialmente ou em paralelo se não houver dependências. Os mapeamentos de índice mostram como o conteúdo enriquecido ou gerado viaja de estruturas de dados na memória para campos em um índice. O documento enriquecido mostra a estrutura de dados que o conjunto de habilidades cria.

A segunda imagem mostra um padrão típico de vetorização integrada. As habilidades para vetorização integrada geralmente incluem uma habilidade de divisão de texto e uma habilidade de incorporação. Uma habilidade de Divisão de Texto divide um documento em partes. Uma habilidade de incorporação chama uma API de incorporação para vetorizar esses segmentos. Este conjunto de habilidades em particular divide o conteúdo em uma matriz de "páginas". Para vetorização integrada, os mapeamentos de projeção controlam como os blocos são mapeados para campos no índice.

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.

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

• Fontes de dados com encriptação ativada através de chaves geridas pelo cliente (CMK).

• Links privados partilhados não são suportados. Se o seu serviço de pesquisa usa conectividade a endpoints privados para aceder a fontes de dados ou outros recursos, as sessões de depuração não conseguem aceder a esses recursos. Para uma solução alternativa, veja Sessões de Depuração e conectividade privada.

• Atualmente, a capacidade de selecionar qual documento depurar não está disponível. Esta limitação não é permanente e deverá 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. O serviço Pesquisa de IA do Azure guarda todo o estado da sessão num novo contentor de blob que cria numa conta do Armazenamento do Azure que fornece. O nome do contentor gerado tem um prefixo de ms-az-cognitive-search-debugsession. Este prefixo reduz a probabilidade de exportar acidentalmente os dados da sessão para outro contentor na sua conta.

Se configurar a ligação da conta de armazenamento utilizando uma identidade gerida, atribua a função Storage Blob Data Contributor à identidade do seu serviço de pesquisa na sua conta de armazenamento. Na sua conta de armazenamento, ative os serviços fidedignos para permitir o acesso de escrita do Pesquisa de IA do Azure.

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 das alterações irá substituir o conjunto de competências 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.

As sessões de depuração ajudam a identificar a causa principal de erros ou avisos, analisando dados, entradas e saídas de aptidões e o mapeamento de campos. Use o painel de detalhes das habilidades para inspecionar o que cada competência recebe como entrada e produz como saída. Esta inspeção ajuda a verificar se as definições de competências, expressões e mapeamentos de campos estão corretamente formados. Se o indexador encontrar problemas de configuração, como configuração incorreta da rede ou erros de acesso relacionados com permissões, reveja a mensagem de erro específica e a documentação associada. Para orientações sobre resolução de problemas, consulte Erros e avisos comuns do indexador.

Sessões de depuração e conectividade privada

As sessões de depuração não suportam links privados partilhados. Se o seu serviço de pesquisa em produção usa conectividade a endpoints privados para aceder a fontes de dados ou outros recursos, as sessões de depuração não podem correr contra esse serviço.

Solução alternativa: usar um serviço de pesquisa de teste

Para depurar o seu conjunto de competências, crie um serviço Pesquisa de IA do Azure separado sem restrições de conectividade privada. Para manter dados de produção e detalhes de esquemas fora de um ambiente não privado, construa a sua configuração de testes com documentos sintéticos:

• Crie documentos de teste que correspondam aos tipos de campo e à estrutura dos seus dados de produção, mas use nomes genéricos de campos (por exemplo, content, title, category) e valores provisórios em vez de dados reais. A lógica do conjunto de competências depende dos tipos de conteúdo e da estrutura, não dos nomes específicos das áreas.
• Copie o JSON do conjunto de competências do seu serviço de produção. Se as entradas de competências referenciarem nomes de campos de produção, atualize essas referências para corresponderem aos nomes genéricos dos seus campos de teste. Use mapeamentos de campos no indexador de teste para alinhar os nomes dos campos de teste com as entradas do conjunto de habilidades.
• Configure um indexador para correr contra a fonte de dados de teste.

Execute a sessão de depuração no serviço de teste para inspecionar entradas e saídas de competências, validar expressões de competências e mapeamentos de campos, e identificar erros. Quando as tuas alterações forem validadas, restaura as referências originais do nome do campo de produção no conjunto de competências JSON e aplica-as de volta ao teu serviço de produção.

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