Diretrizes de solução de problemas do indexador para Azure AI Search

Ocasionalmente, os indexadores têm problemas que não produzem erros ou que ocorrem em outros serviços do Azure, como durante a autenticação ou ao se conectar. Este artigo se concentra na solução de problemas do indexador quando não há mensagens para orientá-lo. Ele também fornece solução de problemas para erros provenientes de recursos que não são de pesquisa usados durante a indexação.

Solucionar problemas de conexões a recursos restritos

Para fontes de dados na segurança de rede do Azure, os indexadores são limitados em como fazem a conexão. Atualmente, os indexadores podem acessar fontes de dados restritas por trás de um firewall IP ou em uma rede virtual por meio de um ponto de extremidade privado usando um link privado compartilhado.

Regras de firewall

O Armazenamento do Microsoft Azure, o Azure Cosmos DB e o SQL do Azure fornecem um firewall configurável. Não há nenhuma mensagem de erro específica quando o firewall bloqueia a solicitação. Normalmente, os erros de firewall são genéricos. Alguns erros comuns incluem:

• The remote server returned an error: (403) Forbidden
• This request is not authorized to perform this operation
• Credentials provided in the connection string are invalid or have expired

Há duas opções para permitir que os indexadores acessem os recursos em uma instância desse tipo:

• Configure uma regra de entrada para o endereço IP do serviço de pesquisa e o intervalo de endereços IP da AzureCognitiveSearch marca de serviço. Os detalhes para configurar restrições de intervalo de endereços IP para cada tipo de fonte de dados podem ser encontrados nos seguintes links:

  • Armazenamento do Azure
  • Azure Cosmos DB
  • SQL do Azure

• Como último recurso ou como medida temporária, desabilite o firewall permitindo o acesso de Todas as redes.

Limitação: as restrições de intervalo de endereços IP só funcionarão se o serviço de pesquisa e sua conta de armazenamento estiverem em regiões diferentes.

Além da recuperação de dados, os indexadores também enviam solicitações de saída por meio de conjuntos de habilidades e habilidades personalizadas. Para habilidades personalizadas com base em uma função do Azure, lembre-se de que as funções do Azure também têm restrições de endereço IP. A lista de endereços IP a serem permitidos para execução de habilidades personalizadas inclui o endereço IP do serviço de pesquisa e o intervalo de endereços IP da marca de serviço AzureCognitiveSearch.

Regras de NSG (Grupo de segurança de rede)

Quando um indexador acessa dados em uma instância gerenciada de SQL ou quando uma VM do Azure é usada como o URI do serviço Web para uma habilidade personalizada, o grupo de segurança de rede determina se as solicitações são permitidas.

Para recursos externos que residem em uma rede virtual, configure regras NSG de entrada para a marca de serviço AzureCognitiveSearch.

Para obter mais informações sobre como se conectar a uma máquina virtual, confira Configurar uma conexão ao SQL Server em uma VM do Azure.

Erros de rede

Normalmente, os erros de rede são genéricos. Alguns erros comuns incluem:

• A network-related or instance-specific error occurred while establishing a connection to the server
• The server was not found or was not accessible
• Verify that the instance name is correct and that the source is configured to allow remote connections

Quando você receber qualquer um desses erros:

• Verifique se a origem está acessível tentando se conectar diretamente a ela e não por meio do serviço de pesquisa
• Verifique o seu recurso no portal do Azure para ver se há erros ou interrupções atuais
• Verificar se há interrupções de rede no Status do Azure
• Verifique se você está usando um DNS público para resolução de nomes e não um DNS privado do Azure

Indexação sem servidor do Banco de Dados SQL do Azure (código de erro 40613)

Se o banco de dados SQL está em uma camada de computação sem servidor, verifique se o banco de dados está em execução (e não em pausa) quando o indexador se conecta a ele.

Se o banco de dados estiver em pausa, o primeiro logon do serviço de pesquisa deverá retomar automaticamente o banco de dados, mas, em vez disso, retornará um erro informando que o banco de dados está indisponível, exibindo o código de erro 40613. Depois que o banco de dados estiver em execução, tente entrar novamente para estabelecer a conectividade.

