Créer un indexeur dans Recherche Azure AI

  • Article

Utilisez un indexeur pour automatiser l’importation et l’indexation des données dans Recherche Azure AI. Un indexeur est un objet nommé sur un service de recherche qui se connecte à une source de données Azure externe, lit les données et les transmet à un moteur de recherche pour l’indexation. L’utilisation d’indexeurs réduit considérablement la quantité et la complexité du code que vous devez écrire si vous utilisez une source de données prise en charge.

Les indexeurs prennent en charge deux flux de travail :

  • Indexation textuelle, extraction de chaînes et de métadonnées à partir de contenu textuel pour les scénarios de recherche en texte intégral.

  • Indexation basée sur les compétences, à l’aide de compétences intégrées ou personnalisées qui ajoutent le Machine Learning intégré pour l’analyse sur les images et le contenu non différencié volumineux, l’extraction ou l’inférence du texte et de la structure. L’indexation basée sur les compétences permet de rechercher du contenu qui n’est pas facilement accessible en texte intégral. Pour en savoir plus, consultez Enrichissement par IA dans Recherche Azure AI.

Cet article se concentre sur les étapes de base de la création d’un indexeur. En fonction de la source de données et de votre flux de travail, une configuration supplémentaire peut être nécessaire.

Prérequis

  • Une source de données prise en charge qui contient le contenu que vous souhaitez ingérer

  • Une source de données d’indexeur qui configure une connexion à des données externes

  • Un index de recherche pouvant accepter des données entrantes

  • Restez dans les limites maximales de votre niveau de service. Le niveau Gratuit autorise trois objets de chaque type et entre une et trois minutes de traitement de l’indexeur (ou entre trois et dix minutes en présence d’un ensemble de compétences).

Modèles d’indexeur

Lors de la création d’un indexeur, la définition est l’un des deux modèles suivants : indexation textuelle ou enrichissement par IA avec des compétences. Les modèles sont les mêmes, sauf que l’indexation basée sur les compétences a davantage de définitions.

Exemple d’indexeur pour l’indexation basée sur le texte

L’indexation basée sur le texte pour la recherche en texte intégral est le cas d’usage principal pour les indexeurs, et pour ce workflow, un indexeur ressemble à cet exemple.

{
  "name": (required) String that uniquely identifies the indexer,
  "description": (optional),
  "dataSourceName": (required) String indicating which existing data source to use,
  "targetIndexName": (required) String indicating which existing index to use,
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "base64EncodeKeys": false,
    "configuration": {}
  },
  "fieldMappings": (optional) unless field discrepancies need resolution,
  "disabled": null,
  "schedule": null,
  "encryptionKey": null
}

Les indexeurs doivent répondre aux exigences suivantes :

  • Une propriété "name" qui identifie de façon unique l’indexeur dans la collection d’indexeurs
  • Une propriété "dataSourceName" qui pointe vers un objet source de données Il spécifie une connexion à des données externes.
  • Une propriété "targetIndexName" qui pointe vers l’index de recherche de destination

Les autres paramètres sont facultatifs et modifient les comportements d’exécution, par exemple le nombre d’erreurs acceptables avant l’échec de l’ensemble du travail. Les paramètres requis sont spécifiés dans tous les indexeurs et sont documentés dans les informations de référence sur l’API REST.

Les indexeurs de données propres à la source pour les objets blob, SQL et Azure Cosmos DB fournissent des paramètres "configuration" supplémentaires pour les comportements propres à la source. Par exemple, si la source est le Stockage Blob, vous pouvez définir un paramètre qui filtre selon les extensions de fichier : "parameters" : { "configuration" : { "indexedFileNameExtensions" : ".pdf,.docx" } }. Si la source est Azure SQL, vous pouvez définir un paramètre de délai d’expiration de requête.

Les mappages de champs sont utilisés pour mapper explicitement des champs source à destination s’il existe des différences par nom ou type entre un champ dans la source de données et un champ dans l’index de recherche.

