Projeções de índice na IA do Azure Search

  • Artigo

Importante

As projeções de índice estão em visualização pública nos termos de uso complementares. Isso está disponível por meio do portal do Azure, APIs REST 2023-10-01-Preview, portal do Azure e bibliotecas de clientes beta que foram atualizadas para incluir o recurso.

As projeções de índice são um componente de uma definição de conjunto de habilidades que estabelecem a forma de um índice secundário, dando suporte a um padrão de índice um-para-muitos, em que o conteúdo de um pipeline de enriquecimento pode ter vários índices como destino.

As projeções de índice levam o conteúdo enriquecido com IA gerado por um pipeline de enriquecimento e o indexam em um índice secundário (diferente daquele que um indexador visa por padrão) em seu serviço de pesquisa. As projeções de índice também permitem remodelar os dados antes de indexá-los, permitindo separar de forma única uma matriz de itens enriquecidos em vários documentos de pesquisa no índice de destino, também conhecido como indexação "um-para-muitos". A indexação "um-para-muitos" é útil em cenários de divisão de dados em partes, nos quais você pode desejar um índice primário para o conteúdo não dividido em partes e um índice secundário para os que são divididos.

Se você já usou habilidades cognitivas, já sabe que conjuntos de habilidadescriam conteúdo enriquecido. Os conjuntos de habilidades movem um documento por meio de uma sequência de enriquecimentos que invocam transformações atômicas, como o reconhecimento de entidades ou a tradução do texto. Por padrão, um documento processado em um conjunto de habilidades é mapeado para um único documento no índice de pesquisa. Isso significa que, se você executar a divisão em partes de um texto de entrada e executar enriquecimentos em cada parte, o resultado no índice será uma matriz dos enriquecimentos gerados, quando for mapeado por meio de outputFieldMappings. Com as projeções de índice, você define um contexto no qual mapear cada parte dos dados enriquecidos para o próprio documento de pesquisa. Isso permite aplicar um mapeamento um-para-muitos dos dados enriquecidos de um documento ao índice de pesquisa.

Definição das projeções de índice

As projeções de índice são definidas dentro de uma definição de conjunto de habilidades e principalmente como uma matriz de seletores, em que cada seletor corresponde a um índice de destino diferente no serviço de pesquisa. Cada seletor necessita dos seguintes parâmetros como parte de sua definição:

  • targetIndexName: o nome do índice no serviço de pesquisa no qual os dados de projeção de índice são indexados.
  • parentKeyFieldName: o nome do campo no índice de destino que contém o valor da chave do documento pai.
  • sourceContext: a anotação de enriquecimento que define em qual granularidade mapear os dados nos documentos de pesquisa individuais. Para obter mais informações, consulte o Contexto de habilidade e linguagem de anotação de entrada.
  • mappings: uma matriz de mapeamentos de dados enriquecidos para campos no índice de pesquisa. Cada mapeamento consiste em:
    • name: o nome do campo no índice de pesquisa no qual os dados devem ser indexados,
    • source: o caminho de anotação de enriquecimento do qual os dados devem ser extraídos.

Cada mapping também pode definir dados recursivamente com um campo sourceContext e inputs opcional, semelhante ao repositório de conhecimento ou à Habilidade do Shaper. Esses parâmetros permitem modelar dados para serem indexados em campos de tipo Edm.ComplexType no índice de pesquisa.

O índice definido no parâmetro targetIndexName tem os seguintes requisitos:

  • Deve ter sido criado no serviço de pesquisa antes da criação do conjunto de habilidades que contém a definição das projeções de índice.
  • Deve conter um campo com o nome definido no parâmetro parentKeyFieldName. Esse campo deve ser do tipo Edm.String, não pode ser o campo-chave e deve ter filterable definido como true.
  • O campo-chave deve ter searchable definido como true e ser definido com o analisador keyword.
  • Deve ter campos definidos para cada um dos names definidos em mappings e nenhum deles pode ser o campo-chave.

Aqui está um exemplo de conteúdo para uma definição de projeções de índice que você pode usar para projetar a saída de páginas individuais pela Divisão da habilidade como seus próprios documentos no índice de pesquisa.

"indexProjections": {
    "selectors": [
        {
            "targetIndexName": "myTargetIndex",
            "parentKeyFieldName": "ParentKey",
            "sourceContext": "/document/pages/*",
            "mappings": [
                {
                    "name": "chunk",
                    "source": "/document/pages/*"
                }
            ]
        }
    ]
}

Tratando documentos pai

