Activation de la mise en cache pour l’enrichissement incrémentiel dans Recherche Azure AI

Article
03/10/2024

Important

Cette fonctionnalité est en préversion publique sous les conditions d’utilisation supplémentaires. L’API REST en préversion prend en charge cette fonctionnalité.

Cet article explique comment ajouter la mise en cache à un pipeline d’enrichissement afin de pouvoir modifier les étapes d’enrichissement en aval sans avoir à effectuer une régénération complète à chaque fois. Par défaut, un ensemble de compétences n'a pas d'état, et toute modification de sa composition nécessite une réexécution complète de l'indexeur. Avec un cache d’enrichissement, l’indexeur peut déterminer les parties de l’arborescence de documents qui doivent être actualisées en fonction des modifications détectées dans les définitions de l’indexeur ou de l’ensemble de compétences. La sortie traitée existante est conservée et réutilisée dans la mesure du possible.

Le contenu mis en cache est placé dans le stockage Azure à l’aide des informations de compte que vous fournissez. Le conteneur, nommé ms-az-search-indexercache-<alpha-numerc-string>, est créé lors de l’exécution de l’indexeur. Il doit être considéré comme un composant interne géré par votre service de recherche et ne doit pas être modifié.

Prérequis

Stockage Azure pour stocker des enrichissements mis en cache. Le compte de stockage doit être de type v2 à usage général.
Pour l’indexation d’objets blob uniquement, si vous avez besoin d’une suppression de document synchronisé à partir du cache et de l’index quand des objets blob sont supprimés de votre source de données, activez une stratégie de suppression dans l’indexeur. Sans cette stratégie, la suppression de document à partir du cache n’est pas prise en charge.

Vous devez connaître la configuration d’indexeurs. Commencez par la présentation de l'indexeur, puis passez aux ensembles de compétences pour découvrir plus d’informations sur les pipelines d’enrichissement. Pour plus d’informations sur les concepts clés, consultez Enrichissement incrémentiel.

Attention

Si vous utilisez l’indexeur SharePoint Online (préversion), vous devez éviter l’enrichissement incrémentiel. Dans certaines circonstances, le cache devient non valide, ce qui exige une réinitialisation et exécution de l’indexeur, si vous choisissez de le recharger.

Activer sur de nouveaux indexeurs

Vous pouvez utiliser le Portail Azure, les API en préversion ou les Kits de développement logiciel (SDK) Azure bêta qui sont requis pour activer un cache d’enrichissement sur un indexeur.

Azure portal
REST

Sur la gauche, sélectionnez Indexeurs, puis Ajouter un indexeur.
Fournissez un nom d’indexeur et un index, une source de données et un ensemble de compétences existants.
Activez la mise en cache incrémentielle et définissez le compte Stockage Azure.

Sur les nouveaux indexeurs, ajoutez la propriété « cache » dans la charge utile de la définition de l’indexeur lors de l’appel de l’indexeur Créer ou Mettre à jour (2021-04-30-Preview). Vous pouvez également utiliser la préversion d’API précédente, 2020-06-30-Preview.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

Activer sur des indexeurs existants

Pour les indexeurs existants qui possèdent déjà un ensemble de compétences, procédez comme suit pour ajouter la mise en cache. Dans le cadre d’une opération unique, réinitialisez et réexécutez l’indexeur entièrement pour charger le cache.

Étape 1 : Obtenir la définition de l’indexeur

Démarrez par un indexeur de travail qui contient les composants suivants : source de données, ensemble de compétences, index. À l’aide d’un client d’API, envoyez une requête GET Indexer pour récupérer l’indexeur. Lorsque vous utilisez la préversion de l’API pour faire une requête GET sur l’indexeur, une propriété « cache » définie sur Null est ajoutée automatiquement aux définitions.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Étape 2 : Définir la propriété cache

Dans la définition de l’index, modifiez « cache » de façon à inclure les propriétés obligatoires et facultatives suivantes :

