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

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.

Meilleures pratiques

Voici quelques bonnes pratiques et recommandations lors de l’utilisation des indexeurs :

Les indexeurs sont conçus pour s’exécuter selon une planification

• Pour une indexation fiable, configurez vos indexeurs pour qu’ils s’exécutent régulièrement. Les exécutions planifiées récupèrent automatiquement tous les documents manqués dans les exécutions précédentes en raison d’erreurs temporaires, d’interruptions réseau ou de problèmes de service temporaires. Cette approche permet de maintenir la cohérence des données et de minimiser la nécessité d’une intervention manuelle.
• Pour les sources de données volumineuses, l’énumération et l’indexation initiales peuvent prendre des heures ou même des jours. L’exécution de votre indexeur selon une planification permet de poursuivre la progression et les erreurs sont retentées automatiquement. Évitez de vous fier uniquement aux exécutions manuelles ou à la demande de l’indexeur, car ces options ne fournissent pas la même fiabilité ou la même récupération d’erreurs temporaires.

Les indexeurs fournissent une indexation optimale au fil du temps

• Les indexeurs intégrés traitent les documents sans rencontrer d’erreurs permanentes et effectuent une nouvelle tentative lors des exécutions planifiées suivantes. Ils offrent un moyen pratique, faible ou sans code d’indexer des données pour des scénarios courants, ce qui facilite le développement et la maintenance plus facile. Lorsqu’un indexeur exécute un ensemble de compétences, chaque exécution a une limite de temps d’exécution fixe. Les indexeurs qui s’exécutent dans l’environnement d’exécution multilocataire ont une durée d’exécution maximale de deux heures. Cette limite est le cas le plus courant, utilisé lorsque les ensembles de compétences ne nécessitent pas de liaisons privées partagées. Les indexeurs configurés pour utiliser des liaisons privées partagées s’exécutent dans un environnement d’exécution privée avec un maximum de 24 heures. Pour la table complète, consultez les limites de l’indexeur. Si le traitement par ensemble de compétences par document empêche l’indexeur de se terminer avant la limite de temps, il s’arrête et laisse les documents restants non traités. Le traitement complet n’est pas garanti lorsque le volume de documents, la taille de fichier, la complexité de l’ensemble de compétences ou l’environnement d’exécution empêchent l’indexeur de terminer dans son temps d’exécution maximal. Le partitionnement de votre source de données peut réduire ce risque, mais ne l’élimine pas, en particulier si vous ajoutez ultérieurement de grands volumes de fichiers à une partition. Ce comportement est attendu. Pour des stratégies pour gérer de grands jeux de données et prendre en charge la récupération incrémentielle, consultez Indexer de grands jeux de données et Planifier les indexeurs. Si votre solution nécessite un contrôle strict sur le moment où l’indexeur traite des documents, utilisez l’alternative d’API Push dans cet article.
• Si votre solution nécessite un contrôle strict sur les chronologies d’indexation, utilisez plutôt les API Push, telles que l’API REST Documents Index ou la méthode IndexDocuments (Kit de développement logiciel (SDK Azure pour .NET) . Ces options vous donnent un contrôle total du pipeline d’indexation.
• Les indexeurs peuvent parfois se désynchroniser avec le planning. Bien que cette condition soit rare et que les mécanismes de récupération automatique existent, la récupération peut prendre du temps. Ce comportement est attendu.

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.

Erreur lors de la connexion à une ressource Microsoft Foundry sur une connexion privée

Si vous obtenez le code d’erreur 403 avec le message suivant, vous pouvez rencontrer un problème avec la façon dont le point de terminaison de ressource est spécifié dans un ensemble de compétences :

• "A Virtual Network is configured for this resource. Please use the correct endpoint for making requests. Check https://aka.ms/cogsvc-vnet for more details."

Cette erreur se produit si vous avez configuré une liaison privée partagée pour les connexions à une ressource Azure Foundry et que le point de terminaison ne dispose pas d’un sous-domaine personnalisé. Un sous-domaine personnalisé constitue la première part du point de terminaison (par exemple, http://my-custom-subdomain.services.ai.azure.com). Un domaine personnalisé peut être manquant si vous avez créé la ressource dans le portail Foundry au lieu du portail Azure.

Si la ressource Foundry n’est pas dans la même région que Recherche IA Azure, utilisez une connexion sans clé pour attacher la ressource.

Erreur lors de l’utilisation d’une liaison privée partagée

Si vous obtenez le code d’erreur 403 avec le message suivant, l’indexeur peut se connecter via le point de terminaison public au lieu d’une liaison privée partagée approuvée :

Unexpected error validating provided resource. {"error":{"code":"403","message":"Public access is disabled. Please configure private endpoint."}}

Cette erreur peut se produire lorsque l’indexeur n’est pas configuré pour utiliser l’environnement d’exécution privée. Vérifiez que la liaison privée partagée est approuvée, définissez la propriété executionEnvironment de l’indexeur sur private, puis vérifiez que la connexion utilise le point de terminaison correct de la ressource et le ID de groupe approprié.

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

Pour autoriser les indexeurs à accéder à ces ressources, utilisez l’une des options suivantes :

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

  • Stockage Azure
  • Azure Cosmos DB
  • Azure SQL

• 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 vous pouvez accéder à votre source en essayant de vous y connecter directement et non via le service de recherche.
• Consultez votre ressource dans le portail Azure pour connaître les erreurs ou pannes actuelles.
• Recherchez les pannes réseau dans Azure État.
• Vérifiez que vous utilisez un DNS public pour la résolution de noms et non un Azure DNS privé.

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 suspendue, la première connexion à partir de votre service de recherche reprend automatiquement la base de données, mais retourne plutôt 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é.

Stratégies d’accès conditionnel Microsoft Entra

Lorsque vous créez un indexeur SharePoint, vous devez 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": une stratégie d’accès conditionnel bloque probablement l’indexeur de la bibliothèque de documents SharePoint.

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

1. Ouvrez le portail Azure et recherchez Accès conditionnel Microsoft Entra.

2. 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.

3. Déterminez quelle stratégie bloque l’indexeur SharePoint d’accéder à la bibliothèque de documents. La stratégie qui peut bloquer l’indexeur inclut le compte d’utilisateur que vous avez utilisé pour vous authentifier 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.
   • Définissez l’état de l’appareil sur Oui.

4. Une fois que vous avez confirmé la stratégie qui bloque l’indexeur, effectuez 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 d’stockage Azure. La mise à jour des paramètres de pare-feu peut prendre jusqu’à 15 minutes pour que l’indexeur de service de recherche accède au compte stockage 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. 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 AzureCognitiveSearch service via l’API de découverte ou le fichier JSON téléchargeable.

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

   

   À partir du fichier JSON, en supposant que le service de recherche se trouve dans la région USA Centre Ouest, la liste des adresses IP pour l’environnement d’exécution de l’indexeur multilocataire est répertoriée.

       {
         "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. 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.

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

8. Attendez quelques minutes pour que la stratégie se mette à jour et applique les nouvelles règles de stratégie.

9. 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 à partir de Stockage Blob Azure et que le conteneur inclut des objets blob 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.

Dans ce cas, vous pouvez définir des options de configuration pour permettre au traitement de l’indexeur de continuer s’il existe des problèmes avec des documents individuels.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-04-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 à partir d’une source de données externe et créent des documents de recherche, que le service de recherche indexe. Parfois, un document qui existe dans la source de données ne parvient pas à apparaître dans un index de recherche. Ce résultat inattendu peut être dû aux raisons suivantes :

• Vous avez mis à jour le document 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 Azure ou en appelant Obtenir l’état de l’indexeur (API REST).
• Les mappages de champs ou l’enrichissement par IA ont changé le document et sa articulation dans l’index de recherche est différente de ce que vous attendez.
• Les valeurs de suivi des modifications sont erronées ou des prérequis sont manquants. Si votre valeur de limite supérieure est une date définie à une date ultérieure, l’indexeur ignore tous les documents dont la date est antérieure. Vous pouvez déterminer l’état du 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.

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 du contenu, vous devez configurer l’indexeur d’objets blob pour extraire le contenu et les métadonnées :

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-04-01
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 Azure.
• 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. Cette condition s’applique aux sources de données qui ont le concept de colonnes, telles que 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 pouvez sélectionner simplement un sous-ensemble d’enregistrements à indexer.
• Les nombres sont vérifiés à 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 tampons peuvent se chevaucher, ce qui entraîne l’indexation d’un document deux ou plusieurs fois. Par conséquent, 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, telles que la duplication de documents, seulement qu’il peut prendre plus de temps pour atteindre la cohérence éventuelle. Cette condition est particulièrement fréquente si l’un des critères suivants est vrai :

• Les demandes d’indexeur à la demande sont émises en succession rapide.
• La topologie de la source de données comprend plusieurs réplicas et partitions, comme la topologie décrite dans les niveaux de cohérence dans Azure Cosmos DB.
• La source de données est une base de données Azure SQL et la colonne choisie en tant que « high water mark » est de type datetime2.

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 le traitement à la demande, rythmez vos demandes dans des intervalles de cinq minutes ou plus, puis exécutez l’indexeur selon une planification.

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

La chronologie suivante explique les conditions dans lesquelles un document est traité deux fois. Elle consigne chaque action et contre-action. La chronologie suivante illustre le problème :

En pratique, ce scénario ne se produit que lorsque vous lancez manuellement des indexeurs à la demande à 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 parallèle

Lorsque plusieurs indexeurs s’exécutent en même temps, certains sont généralement mis en file d’attente et attendent que des ressources se libèrent avant de démarrer. Plusieurs facteurs déterminent le nombre d’indexeurs pouvant s’exécuter simultanément. Si les indexeurs ne sont pas associés à skillsets, le nombre de réplicas et de partitions dans le service AI Search détermine le nombre d’indexeurs pouvant s’exécuter en parallèle.

Si vous associez un indexeur à un ensemble de compétences, il s’exécute dans les clusters internes de recherche IA. La complexité de l’ensemble de compétences et si d’autres ensembles de compétences s’exécutent en même temps déterminent le nombre d’indexeurs qui peuvent s’exécuter simultanément. Les indexeurs intégrés extraient de manière fiable les données de la source, donc aucune donnée n’est manquée si elles s’exécutent selon une planification. Toutefois, les processus d’indexation liés à la parallélisation et à la mise à l’échelle horizontale nécessitent un certain temps pour s’achever.

Indexation de documents avec des étiquettes de confidentialité

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

Contenu connexe

• Résolution des erreurs et des avertissements courants de l’indexeur
• Surveiller l’indexation basée sur un indexeur
• Indexer de grands jeux de données