Créer un index dans Recherche Azure AI
Dans cet article, découvrez les étapes de définition d’un schéma pour un index de recherche et l’envoyer (push) vers un service de recherche. La création d’un index établit la structure de données physiques sur votre service de recherche. Une fois l’index créé, l’étape suivante consiste à charger l’index.
Prérequis
Écrivez des autorisations en tant que contributeur de service de recherche ou une clé API d’administration pour l’authentification basée sur des clés.
Connaissance des données que vous souhaitez indexer. Un index de recherche est basé sur du contenu externe que vous souhaitez rendre consultable. Le contenu pouvant faire l’objet d’une recherche est stocké sous forme de champs dans un index. Vous devriez avoir une idée claire des champs sources pouvant être consultés, récupérés, filtrés, à choix multiples et triés. Consultez la liste de contrôle du schéma pour obtenir de l’aide.
Vous devez avoir un champ unique dans les données sources qui peut être utilisé comme clé (ou ID) de document dans l’index.
Un emplacement d’index stable. Le déplacement d’un index existant vers un autre service de recherche n’est pas pris en charge instantanément. Consultez à nouveau les spécifications de l’application et vérifiez que votre service de recherche existant (capacité et emplacement) sont suffisants pour répondre à vos besoins.
Enfin, tous les niveaux de service ont des limites d’index sur le nombre d’objets que vous pouvez créer. Par exemple, si vous expérimentez le niveau Gratuit, vous ne pouvez avoir que trois index à la fois. Dans l’index même, il existe des limites sur les vecteurs et des limites d’index sur le nombre de champs simples et complexes.
Clés de document
Un index de recherche a deux exigences : il doit avoir un nom et une clé de document.
Une clé de document est l’identificateur unique d’un document de recherche et un document de recherche est une collection de champs qui décrivent complètement quelque chose. Par exemple, si vous indexez un jeu de données de films, un document de recherche contient le titre, le genre et la durée d’un seul film.
Dans la Recherche Azure AI, une clé de document doit être une chaîne provenant de valeurs uniques dans la source de données qui fournit le contenu à indexer. Un service de recherche ne génère pas de valeurs de clé. Toutefois, dans certains scénarios (comme l’indexeur de tables Azure), il synthétise des valeurs existantes afin de créer une clé unique pour les documents indexés.
Durant l’indexation incrémentielle, où les contenus nouveaux et mis à jour sont indexés, les documents entrants avec de nouvelles clés sont ajoutés, tandis que les documents entrants avec des clés existantes sont fusionnés ou remplacés, selon que les champs d’index sont Null ou remplis.
Check-list du schéma
Utilisez cette check-list pour vous aider à prendre les décisions de conception concernant votre index de recherche.
Examinez les conventions d’affectation de noms afin que les noms d’index et de champs soient conformes aux règles d’affectation de noms.
Consultez les types de données pris en charge. Le type de données affecte la façon dont le champ est utilisé. Par exemple, le contenu numérique peut être filtré, mais ne peut pas faire l’objet d’une recherche en texte intégral. Le type de données le plus courant est
Edm.Stringpour le texte pouvant faire l’objet d’une recherche, qui est mis en jeton et interrogé à l’aide du moteur de recherche en texte intégral. Le type de données le plus courant pour un champ vectoriel estEdm.Single, mais vous pouvez également utiliser d’autres types.Identifiez une clé de document. Une clé de document est une condition requise pour les index. Il s’agit d’un seul champ de chaîne renseigné à partir d’un champ de données sources qui contient des valeurs uniques. Par exemple, si vous indexez à partir de Stockage Blob, le chemin de stockage des métadonnées est souvent utilisé comme clé de document parce qu’il identifie de manière unique chaque objet blob dans le conteneur.
Identifiez les champs dans votre source de données qui contribuent au contenu pouvant faire l’objet d’une recherche dans l’index.
Le contenu non vectoriel pouvant faire l’objet d’une recherche comprend des chaînes courtes ou longues qui sont interrogées à l’aide du moteur de recherche en texte intégral. Si le contenu est détaillé (petites phrases ou plus grands morceaux), expérimentez des analyseurs différents pour voir comment le texte est tokénisé.
Le contenu vectoriel pouvant faire l’objet d’une recherche peut être des images ou du texte (dans n’importe quelle langue) qui existe sous forme de représentation mathématique. Vous pouvez utiliser des types de données étroits ou une compression vectorielle pour réduire les champs vectoriels.
Les affectations d’attribut de champ déterminent les comportements de recherche et la représentation physique de votre index sur le service de recherche. Déterminer la façon dont les champs doivent être spécifiés est un processus itératif pour de nombreux clients. Pour accélérer les itérations, commencez par des échantillons de données afin de pouvoir les supprimer et les reconstruire facilement.
Identifiez les champs sources qui peuvent être utilisés comme filtres. Le contenu numérique et les champs de texte courts, en particulier ceux qui ont des valeurs répétées, constituent de bons choix. Lorsque vous utilisez des filtres, n’oubliez pas :
Les filtres peuvent être utilisés dans les requêtes vectorielles et non vectorielles, mais le filtre lui-même est appliqué aux champs alphanumériques (non vectoriels) de votre index.
Les champs filtrables peuvent éventuellement être utilisés dans la navigation à facettes.
Les champs filtrables sont retournés dans un ordre arbitraire, donc pensez à les rendre également triables.
Pour les champs vectoriels, spécifiez une configuration de recherche vectorielle et les algorithmes utilisés pour créer des chemins de navigation et remplir l’espace d’incorporation. Pour plus d'informations, consultez Ajouter des champs vectoriels.
Les champs vectoriels ont des propriétés supplémentaires que les champs non vectoriels n’ont pas, comme les algorithmes à utiliser et la compression vectorielle.
Les champs vectoriels omettent les attributs qui ne sont pas utiles sur les données vectorielles, telles que le tri, le filtrage et la navigation à facettes.
Pour les champs non vectoriels, déterminez s’il faut utiliser l’analyseur par défaut (
"analyzer": null) ou un autre analyseur. Les analyseurs sont utilisés pour tokeniser des champs de texte lors de l’indexation et de l’exécution des requêtes.Pour les chaînes multilingues, envisagez l’utilisation d’un analyseur de langue.
Pour les chaînes avec trait d’union ou les caractères spéciaux, réfléchissez à l’utilisation d’analyseurs spécialisés. Un analyseur mot clé traite par exemple tout le contenu d’un champ comme un jeton unique. Ce comportement est utile pour les données comme les codes postaux, les ID et certains noms de produit. Pour plus d’informations, consultez Recherche de termes partiels et modèles avec des caractères spéciaux.
Remarque
La recherche en texte intégral est effectuée sur les termes qui sont tokenisés pendant l’indexation. Si vos requêtes ne retournent pas les résultats attendus, testez la segmentation du texte en unités lexicales pour vérifier que la chaîne recherchée existe réellement. Vous pouvez essayer différents analyseurs sur des chaînes pour voir comment les jetons sont générés pour différents analyseurs.
Création d'un index
Quand vous êtes prêt à créer l’index, utilisez un client de recherche qui peut envoyer la demande. Vous pouvez utiliser le Portail Azure ou des API REST pour les premières étapes de développement et les tests de preuve de concept. Sinon, vous pouvez utiliser les Kits de développement logiciel (SDK) Azure.
Pendant le développement, prévoyez des régénérations fréquentes. Comme les structures physiques sont créées dans le service, il est nécessaire de supprimer et de recréer les index pour la plupart des modifications. Vous pouvez envisager de travailler sur une partie de vos données pour regénérer plus rapidement.
La conception d’index via le portail applique des exigences et des règles de schéma pour des types de données spécifiques, telles que l’interdiction de la recherche en texte intégral sur les champs numériques.
Connectez-vous au portail Azure.
Vérifiez l’espace disponible. Les services de recherche sont soumis à nombre maximal d’index qui varie par niveau de service. Vérifiez que vous avez de la place pour un deuxième index.
Dans la page Vue d’ensemble du service de recherche, choisissez l’une des options proposées pour créer un index de recherche :
- Ajouter un index (éditeur incorporé pour la spécification d’un schéma d’index)
- Assistants d’importation
L’Assistant est un workflow de bout en bout qui crée un indexeur, une source de données et un index terminé. Il charge également les données. Si ce n’est pas ce que vous voulez, utilisez plutôt l’option Ajouter un index.
La capture d’écran suivante met en évidence l’emplacement où s’affichent les options Ajouter un index, Importer des données et Importer et vectoriser des données dans la barre de commandes.
Une fois l’index créé, vous le retrouverez dans la page des index à partir du volet de navigation gauche.
Conseil
Après avoir créé un index dans le portail, vous pouvez copier la représentation JSON et l’ajouter au code de votre application.
Définir corsOptions pour les requêtes Cross-Origin
Les schémas d’index incluent une section pour la définition de corsOptions. Par défaut, le code JavaScript côté client ne peut pas appeler d’API, car les navigateurs empêchent toutes les requêtes cross-origin. Pour autoriser les requêtes cross-origin à parvenir à votre index, activez CORS (Cross-Origin Resource Sharing) en définissant l’attribut corsOptions. Pour des raisons de sécurité, seules les API de requête prennent en charge CORS.
"corsOptions": {
"allowedOrigins": [
"*"
],
"maxAgeInSeconds": 300
Les propriétés suivantes peuvent être définies pour CORS :
allowedOrigins (obligatoire) : il s’agit d’une liste d’origines autorisées à accéder à votre index. Le code JavaScript servi à partir de ces origines est autorisé à interroger votre index (en supposant que l’appelant fournit une clé valide ou dispose d’autorisations). Chaque origine se présente généralement sous la forme
protocol://<fully-qualified-domain-name>:<port>, bien que<port>soit souvent omis. Pour plus d’informations, consultez la page Cross-origin resource sharing (Wikipedia).Si vous voulez autoriser l'accès à toutes les origines, incluez uniquement l’élément
*dans le tableau allowedOrigins. Si cette pratique est déconseillée pour les services de recherche de production, elle est souvent utile pour le développement et le débogage.maxAgeInSeconds (facultatif) : les navigateurs utilisent cette valeur pour déterminer la durée (en secondes) de mise en cache des réponses CORS préliminaires. Il doit s'agir d'un entier non négatif. Une période de mise en cache plus longue offre de meilleures performances, mais elle étend la durée nécessaire pour qu’une stratégie CORS prenne effet. Si cette valeur n’est pas définie, une durée par défaut de cinq minutes est utilisée.
Mises à jour autorisées sur des index existants
Créer un index crée des structures de données physiques (fichiers et index inversés) sur votre service de recherche. Une fois l’index créé, votre capacité à effectuer des modifications à l’aide de Créer ou mettre à jour un index dépend du fait que vos modifications invalident ou non ces structures physiques. La plupart des attributs de champ ne peuvent pas être modifiés une fois que le champ est créé dans votre index.
Vous pouvez également créer un alias d’index qui sert de référence stable dans votre code d’application. Au lieu de mettre à jour votre code, vous pouvez mettre à jour un alias d’index pour qu’il pointe vers des versions d’index plus récentes.
Pour réduire l’attrition dans le processus de conception, le tableau suivant décrit les éléments fixes et flexibles dans le schéma. La modification d’un élément fixe nécessite la reconstruction de l’index, alors que les éléments flexibles peuvent être modifiés à tout moment sans impacter l’implémentation physique.
| Élément | Possibilité de mise à jour ? |
|---|---|
| Nom | Non |
| Clé | Non |
| Noms et types de champs | Non |
| Attributs de champ (consultable, filtrable, à choix multiples, triable) | Non |
| Attribut de champ (récupérable) | Oui |
| Stocké (s’applique aux vecteurs) | Non |
| Analyseur | Vous pouvez ajouter et modifier des analyseurs personnalisés dans l’index. En ce qui concerne les affectations de l’analyseur aux champs de chaîne, vous pouvez uniquement modifier searchAnalyzer. Toutes les autres affectations et modifications requièrent une reconstruction. |
| Profils de score | Oui |
| Générateurs de suggestions | Non |
| Partage des ressources cross-origin (CORS) | Oui |
| Chiffrement | Oui |
Étapes suivantes
Utilisez les liens suivants pour vous familiariser avec le chargement d’un index avec des données ou étendre un index avec un mappage de synonymes.