Par défaut, un indexeur s’exécute immédiatement lorsque vous le créez sur le service de recherche. Si vous ne souhaitez pas l’exécution de l’indexeur, définissez "disabled" sur true lors de la création de l’indexeur.

Vous pouvez également spécifier une planification ou définir une clé de chiffrement pour effectuer un chiffrement supplémentaire de la définition de l’indexeur.

Exemple d’indexeur pour l’indexation basée sur les compétences

Les indexeurs permettent également enrichissement IA. Toutes les propriétés et tous les paramètres ci-dessus s’appliquent, mais les propriétés supplémentaires suivantes sont propres à l’enrichissement par IA : "skillSetName", "cache" et "outputFieldMappings".

{
  "name": (required) String that uniquely identifies the indexer,
  "dataSourceName": (required) String, provides raw content that will be enriched,
  "targetIndexName": (required) String, name of an existing index,
  "skillsetName" : (required for AI enrichment) String, name of an existing skillset,
  "cache":  {
    "storageConnectionString" : (required if you enable the cache) Connection string to a blob container,
    "enableReprocessing": true
    },
  "parameters": { },
  "fieldMappings": (optional) Maps fields in the underlying data source to fields in an index,
  "outputFieldMappings" : (required) Maps skill outputs to fields in an index,
}

L’enrichissement par IA est son propre sujet et est hors de portée pour cet article. Pour plus d’informations, commencez par Enrichissement par IA, Ensemble de compétences dans Recherche Azure AI, Créer un ensemble de compétences, Mapper les champs de sortie d’enrichissement et Activer la mise en cache pour l’enrichissement par IA.

Préparer les données externes

Les indexeurs fonctionnent avec des jeux de données. Lorsque vous exécutez un indexeur, il se connecte à votre source de données, récupère les données du conteneur ou du dossier et, éventuellement, les sérialise au format JSON avant de les transmettre au moteur de recherche pour l’indexation. Cette section décrit les exigences relatives aux données entrantes pour l’indexation textuelle.

Données sources Tâches
Documents JSON Assurez-vous que la structure ou la forme des données entrantes correspond au schéma de votre index de recherche. La plupart des index de recherche sont assez plats, la collection de champs étant constituée de champs de même niveau. Toutefois, les structures hiérarchiques ou imbriquées sont possibles par le biais de champs et de collections complexes.
Relationnel Fournissez-les sous la forme d’un ensemble de lignes aplati, où chaque ligne devient un document de recherche complet ou partiel dans l’index.

Pour aplatir les données relationnelles dans un ensemble de lignes, vous devez créer une vue SQL ou créer une requête qui retourne des enregistrements parents et enfants dans la même ligne. Par exemple, l’exemple de jeu de données d’hôtels intégré est une base de données SQL qui comporte 50 enregistrements (un pour chaque hôtel), liés aux enregistrements des chambres dans une table connexe. La requête qui aplatit les données collectives dans un ensemble de lignes intègre toutes les informations relatives aux chambres dans les documents JSON de chaque enregistrement d’hôtel. Les informations de chambre intégrées sont générées par une requête qui utilise une clause FOR JSON AUTO.

Vous pouvez en savoir plus sur cette technique dans Définir une requête qui retourne une collection JSON incorporée. Il ne s’agit là que d’un exemple ; vous pouvez trouver d’autres approches qui produisent le même résultat.
Fichiers Un indexeur crée généralement, pour chaque fichier, un document de recherche constitué de champs pour le contenu et les métadonnées. Selon le type de fichier, l’indexeur peut parfois analyser un fichier en plusieurs documents de recherche. Par exemple, dans un fichier CSV, chaque ligne peut devenir un document de recherche autonome.

N’oubliez pas que vous n’avez besoin que d’extraire des données filtrables et pouvant faire l’objet d’une recherche :

  • Les données cherchables correspondent à du texte.
  • Les données filtrables sont alphanumériques.