Como as projeções de índice geram efetivamente documentos "filho" para cada documento "pai" que é executado por meio de um conjunto de habilidades, você também tem as seguintes opções de como tratar a indexação dos documentos "pai".

  • Para manter documentos pai e filho em índices separados, basta garantir que o targetIndexName da sua definição de indexador seja diferente do targetIndexName definido no seletor de projeção de índice.

  • Para indexar documentos pai e filho no mesmo índice, é necessário verificar se o esquema do índice de destino funciona nos dois fieldMappings e outputFieldMappings definidos na definição de indexador e os mappings no seletor de projeção de índice. Em seguida, você apenas forneceria o mesmo targetIndexName para sua definição de indexador e seletor de projeção de índice.

  • Para ignorar documentos pai e apenas indexar documentos filho, ainda é necessário fornecer um targetIndexName na definição de indexador (você pode apenas fornecer o mesmo fornecido para o seletor de projeção de índice). Em seguida, defina um objeto parameters separado próximo sua definição selectors com uma chave projectionMode definida como skipIndexingParentDocuments, conforme mostrado aqui:

    "indexProjections": {
    "selectors": [
        ...
    ],
    "parameters": {
        "projectionMode": "skipIndexingParentDocuments"
    }
}

A versão 2023-10-01-Preview da API REST pode ser usada para criar projeções de índice por meio de adições a um conjunto de habilidades.

Ciclo de vida do conteúdo

Se a fonte de dados do indexador der suporte ao controle de alterações e à detecção de exclusões, o processo de indexação poderá sincronizar os índices primário e secundário para selecionar essas alterações.

Sempre que executar o indexador e o conjunto de habilidades, as projeções de índice serão atualizadas se o conjunto de habilidades ou os dados de origem subjacentes forem alterados. Todas as alterações selecionadas pelo indexador são propagadas por meio do processo de enriquecimento para as projeções no índice, garantindo que os dados projetados sejam uma representação atual do conteúdo na fonte de dados de origem.

Observação

Embora você possa editar os dados nos documentos projetados manualmente usando a API de push de índice, todas as edições serão substituídas na próxima invocação de pipeline, considerando que o documento nos dados de origem está atualizado.

Valor de chave projetado

Cada documento de projeção de índice contém uma chave de identificação exclusiva que o indexador gera para garantir exclusividade e permitir que o controle de alterações e exclusões funcione corretamente. Essa chave contém os seguintes segmentos:

  • Um hash aleatório para garantir a exclusividade. Esse hash será alterado se o documento pai for atualizado em execuções do indexador.
  • A chave do documento pai.
  • O caminho de anotação de enriquecimento que identifica o contexto do qual esse documento foi gerado.

Por exemplo, se você dividir um documento pai com o valor da chave "123" em quatro páginas e cada uma dessas páginas for projetada como seu próprio documento por meio das projeções de índice, a chave da terceira página de texto será semelhante a "01f07abfe7ed_123_pages_2". Se o documento pai for atualizado para adicionar uma quinta página, a nova chave da terceira página poderá ser, por exemplo, "9d800bdacc0e_123_pages_2", já que o valor de hash aleatório é alterado entre as execuções do indexador, mesmo que o restante dos dados de projeção não tenha sido alterado.

Alterações ou adições

Se um documento pai for alterado ao ponto dos dados em um documento de índice projetado serem alterados (um exemplo seria se uma palavra foi alterada em uma página específica, mas nenhuma página nova líquida foi adicionada), os dados no índice de destino para essa projeção específica são atualizados para refletir essa alteração.

Se um documento pai for alterado ao ponto de ter novos documentos filho projetados que não estavam lá antes (um exemplo seria se uma ou mais páginas de texto fossem adicionadas ao documento), esses novos documentos filho serão adicionados na próxima vez que o indexador for executado.

Em ambos os casos, todos os documentos projetados são atualizados para ter um novo valor de hash em sua chave, independentemente do seu conteúdo específico ter sido atualizado.

Exclusões

Se um documento pai for alterado ao ponto de um documento filho gerado por projeções de índice não existir mais (um exemplo seria se um texto for reduzido para que tenha menos partes do que antes), o documento filho correspondente no índice de pesquisa será excluído. Os documentos filho restantes também recebem a chave atualizada para incluir um novo valor de hash, mesmo que o conteúdo não tenha sido alterado de outra forma.

Se um documento pai for completamente excluído da fonte de dados, os documentos filho correspondentes serão excluídos somente se a exclusão for detectada por uma dataDeletionDetectionPolicy definida na definição da fonte de dados. Se você não tiver um dataDeletionDetectionPolicy configurado e precisar excluir um documento pai da fonte de dados, deverá excluir manualmente os documentos filho se eles não forem mais desejados.