Instructions de résolution des problèmes de l’indexeur pour la Recherche Azure AI

Article
01/11/2024

Parfois, les indexeurs rencontrent des problèmes qui ne produisent pas d’erreurs ou qui se produisent sur d’autres services Azure, par exemple lors de l’authentification ou de la connexion. Cet article se concentre sur la résolution des problèmes d’indexeur lorsqu’aucun message ne s’affiche pour vous guider. Il fournit également une résolution des erreurs provenant de ressources hors recherche utilisées lors de l’indexation.

Remarque

Si vous avez une erreur Recherche Azure AI à investiguer, consultez plutôt Résolution des erreurs et des avertissements courants de l’indexeur.

Résoudre les problèmes de connexion aux ressources limitées

Pour les sources de données sous la sécurité réseau Azure, les indexeurs sont limités dans la façon dont ils établissent la connexion. Actuellement, les indexeurs peuvent accéder à des sources de données restreintes derrière un pare-feu IP ou sur un réseau virtuel via un point de terminaison privé à l’aide d’une liaison privée partagée.

Règles de pare-feu

Stockage Azure, Azure Cosmos DB et Azure SQL fournissent un pare-feu configurable. Il n’y a pas de message d’erreur spécifique lorsque le pare-feu bloque la requête. En règle générale, les erreurs de pare-feu sont génériques. Quelques exemples d’erreurs courantes :

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

Vous pouvez utiliser deux options pour autoriser les indexeurs à accéder à ces ressources dans un tel cas :

Configurez une règle entrante pour l’adresse IP de votre service de recherche et la plage d’adresses IP de l’étiquette de service AzureCognitiveSearch. Pour plus d’informations sur la configuration des restrictions de plage d’adresses IP pour chaque type de source de données, consultez les liens suivants :
En dernier recours ou en tant que mesure temporaire, désactivez le pare-feu en autorisant l’accès à partir de Tous les réseaux.

Limitation : les restrictions de plage d’adresses IP fonctionnent seulement si votre service de recherche et votre compte de stockage se trouvent dans des régions différentes.

En plus de la récupération des données, les indexeurs envoient également des requêtes sortantes via des ensembles de compétences et des compétences personnalisées. Pour les compétences personnalisées basées sur une fonction Azure, sachez que les fonctions Azure ont également des restrictions d’adresse IP. La liste d’adresses IP à autoriser pour l’exécution de compétences personnalisées comprend l’adresse IP de votre service de recherche et la plage d’adresses IP de l’étiquette de service AzureCognitiveSearch.

Règles du groupe de sécurité réseau (NSG)

Lorsqu’un indexeur accède à des données sur une instance managée SQL ou lorsqu’une machine virtuelle Azure est utilisée comme URI de service web pour une compétence personnalisée, le groupe de sécurité réseau détermine si les requêtes sont autorisées.

Pour les ressources externes résidant sur un réseau virtuel, configurez des règles de groupe de sécurité réseau entrantes pour l’étiquette de service AzureCognitiveSearch.

Pour plus d’informations sur la connexion à une machine virtuelle, consultez Configurer une connexion à SQL Server sur une machine virtuelle Azure.

Erreurs réseau

En règle générale, les erreurs réseau sont génériques. Quelques exemples d’erreurs courantes :

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

Lorsque vous recevez l’une de ces erreurs :

Assurez-vous que votre source est accessible en essayant de vous y connecter directement et non par le biais du service de recherche
Vérifiez votre ressource dans le portail Azure pour connaître les erreurs ou pannes actuelles
Rechercher des pannes réseau dans État Azure
Vérifiez que vous utilisez un DNS public pour la résolution de noms et pas un DNS privé Azure

Indexation serverless Azure SQL Database (code d’erreur 40613)

Si votre base de données SQL est sur un niveau de calcul serverless, assurez-vous que la base de données est en cours d’exécution (et non en pause) lorsque l’indexeur se connecte à celle-ci.