Recherche Azure AI ne peut pas effectuer de recherche sur des données binaires dans n’importe quel format, bien que le service puisse extraire et déduire des descriptions de texte de fichiers image (voir Enrichissement par IA) pour créer du contenu pouvant faire l’objet d’une recherche. De même, il est possible de décomposer et d’analyser de grands textes avec des modèles de langage naturel pour trouver la structure ou les informations pertinentes. Ce processus génère un nouveau contenu que vous pouvez ajouter à un document de recherche.

Étant donné que les indexeurs ne corrigent pas les problèmes de données, d’autres formes de nettoyage ou de manipulation des données peuvent être nécessaires. Pour plus d’informations, reportez-vous à la documentation de votre produit de base de données Azure.

Préparer une source de données

Les indexeurs requièrent une source de données qui spécifie le type, le conteneur et la connexion.

  1. Vérifiez que vous utilisez un type de source de données pris en charge.

  2. Créez une définition de source de données. La liste suivante répertorie quelques-unes des sources de données les plus fréquemment utilisées :

  3. Si la source de données est une base de données, telle que Azure SQL ou Cosmos DB, activez le suivi des modifications. Stockage Azure dispose d’un suivi des modifications intégré via la propriété LastModified sur chaque objet blob, fichier et table. Les liens ci-dessus pour les différentes sources de données expliquent quelles méthodes de suivi des modifications sont prises en charge par les indexeurs.

Préparation d’un index

Les indexeurs requièrent également un index de recherche. Rappelons que les indexeurs transmettent les données au moteur de recherche pour indexation. Tout comme les indexeurs ont des propriétés qui déterminent le comportement d’exécution, un schéma d’indexation a des propriétés qui influencent profondément la façon dont les chaînes sont indexées (seules les chaînes sont analysées et transformées en jeton).

  1. Commencez par créer un index de recherche.

  2. Configurez la collection de champs et les attributs des champs.

    Les champs sont les seuls récepteurs de contenu externe. En fonction de la façon dont les champs sont attribués dans le schéma, la valeur de chacun d’eux est analysée, tokenisée ou stockée sous forme de chaîne verbatim pour les filtres, la recherche approximative et les requêtes TypeAhead.

    Les indexeurs peuvent automatiquement faire correspondre les champs source aux champs d’index cible lorsque les noms et les types sont équivalents. Si un champ ne peut pas être mappé implicitement, n’oubliez pas que vous pouvez définir un mappage de champs explicite qui indique à l’indexeur comment acheminer le contenu.

  3. Examinez les affectations de l’analyseur sur chaque champ. Les analyseurs peuvent transformer des chaînes. Ainsi, les chaînes indexées peuvent être différentes de celles que vous avez transmises. Vous pouvez évaluer les effets des analyseurs à l’aide d’Analyser le texte (REST). Pour plus d’informations sur les analyseurs, consultez Analyseurs pour le traitement de texte.

Pendant l’indexation, un indexeur vérifie uniquement les noms et les types de champs. Il n’existe aucune étape de validation qui garantit que le contenu entrant est correct pour le champ de recherche correspondant dans l’index.

Créer un indexeur

Lorsque vous êtes prêt à créer un indexeur sur un service de recherche à distance, vous avez besoin d’un client de recherche. Un client de recherche peut être le portail Azure, un client REST ou un code qui instancie un client d’indexeur. Nous vous recommandons le portail Azure ou les API REST pour les premières étapes de développement et les tests de preuve de concept.

  1. Connectez-vous au portail Azure.

  2. Dans la page Vue d’ensemble du service de recherche, choisissez l’une des deux options suivantes :

    • Assistant Importation de données. L’Assistant est unique en ce sens qu’il crée tous les éléments requis. D’autres approches nécessitent une source de données et un index prédéfinis.

    • Nouvel indexeur, éditeur visuel pour spécifier une définition d’indexeur.

    La capture d’écran suivante montre où vous pouvez trouver ces fonctionnalités dans le portail.

    Indexeur des hôtels

