Linee guida per la risoluzione dei problemi dell'indicizzatore per Azure AI Search

In alcuni casi, gli indicizzatori si verificano problemi che non generano errori o che si verificano in altri servizi di Azure, ad esempio durante l'autenticazione o durante la connessione. Questo articolo è incentrato sulla risoluzione dei problemi dell'indicizzatore quando non sono presenti messaggi da guidare. Fornisce anche la risoluzione dei problemi relativi agli errori provenienti da risorse non di ricerca usate durante l'indicizzazione.

Risolvere i problemi relativi alle connessioni alle risorse con restrizioni

Per le origini dati con la sicurezza di rete di Azure, gli indicizzatori sono limitati nel modo in cui effettuano la connessione. Attualmente, gli indicizzatori possono accedere a origini dati limitate dietro un firewall IP o in una rete virtuale tramite un endpoint privato usando un collegamento privato condiviso.

Regole del firewall

Archiviazione di Azure, Azure Cosmos DB e Azure SQL forniscono un firewall configurabile. Non viene visualizzato alcun messaggio di errore specifico quando il firewall blocca la richiesta. In genere, gli errori del firewall sono generici. Di seguito sono riportati alcuni errori comuni:

• 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

Esistono due opzioni per consentire agli indicizzatori di accedere a queste risorse in un'istanza di questo tipo:

• Configurare una regola in ingresso per l'indirizzo IP del servizio di ricerca e l'intervallo di indirizzi IP del AzureCognitiveSearch tag di servizio. Per informazioni dettagliate sulla configurazione delle restrizioni dell'intervallo di indirizzi IP per ogni tipo di origine dati, vedere i collegamenti seguenti:

  • Archiviazione di Azure
  • Azure Cosmos DB
  • Azure SQL

• Come ultima risorsa o come misura temporanea, disabilitare il firewall consentendo l'accesso da Tutte le reti.

Limitazione: le restrizioni relative all'intervallo di indirizzi IP funzionano solo se il servizio di ricerca e l'account di archiviazione si trovano in aree diverse.

Oltre al recupero dei dati, gli indicizzatori inviano anche richieste in uscita tramite set di competenze e competenze personalizzate. Per le competenze personalizzate basate su una funzione di Azure, tenere presente che anche le funzioni di Azure hanno restrizioni relative agli indirizzi IP. L'elenco di indirizzi IP da consentire per l'esecuzione di competenze personalizzate include l'indirizzo IP del servizio di ricerca e l'intervallo di indirizzi IP del tag di servizio AzureCognitiveSearch.

Regole relative al gruppo di sicurezza di rete

Quando un indicizzatore accede ai dati in un'istanza gestita di SQL o quando una macchina virtuale di Azure viene usata come URI del servizio Web per una competenza personalizzata, il gruppo di sicurezza di rete determina se le richieste sono consentite.

Per le risorse esterne che risiedono in una rete virtuale, configurare le regole del gruppo di sicurezza di rete in ingresso per il tag del servizio AzureCognitiveSearch.

Per altre informazioni sulla connessione a una macchina virtuale, vedere Configurare una connessione a SQL Server in una macchina virtuale di Azure.

errori di rete

In genere, gli errori di rete sono generici. Di seguito sono riportati alcuni errori comuni:

• 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 si riceve uno di questi errori:

• Assicurarsi che l'origine sia accessibile provando a connettersi direttamente e non tramite il servizio di ricerca
• Controllare la risorsa nel portale di Azure per eventuali errori o interruzioni correnti
• Verificare eventuali interruzioni di rete nello stato di Azure
• Verificare di usare un DNS pubblico per la risoluzione dei nomi e non un DNS privato di Azure

Indicizzazione serverless del database SQL di Azure (codice di errore 40613)

Se il database SQL si trova in un livello di calcolo serverless, assicurarsi che il database sia in esecuzione (e non sospeso) quando l'indicizzatore si connette.

Se il database è in pausa, il primo accesso dal servizio di ricerca dovrebbe riprendere automaticamente il database, ma restituisce invece un errore che indica che il database non è disponibile, fornendo il codice di errore 40613. Dopo l'esecuzione del database, ripetere l'accesso per stabilire la connettività.

Criteri di accesso condizionale di Microsoft Entra

