Executar ou redefinir indexadores, habilidades ou documentos

Artigo
10/29/2024

No Azure AI Search, há várias maneiras de executar um indexador:

Execute imediatamente após a criação do indexador, supondo que ele não tenha sido criado no modo "desabilitado".
Executar em um agendamento para invocar a execução em intervalos regulares.
Execute sob demanda, com ou sem uma "redefinição".

Este artigo explica como executar indexadores sob demanda, com e sem uma redefinição. Ele também descreve a execução, a duração e a simultaneidade do indexador.

Como os indexadores se conectam aos recursos do Azure

Os indexadores são um dos poucos subsistemas que fazem chamadas de saída evidentes para outros recursos do Azure. Em termos de funções do Azure, os indexadores não têm identidades separadas: uma conexão do mecanismo de pesquisa com outro recurso do Azure é feita usando a identidade gerenciada atribuída pelo usuário ou pelo sistema de um serviço de pesquisa. Se o indexador se conectar a um recurso do Azure em uma rede virtual, você deverá criar um link privado compartilhado para essa conexão. Para obter mais informações sobre conexões seguras, confira Segurança na Pesquisa de IA do Azure.

Execução do indexador

Um serviço de pesquisa executa um trabalho de indexador por unidade de pesquisa. Cada serviço de pesquisa começa com uma unidade de pesquisa, mas cada nova partição ou réplica aumenta as unidades de pesquisa do serviço. Você pode verificar a contagem de unidades de pesquisa na seção Essencial do portal da página de visão geral. Se você precisar de processamento simultâneo, verifique se suas unidades de pesquisa incluem réplicas suficientes. Os indexadores não são executados em segundo plano, portanto, você pode detectar mais limitação de consulta do que o normal se o serviço estiver sob pressão.

A captura de tela a seguir mostra o número de unidades de pesquisa, que determina quantos indexadores podem ser executados ao mesmo tempo.

Depois que a execução do indexador for iniciada, você não poderá pausá-la ou interrompê-la. A execução do indexador é interrompida quando não há mais documentos para carregar ou atualizar ou quando o limite de tempo de execução é atingido.

Você pode executar vários indexadores ao mesmo tempo se tiver capacidade suficiente, mas cada indexador em si é de instância única. Iniciar uma nova instância enquanto o indexador já está na execução gera este erro: "Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."

Um trabalho de indexador é executado em um ambiente de execução gerenciada. Atualmente, há dois ambientes:

Um ambiente de execução privada é executado em clusters de pesquisa específicos para seu serviço de pesquisa. Se o serviço de pesquisa for Standard2 ou superior, você poderá definir o parâmetro executionEnvironment na definição do indexador para sempre executar um indexador no ambiente de execução privada.
Um ambiente multilocatário tem processadores de conteúdo gerenciados e protegidos pela Microsoft sem custo adicional. Esse ambiente é usado para descarregar o processamento computacionalmente intensivo, deixando os recursos específicos do serviço disponíveis para operações de rotina. Sempre que possível, a maioria dos conjuntos de habilidades é executada no ambiente multilocatário. Esse é o padrão.

O processamento computacionalmente intensivo inclui conjuntos de habilidades em execução em processadores de conteúdo e trabalhos de indexador de alto volume ou trabalhos de indexador com documentos grandes. O processamento sem qualificação nos processadores de conteúdo multilocatário é determinado por informações geográficas e do sistema e não está sob o controle do cliente. Serviços S2 e suporte superior fixando um indexador e um processamento de conjunto de habilidades exclusivamente em seus clusters de pesquisa por meio do parâmetro executionEnvironment.

Observação

Firewalls de IP bloqueiam o ambiente multilocatário, portanto, se você tiver um firewall, crie uma regra que permita o processamento multilocatário.

Os limites do indexador variam para cada ambiente:

Carga de trabalho	Duração máxima	Máximo de trabalhos	Ambiente de execução
Execução privada	24 horas	Um trabalho de indexador por unidade de pesquisa ¹.	A indexação não é executada em segundo plano. Em vez disso, o serviço de pesquisa equilibrará todos os trabalhos de indexação em relação às ações de gerenciamento de objetos e consultas contínuas (como a criação ou atualização de índices). Ao executar indexadores, você deve esperar ver um pouco de latência de consulta, se os volumes de indexação forem grandes.
Multilocatário	2 horas ²	Indeterminado ³	Como o cluster de processamento de conteúdo é multilocatário, são adicionados processadores de conteúdo para atender à demanda. Em caso de atraso na execução sob demanda ou agendada, é possível que o sistema esteja adicionando processadores ou aguardando um deles ficar disponível.

¹ As unidades de pesquisa podem ser combinações flexíveis de partições e réplicas, mas os trabalhos do indexador não estão vinculados a um ou outro. Em outras palavras, se você tiver 12 unidades, poderá ter 12 trabalhos de indexador em execução simultaneamente em execução privada, independentemente de como as unidades de pesquisa são implantadas.

² Se forem necessárias mais de duas horas para processar todos os dados, habilite a detecção de alterações e agende o indexador a ser executado em intervalos de 5 minutos para retomar a indexação rapidamente se ele parar devido a um tempo limite. Confira Indexação de um conjunto de dados grande para obter mais estratégias.

³ "Indeterminado" significa que o limite não é quantificado pelo número de trabalhos. Algumas cargas de trabalho, como o processamento de conjunto de habilidades, podem ser executadas em paralelo, o que pode resultar em muitos trabalhos, embora apenas um indexador esteja envolvido. Embora o ambiente não imponha restrições, os limites do indexador para o serviço de pesquisa ainda se aplicam.

Executar sem redefinição

Uma operação Executar indexador detectará e processará apenas o necessário para sincronizar o índice de pesquisa com as alterações na fonte de dados subjacente. A indexação incremental começa localizando uma marca d'água alta interna para localizar o último documento de pesquisa atualizado, que se torna o ponto de partida para a execução do indexador em documentos novos e atualizados na fonte de dados.

A detecção de alterações é essencial para determinar o que é novo ou atualizado na fonte de dados. Os indexadores usam os recursos de detecção de alteração da fonte de dados subjacente para determinar o que há de novo ou atualizado na fonte de dados.

O Armazenamento do Microsoft Azure possui detecção de alteração interna por meio de sua propriedade LastModified.
Outras fontes de dados, como o SQL do Azure ou o Azure Cosmos DB, precisam ser configuradas para detecção de alteração para que o indexador possa ler apenas as linhas novas e atualizadas.

Se o conteúdo subjacente não for alterado, uma operação de execução não terá efeito. Nesse caso, o histórico de execução do indexador indicará 0\0 documentos processados.

Você precisará redefinir o indexador, conforme explicado na próxima seção, para reprocessar na íntegra.

Redefinindo indexadores

Após a execução inicial, um indexador mantém o controle de quais documentos de pesquisa foram indexados por meio de uma marca d' água alta interna. O marcador nunca é exposto, mas internamente o indexador sabe onde parou pela última vez.

Se você precisar recompilar um índice total ou parcialmente, poderá limpar a marca d'água alta do indexador por meio de uma redefinição. As APIs de redefinição estão disponíveis em níveis decrescentes na hierarquia de objetos:

Redefinir Indexadores limpa a marca d'água alta e executa uma reindexação completa de todos os documentos
Redefinir Documentos (versão prévia) reindexa um documento específico ou uma lista de documentos
Redefinir Habilidades (versão prévia) invoca o processamento de habilidades de uma habilidade específica

Após a redefinição, siga com um comando Executar para reprocessar documentos novos e existentes. Documentos de pesquisa órfãos sem correspondência na fonte de dados não podem ser removidos por meio de redefinição/execução. Se você precisar excluir documentos, confira Documentos – Indexar em vez disso.

Como redefinir e executar indexadores

Redefinir limpa a marca d'água alta. Todos os documentos no índice de pesquisa serão sinalizados para substituição completa, sem atualizações embutidas ou mesclagem com o conteúdo existente. Para indexadores com um conjunto de habilidades e cache de enriquecimento, redefinir o índice também redefinirá o conjunto de habilidades implicitamente.

O trabalho real ocorre quando você segue uma redefinição com um comando de Execução:

