Résolution des erreurs et avertissements courants de l’indexeur dans Recherche AZURE AI

Cet article fournit des informations et des solutions aux erreurs et avertissements courants que vous pouvez rencontrer lors de l’indexation et de l’enrichissement par IA dans Azure AI Search.

L’indexation s’arrête lorsque le nombre d’erreurs dépasse « maxFailedItems ».

Si vous souhaitez que les indexeurs ignorent ces erreurs (et ignorent les « documents ayant échoué »), envisagez de mettre à jour le maxFailedItems et le maxFailedItemsPerBatch comme décrit ici.

Les informations sur les erreurs contenues dans cet article peuvent vous aider à résoudre les erreurs, ce qui permet à l’indexation de continuer.

Les avertissements n’arrêtent pas l’indexation, mais ils indiquent des conditions qui peuvent entraîner des résultats inattendus. Que vous preniez des mesures ou non dépend des données et de votre scénario.

Où trouver des erreurs d’indexeur spécifiques ?

Pour vérifier l’état d’un indexeur et identifier les erreurs dans le portail Azure, procédez comme suit :

1. Connectez-vous au Portail Azure, puis trouvez votre service de recherche.

2. Sur la gauche, développez Gestion de la recherche>Les indexeurs et sélectionnez un indexeur.

3. Sous Historique d’exécution, sélectionnez l’état. Tous les statuts, y compris Succès, contiennent des détails sur l'exécution.

4. En cas d’erreur, pointez sur le message d’erreur. Un volet s’affiche sur le côté droit de votre écran affichant des informations détaillées sur l’erreur.

Erreurs temporaires

Pour diverses raisons, telles que les interruptions de communication réseau temporaires, les délais d’expiration des processus longs ou des nuances de document spécifiques, il est courant de rencontrer des erreurs temporaires ou des avertissements pendant les exécutions de l’indexeur. Toutefois, ces erreurs sont temporaires et doivent être résolues dans les exécutions d’indexeur suivantes.

Pour gérer efficacement ces erreurs, nous vous recommandons de mettre votre indexeur selon une planification, par exemple, pour s’exécuter toutes les cinq minutes, où la prochaine exécution commence cinq minutes après la première exécution, en respectant la limite maximale d’exécution sur votre service. Les exécutions planifiées régulièrement permettent de corriger les erreurs temporaires ou les avertissements.

Si une erreur persiste sur plusieurs exécutions d’indexeur, il est probable qu’il ne s’agit pas d’un problème temporaire. Dans ce cas, reportez-vous à la liste ci-dessous pour connaître les solutions potentielles.

Propriétés de l’erreur

Error: Could not read document

L’indexeur n’a pas pu lire le document à partir de la source de données. Cela peut se produire si :

Error: Could not extract content or metadata from your document

L’indexeur avec une source de données Blob n’a pas pu extraire le contenu ou les métadonnées du document (par exemple, un fichier PDF). Cela peut se produire si :

Error: Could not parse document

L’indexeur lit le document à partir de la source de données, mais il y a eu un problème lors de la conversion du contenu du document dans le schéma de mappage de champs spécifié. Cela peut se produire si :

Error: Could not map output field 'xyz' to search index due to deserialization problem while applying mapping function 'abc'

Le mappage de sortie a peut-être échoué, car les données de sortie sont au format incorrect pour la fonction de mappage que vous utilisez. Par exemple, l’application Base64Encode d’une fonction de mappage sur des données binaires génère cette erreur. Pour résoudre le problème, réexécutez l’indexeur sans spécifier de fonction de mappage ou vérifiez que la fonction de mappage est compatible avec le type de données du champ de sortie. Pour plus d’informations, consultez le mappage des champs de sortie .

Error: Could not execute skill

L’indexeur n’a pas pu exécuter une compétence dans l’ensemble de compétences.

Error: Could not execute skill because the Web API request failed

