Partager via

Ajouter l’autocomplétion et les suggestions de recherche aux applications clientes

  • Article

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 via l’autocomplétion, qui complète un terme ou une expression à partir d’une entrée partielle (par exemple en complétant micro en microchip, microscope, microsoft et d’autres correspondances avec « micro »). Les suggestions sont une autre expérience utilisateur, qui produit une courte liste succincte de documents correspondants (par exemple en retournant des titres de livres avec un ID pour vous permettre d’accéder via un lien à 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 des requêtes complétées automatiquement ni des suggestions qui ne retournent aucun résultat.

Pour implémenter ces expériences dans Recherche Azure AI :

  • Ajoutez un suggester au schéma de l’index.
  • Générez une requête qui appelle l’API Autocomplétion ou l’API 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 Configurer 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 Ajouter la recherche à un site web avec .NET.

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=2024-07-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

Le paramètre suggesterName vous donne les champs de type suggesteur utilisés pour compléter des termes ou des 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 en 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ù des caractères sont introduits dans la demande de requête via le contrôle d’autocomplétion de jQuery. Dans l’exemple précédent, minecraf est une illustration statique de ce que le contrôle peut passer en entrée.

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 d’infixe partiels comme rown ou ox. En outre, chaque correspondance définit l’étendue des expansions en aval. Une requête partielle de quick br établit une correspondance avec quick brown ou quick bread, mais ni brown ni bread eux-mêmes ne sont une correspondance, sauf s’ils sont précédés 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 pour déterminer si la complétion du texte se produit sur un ou deux termes.

  • Pour les suggestions, définissez $select pour retourner des champs contenant des valeurs uniques ou de différenciation, comme 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.

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.

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 HomeController.cs qui contient la logique pour 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 sont montrées seulement quand il y a au moins trois caractères 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 serait le suivant : microsoft, microscope, etc. La mise en surbrillance est basée sur les paramètres HighlightPreTag et HighlightPostTag, définis inline avec la fonction Suggest.

source: "/home/suggest?highlights=true&fuzzy=true&",

Fonction Suggest

Si vous utilisez C# et une application MVC, le fichier HomeController.cs dans 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 mises en surbrillance en correspondance sont retournées ou si la correspondance approximative est utilisée en plus de l’entrée du terme à rechercher. 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.

Étape suivante

Le tutoriel suivant illustre une expérience de recherche en cours de frappe.

Ajouter une recherche à un site web (C#)