Gérer un cache d’enrichissement (version préliminaire)

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Important

Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.

Un cache d’enrichissement (version préliminaire) est une fonctionnalité facultative qui stocke le contenu enrichi créé pendant l’exécution de l’ensemble de compétences. Il conserve le contenu entre les exécutions afin que seules les compétences modifiées et les documents nécessitent un retraitement. Il ne s’agit pas d’une sauvegarde des sorties d’ensemble de compétences, de l’état de l’indexeur ou des documents indexés.

Vous créez le cache d’enrichissement dans stockage Azure. Le cache contient la sortie du craquage de document, ainsi que les sorties de chaque compétence pour chaque document. Bien que la mise en cache soit facturable (elle utilise stockage Azure), le coût global de l’enrichissement est réduit, car les coûts de stockage sont inférieurs à l’extraction d’images et au traitement ia.

Si vous configurez un cache d’enrichissement, cet article explique comment gérer les mises à jour des compétences et des sources de données afin d’obtenir un utilitaire maximal à partir d’enrichissements mis en cache.

Conditions préalables

Limitations

Attention

Si vous utilisez l'indexeur SharePoint (préversion), évitez l'enrichissement incrémentiel. Dans certaines circonstances, le cache n’est plus valide. Pour le recharger, effectuez une réinitialisation de l’indexeur et une reconstruction complète.

Les sources de données volumineuses présentent une limitation supplémentaire du cache.

Attention

Pour les sources de données volumineuses, un cache d’enrichissement peut accroître le volume total de retraitement lorsque des compétences dont l’exécution est longue, des interruptions répétées ou des échecs fréquents des compétences se produisent. L’indexeur privilégie l’exactitude plutôt que la minimisation du retraitement, de sorte qu’une accumulation dans le cache due à des interruptions répétées accentue le mécanisme de nouvelle tentative.

Pour effectuer une récupération à partir d’un backlog de cache croissant, partitionnez la source de données en conteneurs ou dossiers virtuels plus petits. Utilisez ensuite des indexeurs parallèles pointant vers le même index. Pour dissocier le cache, définissez la propriété cache sur null dans l’indexeur.

Configuration du cache

Physiquement, le cache est stocké dans un conteneur d’objets blob et des tables dans votre compte stockage Azure, un par indexeur. Chaque indexeur reçoit un identificateur de cache unique et immuable qui correspond au conteneur qu’il utilise.

Le cache est créé lorsque vous spécifiez la cache propriété et exécutez l’indexeur. Seul le contenu enrichi peut être mis en cache. Si votre indexeur n’a pas de jeu de compétences attaché, la mise en cache ne s’applique pas.

L’exemple suivant illustre un indexeur avec la mise en cache activée. Consultez Configurer la mise en cache de l’enrichissement pour obtenir des instructions complètes.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Gestion du cache

L’indexeur gère le cycle de vie du cache. Si vous supprimez un indexeur, vous supprimez également son cache. Si vous définissez la propriété de cache l'indexeur sur Null ou modifiez l'chaîne de connexion, le cache existant est supprimé lors de l'exécution de l'indexeur suivant.

Bien que l’enrichissement incrémentiel soit conçu pour détecter et répondre aux modifications sans intervention de votre part, vous pouvez définir des paramètres pour appeler des comportements spécifiques :

Hiérarchiser les nouveaux documents

La propriété cache inclut un paramètre enableReprocessing qui contrôle si le contenu mis en cache est retraité. Lorsque la valeur est true (valeur par défaut), l’indexeur retraite les documents mis en cache lorsque vous le réexécutez si une mise à jour de compétence les affecte.

Lorsque la valeur est false, l’indexeur ne retraite pas les documents existants, ce qui hiérarchise le nouveau contenu. Définissez enableReprocessing la valeur false uniquement temporairement. Assurer la fidélité la plupart du temps garantit que les documents nouveaux et existants restent valides par rapport à la définition actuelle de l’ensemble de compétences.

Ignorer l'évaluation des compétences

La modification d’une compétence va généralement de pair avec le retraitement de cette compétence. Toutefois, certaines modifications apportées à une compétence ne doivent pas déclencher le retraitement. Par exemple, le déploiement d’une compétence personnalisée vers un nouvel emplacement ou avec une nouvelle clé d’accès. Ces modifications sont généralement des modifications périphériques qui n’affectent pas la substance de la sortie des compétences.

Si vous savez qu’une modification de la compétence est superficielle, remplacez l’évaluation des compétences en définissant le disableCacheReprocessingChangeDetection paramètre sur true :

  1. Appelez Mettre à jour l’ensemble de compétences et modifiez la définition de l’ensemble de compétences.
  2. Ajoutez le disableCacheReprocessingChangeDetection=true paramètre à la demande.
  3. Envoyez la modification.

Lorsque vous définissez ce paramètre, seules les mises à jour de la définition de l’ensemble de compétences sont validées. La modification n’est pas évaluée pour les effets sur le cache existant. Utilisez une version préliminaire de l’API, 2020-06-30-Preview ou version ultérieure. Utilisez la dernière API en préversion.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection

Ignorer les vérifications de validation de la source de données

