Résoudre les erreurs et les avertissements courants de l’indexeur dans la Recherche Azure AI

Cet article fournit des informations et des solutions pour les erreurs et avertissements courants que vous pourriez rencontrer pendant l’indexation et l’enrichissement par IA dans la Recherche Azure AI.

L’indexation s’arrête quand le nombre d’erreurs dépasse la valeur de 'maxFailedItems'.

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

Les informations d’erreur de cet article peuvent vous aider à résoudre les erreurs et à poursuivre l’indexation.

L’indexation des avertissements ne s’arrête pas, mais certaines conditions pourraient entraîner des résultats inattendus. Vos données et votre scénario conditionnent les mesures que vous devriez prendre.

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 Les indexeurs de gestion de>la recherche et sélectionnez un indexeur.

3. Sous Historique d’exécution, sélectionnez l’état. Tous les états, y compris Réussite, ont 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 des erreurs

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 a lu le document à partir de la source de données, mais un problème est survenu lors de la conversion du contenu du document au 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é parce que les données de sortie ne sont pas au bon format pour la fonction de mappage que vous utilisez. Par exemple, l’application de la fonction de mappage Base64Encode sur des données binaires génère cette erreur. Pour résoudre le problème, réexécutez l’indexeur sans spécifier la fonction de mappage ou assurez-vous que la fonction de mappage est compatible avec le type de données du champ de sortie. Pour plus d’informations, consultez Mappage de 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é parce que l’appel de l’API web a échoué. En règle générale, cette classe de défaillance se produit lorsque des compétences personnalisées sont utilisées. Dans ce cas, vous devez déboguer votre code personnalisé pour résoudre le problème. Si au contraire l’échec provient d’une compétence intégrée, consultez le message d’erreur dans lequel vous trouverez peut-être de l’aide pour résoudre le 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. Le point de terminaison de votre API web peut échouer, car l’indexeur lui 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é parce que l’API web a retourné une réponse non valide. En règle générale, cette classe de défaillance se produit lorsque des compétences personnalisées sont utilisées. Dans ce cas, vous devez déboguer votre code personnalisé pour résoudre le problème. Si au contraire l’échec est dû à une compétence intégrée, remplissez 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 comporte un champ dont le type de données est différent de celui du champ que vous essayez de mapper dans votre index, vous pouvez rencontrer cette erreur. Vérifiez vos types de données de champ de source de données et vérifiez qu’ils sont correctement mappés à 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. Veuillez suivre les instructions ci-dessous en fonction de la compétence qui a retourné cette erreur.

Compétences Azure AI services intégrées

Bon nombre des compétences cognitives intégrées, notamment la détection de la langue, la reconnaissance d’entités ou la reconnaissance optique de caractères (OCR), s’appuient sur un point de terminaison d’API Azure AI services. Parfois, des problèmes temporaires peuvent survenir avec ces points de terminaison, entraînant l’expiration d’une demande. Il n’existe aucun remède pour ces problèmes temporaires, si ce n’est d’attendre et de réessayer. Pour résoudre le problème, réglez votre indexeur afin de l’exécuter selon une planification. L'indexation planifiée reprend là où elle s'était arrêtée. Si les problèmes temporaires ont été résolus, l'indexation et le traitement des compétences cognitives devraient reprendre à 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, veuillez remplir un ticket de support pour obtenir de l’aide, car il ne s’agit pas d’un problème attendu.

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, vérifiez votre compétence personnalisée et assurez-vous qu’elle n’est pas bloquée dans une boucle infinie et qu’elle renvoie un résultat de manière cohérente. Après vous être assuré qu’un résultat est renvoyé, vérifiez la durée d’exécution. Si vous n'avez pas explicitement défini une valeur timeout dans votre définition de compétence personnalisée, la valeur par défaut timeout est 30 secondes. Si 30 secondes ne suffisent pas à l’exécution de votre compétence, vous pouvez spécifier une valeur timeout plus élevée dans la définition de votre compétence personnalisée. Voici un exemple de définition de compétence personnalisée où le délai d’expiration est fixé à 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 paramètre timeout est de 230 secondes. Si votre compétence personnalisée ne peut pas s’exécuter de façon constante en 230 secondes, vous pouvez réduire la valeur batchSize de votre compétence personnalisée afin qu’elle ait moins de documents à traiter en une seule exécution. Si vous avez déjà réglé votre valeur batchSize sur 1, vous devez réécrire la compétence pour pouvoir l’exécuter en moins de 230 secondes ou la diviser en plusieurs compétences personnalisées de sorte que le délai d’exécution d’une seule compétence personnalisée soit au maximum de 230 secondes. Pour plus d'informations, consultez la documentation sur les 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