Si la base de données est en pause, la première connexion de votre service de recherche devrait normalement entraîner la reprise automatique de la base de données, mais retourne à la place une erreur indiquant que la base de données n’est pas disponible, en donnant le code d’erreur 40613. Une fois que la base de données est en cours d’exécution, retentez la connexion pour établir la connectivité.

Politiques d’accès conditionnel à Microsoft Entra

Quand vous créez un indexeur SharePoint Online, une étape vous demande de vous connecter à votre application Microsoft Entra après avoir fourni un code d’appareil. Si vous recevez un message indiquant "Your sign-in was successful but your admin requires the device requesting access to be managed", l’indexeur ne peut probablement pas accéder à la bibliothèque de documents SharePoint en raison d’une stratégie d’accès conditionnel.

Pour mettre à jour la stratégie et autoriser l’accès de l’indexeur à la bibliothèque de documents :

Ouvrez le portail Azure et recherchez Accès conditionnel Microsoft Entra.
Sélectionnez Stratégies dans le menu de gauche. Si vous n’avez pas accès à cette page, vous devez trouver une personne avec l’accès ou obtenir l’accès.
Déterminez quelle stratégie empêche l’indexeur SharePoint Online d’accéder à la bibliothèque de documents. La stratégie susceptible de bloquer l’indexeur inclut le compte d’utilisateur que vous avez utilisé pour l’authentification pendant l’étape de création de l’indexeur dans la section Utilisateurs et groupes. La stratégie peut également avoir des conditions qui :
- Limitent les plateformes Windows.
- Limitent les Applications mobiles et clients de bureau.
- Ont l’État de l’appareil configuré sur Oui.
Une fois que vous avez déterminé quelle stratégie bloque l’indexeur, créez une exemption pour l’indexeur. Commencez par récupérer l’adresse IP du service de recherche.

D’abord, obtenez le nom de domaine complet (FQDN) de votre service de recherche. Le FQDN ressemble à <your-search-service-name>.search.windows.net. Vous pouvez trouver le FQDN dans le portail Azure.

Maintenant que vous avez le FQDN, obtenez l’adresse IP du service de recherche en exécutant nslookup (ou une commande ping) du FQDN. Dans l’exemple suivant, vous ajoutez « 150.0.0.1 » à une règle de trafic entrant sur le pare-feu du Stockage Azure. L’accès au compte de stockage Azure peut prendre jusqu’à 15 minutes après la mise à jour des paramètres du Pare-feu.
```
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
```
Récupérez les plages d’adresses IP pour l’environnement d’exécution de l’indexeur pour votre région.

Des adresses IP supplémentaires sont utilisées pour les requêtes qui proviennent de l’environnement d’exécution multilocataire de l’indexeur. Vous pouvez récupérer cette plage d’adresses IP à partir de l’étiquette de service .

Vous pouvez obtenir les plages d’adresses IP de l’étiquette de service AzureCognitiveSearch avec l’API de détection ou le fichier JSON téléchargeable.

Pour cet exercice, en supposant que le service de recherche est le cloud public Azure, le fichier JSON Azure public doit être téléchargé.