Todos os novos documentos encontrados na fonte subjacente são adicionados ao índice de pesquisa.
Todos os documentos existentes na fonte de dados e no índice de pesquisa serão substituídos no índice de pesquisa.
Qualquer conteúdo aprimorado criado a partir do conjunto de habilidades será recriado. O cache de enriquecimento, se habilitado, será atualizado.

Conforme observado anteriormente, a redefinição é uma operação passiva: você deve seguir uma solicitação de Execução para recriar o índice.

As operações de redefinição/execução se aplicam a um índice de pesquisa ou a um repositório de conhecimento, a projeções ou documentos específicos e a aprimoramentos em cache, se uma redefinição incluir habilidades explícita ou implicitamente.

A redefinição também se aplica às operações de criação e atualização. Ela não disparará a exclusão nem limpará documentos órfãos no índice de pesquisa. Para obter mais informações sobre como excluir documentos, confira Documentos – Índice.

Depois de redefinir um indexador, não é possível desfazer a ação.

Entre no portal do Azure e abra a página do serviço de pesquisa.
Na página Visão geral, selecione a guia Índices.
Selecione um indexador.
Selecione o comando de Redefinição e, em seguida, selecione Sim para confirmar a ação.
Atualize a página para mostrar o status. Você pode selecionar o item para exibir os detalhes.
Selecione Executar para iniciar o processamento do indexador ou aguarde a próxima execução agendada.

O exemplo a seguir ilustra as chamadas REST de Redefinir Indexador e Executar Indexador. Use Obter status do indexador para verificar os resultados.

Não há parâmetros ou propriedades para nenhuma dessas chamadas.

POST /indexers/[indexer name]/reset?api-version=[api-version]

POST /indexers/[indexer name]/run?api-version=[api-version]

GET /indexers/[indexer name]/status?api-version=[api-version]

O exemplo a seguir (em azure-search-dotnet-samples/multiple-data-sources/) ilustra os métodos ResetIndexers e RunIndexers no SDK do Azure .NET.

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    //Rest the indexer if it exsits.
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

// Run indexer
Console.WriteLine("Running Blob Storage indexer...\n");