L’indexeur a lu et traité le document mais, en raison d’une discordance de configuration des champs d’index et des données extraites et traitées par l’indexeur, il n’a pas été possible d’ajouter les données à l’index de recherche. Cela peut se produire si :

Dans tous ces cas, consultez les types de données pris en charge et le mappage des types de données pour les indexeurs pour vous assurer de générer le schéma d’index correctement et de définir les mappages de champs d’indexeur appropriés. Le message d’erreur comprend des détails qui peuvent aider à identifier 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 en tant que clé composite ou, lorsque la table a défini un index cluster unique (comme avec l’index SQL, mais pas l’index Azure Search). Ceci est principalement dû au fait que l’attribut de clé est transformé en une clé primaire composite dans un index cluster unique. Dans ce cas, vérifiez que votre table SQL ne comporte pas d’index cluster unique, ou que vous mappez le champ clé à un champ pour lequel les valeurs en double sont impossibles.

Error: Could not process document within indexer max run time

Cette erreur se produit lorsque l’indexeur ne peut pas terminer le traitement d’un document unique à partir de la source de données en respectant le temps d’exécution autorisé. Le temps d’exécution maximal est plus court quand des ensembles de compétences sont utilisés. Lorsque cette erreur se produit, si maxFailedItems est défini sur une valeur autre que 0, l’indexeur ignore le document pour les prochaines exécutions, de façon que l’indexation puisse progresser. Si vous ne pouvez pas vous permettre d’ignorer un document, ou si vous voyez cette erreur régulièrement, pensez à diviser les documents en documents plus petits pour qu’une seule exécution de l’indexeur puisse traiter une partie de ces derniers.

Error: Could not project document

Cette erreur se produit lorsque l’indexeur tente de projeter des données dans une base de connaissances et échoue. Cet échec peut être systématique et réparable, ou il peut s’agir d’un échec temporaire au niveau du récepteur de sortie de projection. Dans ce cas, vous devrez attendre un peu avant de réessayer. 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 à Azure AI services a fait l’objet d’une limitation. En général, cette classe d’échec est due au fait qu’un trop grand nombre de compétences s’exécutent en parallèle. Si vous utilisez la bibliothèque de client Microsoft.Search.Documents pour exécuter l’indexeur, vous pouvez utiliser SearchIndexingBufferedSender afin de bénéficier d’une nouvelle tentative automatique pour les étapes qui ont é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 quand un cache d’annotations est ajouté ou supprimé de l’indexeur sans que celui ne soit réinitialisé. Pour résoudre ce problème, vous devez réinitialiser et réexécuter l’indexeur.

Warning: Skill input was invalid

Il manque une entrée à la compétence, un type est incorrect ou non valide. Les informations suivantes peuvent s’afficher :

• Could not execute skill

• Skill executed but may have unexpected results

Les compétences cognitives nécessitaient des entrées et des entrées facultatives. Par exemple, la compétence d’extraction d’expression clé a deux entrées obligatoires, text et languageCode, et aucune entrée facultative. Les entrées de compétences personnalisées sont toutes considérées comme des entrées facultatives.

S’il manque des entrées nécessaires ou si l’entrée n’est pas du bon type, la compétence est ignorée et génère un avertissement. Les compétences ignorées ne génèrent aucun résultat. 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.

S’il manque une entrée facultative, la compétence est quand même exécutée, mais elle peut produire des résultats inattendus 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 disposez d’un document contenant des informations sur des personnes avec les champs firstName, middleName et lastName, certains documents ne comportent peut-être 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 une action est nécessaire suite à cet avertissement.

Si vous souhaitez fournir une valeur par défaut pour une entrée manquante, vous pouvez utiliser la compétence conditionnelle afin de générer une valeur par défaut, puis utiliser la sortie de la compétence conditionnelle en tant qu’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 transmises dans l'entrée languageCode facultative d’une compétence située en aval n’est pas prise en charge. Cela peut se produire si vous transmettez la sortie de LanguageDetectionSkill à des compétences ultérieures, et que la sortie comporte plus de langues que celles prises en charge dans les compétences situées en aval.

