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. Ele mostra uma representação do documento enriquecido ou os detalhes de uma habilidade ou mapeamento.
A primeira imagem mostra um padrão para o 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 os campos em um índice.
A segunda imagem mostra um padrão típico para vetorização integrada. Geralmente, as habilidades para vetorização integrada incluem a Divisão de Texto e uma habilidade de inserção. Uma habilidade de Divisão de Texto agrupa um documento em páginas. As habilidades de inserção fornecem vetorização. Os mapeamentos de projeção controlam como partes do conteúdo são indexadas. Esse conjunto de habilidades específico ignora o índice pai e cria um índice de conteúdo em partes, usando metadados para identificar a origem da parte.
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 Online.
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.
Atualmente, a capacidade de selecionar qual documento depurar não está disponível. Essa limitação não é permanente e será suspensa 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 estado da sessão é salvo em um novo contêiner de blob criado pelo serviço da IA do Azure 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 os dados de sessão acidentalmente para outro contêiner na sua conta.
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.
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.