L’exécution de la compétence a échoué, car l’appel à l’API web a échoué. En règle générale, cette classe d’échec se produit lorsque des compétences personnalisées sont utilisées, auquel cas vous devez déboguer votre code personnalisé pour résoudre le problème. Si au lieu de cela, l’échec provient d’une compétence intégrée, reportez-vous au message d’erreur pour obtenir de l’aide sur la résolution du problème.

Lors du débogage de ce problème, prêtez attention aux éventuels avertissements d’entrée de compétence pour cette compétence. Votre point de terminaison d’API web peut échouer, car l’indexeur transmet une entrée inattendue.

Error: Could not execute skill because Web API skill response is invalid

L’exécution de la compétence a échoué, car l’appel à l’API web a retourné une réponse non valide. En règle générale, cette classe d’échec se produit lorsque des compétences personnalisées sont utilisées, auquel cas vous devez déboguer votre code personnalisé pour résoudre le problème. Si au lieu de cela, l’échec provient d’une compétence intégrée, déposez un ticket de support pour obtenir de l’aide.

Error: Type of value has a mismatch with column type. Couldn't store in 'xyz' column. Expected type is 'abc'

Si votre source de données a un champ avec un type de données différent du champ que vous essayez de mapper dans votre index, vous risquez de rencontrer cette erreur. Vérifiez vos types de données de champ de source de données et vérifiez qu’ils sont mappés correctement à vos types de données d’index.

Error: Skill did not execute within the time limit

Il existe deux cas dans lesquels vous pouvez rencontrer ce message d’erreur, chacun d’entre eux devant être traité différemment. Suivez les instructions ci-dessous en fonction de la compétence qui a causé cette erreur.

Compétences intégrées des outils Foundry

La plupart des compétences cognitives intégrées, telles que la détection de langage, la reconnaissance d’entité ou l’OCR, sont soutenues par un point de terminaison d’API Foundry Tools. Parfois, il existe des problèmes temporaires avec ces points de terminaison et une demande expire. Pour les problèmes temporaires, il n’existe aucun remède, sauf pour attendre et réessayer. En guise d’atténuation, envisagez de définir votre indexeur pour qu’il s’exécute selon une planification. L’indexation planifiée récupère là où elle s’est arrêtée. En supposant que les problèmes temporaires soient résolus, l’indexation et le traitement des compétences cognitives devraient pouvoir se poursuivre lors de la prochaine exécution planifiée.

Si vous continuez à voir cette erreur sur le même document pour une compétence cognitive intégrée, créez un ticket de support pour obtenir de l’aide, car cela n’est pas prévu.

Compétences personnalisées

Si vous rencontrez une erreur d’expiration d’une compétence personnalisée, vous pouvez essayer plusieurs solutions. Tout d’abord, passez en revue votre compétence personnalisée et assurez-vous qu’elle ne se bloque pas dans une boucle infinie et qu’elle retourne un résultat de manière cohérente. Une fois que vous avez confirmé qu’un résultat est obtenu, vérifiez la durée d’exécution. Si vous n’avez pas défini explicitement de timeout valeur sur votre définition de compétence personnalisée, la valeur par défaut timeout est de 30 secondes. Si 30 secondes ne sont pas suffisamment longues pour que votre compétence s’exécute, vous pouvez spécifier une valeur plus élevée timeout sur votre définition de compétence personnalisée. Voici un exemple de définition de compétence personnalisée où le délai d’expiration est défini sur 90 secondes :

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "uri": "<your custom skill uri>",
        "batchSize": 1,
        "timeout": "PT90S",
        "context": "/document",
        "inputs": [
          {
            "name": "input",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "output",
            "targetName": "output"
          }
        ]
      }

La valeur maximale que vous pouvez définir pour le timeout paramètre est de 230 secondes. Si votre compétence personnalisée ne peut pas s’exécuter de manière cohérente dans les 230 secondes, vous pouvez envisager de réduire la batchSize compétence personnalisée afin qu’elle ait moins de documents à traiter au sein d’une seule exécution. Si vous avez déjà défini votre batchSize valeur 1, vous devez réécrire la compétence pour pouvoir s’exécuter en moins de 230 secondes, ou la fractionner en plusieurs compétences personnalisées afin que le temps d’exécution d’une seule compétence personnalisée soit un maximum de 230 secondes. Pour plus d’informations, consultez la documentation des compétences personnalisées .