Quando si crea un indicizzatore di SharePoint Online, è necessario eseguire un passaggio che richiede di accedere all'app Microsoft Entra dopo aver fornito un codice del dispositivo. Se viene visualizzato un messaggio che indica "Your sign-in was successful but your admin requires the device requesting access to be managed", l'indicizzatore è probabilmente bloccato dalla raccolta documenti di SharePoint da un criterio di accesso condizionale.

Per aggiornare i criteri e consentire l'accesso dell'indicizzatore alla raccolta documenti:

1. Aprire il portale di Azure e cercare l'accesso condizionale Microsoft Entra.

2. Selezionare Criteri, nel menu a sinistra. Se non si ha accesso per visualizzare questa pagina, è necessario trovare qualcuno che ha accesso o ottenere l'accesso.

3. Determinare i criteri che impediscono all'indicizzatore di SharePoint Online di accedere alla raccolta documenti. I criteri che potrebbero bloccare l'indicizzatore includono l'account utente usato per l'autenticazione durante il passaggio di creazione dell'indicizzatore nella sezione Utenti e gruppi . I criteri potrebbero avere anche condizioni che:

   • Limitano le piattaforme Windows.
   • Limitano le app per dispositivi mobili e client desktop.
   • Fanno in modo che lo stato del dispositivo sia configurato su Sì.

4. Dopo aver confermato quali criteri bloccano l'indicizzatore, effettuare un'esenzione per l'indicizzatore. Per iniziare, recuperare l'indirizzo IP del servizio di ricerca.

   Prima di tutto, ottenere il nome di dominio completo (FQDN) del servizio di ricerca. Il nome di dominio completo è simile a <your-search-service-name>.search.windows.net. È possibile trovare il nome di dominio completo nel portale di Azure.

   

   Dopo aver ottenuto il nome di dominio completo, ottenere l'indirizzo IP del servizio di ricerca eseguendo un nslookup (o un ping) del nome di dominio completo. Nell'esempio seguente si aggiungerà "150.0.0.1" a una regola in ingresso nel firewall di Archiviazione di Azure. L'aggiornamento delle impostazioni del firewall potrebbe richiedere fino a 15 minuti perché l'indicizzatore del servizio di ricerca possa accedere all'account di archiviazione di 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. Ottenere gli intervalli di indirizzi IP per l'ambiente di esecuzione dell'indicizzatore per l'area.

   Gli indirizzi IP aggiuntivi vengono usati per le richieste provenienti dall'ambiente di esecuzione multi-tenant dell'indicizzatore. È possibile ottenere questo intervallo di indirizzi IP dal tag del servizio.

   Gli intervalli di indirizzi IP per il tag di servizio AzureCognitiveSearch possono essere ottenuti tramite l'API di individuazione o il file JSON scaricabile.

   Per questo esercizio, supponendo che il servizio di ricerca sia il cloud pubblico di Azure, è necessario scaricare il file JSON pubblico di Azure.

   

   Dal file JSON, supponendo che il servizio di ricerca si trovi negli Stati Uniti centro-occidentali, l'elenco di indirizzi IP per l'ambiente di esecuzione dell'indicizzatore multi-tenant è elencato di seguito.

       {
         "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. Tornare alla pagina Accesso condizionale nel portale di Azure, selezionare Località denominate dal menu a sinistra, quindi selezionare + Posizione intervalli IP. Assegnare al nuovo percorso denominato un nome e aggiungere gli intervalli IP per gli ambienti di esecuzione del servizio di ricerca e dell'indicizzatore raccolti negli ultimi due passaggi. 1

   • Per l'indirizzo IP del servizio di ricerca, potrebbe essere necessario aggiungere "/32" alla fine dell'indirizzo IP perché accetta solo intervalli IP validi.
   • Tenere presente che per gli intervalli IP dell'ambiente di esecuzione dell'indicizzatore è sufficiente aggiungere gli intervalli IP per l'area in cui si trova il servizio di ricerca.

7. Escludere il nuovo percorso denominato dai criteri:

   1. Selezionare Criteri, nel menu a sinistra.
   2. Selezionare i criteri che bloccano l'indicizzatore.
   3. Selezionare Condizioni.
   4. Seleziona Posizione.
   5. Selezionare Escludi e quindi aggiungere il nuovo percorso denominato.
   6. Fare clic su Salva per salvare le modifiche.

8. Attendere alcuni minuti per l'aggiornamento e l'applicazione delle nuove regole dei criteri.

9. Tentare di creare di nuovo l'indicizzatore:

   1. Inviare una richiesta di aggiornamento per l'oggetto origine dati creato.
   2. Inviare nuovamente la richiesta di creazione dell'indicizzatore. Usare il nuovo codice per accedere, quindi inviare un'altra richiesta di creazione dell'indicizzatore.

Indicizzazione di tipi di documento non supportati

Se si esegue l'indicizzazione del contenuto da Archiviazione BLOB di Azure e il contenitore include BLOB di un tipo di contenuto non supportato, l'indicizzatore ignora tale documento. In altri casi, potrebbero verificarsi problemi con i singoli documenti.

In questo caso, è possibile impostare le opzioni di configurazione per consentire all'elaborazione dell'indicizzatore di continuare in caso di problemi con singoli documenti.

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 } }
}

