Definir uma projeção de índice para indexação pai-filho

Se você estiver agrupando conteúdo para um padrão RAG ou vetorização, poderá especificar uma projeção de índice para controlar a indexação um para muitos, em que o conteúdo de origem (um) é projetado para um ou mais índices (muitos). A intenção de uma projeção de índice é controlar se os elementos do documento pai, como um nome de arquivo ou a data de criação:

• Repetir para cada filho (ou bloco) em um único índice
• São indexados como documentos de pesquisa autônomos no mesmo índice
• Ou são ingeridos em índices separados

Recomendamos que se repita os campos pai em um único índice, porque usar formatos diferentes de documento ou dividir o conteúdo em dois índices pode dificultar a consulta, especialmente na pesquisa clássica, na qual não há suporte para as associações de índices.

Em Pesquisa de IA do Azure , o agrupamento é executado por habilidades e, portanto, depende de indexadores. Para definir uma projeção de índice, especifique-a em um conjunto de habilidades.

Pré-requisitos

• Pesquisa de IA do Azure , qualquer nível ou região.

• Um pipeline de indexação com base em indexador.

• Uma fonte de dados com suporte que tem conteúdo que você deseja agrupar.

• Um índice (um ou vários) que aceita a saída do pipeline do indexador.

• Uma habilidade que fragmenta conteúdo, como a Habilidade de Divisão de Texto.

O conjunto de habilidades contém a projeção do indexador que adapta os dados para a indexação um para muitos. Um conjunto de habilidades também pode ter outras habilidades, como uma habilidade de inserção, como AzureOpenAIEmbedding , se o cenário incluir vetorização integrada.

Escolher uma abordagem

As projeções de índice geram os documentos "filho" (blocos) para cada documento "pai". Escolha como lidar com o conteúdo principal:

Para a maioria dos cenários de RAG, use a primeira abordagem. Consulte o exemplo clássico de RAG.

Etapas de implementação para a abordagem recomendada

1. Crie um índice projetado para blocos, com campos principais incluídos.
2. Crie um conjunto de habilidades com uma habilidade de blocos e indexProjections.
3. Crie um indexador apontando para a fonte de dados com suporte.

Se a fonte de dados der suporte ao controle de alterações, o indexador sincronizará as alterações automaticamente.

Criar um índice para indexação um para muitos

Se você criar um índice para segmentos que repetem valores do pai ou índices separados para posicionamento de campo pai-filho, o índice primário usado para pesquisa é projetado em torno de segmentos de dados. O esquema de índice deve ter os seguintes campos:

• Um campo de chave de documento que identifica exclusivamente cada documento. Ele deve ser definido como tipo Edm.String com o analisador keyword.

• Um campo que associa cada bloco com seu elemento pai. Deve ser do tipo Edm.String. Ele não pode ser o campo de chave do documento e deve ter filterable sido definido como true. Ele é conhecido como parent_id nos exemplos e como um valor de chave projetado neste artigo.

• Outros campos para conteúdo, como texto ou campos de partes vetorizados.

Um índice deve existir no serviço de pesquisa antes de criar o conjunto de habilidades ou executar o indexador. O selectors que você definir no conjunto de habilidades deve incluir esses campos.

Esquema de índice único inclusive de campos pai e filho

Um único índice criado em torno de segmentos, com conteúdo pai que se repete para cada segmento, é o padrão predominante para cenários de pesquisa de RAG e busca em vetores. A capacidade de associar o conteúdo pai correto a cada segmento é ativado por projeções de índice.

O esquema a seguir é um exemplo que atende aos requisitos para projeções de índice. Neste exemplo:

• Os campos pai são parent_id e título, e eles se repetem para cada segmento
• Os campos filho são os segmentos vetoriais e não vetoriais. O chunk_id é a ID do documento desse índice.

Você pode usar o portal Azure, AS APIs REST ou um SDK do Azure para criar um índice.