Error: Could not 'MergeOrUpload' | 'Delete' document to the search index

Le document a été lu et traité, mais l’indexeur n’a pas pu l’ajouter à l’index de recherche. Cela peut se produire si :

Error: Could not index document because some of the document's data was not valid

Le document a été lu et traité par l’indexeur, mais en raison d’une incompatibilité dans la configuration des champs d’index et des données extraites et traitées par l’indexeur, il n’a pas pu être ajouté à l’index de recherche. Cela peut se produire si :

Dans tous ces cas, reportez-vous aux types de données pris en charge et au mappage de type de données pour les indexeurs afin de vous assurer que vous générez correctement le schéma d’index et que vous avez configuré les mappages de champs d’indexeur appropriés. Le message d’erreur inclut des détails qui peuvent aider à suivre la source de l’incompatibilité.

Error: Integrated change tracking policy cannot be used because table has a composite primary key

Cela s’applique aux tables SQL et se produit généralement lorsque la clé est définie comme une clé composite ou, lorsque la table a défini un index cluster unique (comme dans un index SQL, et non comme dans un index Recherche Azure). La raison principale est que l’attribut de clé est modifié pour être une clé primaire composite dans un index cluster unique. Dans ce cas, assurez-vous que votre table SQL n’a pas d’index cluster unique ou que vous mappez le champ clé à un champ qui n’a pas de valeurs en double.

Error: Could not process document within indexer max run time

Cette erreur se produit lorsque l’indexeur ne parvient pas à terminer le traitement d’un document unique à partir de la source de données dans le temps d’exécution autorisé. La durée d’exécution maximale est plus courte lorsque des ensembles de compétences sont utilisés. Lorsque cette erreur se produit, si vous avez défini maxFailedItems sur une valeur autre que 0, l’indexeur contourne le document lors des exécutions futures afin que l’indexation puisse progresser. Si vous ne pouvez pas vous permettre d’ignorer n’importe quel document ou si vous voyez cette erreur de façon cohérente, envisagez de diviser les documents en documents plus petits afin que la progression partielle puisse être effectuée au sein d’une seule exécution de l’indexeur.

Error: Could not project document

Cette erreur se produit lorsque l’indexeur tente de projeter des données dans une base de connaissances et qu’il y a eu un échec lors de la tentative. Cet échec peut être cohérent et corrigeable, ou il peut s’agir d’un échec temporaire avec le récepteur de sortie de projection que vous devrez peut-être attendre et réessayer pour résoudre. Voici un ensemble d’états d’échec connus et de résolutions possibles.

Error: The cognitive service for skill '<skill-name>' has been throttled

L’exécution de la compétence a échoué parce que l’appel à Foundry Tools a fait l’objet d’une limitation. En règle générale, cette classe d’échec se produit lorsque trop de compétences s’exécutent en parallèle. Si vous utilisez la bibliothèque cliente Microsoft.Search.Documents pour exécuter l’indexeur, vous pouvez utiliser SearchIndexingBufferedSender pour obtenir une nouvelle tentative automatique lors des étapes ayant échoué. Sinon, vous pouvez réinitialiser et réexécuter l’indexeur.

Error: Expected IndexAction metadata

Une erreur « Métadonnées IndexAction attendues » signifie que lorsque l’indexeur a tenté de lire le document pour identifier l’action à entreprendre, il ne trouve pas de métadonnées correspondantes sur le document. En règle générale, cette erreur se produit lorsque l’indexeur a un cache d’annotation ajouté ou supprimé sans réinitialiser l’indexeur. Pour résoudre ce problème, vous devez réinitialiser et réexécuter l’indexeur.

Warning: Skill input was invalid

Une entrée pour la compétence est manquante, a un type incorrect ou est non valide. Vous pouvez voir les informations suivantes :

• Could not execute skill

• Skill executed but may have unexpected results