Notez que vous pouvez également recevoir un avertissement similaire à celui-ci si une entrée countryHint non valide est passée à 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 à deux lettres ISO 3166-1 alpha-2 valides. Si certains sont valides et d’autres ne le sont pas, poursuivez avec les instructions suivantes, mais remplacez languageCode par countryHint et defaultLanguageCode par defaultCountryHint pour correspondre à votre cas d’usage.

Si vous savez que votre jeu de données utilise une seule langue, vous devriez supprimer LanguageDetectionSkill et l’entrée de compétence languageCode, puis utiliser plutôt defaultLanguageCode pour ce paramètre de 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 résultat pour la compétence 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 générer 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 Text SplitSkill : 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é en une seule fois. Si l’entrée de texte dépasse la limite, le texte est tronqué avant d’être enrichi. La compétence s’exécute, mais pas sur toutes vos données.

Dans l’exemple LanguageDetectionSkill ci-dessous, le champ d’entrée 'text' peut déclencher cet avertissement si l’entrée dépasse la limite de caractères. Pour connaître les limites d’entrée, consultez 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 voulez vous assurer que tout le texte est analysé, pensez à utiliser la compétence Split.

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. Examinez les avertissements pour comprendre l’impact sur vos données et déterminer si des mesures supplémentaires sont nécessaires.

Warning: The current indexer configuration does not support incremental progress

Cet avertissement s’affiche uniquement pour des sources de données Azure Cosmos DB.

Dans le cas où l’exécution de l’indexeur est interrompue par des défaillances passagères ou un dépassement du délai d’exécution, la progression incrémentielle pendant l’indexation permet à l’indexeur de reprendre là il en était lors de sa dernière exécution, plutôt que d’avoir à tout réindexer depuis le début. Ceci est particulièrement important lors de l’indexation de grandes collections.

La possibilité de reprendre un travail d’indexation inachevé dépend de la disponibilité de documents ordonnés par la colonne _ts. L’indexeur utilise l’horodatage pour déterminer le prochain document à récupérer. Si la colonne _ts 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 commence au début, cet avertissement s’affiche.

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

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 présentant une propriété de chaîne de plus de 32 000 caractères est en cours de projection, seuls les 32 000 premiers caractères sont conservés. Pour contourner ce problème, évitez de projeter des lignes comportant des propriétés de chaîne de plus de 32 000 caractères.

Warning: Truncated extracted text to X characters

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

Pour plus d’informations, consultez Limites des indexeurs.

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

Les mappages de champs de sortie qui font référence à des données inexistantes/null génèrent des avertissements pour chaque document et créent un champ d’index vide. Pour contourner ce problème, vérifiez que les chemins sources de mappage de champs de sortie sont corrects ou définissez une valeur par défaut à l’aide de la compétence conditionnelle. Pour plus d’informations, consultez Mappage de champs de sortie.

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

Pour détecter les modifications, les stratégies de détection des modifications de données ont des exigences spécifiques pour les colonnes qu’elles utilisent. L’une de ces exigences est que la 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 respectent pas cette exigence, car elles ne changent pas à 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 connaître la méthode d’encodage du texte avant de pouvoir l’analyser. Les deux méthodes les plus courantes pour encoder du texte sont UTF-16 et UTF-8. UTF-8 est un encodage de longueur variable où chaque caractère est compris entre 1 et 4 octets. UTF-16 est un encodage de longueur fixe où chaque caractère a une longueur de 2 octets. UTF-16 a deux variantes différentes, big endian et little endian. L’encodage de texte est déterminé par une byte order mark, une série d’octets avant le texte.

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

Pour contourner cet avertissement, déterminez l’encodage de texte pour ce 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, modifiez votre stratégie d’indexation sur Cohérent.

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 de langage d’Azure AI services. Dans certains cas, vous pouvez sans risque ignorer cet avertissement, par exemple si la chaîne longue n’est qu’une longue URL. Sachez que lorsqu’un mot dépasse 64 caractères, il est tronqué à 64 caractères, ce qui peut impacter 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. Vérifiez 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.