Ajouter l’autocomplétion et les suggestions de recherche aux applications clientes
La recherche en cours de frappe est une technique courante pour améliorer la productivité des requêtes. Dans Recherche Azure AI, cette expérience est prise en charge par l’autocomplétion qui termine un terme ou une expression en fonction d’une entrée partielle (en complétant « micro » par « microchip », « microscope », « microsoft » et toute autre correspondance). Les suggestions constituent une autre expérience utilisateur : il s’agit d’une liste succincte de documents correspondants (retournant des titres de livres avec un ID pour pouvoir lier vers une page d’informations sur ce livre). L’autocomplétion et les suggestions sont basées sur une correspondance dans l’index. Le service n’offre pas de requêtes ou de suggestions remplies automatiquement qui ne retournent aucun résultat.
Pour implémenter ces expériences dans Recherche Azure AI :
- Ajoutez un
suggesterau schéma de l’index. - Générez une requête qui appelle l’API Autocomplétion ou Suggestions sur la requête.
- Ajoutez un contrôle d’interface utilisateur pour gérer les interactions de type recherche en cours de frappe dans votre application cliente. Nous vous recommandons d’utiliser une bibliothèque JavaScript existante à cet effet.
Dans Recherche Azure AI, les requêtes remplies automatiquement et les résultats suggérés sont récupérés à partir de l’index de recherche, depuis des champs sélectionnés que vous avez enregistrés avec un suggesteur. Un suggesteur fait partie de l’index. Il spécifie les champs fournissant du contenu qui complète une requête et/ou suggère un résultat. Quand l’index est créé et chargé, une structure de données de suggesteur est créée en interne pour stocker les préfixes utilisés pour la correspondance sur des requêtes partielles. Pour les suggestions, le choix de champs appropriés qui sont uniques, ou au moins non répétitifs, est essentiel à l’expérience. Pour plus d’informations, consultez Créer un suggesteur.
Le reste de cet article se concentre sur les requêtes et le code client. Il utilise JavaScript et C# pour illustrer des points clés. Les exemples d’API REST sont utilisés pour présenter chaque opération de façon concise. Pour obtenir des exemples de code de bout en bout, consultez Étapes suivantes.
Configurer une demande
Les éléments d’une demande incluent l’une des API de recherche en cours de frappe, une requête partielle et un suggesteur. Le script suivant illustre les composants d’une demande, à l’aide de l’API REST d’autocomplétion.
POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2020-06-30
{
"search": "minecraf",
"suggesterName": "sg"
}
Le paramètre « suggesterName » vous donne les champs de type suggesteur utilisés pour compléter les termes ou les suggestions. Pour les suggestions en particulier, la liste de champs doit être composée de ceux qui offrent des choix clairs parmi les résultats de correspondance. Sur un site qui vend des jeux informatiques, le champ peut être le titre du jeu.
Le paramètre « search » fournit la requête partielle, où les caractères sont transmis à la demande de requête via le contrôle jQuery Autocomplete. Dans l’exemple ci-dessus, « minecraf » est une illustration statique de ce que le contrôle peut transmettre.
Les API n’imposent pas d’exigences de longueur minimale sur la requête partielle qui peut ne compter qu’un seul caractère. Toutefois, le contrôle Autocomplete de jQuery fournit une longueur minimale. Un minimum de deux ou trois caractères est normal.
Les correspondances se trouvent au début d’un terme n’importe où dans la chaîne d’entrée. Prenons comme exemple « the quick brown fox » : l’autocomplétion et les suggestions correspondent à des versions partielles de « the », « quick », « brown » ou « fox », mais pas à des termes partiels comme « rown » ou « ox ». En outre, chaque correspondance définit l’étendue des expansions en aval. Une requête partielle « quick br » est une correspondance de « quick Brown » ou « quick Bread », mais ni « brown » ni « bread » ne sont une correspondance, sauf précédé de « quick ».
API pour la recherche en cours de frappe
Cliquez sur les liens suivants pour accéder aux pages de référence des SDK REST et .NET :
Structurer une réponse
Les réponses pour l’autocomplétion et les suggestions sont ce que vous pouvez attendre pour le modèle : l’autocomplétion retourne une liste de termes et les suggestions retournent des termes plus un ID de document pour vous permettre de récupérer le document (utilisez l’API Document de recherche pour récupérer le document spécifique pour une page d’informations).
Les réponses sont mises en forme par les paramètres que vous incluez dans la demande :
Pour l'autocomplétion, définissez autocompleteMode afin de déterminer si la complétion du texte se produit sur un ou deux termes.
Pour les suggestions, définissez $select pour renvoyer des champs contenant des valeurs uniques ou de différenciation, telles que des noms et une description. Évitez les champs qui contiennent des valeurs en double (par exemple, une catégorie ou une ville).
Les paramètres suivants s’appliquent à la fois à l’autocomplétion et aux suggestions. Ils s’appliquent toutefois davantage aux suggestions, en particulier lorsqu’un suggesteur contient plusieurs champs.
| Paramètre | Utilisation |
|---|---|
| searchFields | Limitez la requête à des champs spécifiques. |
| $filter | Appliquez des critères de correspondance sur le jeu de résultats ($filter=Category eq 'ActionAdventure'). |
| $top | Limitez les résultats à un nombre spécifique ($top=5). |
Ajouter un code d’interaction utilisateur
Le remplissage automatique du terme d’une requête ou la mise à disposition d’une liste de liens correspondants nécessite un code d’interaction utilisateur (en général JavaScript) qui peut consommer des requêtes provenant de sources externes, comme les requêtes d’autocomplétion ou de suggestion sur un index Recherche cognitive Azure.
Bien que vous puissiez écrire ce code en mode natif, il est plus facile d’utiliser des fonctions d’une bibliothèque JavaScript existante, comme l’une des suivantes.
Le widget d'autocomplétion (jQuery UI) apparaît dans l'extrait de code de suggestion. Vous pouvez créer une zone de recherche, puis la référencer dans une fonction JavaScript qui utilise le widget d’autocomplétion. Les propriétés du widget définissent la source (fonction d’autocomplétion ou de suggestions), la longueur minimale des caractères d’entrée avant que l’action soit effectuée et le positionnement.
Le plug-in d'autocomplétion XDSoft apparaît dans l'extrait de code d'autocomplétion.
les suggestions apparaissent dans le tutoriel JavaScript et dans l'exemple de code.
Utilisez ces bibliothèques dans le client pour créer une zone de recherche prenant en charge les suggestions et l'autocomplétion. Les entrées collectées dans la zone de recherche peuvent ensuite être associées à des actions de suggestion et d'autocomplétion sur le service de recherche.
Suggestions
Cette section vous guide tout au long de l’implémentation des résultats suggérés, en commençant par la définition de la zone de recherche. Elle montre également un script qui appelle la première bibliothèque d’autocomplétion JavaScript référencée dans cet article.
Créer une zone de recherche
En prenant l’exemple de la bibliothèque d’autocomplétion jQuery UI et d’un projet MVC en C#, vous pouvez définir la zone de recherche à l’aide de JavaScript dans le fichier Index.cshtml. La bibliothèque ajoute l’interaction de recherche en cours de frappe en effectuant des appels asynchrones au contrôleur MVC afin de récupérer les suggestions.
Dans Index.cshtml sous le dossier \Views\Home, une ligne pour créer une zone de recherche peut se présenter comme suit :
<input class="searchBox" type="text" id="searchbox1" placeholder="search">
Cet exemple est une simple zone de texte avec une classe pour le style, un ID qui doit être référencé par JavaScript et un texte d’espace réservé.
Dans le même fichier, incorporez le code JavaScript qui fait référence à la zone de recherche. La fonction suivante appelle l’API Suggest, qui demande les documents correspondants suggérés en fonction des entrées de terme partielles :
$(function () {
$("#searchbox1").autocomplete({
source: "/home/suggest?highlights=false&fuzzy=false&",
minLength: 3,
position: {
my: "left top",
at: "left-23 bottom+10"
}
});
});
source indique à la fonction d’autocomplétion de jQuery UI où récupérer la liste des éléments à afficher sous la zone de recherche. Dans la mesure où ce projet est un projet MVC, il appelle la fonction Suggest dans le fichier HomeController.cs qui contient la logique permettant de retourner les suggestions de requête. Cette fonction transmet également quelques paramètres pour contrôler la mise en surbrillance, les correspondances approximatives et les termes. L’API JavaScript d’autocomplétion ajoute le paramètre de terme.
minLength: 3 garantit que les recommandations ne sont affichées que lorsque plus de trois caractères sont saisis dans la zone de recherche.
Activer la correspondance approximative
La recherche approximative vous permet d’obtenir des résultats selon des correspondances proches, même si l’utilisateur a mal épelé un mot dans la zone de recherche. La distance d’édition est 1, ce qui signifie qu’il peut y avoir un écart maximal de 1 caractère entre l’entrée de l’utilisateur et une correspondance.
source: "/home/suggest?highlights=false&fuzzy=true&",
Activer la mise en surbrillance
La mise en surbrillance applique le style de police aux caractères du résultat qui correspondent à l’entrée de l’utilisateur. Par exemple, si l’entrée partielle est « micro », le résultat est le suivant : microsoft, microscope, et ainsi de suite. La mise en surbrillance est basée sur les paramètres HighlightPreTag et HighlightPostTag, définis en ligne avec la fonction Suggestion.
source: "/home/suggest?highlights=true&fuzzy=true&",
Fonction Suggest
Si vous utilisez C# et une application MVC, le fichier HomeController.cs, sous le répertoire Controllers, est l’endroit où vous pouvez créer une classe pour les résultats suggérés. Dans .NET, une fonction Suggest est basée sur la méthode SuggestAsync. Pour plus d’informations sur le kit de développement logiciel (SDK) .NET, consultez Guide pratique pour utiliser la Recherche Azure AI à partir d’une application .NET.
La méthode InitSearch crée un client d’index HTTP authentifié dans le service Recherche Azure AI. Les propriétés de la classe SuggestOptions déterminent les champs recherchés et retournés dans les résultats, le nombre de correspondances et l’utilisation de la correspondance approximative.
Pour l’autocomplétion, la correspondance approximative est limitée à une distance d’une modification (un caractère omis ou mal placé). La correspondance approximative dans les requêtes avec autocomplétion peut parfois produire des résultats inattendus, en fonction de la taille de l’index et de son partitionnement.
public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
InitSearch();
var options = new SuggestOptions()
{
UseFuzzyMatching = fuzzy,
Size = 8,
};
if (highlights)
{
options.HighlightPreTag = "<b>";
options.HighlightPostTag = "</b>";
}
// Only one suggester can be specified per index.
// The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
// During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);
// Convert the suggest query results to a list that can be displayed in the client.
List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();
// Return the list of suggestions.
return new JsonResult(suggestions);
}
La fonction SuggestAsync prend deux paramètres qui déterminent si les meilleurs résultats sont renvoyés ou si la correspondance approximative est utilisée en plus de la recherche de terme. Vous pouvez inclure jusqu’à huit correspondances dans les résultats suggérés. La méthode crée un objet SuggestOptions, qui est ensuite passé à l’API de suggestion. Le résultat est ensuite converti en JSON pour être visible par le client.
Autocomplétion
Jusqu’à présent, le code de l’expérience utilisateur de recherche a été centré sur les suggestions. Le bloc de code suivant montre l’autocomplétion, en utilisant la fonction d’autocomplétion XDSoft jQuery UI, en passant une requête d’autocomplétion pour Recherche Azure AI. Comme avec les suggestions, dans une application C#, le code qui prend en charge l’interaction utilisateur se trouve dans index.cshtml.
$(function () {
// using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
// $.autocomplete -> $.autocompleteInline
$("#searchbox1").autocompleteInline({
appendMethod: "replace",
source: [
function (text, add) {
if (!text) {
return;
}
$.getJSON("/home/autocomplete?term=" + text, function (data) {
if (data && data.length > 0) {
currentSuggestion2 = data[0];
add(data);
}
});
}
]
});
// complete on TAB and clear on ESC
$("#searchbox1").keydown(function (evt) {
if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
$("#searchbox1").val(currentSuggestion2);
return false;
} else if (evt.keyCode === 27 /* ESC */) {
currentSuggestion2 = "";
$("#searchbox1").val("");
}
});
});
Fonction d’autocomplétion
La fonction Autocomplétion est basée sur la méthode AutocompleteAsync. Comme avec les suggestions, ce bloc de code se trouve dans le fichier HomeController.cs.
public async Task<ActionResult> AutoCompleteAsync(string term)
{
InitSearch();
// Setup the autocomplete parameters.
var ap = new AutocompleteOptions()
{
Mode = AutocompleteMode.OneTermWithContext,
Size = 6
};
var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);
// Convert the autocompleteResult results to a list that can be displayed in the client.
List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();
return new JsonResult(autocomplete);
}
La fonction d’autocomplétion prend l’entrée du terme de recherche. La méthode crée un objet AutoCompleteParameters. Le résultat est ensuite converti en JSON pour être visible par le client.
Étapes suivantes
Le tutoriel suivant illustre une expérience de recherche en cours de frappe.