Dans le fichier JSON, en supposant que le service de recherche se trouve dans la région USA Centre-Ouest, les adresses IP de l’environnement d’exécution de l’indexeur multilocataire sont listées ci-dessous.
```
    {
      "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"
        ]
      }
    }
```
Retournez sur la page Accès conditionnel dans le portail Azure, sélectionnez Emplacements nommés dans le menu de gauche, puis choisissez+ Emplacement des plages d’adresses IP. Donnez un nom à votre nouvel emplacement nommé et ajoutez les plages d’adresses IP pour votre service de recherche et les environnements d’exécution de l’indexeur que vous avez collectés au cours des deux dernières étapes. 1
- Pour l’adresse IP de votre service de recherche, vous risquez de devoir ajouter « /32 » à la fin de l’adresse IP, car le système n’accepte que des plages d’adresses IP valides.
- N’oubliez pas que pour les plages d’adresses IP de l’environnement d’exécution de l’indexeur, vous devez uniquement ajouter les plages d’adresses IP pour la région dans laquelle se trouve votre service de recherche.
Excluez le nouvel emplacement nommé de la stratégie :
1. Sélectionnez Stratégies dans le menu de gauche.
2. Sélectionnez la stratégie qui bloque l’indexeur.
3. Sélectionnez Conditions.
4. Sélectionner Emplacements.
5. Sélectionnez Exclure, puis ajoutez le nouvel emplacement nommé.
6. Enregistrez les modifications.
Attendez quelques minutes pour que la stratégie se mette à jour et applique les nouvelles règles de stratégie.
Tentative de recréation de l’indexeur :
1. Envoyez une requête de mise à jour pour l’objet source de données que vous avez créé.
2. Renvoyez la requête de création de l’indexeur. Utilisez le nouveau code pour vous connecter, puis envoyez une autre requête de création d’indexeur.

Indexation de types de documents non pris en charge

Si vous indexez du contenu du Stockage Blob Azure et que le conteneur comprend des blobs d’un type de contenu non pris en charge, l’indexeur ignore ce document. Dans d’autres cas, des problèmes avec des documents individuels risquent de se produire.

Le cas échéant, vous pouvez définir des options de configuration pour permettre au traitement de l’indexeur de continuer en cas de problèmes avec des documents individuels.

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

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

Documents manquants

Les indexeurs extraient des documents ou des lignes d’une source de données externe et créent des documents de recherche qui sont alors indexés par le service de recherche. Parfois, un document existant dans la source de données n’apparaît pas dans un index de recherche. Ce résultat inattendu peut être dû aux raisons suivantes :

Le document a été mis à jour après l’exécution de l’indexeur. Si votre indexeur suit une planification, il est réexécuté et prend le document.
Le délai de l’indexeur a expiré avant l’ingestion du document. Il y a des limites de temps de traitement maximum au-delà desquelles aucun document n’est traité. Vous pouvez surveiller l’état de l’indexeur dans le portail ou en appelant Obtenir l’état de l’indexeur (API REST).
Des mappages de champs ou un enrichissement par IA ont modifié le document et son articulation dans l’index de recherche est différente que ce à quoi vous vous attendiez.
Les valeurs de suivi des modifications sont erronées ou des prérequis sont manquants. Si la valeur de la limite supérieure est une date définie dans le futur, tous les documents dont la date est antérieure à celle-ci sont ignorés par l’indexeur. Vous pouvez déterminer l’état de suivi des modifications de votre indexeur à l’aide des champs « initialTrackingState » et « finalTrackingState » dans l’état de l’indexeur. Les indexeurs pour Azure SQL et MySQL doivent avoir un index dans la colonne de limite supérieure de la table source, sinon les requêtes utilisées par l’indexeur risquent d’expirer.

Conseil

Si des documents sont manquants, vérifiez la requête que vous utilisez pour vous assurer qu’elle n’exclut pas le document concerné. Pour rechercher un document spécifique, utilisez l'API REST de document de recherche.

Contenu manquant de Stockage Blob

L’indexeur d’objets blob recherche et extrait du texte dans les objets blob d’un conteneur. L’extraction de texte peut poser les problèmes suivants :

Le document ne contient que des images numérisées. Les objets blob PDF comportant du contenu non textuel, comme des images numérisées (JPG), ne produisent pas de résultats dans un pipeline d’indexation blob standard. Si vous avez du contenu d’image comportant des éléments textuels, vous pouvez utiliser la reconnaissance optique de caractères ou l’analyse d’image pour rechercher et extraire le texte.
L’indexeur d’objets blob est configuré pour indexer uniquement les métadonnées. Pour extraire le contenu, il doit être configuré de façon à extraire à la fois le contenu et les métadonnées :

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

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