Políticas de acesso condicional do Microsoft Entra

Quando você cria um indexador do SharePoint Online, há uma etapa que exige que você entre no aplicativo do Microsoft Entra depois de fornecer um código de dispositivo. Se você receber uma mensagem informando "Your sign-in was successful but your admin requires the device requesting access to be managed", o indexador provavelmente está bloqueado da biblioteca de documentos do SharePoint por uma política de acesso condicional.

Para atualizar a política e permitir o acesso do indexador à biblioteca de documentos:

1. Abra o portal do Azure e pesquise pelo Acesso condicional do Microsoft Entra.

2. Selecione Políticas no menu à esquerda. Se você não tiver acesso para exibir esta página, será necessário encontrar alguém que tenha ou forneça acesso.

3. Determine qual política está impedindo que o indexador do SharePoint Online acesse a biblioteca de documentos. A política que pode estar bloqueando o indexador inclui a conta de usuário que você usou para autenticar durante a etapa de criação do indexador na seção Usuários e grupos. A política também pode ter Condições que:

   • Restrinja as plataformas Windows.
   • Restrinja Aplicativos móveis e clientes de área de trabalho.
   • Ter o Estado do dispositivo configurado como Sim.

4. Depois de confirmar qual política está bloqueando o indexador, faça uma isenção para o indexador. Comece recuperando o endereço IP do serviço de pesquisa.

   Primeiro, obtenha o nome de domínio totalmente qualificado (FQDN) do serviço de pesquisa. O FQDN parece <your-search-service-name>.search.windows.net. Você pode encontrar o FQDN no portal do Azure.

   

   Agora que você tem o FQDN, obtenha o endereço IP do serviço de pesquisa executando um nslookup (ou um ping) do FQDN. No exemplo a seguir, você adicionaria "150.0.0.1" a uma regra de entrada no firewall do Armazenamento do Azure. Pode levar até 15 minutos depois que as configurações do firewall forem atualizadas para que o indexador do serviço de pesquisa possa acessar a conta de Armazenamento do Azure.

   nslookup contoso.search.windows.net
   Server:  server.example.org
   Address:  10.50.10.50
   
   Non-authoritative answer:
   Name:    <name>
   Address:  150.0.0.1
   Aliases:  contoso.search.windows.net
   

5. Obtenha os intervalos de endereços IP para o ambiente de execução do indexador para sua região.

   Endereços IP extras são usados para solicitações originadas do ambiente de execução multilocatário do indexador. Você pode obter esse intervalo de endereços IP da marca de serviço.

   Os intervalos de endereços IP para a marca de serviço AzureCognitiveSearch podem ser obtidos por meio da API de descoberta ou do arquivo JSON para download.

   Para este exercício, supondo que o serviço de pesquisa seja a nuvem pública do Azure, o arquivo JSON público do Azure deve ser baixado.

   

   No arquivo JSON, supondo que o serviço de pesquisa esteja no Centro-Oeste dos EUA, a lista de endereços IP para o ambiente de execução do indexador multilocatário está listada abaixo.

       {
         "name": "AzureCognitiveSearch.WestCentralUS",
         "id": "AzureCognitiveSearch.WestCentralUS",
         "properties": {
           "changeNumber": 1,
           "region": "westcentralus",
           "platform": "Azure",
           "systemService": "AzureCognitiveSearch",
           "addressPrefixes": [
             "52.150.139.0/26",
             "52.253.133.74/32"
           ]
         }
       }
   

6. De volta à página do Acesso Condicional no portal do Azure, selecione Localizações nomeadas no menu à esquerda e escolha + Localização dos intervalos de IP. Dê um nome ao seu novo local nomeado e adicione os intervalos de IP para os ambientes de execução do serviço de pesquisa e do indexador que você coletou nas duas últimas etapas. 1

   • Para o endereço IP do serviço de pesquisa, talvez seja necessário adicionar "/32" ao final do endereço IP, pois ele aceita apenas intervalos de IP válidos.
   • Lembre-se de que, para os intervalos de IP do ambiente de execução do indexador, você só precisa adicionar os intervalos de IP para a região em que o serviço de pesquisa está.