try
{
    await indexerClient.RunIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

Como redefinir habilidades (versão prévia)

Para indexadores que têm conjuntos de habilidades, você pode redefinir habilidades individuais para forçar o processamento dessa habilidade e das habilidades de downstream dependentes da saída. O cache de enriquecimento, se habilitado, também será atualizado.

No momento, as habilidades de redefinição estão disponíveis apenas para REST até 2020-06-30-preview ou posterior. Recomendamos a API de versão prévia mais recente.

POST /skillsets/[skillset name]/resetskills?api-version=2024-05-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

Você pode especificar habilidades individuais, conforme indicado no exemplo acima, mas se qualquer uma dessas habilidades exigir a saída de habilidades não listadas (#2 por meio de #4), as habilidades não listadas serão executadas, a menos que o cache possa fornecer as informações necessárias. Para que isso seja verdadeiro, os aprimoramentos em cache para habilidades #2 por meio de #4 não devem ter dependência em #1 (listado para redefinição).

Se nenhuma habilidade for especificada, o concordador inteiro será executado e, se o Caching estiver habilitado, o cache também será atualizado.

Lembre-se de acompanhar Executar Indexador para invocar o processamento real.

Como redefinir documentos (versão prévia)

O serviço Indexadores – Redefinir Documentos aceita uma lista de chaves de documento para que você possa atualizar documentos específicos. Se especificado, os parâmetros de redefinição se tornarão o único determinante do que é processado, independentemente de outras alterações nos dados subjacentes. Por exemplo, se 20 blobs foram adicionados ou atualizados desde a última execução do indexador, mas você redefinir apenas um documento, apenas esse documento será processado.

Em uma base por documento, todos os campos nesse documento de pesquisa são atualizados com valores da fonte de dados. Você não pode escolher quais campos atualizar.

Se o documento for enriquecido por meio de um conjunto de habilidades e tiver dados armazenados em cache, o conjunto de habilidades será invocado apenas para os documentos especificados e o cache será atualizado para os documentos reprocessados.

Quando você estiver testando esta API pela primeira vez, as seguintes APIs podem ajudar a validar e testar os comportamentos. Você pode usar a API de versão prévia 2020-06-30-preview e posterior. Recomendamos a API de versão prévia mais recente.

Chame o serviço Indexadores – Obter Status com uma API de versão prévia para verificar o status da redefinição e o status da execução. Você pode encontrar informações sobre a solicitação de redefinição no final da resposta de status.
Chame o serviço Indexadores – Redefinir Documentos com uma API de versão prévia para especificar quais documentos processar.
```
POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
{
    "documentKeys" : [
        "1001",
        "4452"
    ]
}
```
- As chaves de documento fornecidas na solicitação são valores do índice de pesquisa, que podem ser diferentes dos campos correspondentes na fonte de dados. Se você não tiver certeza do valor da chave, envie uma consulta para retornar o valor. Você pode usar select para retornar apenas o campo-chave do documento.
- Para BLOBs analisados em vários documentos de pesquisa (onde parsingMode está configurado para jsonLines ou jsonArrays, ou delimitedText), a chave do documento é gerada pelo indexador e pode ser desconhecida para você. Nesse cenário, uma consulta para a chave do documento para retornar o valor correto.
Chame Executar Indexador (qualquer versão de API) para processar os documentos especificados. Somente esses documentos específicos são indexados.
Chame Executar Indexador pela segunda vez para processar na última marca d'água alta.
Chame Pesquisar Documentos para verificar os valores atualizados e também para retornar as chaves do documento se não tiver certeza do valor. Use "select": "<field names>" se você quiser limitar quais campos aparecem na resposta.

Substituição da lista de chaves do documento

Chamar Redefinir Documentos com a API várias vezes usando diferentes chaves acrescenta as novas chaves à lista de chaves de documento redefinidas. Chamar a API com o parâmetro overwrite definido como true substituirá a lista atual pela nova:

POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2020-06-30-Preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

Verificar o status de redefinição "currentState"

Para verificar o status de redefinição e para ver quais chaves do documento estão na fila para processamento, siga estas etapas.

Chame Obter Status do Indexador com uma API de versão prévia.

A API em versão prévia retornará a seção currentState, encontrada no final da resposta.

"currentState": {
    "mode": "indexingResetDocs",
    "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "resetDocsInitialTrackingState": null,
    "resetDocsFinalTrackingState": null,
    "resetDocumentKeys": [
        "200",
        "630"
    ]
}

Verifique o "modo":

Para Redefinir Conjuntos de Habilidades, o "modo" deve ser definido como indexingAllDocs (porque possivelmente todos os documentos serão afetados, em termos dos campos preenchidos por meio do enriquecimento de IA).

Para Redefinir Documentos, o "mode" deve ser definido como indexingResetDocs. O indexador retém esse status até que todas as chaves do documento fornecidas na chamada Redefinir Documentos sejam processadas. Durante esse tempo, nenhum outro trabalho do indexador será executado enquanto a operação estiver em andamento. Localizar todos os documentos na lista de chaves do documento requer a quebra de cada documento para localizar e corresponder à chave, e isso pode levar algum tempo se o conjunto de dados for grande. Se um contêiner de blob contiver centenas de BLOBs e os documentos que você deseja redefinir estiverem no final, o indexador não encontrará os BLOBs correspondentes até que todos os outros tenham sido verificados primeiro.
Depois que os documentos forem reprocessados, execute Obter Status do Indexador novamente. O indexador voltará ao modo indexingAllDocs e processará os documentos novos ou atualizados na próxima execução.

Próximas etapas

As APIs de redefinição são usadas para informar o escopo da próxima execução do indexador. Para o processamento real, você precisará invocar uma execução de indexador sob demanda ou permitir que um trabalho agendado conclua o trabalho. Depois que a execução for concluída, o indexador retornará ao processamento normal, independentemente de estar em um agendamento ou em um processamento sob demanda.

Depois de redefinir e executar novamente os trabalhos do indexador, você pode monitorar o status do serviço de pesquisa ou obter informações detalhadas por meio do log de recurso.

Compartilhar via