Les compétences cognitives ont besoin d’entrées et d’entrées facultatives. Par exemple, la compétence d’extraction d’expressions clés a deux entrées requises text, languageCodeet aucune entrée facultative. Les entrées de compétence personnalisées sont toutes considérées comme des entrées facultatives.

Si les entrées nécessaires sont manquantes ou si l’entrée n’est pas le type approprié, la compétence est ignorée et génère un avertissement. Les compétences ignorées ne génèrent pas de résultats. Si des compétences situées en aval utilisent les résultats de la compétence ignorée, elles peuvent générer d’autres avertissements.

Si une entrée facultative est manquante, la compétence s’exécute toujours, mais elle peut produire une sortie inattendue en raison de l’entrée manquante.

Dans les deux cas, cet avertissement est dû à la forme de vos données. Par exemple, si vous avez un document contenant des informations sur les personnes avec les champs firstName, middleName, et lastName, il se peut que vous ayez des documents qui n'ont pas d'entrée pour middleName. Si vous transmettez middleName en tant qu’entrée à une compétence dans le pipeline, il est prévu que cette entrée de compétence soit parfois manquante. Vous devez évaluer vos données et votre scénario pour déterminer si aucune action n’est requise à la suite de cet avertissement.

Si vous souhaitez fournir une valeur par défaut pour une entrée manquante, vous pouvez utiliser la compétence conditionnelle pour générer une valeur par défaut, puis utiliser la sortie de la compétence conditionnelle comme entrée de compétence.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'en'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

Warning: Skill input 'languageCode' has the following language codes 'X,Y,Z', at least one of which is invalid.

Une ou plusieurs des valeurs passées dans l’entrée facultative languageCode d’une compétence en aval ne sont pas prises en charge. Cela peut se produire si vous passez la sortie de LanguageDetectionSkill aux compétences suivantes, et que la sortie se compose de plus de langues que celles prises en charge dans ces compétences en aval.

Notez que vous pouvez également obtenir un avertissement similaire à celui-ci si une entrée non valide countryHint est transmise à LanguageDetectionSkill. Si cela se produit, vérifiez que le champ que vous utilisez à partir de votre source de données pour cette entrée contient des codes de pays iso 3166-1 alpha-2 valides. Si certains sont valides et que certains ne sont pas valides, poursuivez avec les instructions suivantes, mais remplacez languageCodecountryHint par et defaultLanguageCode par defaultCountryHint pour correspondre à votre cas d’usage.

Si vous savez que votre jeu de données est dans une seule langue, vous devez supprimer languageDetectionSkill et l’entrée languageCode de compétence et utiliser le defaultLanguageCode paramètre de compétence pour cette compétence, en supposant que la langue est prise en charge pour cette compétence.

Si vous savez que votre jeu de données contient plusieurs langues et que vous avez donc besoin de LanguageDetectionSkill et de l’entrée languageCode, ajoutez un paramètre ConditionalSkill pour filtrer le texte selon les langues non prises en charge avant de passer le texte à la compétence en aval. Voici un exemple de ce à quoi cela peut ressembler pour EntityRecognitionSkill :

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'de' || $(/document/language) == 'en' || $(/document/language) == 'es' || $(/document/language) == 'fr' || $(/document/language) == 'it'" },
        { "name": "whenTrue", "source": "/document/content" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "supportedByEntityRecognitionSkill" } ]
}

Voici quelques références pour les langues actuellement prises en charge pour chacune des compétences qui peuvent produire ce message d’erreur :

• Langues prises en charge par EntityRecognitionSkill
• Langues prises en charge par EntityLinkingSkill
• Langues prises en charge par KeyPhraseExtractionSkill
• Langues prises en charge par LanguageDetectionSkill
• Langues prises en charge par PIIDetectionSkill
• Langues prises en charge par SentimentSkill
• Langues prises en charge par Translator
• Langues prises en charge par SplitSkill Texte :da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

Les compétences cognitives limitent la longueur du texte qui peut être analysée à la fois. Si l’entrée de texte dépasse la limite, le texte est tronqué avant son enrichissement. La fonctionnalité s’exécute, mais pas sur toutes vos données.