Contenu manquant d’Azure Cosmos DB

La Recherche Azure AI a une dépendance implicite sur l’indexation d’Azure Cosmos DB. Si vous désactivez l’indexation automatique dans Azure Cosmos DB, la Recherche Azure AI renvoie un état de réussite, mais ne parvient pas à indexer le contenu du conteneur. Pour savoir comment vérifier les paramètres et activer l’indexation, voir Gérer l’indexation dans Azure Cosmos DB.

Différence de nombre de documents entre la source de données et l’index

Un indexeur risque d’afficher un nombre de documents différent de celui de la source de données, de l’index lui-même ou du nombre dans votre code. Voici quelques raisons possibles pour lesquelles ce comportement peut se produire :

L’index peut afficher en retard le nombre réel de documents, en particulier dans le portail.
L’indexeur a une stratégie de document supprimé. Les documents supprimés sont comptabilisés par l’indexeur s’ils sont indexés avant d’être supprimés.
Si la colonne ID de la source de données n’est pas unique. Cela s’applique aux sources de données qui utilisent le concept de colonnes, comme Azure Cosmos DB.
Si la définition de la source de données a une requête différente de celle que vous utilisez pour estimer le nombre d’enregistrements. Par exemple, dans votre base de données, vous interrogez le nombre d’enregistrements de base de données, tandis que dans la requête de définition de source de données, vous risquez de sélectionner seulement une partie des enregistrements à indexer.
Les nombres sont vérifiés à des intervalles différents pour chaque composant du pipeline : source de données, indexeur et index.
La source de données a un fichier mappé à plusieurs documents. Cette condition peut se produire lorsque l’indexation d’objets blob et « parsingMode » sont définis sur jsonArray et jsonLines.

Documents traités plusieurs fois

Les indexeurs utilisent une stratégie de mise en mémoire tampon conservatrice pour que chaque document nouveau ou changé dans la source de données soit pris en compte pendant l’indexation. Dans certaines situations, ces mémoires tampon peuvent se chevaucher, ce qui fait qu’un indexeur indexe un document deux fois ou plus, et que le nombre de documents traités est supérieur au nombre réel de documents dans la source de données. Ce comportement n’affecte pas les données stockées dans l’index, comme la duplication des documents, mais il peut allonger le délai nécessaire pour finir par atteindre une cohérence. Cette condition est particulièrement fréquente si l’un des critères suivants est vrai :

Les demandes d’indexation à la demande sont émises et se suivent rapidement
La topologie de la source de données inclut plusieurs réplicas et partitions (un exemple de ce type est présenté ici)
La source de données est une base de données Azure SQL et la colonne choisie comme « point d’eau élevé » est de typedatetime2

Les indexeurs ne sont pas destinés à être appelés plusieurs fois à brefs intervalles. Si vous avez besoin de mises à jour rapides, l’approche recommandée consiste à envoyer les mises à jour vers l’index tout en mettant simultanément à jour la source de données. Pour un traitement à la demande, nous vous recommandons d’échelonner vos demandes par intervalles de cinq minutes ou plus, puis d’exécuter l’indexeur de manière planifiée.

Exemple de traitement de documents en double avec une mémoire tampon de 30 secondes

Les conditions dans lesquelles un document est traité deux fois sont expliquées dans la chronologie suivante qui indique chaque action et contre-action. La chronologie suivante illustre le problème :