{
    "name": "my_consolidated_index",
    "fields": [
        {"name": "chunk_id", "type": "Edm.String", "key": true, "filterable": true, "analyzer": "keyword"},
        {"name": "parent_id", "type": "Edm.String", "filterable": true},
        {"name": "title", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "retrievable": true},
        {"name": "chunk", "type": "Edm.String","searchable": true,"retrievable": true},
        {"name": "chunk_vector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": false, "stored": false, "dimensions": 1536, "vectorSearchProfile": "hnsw"}
    ],
    "vectorSearch": {
        "algorithms": [{"name": "hnsw", "kind": "hnsw", "hnswParameters": {}}],
        "profiles": [{"name": "hnsw", "algorithm": "hnsw"}]
    }
}

 # Create a search index  
 index_name = "my_consolidated_index"
 index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)  
 fields = [
     SearchField(name="document_id", type=SearchFieldDataType.String, key=True, sortable=True, filterable=True, facetable=True, analyzer_name="keyword"),  
     SearchField(name="parent_id", type=SearchFieldDataType.String, filterable=True),  
     SearchField(name="title", type=SearchFieldDataType.String, searchable=True, sortable=False, filterable=True, facetable=False, retrievable=True), 
     SearchField(name="chunk", type=SearchFieldDataType.String, sortable=False, filterable=False, facetable=False, retrievable=True),  
     SearchField(name="chunk_vector", type=SearchFieldDataType.Collection(SearchFieldDataType.Single, searchable=True, retrievable=False), vector_search_dimensions=1024, vector_search_profile_name="myHnswProfile")
     ]  

 # Configure the vector search configuration  
 vector_search = VectorSearch(  
     algorithms=[  
         HnswAlgorithmConfiguration(name="myHnsw"),
     ],  
     profiles=[  
         VectorSearchProfile(  
             name="myHnswProfile",  
             algorithm_configuration_name="myHnsw",  
             vectorizer_name="myOpenAI",  
         )
     ],  
     vectorizers=[  
         AzureOpenAIVectorizer(  
             vectorizer_name="myOpenAI",  
             kind="azureOpenAI",  
             parameters=AzureOpenAIVectorizerParameters(  
                 resource_url=AZURE_OPENAI_ACCOUNT,  
                 deployment_name="text-embedding-3-large",
                 model_name="text-embedding-3-large"
             ),
         ),  
     ], 
 )  

 # Create the search index
 index = SearchIndex(name=index_name, fields=fields, vector_search=vector_search)  
 result = index_client.create_or_update_index(index)  
 print(f"{result.name} created")  

Adicionar projeções de índice a um conjunto de habilidades

As projeções de índice são definidas dentro de uma definição de conjunto de habilidades e são definidas principalmente como uma matriz de selectors, em que cada seletor corresponde a um índice de destino diferente no serviço de pesquisa. Esta seção começa com sintaxe e exemplos de contexto, seguidos de referência de parâmetro.

"indexProjections": {
    "selectors": [
        {
            "targetIndexName": "my_consolidated_index",
            "parentKeyFieldName": "parent_id",
            "sourceContext": "/document/pages/*",
            "mappings": [
                {
                    "name": "chunk",
                    "source": "/document/pages/*",
                    "sourceContext": null,
                    "inputs": []
                },
                {
                    "name": "chunk_vector",
                    "source": "/document/pages/*/chunk_vector",
                    "sourceContext": null,
                    "inputs": []
                },
                {
                    "name": "title",
                    "source": "/document/title",
                    "sourceContext": null,
                    "inputs": []
                }
            ]
        }
    ],
    "parameters": {
        "projectionMode": "skipIndexingParentDocuments"
    }
}

index_projections = SearchIndexerIndexProjection(  
    selectors=[  
        SearchIndexerIndexProjectionSelector(  
            target_index_name=index_name,  
            parent_key_field_name="parent_id",  
            source_context="/document/pages/*",  
            mappings=[  
                InputFieldMappingEntry(name="chunk", source="/document/pages/*"),  
                InputFieldMappingEntry(name="chunk_vector", source="/document/pages/*/chunk_vector"),
                InputFieldMappingEntry(name="title", source="/document/title")
            ],  
        ),  
    ],  
    parameters=SearchIndexerIndexProjectionsParameters(  
        projection_mode=IndexProjectionMode.SKIP_INDEXING_PARENT_DOCUMENTS  
    ),  
) 

Referência de parâmetro

Os parâmetros têm os seguintes elementos como parte de sua definição.

Os seletores têm os seguintes elementos como parte de sua definição.

O mappings parâmetro é importante. Você deve mapear de forma explícita cada campo no índice filho, exceto para os campos de ID, como a chave de documento e a ID pai.

Esse requisito contrasta com outras convenções de mapeamento de campo em Pesquisa de IA do Azure . Para alguns tipos de fonte de dados, o indexador pode mapear implicitamente campos com base em nomes semelhantes ou características conhecidas (por exemplo, indexadores de blob usam o caminho de armazenamento de metadados exclusivo como a chave de documento padrão). Mas, para projeções de indexador, você deve especificar de forma explicita cada mapeamento de campo no lado "muitos" do relacionamento.

Examinar mapeamentos de campo

Os indexadores são afiliados a três tipos diferentes de mapeamentos de campo. Antes de executar o indexador, verifique os mapeamentos de campo e saiba quando usar cada tipo.