Dans l’exemple LanguageDetectionSkill ci-dessous, le 'text' champ d’entrée peut déclencher cet avertissement si l’entrée dépasse la limite de caractères. Vous trouverez des limites d’entrée dans la documentation de référence sur les compétences.

 {
    "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
    "inputs": [
      {
        "name": "text",
        "source": "/document/text"
      }
    ],
    "outputs": [...]
  }

Si vous souhaitez vous assurer que tout le texte est analysé, envisagez d’utiliser la compétence Fractionner.

Warning: Web API skill response contains warnings

L’indexeur a exécuté la compétence dans l’ensemble de compétences, mais la réponse à la demande de l’API web indique qu’il y a des avertissements. Passez en revue les avertissements pour comprendre comment vos données sont affectées et si d’autres actions sont requises.

Warning: The current indexer configuration does not support incremental progress

Cet avertissement se produit uniquement pour les sources de données Azure Cosmos DB.

La progression incrémentielle pendant l’indexation garantit que si l’exécution de l’indexeur est interrompue par des échecs temporaires ou une limite de temps d’exécution, l’indexeur peut récupérer là où il a quitté la prochaine fois qu’il s’exécute, au lieu de devoir réindexer l’ensemble de la collection à partir de zéro. Cela est particulièrement important lors de l’indexation de grandes collections.

La possibilité de reprendre un travail d’indexation non terminé dépend d'avoir les documents ordonnés selon la colonne _ts. L’indexeur utilise l’horodatage pour déterminer le document à récupérer ensuite. Si la _ts colonne est manquante ou si l’indexeur ne peut pas déterminer si une requête personnalisée est ordonnée par celle-ci, l’indexeur démarre au début et vous verrez cet avertissement.

Il est possible de remplacer ce comportement, en activant la progression incrémentielle et en supprimant cet avertissement à l’aide de la assumeOrderByHighWaterMarkColumn propriété de configuration.

Pour plus d’informations, consultez Progression incrémentielle et requêtes personnalisées.

Warning: Some data was lost during projection. Row 'X' in table 'Y' has string property 'Z' which was too long.

Le service Stockage Table impose des limites sur la taille des propriétés d’entité. Les chaînes peuvent comporter 32 000 caractères ou moins. Si une ligne avec une propriété de chaîne supérieure à 32 000 caractères est projetée, seuls les 32 000 premiers caractères sont conservés. Pour contourner ce problème, évitez de projeter des lignes avec des propriétés de chaîne supérieures à 32 000 caractères.

Warning: Truncated extracted text to X characters

Les indexeurs limitent la quantité de texte pouvant être extraite de n’importe quel document. Cette limite dépend du niveau tarifaire : 32 000 caractères pour le niveau Gratuit, 64 000 pour Basic, 4 millions pour Standard, 8 millions pour Standard S2 et 16 millions pour Standard S3. Le texte tronqué ne sera pas indexé. Pour éviter cet avertissement, essayez de séparer les documents avec de grandes quantités de texte en plusieurs documents plus petits.

Pour plus d’informations, consultez limites de l’indexeur.

Warning: Could not map output field 'X' to search index

Les mappages de champs de sortie qui référencent des données inexistantes/null produisent des avertissements pour chaque document et entraînent un champ d’index vide. Pour contourner ce problème, vérifiez deux fois les chemins sources de mappage de champs de sortie pour les fautes de frappe possibles ou définissez une valeur par défaut à l’aide de la compétence conditionnelle. Pour plus d’informations, consultez le mappage des champs de sortie .

Warning: The data change detection policy is configured to use key column 'X'

Les stratégies de détection des modifications de données ont des exigences spécifiques pour les colonnes qu’ils utilisent pour détecter les modifications. L’une de ces exigences est que cette colonne est mise à jour chaque fois que l’élément source est modifié. Une autre exigence est que la nouvelle valeur de cette colonne est supérieure à la valeur précédente. Les colonnes clés ne répondent pas à cette exigence, car elles ne changent pas sur chaque mise à jour. Pour contourner ce problème, sélectionnez une autre colonne pour la stratégie de détection des modifications.

