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

Ocasionalmente, os indexadores se deparam com problemas que não produzem erros ou que ocorrem em outros serviços do Azure, como durante a autenticação ou ao conectar. Este artigo se concentra na solução de problemas do indexador quando não há mensagens para guiá-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 com recursos restritos

Para fontes de dados sob a segurança de rede do Azure, os indexadores são limitados na forma 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 da firewall

O Armazenamento do Azure, o Azure Cosmos DB e o Azure SQL 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:

• 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 esses recursos em tal instância:

• Configure uma regra de entrada para o endereço IP do seu serviço de pesquisa e o intervalo de endereços IP da etiqueta de AzureCognitiveSearch serviço. 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
  • BD do Cosmos para o Azure
  • SQL do Azure

• Como último recurso ou como medida temporária, desative o firewall permitindo o acesso a partir de Todas as Redes.

Limitação: as restrições de intervalo de endereços IP só funcionam se o seu serviço de pesquisa e a 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 baseadas em uma função do Azure, esteja ciente 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 a execução de habilidades personalizadas inclui o endereço IP do seu serviço de pesquisa e o intervalo de endereços IP da etiqueta de AzureCognitiveSearch serviço.

Regras do grupo de segurança de rede (NSG)

Quando um indexador acessa dados em uma instância gerenciada pelo 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 AzureCognitiveSearch etiqueta de serviço.

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

Erros de rede

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

• 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:

• Certifique-se de que sua fonte está acessível tentando se conectar a ela diretamente e não através do serviço de pesquisa
• Verifique o seu recurso no portal do Azure para quaisquer 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 estiver em uma camada de computação sem servidor, verifique se o banco de dados está em execução (e não pausado) quando o indexador se conectar a ele.

Se o banco de dados estiver pausado, espera-se que o primeiro logon do seu serviço de pesquisa retome automaticamente o banco de dados, mas em vez disso retorna um erro informando que o banco de dados não está disponível, fornecendo o código de erro 40613. Depois que o banco de dados estiver em execução, tente entrar novamente para estabelecer 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 seu aplicativo Microsoft Entra depois de fornecer um código de dispositivo. Se você receber uma mensagem dizendo "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 procure Acesso Condicional do Microsoft Entra.

2. Selecione Políticas no menu à esquerda. Se você não tiver acesso para visualizar esta página, precisará encontrar alguém que tenha acesso ou obter acesso.

3. Determine qual política está bloqueando o acesso do indexador do SharePoint Online à 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 desktop.
   • 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 por recuperar o endereço IP do serviço de pesquisa.

   Primeiro, obtenha o nome de domínio totalmente qualificado (FQDN) do seu serviço de pesquisa. O FQDN se parece com <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 após as configurações de firewall terem sido 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 a partir da etiqueta de serviço.

   Os intervalos de endereços IP para a AzureCognitiveSearch etiqueta de serviço 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 Acesso Condicional no portal do Azure, selecione Locais nomeados no menu à esquerda e, em seguida, selecione + Localização de intervalos IP. Dê um nome ao seu novo local nomeado e adicione os intervalos de IP para o serviço de pesquisa e os ambientes de execução do indexador que você coletou nas duas últimas etapas. 1

   • Para o endereço IP do seu serviço de pesquisa, talvez seja necessário adicionar "/32" ao final do endereço IP, uma vez que ele só aceita intervalos de IP válidos.
   • Lembre-se de que, para os intervalos 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. Selecione Locais.
   5. Selecione Excluir e adicione o novo local nomeado.
   6. Salve as alterações.

8. Aguarde alguns minutos até que a política atualize 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 enviar outra solicitação de criação de indexador.

Indexação de tipos de documentos não suportados

Se você estiver indexando 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á esse documento. Noutros casos, poderá haver problemas com documentos individuais.

Nessa situação, você pode definir opções de configuração para permitir que o processamento do indexador continue no 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 em falta

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. Este resultado inesperado pode ocorrer devido às seguintes razões:

• O documento foi atualizado depois que o indexador foi executado. Se o indexador estiver em um cronograma, ele eventualmente será executado novamente e pegará o documento.
• O indexador atingiu o tempo limite antes que o documento pudesse ser ingerido. Existem prazos máximos de processamento após os quais nenhum documento é processado. Você pode verificar o status do indexador no portal ou chamando Get Indexer Status (REST API).
• Mapeamentos de campo ou enriquecimento de IA mudaram o documento e sua articulação no índice de pesquisa é diferente do esperado.
• Os valores de controle de alterações estão errados ou os pré-requisitos estão faltando. Se o valor da marca d'água alto for uma data definida para uma hora futura, todos os documentos que tiverem 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 para SQL e MySQL do Azure devem ter um índice na coluna de marca d'água alta da tabela de origem, ou as consultas usadas pelo indexador podem atingir o tempo limite.

Conteúdo ausente do armazenamento de Blob

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

• O documento contém apenas imagens digitalizadas. Blobs de PDF com 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, poderá usar OCR ou análise de imagem para localizar e extrair o texto.

• O indexador de blob é configurado apenas para indexar metadados. Para extrair conteúdo, o indexador de blob deve ser configurado para extrair 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 na indexação do Azure Cosmos DB. Se você desativar a indexação automática no Azure Cosmos DB, o Azure AI Search retornará um estado bem-sucedido, mas não conseguirá indexar o conteúdo do contêiner. Para obter instruções sobre como verificar as configurações e ativar a indexação, consulte Gerenciar indexação no Azure Cosmos DB.

Discrepância na 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 algumas razões possíveis pelas quais esse comportamento pode ocorrer:

• O índice pode demorar a mostrar a contagem real de documentos, especialmente no portal.
• O indexador tem uma Política de Documentos Excluídos. Os documentos excluídos sã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 a fontes de dados que têm o conceito de colunas, como o Azure Cosmos DB.
• Se a definição da fonte de dados tiver uma consulta diferente daquela 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 do 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 a indexação de blobs e "parsingMode" é definida como jsonArray e jsonLines.

Documentos processados várias vezes

Os indexadores usam uma estratégia conservadora de buffer para garantir que cada documento novo e alterado na fonte de dados seja coletado 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 para ser maior do que o número real de documentos na fonte de dados. Esse comportamento não afeta os dados armazenados no índice, como a duplicação de documentos, apenas que pode levar mais tempo para alcançar uma eventual consistência. Esta condição é especialmente prevalente se qualquer um dos seguintes critérios for verdadeiro:

• As solicitações do indexador sob demanda são emitidas em rápida sucessão
• A topologia da fonte de dados inclui várias réplicas e partições (um desses exemplos é 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 se destinam a ser invocados várias vezes em rápida sucessão. Se você precisar de atualizações rapidamente, a abordagem suportada é enviar atualizações por push para o índice e, ao mesmo tempo, atualizar a fonte de dados. Para processamento sob demanda, recomendamos que você acelere suas solicitações em intervalos de cinco minutos ou mais e execute o indexador de acordo com uma programação.

Exemplo de processamento de documentos duplicados com buffer de 30 segundos

As condições em que um documento é processado duas vezes são explicadas na seguinte linha do tempo, que regista cada ação e contraação. A seguinte cronologia ilustra o problema:

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

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 ser executados. 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 executar em paralelo depende do número de réplicas e partições configuradas no serviço AI Search.

Por outro lado, se um indexador estiver associado a um conjunto de habilidades, ele opera dentro dos clusters internos do AI Search. A capacidade de correr simultaneamente neste caso é determinada pela complexidade do conjunto de habilidades e se outros conjuntos de habilidades estão sendo executados simultaneamente. Os indexadores integrados são projetados para extrair dados da fonte de forma confiável, para que nenhum dado seja perdido se executado em uma programação. No entanto, espera-se que os processos indexadores de paralelização e dimensionamento possam exigir algum tempo.

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

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

Consulte também

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