7. Exclua o novo local nomeado da política:

   1. Selecione Políticas no menu à esquerda.
   2. Selecione a política que está bloqueando o indexador.
   3. Selecione Condições.
   4. Select Localizações.
   5. Selecione Excluir e adicione a nova Localização nomeada.
   6. Salve as alterações.

8. Aguarde alguns minutos para que a política seja atualizada e aplique as novas regras de política.

9. Tente criar o indexador novamente:

   1. Envie uma solicitação de atualização para o objeto de fonte de dados que você criou.
   2. Reenvie a solicitação de criação do indexador. Use o novo código para entrar e envie outra solicitação de criação do indexador.

Indexando tipos de documentos sem suporte

Se você estiver indexando o conteúdo do Armazenamento de Blobs do Azure e o contêiner incluir blobs de um tipo de conteúdo sem suporte, o indexador ignorará esses documentos. Em outros casos, pode haver problemas com documentos individuais.

Nesta situação, você pode definir opções de configuração para permitir que o processamento do indexador continue em caso de problemas com documentos individuais.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

Documentos ausentes

Os indexadores extraem documentos ou linhas de uma fonte de dados externa e criam documentos de pesquisa que são indexados pelo serviço de pesquisa. Ocasionalmente, um documento que existe na fonte de dados não aparece em um índice de pesquisa. Esse resultado inesperado pode ocorrer pelos seguintes motivos:

• O documento foi atualizado após a execução do indexador. Se o indexador estiver em um agendamento, eventualmente é executado novamente e pega o documento.
• O indexador atingiu o tempo limite antes que o documento pudesse ser ingerido. Há limites máximos de tempo de processamento após os quais nenhum documento é processado. Verifique o status do indexador no portal do Azure ou chamando Obter Status do Indexador (API REST).
• Mapeamentos de campo ou enriquecimento de IA mudaram o documento e sua articulação no índice de pesquisa é diferente do esperado.
• Os valores do controle de alterações estão errados ou pré-requisitos estão ausentes. Se o valor da marca d'água alta for uma data definida como uma hora futura, todos os documentos com uma data anterior serão ignorados pelo indexador. Você pode determinar o estado de controle de alterações do indexador usando os campos "initialTrackingState" e "finalTrackingState" no status do indexador. Os indexadores do SQL do Azure e do MySQL devem ter um índice na coluna de marca d'água alta da tabela de origem ou as consultas usadas pelo indexador podem ter o tempo esgotado.

Conteúdo ausente no Armazenamento de Blobs

O indexador de Blob localiza e extrai o texto de blobs em um contêiner. Alguns problemas com a extração de texto incluem:

• O documento contém apenas imagens digitalizadas. Blobs PDF que têm conteúdo não textual, como imagens digitalizadas (JPGs), não produzem resultados em um pipeline de indexação de Blob padrão. Se você tiver conteúdo de imagem com elementos de texto, você pode usar OCR ou análise de imagem para localizar e extrair o texto.

• O indexador de Blob está configurado para metadados do índice. Para extrair o conteúdo, o indexador de Blob deve ser configurado para extrair o conteúdo e metadados:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Conteúdo ausente do Azure Cosmos DB

O Azure AI Search tem uma dependência implícita da indexação do Azure Cosmos DB. Se você desativar a indexação automática no Azure Cosmos DB, o Azure AI Search retorna um estado de êxito mas não consegue indexar o conteúdo do contêiner de índice. Para obter instruções sobre como verificar as configurações e ative a indexação, consulte Gerenciar a indexação no Azure Cosmos DB.

Discrepância de contagem de documentos entre a fonte de dados e o índice

Um indexador pode mostrar uma contagem de documentos diferente da fonte de dados, do próprio índice ou da contagem em seu código. Aqui estão alguns possíveis motivos pelos quais esse comportamento pode ocorrer:

• O índice pode ter um atraso ao mostrar a contagem real de documentos, especialmente no portal do Azure.
• O indexador tem uma Política de Documento Excluída. Os documentos excluídos serão contados pelo indexador se os documentos forem indexados antes de serem excluídos.
• Se a coluna ID na fonte de dados não for exclusiva. Isso se aplica às fontes de dados que têm o conceito de coluna, como o Azure Cosmos DB.
• Se a definição da fonte de dados tiver uma consulta diferente da que você está usando para estimar o número de registros. Por exemplo, em seu banco de dados, você está consultando a contagem de registros de banco de dados, enquanto na consulta de definição da fonte de dados, você pode estar selecionando apenas um subconjunto de registros para indexar.
• As contagens estão sendo verificadas em intervalos diferentes para cada componente do pipeline: fonte de dados, indexador e índice.
• A fonte de dados tem um arquivo mapeado para muitos documentos. Essa condição pode ocorrer quando os blobs de indexação e "parsingMode" são definidos como jsonArray e jsonLines.

Documentos processados várias vezes

Os indexadores usam uma estratégia de buffer conservadora para garantir que todos os documentos novos e alterados na fonte de dados são coletados durante a indexação. Em determinadas situações, esses buffers podem se sobrepor, fazendo com que um indexador indexe um documento duas ou mais vezes, resultando na contagem de documentos processados como mais do que o número real de documentos na fonte de dados. Este comportamento não afeta os dados armazenados no índice, como a duplicação de documentos, apenas que pode levar mais tempo para alcançar a consistência eventual. Esta condição será especialmente predominante se qualquer um dos seguintes critérios for verdadeiro:

• As solicitações do indexador sob demanda são emitidas em sucessão rápida
• A topologia da fonte de dados inclui várias réplicas e partições (um exemplo desse exemplo é discutido aqui)
• A fonte de dados é um banco de dados SQL do Azure e a coluna escolhida como "marca d'água alta" é do tipo datetime2

Os indexadores não devem ser invocados várias vezes em sucessão rápida. Se você precisar de atualizações rapidamente, a abordagem com suporte é fazer push de atualizações para o índice ao atualizar simultaneamente a fonte de dados. Para o processamento sob demanda, recomendamos que você adonde suas solicitações em intervalos de cinco minutos ou mais e execute o indexador em um agendamento.

Exemplo de processamento de documento duplicado com buffer de 30 segundos

As condições nas quais um documento é processado duas vezes são explicadas na linha do tempo a seguir que observa cada ação e ação de contador. A linha do tempo a seguir ilustra o problema:

Na prática, esse cenário só acontece quando os indexadores sob demanda são invocados manualmente em minutos uns dos outros, para determinadas fontes de dados. Isso pode resultar em números incompatíveis (por exemplo, o indexador processa o total de 345 documentos de acordo com as estatísticas de execução do indexador, mas há 340 documentos na fonte e índice de dados) ou potencialmente um aumento na cobrança se você estiver executando as mesmas habilidades para o mesmo documento várias vezes. Executar um indexador usando uma agenda é a recomendação preferencial.

Indexação paralela

Quando vários indexadores estão operando simultaneamente, é comum que alguns entrem em uma fila, aguardando que os recursos disponíveis comecem a execução. O número de indexadores que podem ser executados simultaneamente depende de vários fatores. Se os indexadores não estiverem vinculados a conjuntos de habilidades, a capacidade de execução em paralelo dependerá do número de réplicas e partições configuradas no serviço de Pesquisa de IA.

Por outro lado, se um indexador estiver associado a um conjunto de habilidades, ele operará dentro dos clusters internos da Pesquisa de IA. A capacidade de executar simultaneamente neste caso é determinada pela complexidade do conjunto de habilidades e se outros conjuntos de habilidades estão sendo executados simultaneamente. Os indexadores internos são projetados para extrair dados de forma confiável da origem, portanto, nenhum dado será perdido se estiver em execução em um agendamento. No entanto, espera-se que os processos do indexador de paralelização e dimensionamento possam exigir algum tempo.

Indexação de documentos com rótulos de confidencialidade

Se você tiver rótulos de confidencialidade definidos em documentos, talvez não consiga indexá-los. Se você estiver recebendo erros, remova os rótulos antes da indexação.

Confira também

• Solução de problemas com erros e avisos comuns do indexador
• Monitorar indexação baseada em indexador