Sessões de Depuração na IA do Azure Search

As Sessões de Depuração são um editor visual que funciona com um conjunto de habilidades existente no portal do Azure, expondo a estrutura e o conteúdo de apenas um documento enriquecido, enquanto ele é produzido por um indexador e um conjunto de habilidades, durante a sessão. Como você está trabalhando com um documento dinâmico, 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á confirmá-las em um conjunto de habilidades publicado para aplicar as correções globalmente.

Este artigo explica os cenários com suporte e como o editor é 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 gerado em tempo de execução.

Cenários com suporte

Use sessões de depuração para investigar e resolver problemas com:

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

• Habilidades internas usadas para vetorização integrada, com agrupamento de dados por meio da Divisão de Texto e vetorização por meio de uma habilidade de inserção.

• Habilidades personalizadas usadas para integrar o processamento externo fornecido por você.

Compare as imagens da sessão de depuração a seguir para os dois primeiros cenários. Para ambos os cenários, a área de superfície mostra a progressão das habilidades que geram ou transformam o conteúdo a 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 faz diferenciação do contexto. Mostra uma representação do documento enriquecido criado pelo pipeline ou os detalhes de uma habilidade ou mapeamento.

A primeira imagem mostra um padrão para o enriquecimento de IA aplicado (sem vectores). 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 é transferido de estruturas de dados na memória para os campos em um índice. O documento enriquecido mostra a estrutura de dados criada pelo conjunto de habilidades.

A segunda imagem mostra um padrão típico para vetorização integrada. Geralmente, as habilidades de vetorização integrada 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 essas partes. Este conjunto de habilidades específico divide o conteúdo em uma matriz de "páginas". Para realizar a vetorização integrada, os mapeamentos de projeção controlam como as partes são mapeadas para os campos no índice.

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.

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

• Fontes de dados com criptografia habilitada por meio de chaves gerenciadas pelo cliente (CMK).

• Não há suporte para links privados compartilhados. Se o serviço de pesquisa usar conectividade de ponto de extremidade privado para acessar fontes de dados ou outros recursos, as sessões de depuração não poderão acessar esses recursos. Para obter uma solução alternativa, consulte Sessões de depuração e conectividade privada.

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

Como uma sessão de depuração funciona

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 que contém um único documento usado para testar o conjunto de habilidades. O serviço Pesquisa de IA do Azure  salva todo o estado da sessão em um novo contêiner de blob que ele cria em uma conta Armazenamento do Azure que você fornece. O nome do contêiner gerado tem um prefixo de ms-az-cognitive-search-debugsession. Esse prefixo reduz a chance de exportar dados de sessão acidentalmente para outro contêiner em sua conta.

Se você configurar a conexão da conta de armazenamento usando uma identidade gerenciada, atribua a Storage Blob Data Contributor função à identidade do serviço de pesquisa na conta de armazenamento. Na sua conta de armazenamento, habilite os serviços confiáveis para permitir o acesso de gravação do Pesquisa de IA do Azure.

Uma cópia armazenada 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 aspecto 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 afetam o conjunto de habilidades publicado, a menos que você as confirme. A confirmação das 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 poderá ser usada para enriquecer um documento de forma incremental, testar e validar cada alteração antes de confirmar as alterações.

As sessões de depuração ajudam a identificar a causa raiz de erros ou avisos analisando dados, entradas e saídas de habilidades e mapeamentos de campo. Use o painel de detalhes da habilidade para inspecionar o que cada habilidade recebe como entrada e produz como saída. Essa inspeção ajuda a verificar se definições de habilidade, expressões e mapeamentos de campo estão formados corretamente. Se o indexador encontrar problemas de configuração, como configuração de rede incorreta ou erros de acesso relacionados à permissão, examine a mensagem de erro específica e a documentação vinculada. Para obter diretrizes de soluçã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 dão suporte a links privados compartilhados. Se o seu serviço de pesquisa de produção usar conectividade de ponto de extremidade privado para acessar fontes de dados ou outros recursos, as sessões de depuração não poderão ser executadas nesse serviço.

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

Para depurar seu conjunto de habilidades, crie um serviço Pesquisa de IA do Azure  separado sem restrições de conectividade privada. Para manter os dados de produção e os detalhes do esquema fora de um ambiente não privado, crie sua configuração de teste com documentos sintéticos:

• Crie documentos de teste que correspondam aos tipos de campo e à estrutura dos dados de produção, mas use nomes de campo genéricos (por exemplo, content, title, ) categorye valores de espaço reservado em vez de dados reais. A lógica do conjunto de habilidades depende de tipos de conteúdo e estrutura, não de nomes de campo específicos.
• Copie o JSON do conjunto de habilidades do seu serviço de produção. Se as entradas de habilidade fizerem referência a nomes de campo de produção, atualize essas referências para corresponder aos nomes de campo de teste genéricos. Use mapeamentos de campo no indexador de teste para alinhar os nomes dos campos de teste com as entradas do conjunto de habilidades.
• Configure um indexador para ser executado na fonte de dados de teste.

Execute a sessão de depuração no serviço de teste para inspecionar entradas e saídas de habilidades, validar expressões de habilidade e mapeamentos de campo e identificar erros. Quando as suas alterações forem validadas, restaure as referências originais dos nomes de campo de produção no JSON do conjunto de habilidades e aplique-as novamente ao seu serviço de produção.

Layout da sessão de depuração

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

Ao selecionar qualquer habilidade ou mapeamento, um painel será aberto ao lado, mostrando informações relevantes.

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.

Painel de detalhes da habilidade

O painel de detalhes de habilidades tem as seguintes seções:

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

Painel da estrutura de dados enriquecidos

O painel da Estrutura de dados enriquecidos desliza para o lado quando você seleciona a exibição azul ou oculta o símbolo de seta. É uma representação legível para humanos do que o documento enriquecido contém. Capturas de tela prévias neste artigo mostram exemplos da estrutura de dados enriquecida.

Próximas etapas

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.