(Obligatoire) storageConnectionString doit être défini sur une chaîne de connexion Stockage Azure.
(Facultatif) La propriété booléenne enableReprocessing (true par défaut) indique que l’enrichissement incrémentiel est activé. Définissez-la sur false si vous souhaitez interrompre le traitement incrémentiel pendant que d’autres opérations gourmandes en ressources, telles que l’indexation de nouveaux documents, sont en cours d’exécution, puis la revenir à true plus tard.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Étape 3 : Réinitialiser l’indexeur

Réinitialiser l’indexeur est nécessaire lors de la configuration de l’enrichissement incrémentiel pour que les indexeurs existants puissent garantir que tous les documents sont dans un état cohérent. Vous pouvez utiliser le portail ou un client d’API pour cette tâche.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Étape 4 : Enregistrer l’indexeur

Indexeur Mettre à jour (2021-04-30-Preview) avec une requête PUT, où le corps de la requête comprend « cache ».

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

Si vous émettez maintenant une autre requête GET sur l’indexeur, la réponse du service inclut une propriété ID dans l’objet cache. La chaîne alphanumérique est ajoutée au nom du conteneur contenant tous les résultats mis en cache et l’état intermédiaire de chaque document traité par cet indexeur. L’ID est utilisé pour nommer le cache de manière unique dans Stockage Blob.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

Étape 5 : Exécuter l’indexeur

Pour exécuter l’indexeur, vous pouvez utiliser le portail ou l’API. Dans le portail, à partir de la liste des indexeurs, sélectionnez l’indexeur, puis Exécuter. L’un des avantages à utiliser le portail est que vous pouvez surveiller l’état de l’indexeur, noter la durée du travail et connaître le nombre de documents traités. Les pages du portail sont actualisées à des intervalles de quelques minutes.

Vous pouvez également utiliser REST pour exécuter l’indexeur :

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Remarque

Une réinitialisation et une réexécution de l’indexeur entraînent une régénération complète afin que le contenu puisse être mis en cache. Tous les enrichissements cognitifs sont réexécutés sur tous les documents. La réutilisation du contenu enrichi à partir du cache commence après le chargement du cache.

Rechercher la sortie mise en cache

Recherchez le cache dans Stockage Azure, sous le conteneur blob. ms-az-search-indexercache-<some-alphanumeric-string> est le nom du conteneur.

Un cache est créé et utilisé par un indexeur. Son contenu n’est pas lisible par l’utilisateur.

Pour vérifier si le cache est opérationnel, modifiez un ensemble de compétences et exécutez l’indexeur, puis comparez les métriques avant et après pour le nombre de documents et le temps d’exécution.

Les ensemble de compétences qui incluent l’analyse d’images et la reconnaissance optique de caractères (OCR) des documents numérisés constituent de bons scénarios de test. Si vous modifiez une compétence de texte en aval ou toute compétence qui n’est pas liée à une image, l’indexeur peut récupérer tout le contenu des images et de l’OCR traités précédemment à partir du cache, mettre à jour et traiter uniquement les modifications relatives au texte indiquées par vos modifications. Vous pouvez vous attendre à voir moins de documents dans le nombre de documents d’exécution d’indexeur, des durées d’exécution plus courtes et moins de frais sur votre facture.

L’ensemble de fichiers utilisé dans les didacticiels cog-search-demo est un cas de test utile, car il contient 14 fichiers de différents formats JPG, PNG, HTML, DOCX, PPTX et d’autres types. Changez en en es ou en une autre langue dans la compétence de traduction de texte pour les tests de preuve de concept de l’enrichissement incrémentiel.

Erreurs courantes

L’erreur suivante se produit si vous oubliez de spécifier une préversion de l’API dans la requête :

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

Une erreur 400 Demande incorrecte se produit également si une exigence d’indexeur est manquante. Le message d’erreur spécifie toutes les dépendances manquantes.

Étapes suivantes

L’enrichissement incrémentiel s’applique aux indexeurs qui contiennent des ensembles de compétences, ce qui fournit du contenu réutilisable pour les index et les bases de connaissances. Pour plus d’informations sur la mise en cache et les ensembles de compétences, consultez les liens suivants.