Exécuter l’indexeur

Par défaut, un indexeur s’exécute immédiatement lorsque vous le créez sur le service de recherche. Vous pouvez remplacer ce comportement en affectant à "disabled" la valeur true dans la définition de l’indexeur. L’exécution de l’indexeur est le moment crucial où vous découvrez s’il existe des problèmes avec les connexions, les mappages de champs ou la construction d’ensembles de compétences.

Il existe plusieurs façons d’exécuter un indexeur :

  • Exécution à la création ou à la mise à jour de l’indexeur (valeur par défaut)

  • Exécution à la demande quand aucune modification n’est apportée à la définition, ou précédée d’une réinitialisation pour l’indexation complète. Pour plus d’informations, consultez Exécuter ou réinitialiser des indexeurs.

  • Planification du traitement de l’indexeur pour appeler l’exécution à intervalles réguliers

L’exécution planifiée est généralement implémentée lorsque vous avez besoin d’une indexation incrémentielle pour pouvoir récupérer les dernières modifications. En tant que telle, la planification est dépendante de la détection des modifications.

Les indexeurs sont l’un des rares sous-systèmes qui effectuent des appels sortants explicites vers d’autres ressources Azure. En termes de rôles Azure, les indexeurs n’ont pas d’identités distinctes : une connexion du moteur de recherche à une autre ressource Azure est effectuée à l’aide de l’identité managée affectée par le système ou affectée par l’utilisateur d’un service de recherche. Si l’indexeur se connecte à une ressource Azure sur un réseau virtuel, vous devez créer une liaison privée partagée pour cette connexion. Pour plus d’informations sur les connexions sécurisées, consultez Sécurité dans Recherche Azure AI.

Vérifier les résultats

Effectuez un monitoring de l’état de l’indexeur pour le connaître. Une exécution réussie peut quand même comporter des avertissements et des notifications. Veillez à vérifier les notifications d’état de réussite et d’échec pour plus d’informations sur le travail.

À titre de vérification du contenu, exécutez des requêtes sur l’index rempli pour renvoyer des documents entiers ou des champs sélectionnés.

Détection des modifications et état interne

Si votre source de données prend en charge la détection des modifications, un indexeur peut repérer les changements effectués dans les données sous-jacentes et ne traiter que les nouveaux documents et les documents mis à jour à chaque exécution de l’indexeur. Le contenu non modifié, lui, reste inchangé. Si l’historique d’exécutions de l’indexeur indique qu’une exécution a réussi avec 0/0 documents traités, cela signifie que l’indexeur n’a pas trouvé de lignes ni d’objets blob nouveaux ou modifiés dans la source de données sous-jacente.

La logique de détection des modifications est intégrée aux plateformes de données. La façon dont un indexeur prend en charge la détection des modifications varie selon la source de données :

Les indexeurs effectuent le suivi du dernier document qu’ils ont traité à partir de la source de données via un point d’eau élevé interne. Le marqueur n’est jamais exposé dans l’API, mais en interne, l’indexeur garde une trace de l’endroit où il s’est arrêté. Lorsque l’indexation reprend, par le biais d’une exécution planifiée ou d’un appel à la demande, l’indexeur fait référence à la limite supérieure afin de pouvoir reprendre là où il s’était arrêté.

Si vous devez effacer la limite supérieure pour réindexer entièrement, vous pouvez utiliser l’option Réinitialiser l’indexeur. Pour une réindexation plus sélective, utilisez Réinitialiser les compétences ou Réinitialiser les documents. Grâce aux API de réinitialisation, vous pouvez effacer l’état interne, ainsi que vider le cache si vous avez activé l’enrichissement incrémentiel. Pour plus d’informations et une comparaison de chaque option de réinitialisation, consultez Exécuter ou réinitialiser des indexeurs, des compétences et des documents.

Étapes suivantes