Warning: Document text appears to be UTF-16 encoded, but is missing a byte order mark

Les modes d’analyse de l’indexeur doivent savoir comment le texte est encodé avant de l’analyser. Les deux méthodes les plus courantes d’encodage de texte sont UTF-16 et UTF-8. UTF-8 est un encodage de longueur variable où chaque caractère est compris entre 1 octet et 4 octets de long. UTF-16 est un encodage de longueur fixe où chaque caractère est de 2 octets de long. UTF-16 a deux variantes différentes, big endian et little endian. L’encodage de texte est déterminé par une byte order marksérie d’octets avant le texte.

Si aucune marque d’ordre d’octet n’est présente, le texte est supposé être encodé en UTF-8.

Pour contourner cet avertissement, déterminez l’encodage de texte de cet objet blob et ajoutez la marque d’ordre d’octet appropriée.

Warning: Azure Cosmos DB collection 'X' has a Lazy indexing policy. Some data may be lost

Les collections dotées de stratégies d’indexation différée ne peuvent pas être interrogées de manière cohérente, ce qui entraîne une absence de données dans votre indexeur. Pour contourner cet avertissement, remplacez votre stratégie d’indexation par Cohérence.

Warning: The document contains very long words (longer than 64 characters). These words may result in truncated and/or unreliable model predictions.

Cet avertissement est transmis à partir du service linguistique de Foundry Tools. Dans certains cas, il est sûr d’ignorer cet avertissement, par exemple si la chaîne longue n’est qu’une longue URL. N’oubliez pas que lorsqu’un mot est supérieur à 64 caractères, il est tronqué à 64 caractères qui peuvent affecter les prédictions de modèle.

Error: Cannot write more bytes to the buffer than the configured maximum buffer size

Les indexeurs ont des limites de taille de document. Assurez-vous que les documents de votre source de données sont inférieurs à la limite de taille prise en charge, comme documenté pour votre niveau de service.

Error: Failed to compare value 'X' of type M to value 'Y' of type N.

Cette erreur se produit généralement dans les indexeurs Azure SQL lorsque le type de colonne source utilisé pour dataChangeDetectionPolicy ne correspond pas à ce que l’indexeur attend, en particulier s’il convertHighWaterMarkToRowVersion est activé.

Par exemple, si la colonne utilisée pour la détection des modifications est de type datetime, mais que l’indexeur attend un type rowversion, car convertHighWaterMarkToRowVersion est activé, l’incompatibilité provoque une erreur.

Vérifiez le type de données de la colonne « High Water Mark » dans la source et mettez à jour la configuration de l’indexeur en conséquence. Une fois vérifié et mis à jour, réinitialisez et réexécutez l’indexeur pour traiter les valeurs de colonne.

Error: Access denied to Virtual Network/Firewall rules.

Cette erreur se produit généralement en raison de l’une des opérations suivantes :

• Restrictions de pare-feu sur les ressources Azure requises par votre indexeur, en fonction de votre configuration. Ces ressources peuvent inclure : la source de données, le compte stockage Azure (utilisé pour les sessions de débogage, l’enrichissement incrémentiel ou la base de connaissances), La fonction Azure (utilisée pour les compétences personnalisées de l’API web) ou les déploiements Microsoft Foundry utilisés lors de l’enrichissement par IA.
• Configurations de point de terminaison privé qui bloquent l’accès de l’indexeur à ces ressources.

Vérifiez que l’indexeur a accès à vos composants d’installation en examinant vos configurations de ressources pour confirmer qu’elles autorisent le trafic vers tous les services requis :

• Paramètres de restriction du pare-feu et de l’adresse IP
• Configuration de liaison privée partagée

Error: Credentials provided in the connection string are invalid or have expired.

Cette erreur se produit lorsque l’indexeur Azure AI Search ne peut pas s’authentifier à l’aide de la chaîne de connexion fournie ou qu’il rencontre des problèmes d’accès au compte de stockage pour vérifier les informations d’identification.