Documenti mancanti

Gli indicizzatori estraggono documenti o righe da un'origine dati esterna e creano documenti di ricerca, che vengono quindi indicizzati dal servizio di ricerca. In alcuni casi, un documento presente nell'origine dati non viene visualizzato in un indice di ricerca. Questo risultato imprevisto può verificarsi a causa dei motivi seguenti:

• Il documento è stato aggiornato dopo l'esecuzione dell'indicizzatore. Se l'indicizzatore fa parte di una pianificazione, a un certo punto viene eseguito nuovamente e seleziona il documento.
• Timeout dell'indicizzatore prima dell'inserimento del documento. Sono previsti limiti di tempo di elaborazione massimi dopo i quali non vengono elaborati documenti. È possibile controllare lo stato dell'indicizzatore nella portale di Azure o chiamando Get Indexer Status (API REST).
• I mapping dei campi o l'arricchimento tramite intelligenza artificiale hanno modificato il documento e la relativa articolazione nell'indice di ricerca è diversa da quella prevista.
• I valori di rilevamento delle modifiche sono errati o mancano i prerequisiti. Se il valore limite elevato è una data impostata su un'ora futura, tutti i documenti con una data precedente vengono ignorati dall'indicizzatore. È possibile determinare lo stato di rilevamento delle modifiche dell'indicizzatore usando i campi "initialTrackingState" e "finalTrackingState" nello stato dell'indicizzatore. Gli indicizzatori per Azure SQL e MySQL devono avere un indice nella colonna High Water Mark della tabella di origine o le query usate dall'indicizzatore potrebbero raggiungere un timeout.

Contenuto mancante da Archiviazione BLOB

L'indicizzatore BLOB trova ed estrae il testo dai BLOB in un contenitore. I problemi relativi all'estrazione del testo includono i seguenti:

• Il documento contiene solo immagini digitalizzate. I BLOB PDF con contenuti non testuali, ad esempio immagini digitalizzate (JPG), non producono risultati in una pipeline di indicizzazione BLOB standard. Se è presente contenuto di immagini con elementi di testo, è possibile usare la OCR o analisi delle immagini per trovare ed estrarre il testo.

• L'indicizzatore BLOB è configurato solo per i metadati dell'indice. Per estrarre il contenuto, l'indicizzatore BLOB deve essere configurato per estrarre sia il contenuto che i metadati:

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" } }
}

Contenuto mancante da Azure Cosmos DB

Azure AI Search ha una dipendenza implicita dall'indicizzazione di Azure Cosmos DB. Se si disattiva l'indicizzazione automatica in Azure Cosmos DB, Azure AI Search restituisce uno stato di esito positivo, ma non riesce a indicizzare i contenuti dei contenitori. Per istruzioni su come controllare le impostazioni e attivare l'indicizzazione, vedere Gestire l'indicizzazione in Azure Cosmos DB.

Discrepanza tra l'origine dati e l'indice del conteggio dei documenti

Un indicizzatore potrebbe mostrare un numero di documenti diverso rispetto all'origine dati, all'indice stesso o al conteggio nel codice. Ecco alcuni possibili motivi per cui questo comportamento può verificarsi:

• L'indice può essere ritardato nella visualizzazione del conteggio dei documenti reali, in particolare nel portale di Azure.
• L'indicizzatore ha criteri di documento eliminati. I documenti eliminati vengono conteggiati dall'indicizzatore se i documenti vengono indicizzati prima dell'eliminazione.
• Se la colonna ID nell'origine dati non è univoca. Questo vale per le origini dati che hanno il concetto di colonne, ad esempio Azure Cosmos DB.
• Se la definizione dell'origine dati ha una query diversa da quella usata per stimare il numero di record. Nel database, ad esempio, si esegue una query sul numero di record del database, mentre nella query di definizione dell'origine dati è possibile selezionare solo un subset di record da indicizzare.
• I conteggi vengono controllati a intervalli diversi per ogni componente della pipeline: origine dati, indicizzatore e indice.
• L'origine dati ha un file mappato a molti documenti. Questa condizione può verificarsi quando l'indicizzazione di BLOB e "parsingMode" sono impostati su jsonArray e jsonLines.

Documenti elaborati più volte

Gli indicizzatori usano una strategia di buffering conservativo per garantire che ogni documento nuovo e modificato nell'origine dati venga prelevato durante l'indicizzazione. In determinate situazioni, questi buffer possono sovrapporsi, causando l'indicizzazione di un documento due o più volte, determinando che il numero di documenti elaborati sia maggiore del numero effettivo di documenti nell'origine dati. Questo comportamento non influisce sui dati archiviati nell'indice, ad esempio la duplicazione di documenti, solo che possono richiedere più tempo per raggiungere la coerenza finale. Questa condizione è particolarmente diffusa se uno dei criteri seguenti è vero:

• Le richieste dell'indicizzatore su richiesta vengono eseguite in rapida successione
• La topologia dell'origine dati include più repliche e partizioni (un esempio è illustrato qui)
• L'origine dati è un database SQL di Azure e la colonna scelta come "high water mark" è di tipo datetime2

Gli indicizzatori non devono essere richiamati più volte in rapida successione. Se sono necessari aggiornamenti rapidamente, l'approccio supportato consiste nell'eseguire il push degli aggiornamenti all'indice durante l'aggiornamento simultaneo dell'origine dati. Per l'elaborazione su richiesta, è consigliabile gestire le richieste in intervalli di cinque minuti o più ed eseguire l'indicizzatore in base a una pianificazione.

Esempio di elaborazione di documenti duplicati con 30 secondi di buffer

Le condizioni in base alle quali un documento viene elaborato due volte vengono spiegate nella sequenza temporale seguente che annota ogni azione e azione di contatore. La sequenza temporale seguente illustra il problema:

In pratica, questo scenario si verifica solo quando gli indicizzatori su richiesta vengono richiamati manualmente tra loro in pochi minuti, per determinate origini dati. Può comportare numeri non corrispondenti (ad esempio l'indicizzatore ha elaborato 345 documenti totali in base alle statistiche di esecuzione dell'indicizzatore, ma sono presenti 340 documenti nell'origine dati e nell'indice) o una fatturazione potenzialmente aumentata se si eseguono le stesse competenze per lo stesso documento più volte. L'esecuzione di un indicizzatore usando una pianificazione è la raccomandazione preferita.

Indicizzazione parallela

Quando più indicizzatori funzionano contemporaneamente, è normale che alcuni immettano una coda, in attesa che le risorse disponibili inizino l'esecuzione. Il numero di indicizzatori che possono essere eseguiti contemporaneamente dipende da diversi fattori. Se gli indicizzatori non sono collegati ai set di competenze, la capacità di esecuzione in parallelo si basa sul numero di repliche e partizioni configurate nel servizio AI Search.

D'altra parte, se un indicizzatore è associato a un set di competenze, opera all'interno dei cluster interni di AI Search. La possibilità di eseguire simultaneamente in questo caso è determinata dalla complessità del set di competenze e dal fatto che altri set di competenze vengano eseguiti contemporaneamente. Gli indicizzatori predefiniti sono progettati per estrarre in modo affidabile i dati dall'origine, quindi non viene perso alcun dato se è in esecuzione in base a una pianificazione. Tuttavia, è previsto che i processi dell'indicizzatore di parallelizzazione e la scalabilità orizzontale richiedano tempo.

Indicizzazione di documenti con etichette di riservatezza

Se nei documenti sono impostate etichette di riservatezza, potrebbe non essere possibile indicizzare i documenti. Se si verificano errori, rimuovere le etichette prima dell'indicizzazione.

Vedi anche

• Risoluzione degli errori e degli avvisi comuni dell'indicizzatore
• Monitorare l'indicizzazione basata su indicizzatore