Os mapeamentos de campo são definidos em um indexador e usados para mapear um campo de origem para um campo de índice. Os mapeamentos de campo são usados para caminhos de dados que levantam dados da origem e os transmitem para indexação, sem nenhuma etapa de processamento de habilidades intermediárias. Normalmente, um indexador pode mapear automaticamente campos com o mesmo nome e tipo. Mapeamentos de campo explícitos só são necessários quando há discrepâncias. Na indexação um para muitos e nos padrões discutidos até agora, talvez você não precise de mapeamentos de campo.

Os mapeamentos de campo de saída são definidos em um indexador e usados para mapear o conteúdo enriquecido gerado por um conjunto de habilidades para um campo no índice principal. Os fragmentos são considerados conteúdo enriquecido devido à criação por uma habilidade (Divisão de Texto), mas você não precisa de um mapeamento de campo de saída para fragmentos ou para projeções de índice, que são definidas por mapeamento de seletor.

Selectors.mappings é definido em um conjunto de habilidades e é mapeado para os campos no índice filho. Quando o índice filho também inclui campos pai (como na solução de índice consolidado), você deve definir mapeamentos de campo para cada campo com conteúdo, incluindo o campo de título de nível pai, supondo que o título deva aparecer em cada documento segmentado. Se você estiver usando índices pai e filho separados, o seletor deverá ter mapeamentos de campo apenas para os campos de nível filho.

Executar o indexador

Depois de criar uma fonte de dados, índices e conjunto de habilidades, você estará pronto para criar e executar o indexador. Esta etapa ativa a execução do pipeline.

Você pode consultar o índice de pesquisa após a conclusão do processamento para testar sua solução.

Ciclo de vida do conteúdo

Dependendo da fonte de dados subjacente, um indexador geralmente pode fornecer controle de alterações e detecção de exclusão contínuas. Esta seção explica o ciclo de vida de conteúdo da indexação um para muitos em relação à atualização de dados.

Para fontes de dados que fornecem controle de alterações e detecção de exclusão, um processo de indexador pode detectar alterações em seus dados de origem. Sempre que você 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 captadas 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. A atividade de atualização de dados é capturada em um valor chave projetado para cada bloco. Esse valor é atualizado quando os dados subjacentes são alterados.

Conteúdo atualizado

Se você adicionar um novo conteúdo à sua fonte de dados, novos fragmentos ou documentos filhos serão adicionados ao índice na próxima execução do processo de indexação.

Se você modificar o conteúdo existente na fonte de dados, as partes serão atualizadas incrementalmente no índice de pesquisa se a fonte de dados que você está usando oferecer suporte à detecção de controle de alterações e exclusão. Por exemplo, se uma palavra ou frase for alterada em um documento, a parte no índice de destino que contém essa palavra ou frase será atualizada na próxima execução do indexador. Outros tipos de atualizações, como alterar um tipo de campo e algumas atribuições, não têm suporte para campos existentes. Para obter mais informações sobre atualizações permitidas, consulte Atualizar um esquema de índice.

Algumas fontes de dados, como Armazenamento do Azure, dão suporte ao rastreamento de alterações e exclusões por padrão, com base no timestamp. Outras fontes de dados, como Microsoft OneLake, SQL do Azure ou Azure Cosmos DB devem ser configuradas para controle de alterações.

Conteúdo excluído

Se o conteúdo de origem não existir mais (por exemplo, se o texto for reduzido para ter menos partes), 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 não tiver dataDeletionDetectionPolicy configurado e precisar excluir um documento pai da fonte de dados, você deve excluir manualmente os documentos filho caso não sejam mais necessários.

Valor de chave projetado

Para garantir a integridade dos dados para conteúdo atualizado e excluído, a atualização de dados na indexação um para muitos depende de um valor de chave projetado no lado "muitos". Se você estiver usando a vetorização integrada ou o assistente de importação de dados, o valor da chave projetada é o campo parent_id no lado em partes ou "muitos" do índice.

Um valor de chave projetado é um identificador exclusivo que o indexador gera para cada documento. Ele garante a exclusividade e permite que o controle de alteração e exclusão funcione corretamente. Essa chave contém os seguintes segmentos:

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

Por exemplo, se você dividir um documento pai com o valor de chave "aa1b22c33" em quatro páginas e cada uma dessas páginas for projetada como seu próprio documento por meio de projeções de índice:

• aa1b22c33
• aa1b22c33_pages_0
• aa1b22c33_pages_1
• aa1b22c33_pages_2

Se o documento pai for atualizado nos dados de origem, possivelmente resultando em páginas mais divididas, as alterações no hash aleatório fazem com que mais páginas sejam adicionadas e o conteúdo de cada parte seja atualizado para corresponder ao que está no documento de origem.

