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

• 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. 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 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 raiz de erros ou avisos analisando os dados, as entradas e saídas de habilidades e os mapeamentos de campo. Se o indexador encontrar problemas de configuração, como configuração de rede incorreta, erros de acesso relacionados a permissões ou similares, revise a mensagem de erro específica juntamente com a documentação vinculada fornecida. Para obter orientações sobre solução de problemas, consulte os erros e avisos comuns do indexador.

Depurar sessões com conectividade privada

Se seu pipeline de enriquecimento de IA usa links privados compartilhados para acessar recursos do Azure, é necessária uma configuração adicional para garantir que as sessões de indexador e depuração funcionem corretamente. Isso inclui permissões, acesso confiável e configuração de rede.

• Se você estiver usando a identidade gerenciada, atribua as funções necessárias à identidade do serviço de pesquisa, incluindo Storage Blob Data Contributor, para que as sessões de depuração possam gravar dados da sessão em sua conta de armazenamento.
• Certifique-se de que o serviço de pesquisa tenha acesso a todos os recursos referenciados na definição do conjunto de habilidades, incluindo qualquer usado na sessão de depuração.
• Na sua conta de armazenamento, habilite os serviços confiáveis para permitir o acesso a partir do Azure AI Search.
• Defina "executionEnvironment" = "private" a propriedade na definição do indexador para garantir que o indexador seja executado em um contexto privado.
• Crie um link privado compartilhado para cada recurso acessado pelo serviço de pesquisa, incluindo: sua fonte de dados, se configurada para indexar cache de enriquecimento de IA e armazenamento de conhecimento, e quaisquer outros recursos configurados em seu conjunto de habilidades.
• Para obter outras diretrizes de solução de problemas, consulte os erros e avisos comuns do indexador.

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.