La plupart des modifications apportées à une définition de source de données invalident le cache. Toutefois, pour les scénarios où vous savez qu'une modification ne doit pas invalider le cache, par exemple modifier un chaîne de connexion ou faire pivoter la clé sur le compte de stockage, ajoutez le paramètre ignoreResetRequirement sur la mise à jour de source data source. Définissez ce paramètre sur true pour permettre à la validation de passer en revue, sans déclencher une condition de réinitialisation qui entraînerait la reconstruction et le remplissage de tous les objets à partir de zéro.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

Forcer l’évaluation des compétences

L’objectif du cache est d’éviter le traitement inutile. Toutefois, supposons que vous apportez une modification à une compétence que l’indexeur ne détecte pas (par exemple, en modifiant un élément dans du code externe, tel qu’une compétence personnalisée).

Dans ce cas, utilisez l’API Réinitialiser les compétences pour forcer le retraitement d’une compétence particulière, y compris les compétences en aval qui ont une dépendance sur la sortie de cette compétence. Cette API accepte une requête POST avec une liste de compétences qui doivent être invalidées et marquées pour le retraitement. Après la réinitialisation des compétences, effectuez une requête Run Indexer pour appeler le traitement du pipeline.

Rafraîchir le cache de documents spécifiques

Si vous réinitialisez un indexeur, tous les documents du corpus de recherche sont retratés.

Dans les scénarios où seuls quelques documents ont besoin de retraitement, utilisez Réinitialiser les documents (préversion) pour forcer le retraitement de documents spécifiques. Lorsque vous réinitialisez un document, l’indexeur invalide le cache de ce document. L’indexeur retraite ensuite le document en le lisant à partir de la source de données. Pour plus d’informations, consultez Exécuter ou réinitialiser des indexeurs, des compétences et des documents.

Pour réinitialiser des documents spécifiques, incluez dans la requête une liste des clés des documents telles qu’elles sont lues à partir de l’index de recherche. Si la clé est mappée à un champ dans la source de données externe, utilisez la valeur de l’index de recherche.

Selon la façon dont vous appelez l’API, la requête ajoute, remplace ou met en file d’attente la liste des clés :

  • L’appel de l’API plusieurs fois avec différentes clés ajoute les nouvelles clés à la liste des clés de document à réinitialiser.

  • Si vous appelez l’API avec le paramètre de chaîne de requête overwrite défini sur true, la liste actuelle des clés de document à réinitialiser est remplacée par la charge utile de la demande.

  • L’appel de l’API ajoute les clés de document à la file d’attente du travail que l’indexeur effectue. Lorsque l’indexeur est appelé ensuite, comme planifié ou à la demande, il hiérarchise le traitement des clés de document de réinitialisation avant toute autre modification de la source de données.

L’exemple suivant illustre une demande de document de réinitialisation :

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Modifications qui invalident le cache

Lorsque vous activez un cache, l’indexeur vérifie les modifications apportées à la composition de votre pipeline pour déterminer le contenu qu’il peut réutiliser et le contenu qui a besoin de retraitement. Cette section répertorie les modifications qui invalident le cache, puis les modifications qui déclenchent le traitement incrémentiel.

Une modification invalidante est une modification où l’intégralité du cache devient non valide. Par exemple, la mise à jour de votre source de données est une modification invalidante. Voici la liste complète des modifications apportées à n’importe quelle partie du pipeline d’indexeur qui invalide votre cache :

  • Modification du type de source de données
  • Modification du conteneur de source de données
  • Modification des informations d’identification de la source de données
  • Modification de la stratégie de détection des modifications de source de données
  • Changement de la politique de détection des suppressions de source de données
  • Modification des mappages de champs de l’indexeur
  • Modification des paramètres d’indexeur :
    • Mode d’analyse
    • Extensions de nom de fichier exclues
    • Extensions de nom de fichier indexées
    • Indexer les métadonnées de stockage uniquement pour les documents surdimensionnés
    • En-têtes de texte délimités
    • Délimiteur de texte délimité
    • Racine du document
    • Action d’image (modifications apportées à l’extraction des images)

Modifications qui déclenchent un traitement incrémentiel

Le traitement incrémentiel évalue votre définition d’ensemble de compétences et détermine les compétences à réexécuter. Il met à jour sélectivement les parties affectées de l’arborescence de documents. Voici la liste complète des modifications qui entraînent l’enrichissement incrémentiel :

  • Modification du type de compétence (mise à jour du type OData de la compétence)
  • Mise à jour des paramètres spécifiques aux compétences, tels qu’une URL, des valeurs par défaut ou d’autres paramètres
  • Modification des sorties de compétence, par exemple lorsque la compétence retourne des sorties supplémentaires ou différentes
  • Modification des paramètres de compétence entraînant une ascendance ou un enchaînement de compétences différent
  • Invalidation de toute compétence en amont, si vous mettez à jour une compétence qui sert d’entrée à cette compétence
  • Mise à jour de l’emplacement de projection de la base de connaissances, ce qui entraîne la re-projection de documents
  • Modification des projections de la base de connaissances, ce qui entraîne la re-projection de documents
  • Modification des mappages de champs de sortie sur un indexeur, ce qui entraîne la re-projection de documents vers l’index

API utilisées pour la mise en cache

Les API en préversion fournissent des propriétés supplémentaires sur les indexeurs. Utilisez la dernière API en préversion.

Utilisez la version généralement disponible pour les ensembles de compétences et les sources de données. En plus de la documentation de référence, consultez Configurer la mise en cache pour l’enrichissement incrémentiel pour plus d’informations sur l’ordre des opérations.

  • Last updated on