Exemplo de índices pai-filho separados

Esta seção mostra um exemplo para índices pai e filho separados. É um padrão incomum, mas é possível que você tenha requisitos de aplicativo que sejam melhor atendidos usando essa abordagem. Nesse cenário, você está projetando conteúdo pai-filho em dois índices separados.

1. Crie dois esquemas de índice.

   Cada esquema tem os campos para a granularidade específica, com o campo ID pai comum aos dois índices para uso em uma consulta de pesquisa. O corpus de pesquisa principal é o índice filho, mas você pode fazer uma consulta de pesquisa a fim de recuperar os campos pai para cada correspondência no resultado. Pesquisa de IA do Azure  não dá suporte a junções no momento da consulta, portanto, o código do aplicativo ou a camada de orquestração precisariam mesclar ou agrupar resultados que possam ser passados para um aplicativo ou processo.

   O índice pai possui um campo chamado parent_id e um título. O parent_id é a chave do documento. Você não precisa de configuração de pesquisa de vetor, a menos que deseje vetorizar campos no nível do documento pai.

   {
       "name": "my-parent-index",
       "fields": [
   
           {"name": "parent_id", "type": "Edm.String", "key":true, "filterable": true},
           {"name": "title", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "retrievable": true}
       ]
   }
   

   O índice filho tem os campos segmentados, além do campo parent_id. Se você estiver usando a vetorização integrada, perfis de pontuação, o classificador semântico ou analisadores, você os definirá no índice filho.

   {
       "name": "my-child-index",
       "fields": [
           {"name": "chunk_id", "type": "Edm.String", "key": true, "filterable": true, "analyzer": "keyword"},
           {"name": "parent_id", "type": "Edm.String", "filterable": true},
            {"name": "chunk", "type": "Edm.String","searchable": true,"retrievable": true},
           {"name": "chunk_vector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": false, "stored": false, "dimensions": 1536, "vectorSearchProfile": "hnsw"}
       ],
       "vectorSearch": {
           "algorithms": [{"name": "hsnw", "kind": "hnsw", "hnswParameters": {}}],
           "profiles": [{"name": "hsnw", "algorithm": "hnsw"}]
       },
       "scoringProfiles": [],
       "semanticConfiguration": [],
       "analyzers": []
   }
   

2. Atualize o indexador para especificar o parent-index como o alvo.

   A definição do indexador especifica os componentes do pipeline. Na definição do indexador, o nome do índice a ser fornecido é o índice pai. Se você precisar de mapeamentos de campo para os campos de nível pai, defina-os em outputFieldMappings. Para a indexação um para muitos que utiliza índices distintos, a definição do indexador terá a aparência do exemplo a seguir.

   {
     "name": "my-indexer",
     "dataSourceName": "my-ds",
     "targetIndexName": "my-parent-index",
     "skillsetName" : "my-skillset",
     "parameters": { },
     "fieldMappings": (optional) Maps fields in the underlying data source to fields in an index,
     "outputFieldMappings" : (required) Maps skill outputs to fields in an index,
   }
   

3. Adicione indexProjections ao conjunto de habilidades.

   Aqui está um exemplo de uma definição de projeção de índice que especifica o caminho de dados que o indexador deve usar para indexar o conteúdo. Ele especifica o nome do índice filho na definição de projeção de índice, e também especifica os mapeamentos de cada campo filho ou em nível de segmento. Esse é o único lugar em que o nome do índice filho é especificado.

   Observe que parameters é nulo e está usando o padrão includeIndexingParentDocuments. O indexador preenche o índice pai. A matriz selectors é usada para projetar os documentos de bloco no índice filho.

   "indexProjections": {
       "selectors": [
           {
               "targetIndexName": "my-child-index",
               "parentKeyFieldName": "parent_id",
               "sourceContext": "/document/pages/*",
               "mappings": [
                   {
                       "name": "chunk",
                       "source": "/document/pages/*",
                       "sourceContext": null,
                       "inputs": []
                   },
                   {
                       "name": "chunk_vector",
                       "source": "/document/pages/*/chunk_vector",
                       "sourceContext": null,
                       "inputs": []
                   }
               ]
           }
       ],
       "parameters": {}
   }
   

4. Execute o indexador. Se você executou anteriormente o indexador, lembre-se de redefini-lo primeiro.

   Você deve ter dois índices preenchidos com o conteúdo apropriado. Consulte os índices no Gerenciador de Pesquisa para verificar se cada um tem o conteúdo correto.

Próxima etapa

O agrupamento de dados e a indexação um-para-muitos fazem parte do padrão RAG clássico na Pesquisa de IA do Azure. Continue no tutorial a seguir e no exemplo de código para saber mais sobre ele.