Chronologie (hh:mm:ss)	Événement	Limite supérieure de l’indexeur	Commentaire
00:01:00	Écrire `doc1` dans la source de données avec une cohérence finale	`null`	L’horodatage du document est 00:01:00.
00:01:05	Écrire `doc2` dans la source de données avec une cohérence finale	`null`	L’horodatage du document est 00:01:05.
00:01:10	Lancement de l’indexeur	`null`
00:01:11	Requêtes de l’indexeur pour toutes les modifications avant 00:01:10 ; le réplica que l’indexeur interroge est le seul à connaître `doc2` ; récupère `doc2` uniquement	`null`	L’indexeur demande toutes les modifications avant de commencer l’horodatage mais reçoit en fait un sous-ensemble. Ce comportement nécessite la mémoire tampon des périodes passées.
00:01:12	L’indexeur traite `doc2` pour la première fois	`null`
00:01:13	Fin de l’indexeur	00:01:10	La limite supérieure est mise à jour avec l’horodatage de l’exécution de l'indexeur actuel.
00:01:20	Lancement de l’indexeur	00:01:10
00:01:21	Requêtes de l’indexeur pour toutes les modifications entre 00:00:40 et 00:01:20 ; le réplica que l’indexeur interroge est le seul à connaître `doc1` et `doc2` ; récupère `doc1` et `doc2` uniquement	00:01:10	Demandes de l’indexeur pour toutes les modifications entre la limite supérieure actuelle moins la mémoire tampon de 30 secondes et l’horodatage de début d’exécution de l’indexeur actuel.
00:01:22	L’indexeur traite `doc1` pour la première fois	00:01:10
00:01:23	L’indexeur traite `doc2` pour la deuxième fois	00:01:10
00:01:24	Fin de l’indexeur	00:01:20	La limite supérieure est mise à jour avec l’horodatage de l’exécution de l'indexeur actuel.
00:01:32	Lancement de l’indexeur	00:01:20
00:01:33	Requêtes de l’indexeur pour toutes les modifications entre 00:00:50 et 00:01:32 ; récupère `doc1` et `doc2`	00:01:20	Demandes de l’indexeur pour toutes les modifications entre la limite supérieure actuelle moins la mémoire tampon de 30 secondes et l’horodatage de début d’exécution de l’indexeur actuel.
00:01:34	L’indexeur traite `doc1` pour la deuxième fois	00:01:20
00:01:35	L’indexeur traite `doc2` pour la troisième fois	00:01:20
00:01:36	Fin de l’indexeur	00:01:32	La limite supérieure est mise à jour avec l’horodatage de l’exécution de l'indexeur actuel.
00:01:40	Lancement de l’indexeur	00:01:32
00:01:41	Requêtes de l’indexeur pour toutes les modifications entre 00:01:02 et 00:01:40 ; récupère `doc2`	00:01:32	Demandes de l’indexeur pour toutes les modifications entre la limite supérieure actuelle moins la mémoire tampon de 30 secondes et l’horodatage de début d’exécution de l’indexeur actuel.
00:01:42	L’indexeur traite `doc2` pour la quatrième fois	00:01:32
00:01:43	Fin de l’indexeur	00:01:40	Notez que l’exécution de cet indexeur a commencé plus de 30 secondes après la dernière écriture dans la source de données et a également traité `doc2`. Il s’agit du comportement attendu, car si toutes les exécutions de l’indexeur avant 00:01:35 sont éliminées, celle-ci devient la première et la seule exécution pour traiter `doc1` et `doc2`.

En pratique, ce scénario ne se produit que lorsque des indexeurs à la demande sont invoqués manuellement à quelques minutes d'intervalle, pour certaines sources de données. Cela peut entraîner une erreur dans les chiffres (par exemple, l’indexeur a traité 345 documents au total selon ses statistiques d’exécution, mais il y a 340 documents dans la source de données et l’index), ou une facturation potentiellement élevée si vous exécutez plusieurs fois les mêmes compétences pour le même document. L’exécution planifiée d’un indexeur est la meilleure approche.

Indexation de documents avec des étiquettes de confidentialité

Si vous avez des étiquettes de confidentialité définies sur des documents, vous ne pouvez peut-être pas les indexer. Si vous obtenez des erreurs, supprimez les étiquettes avant l’indexation.