Partilhar via

Adicionar preenchimento automático e sugestões de pesquisa em aplicativos cliente

  • Artigo

A pesquisa à medida que escreve é uma técnica comum para melhorar a produtividade das consultas. No Azure AI Search, essa experiência é suportada por meio do preenchimento automático, que conclui um termo ou frase com base na entrada parcial (por exemplo, completar micro com microchip, microscópio, microsoft e quaisquer outras microcorrespondências). Uma segunda experiência do usuário são as sugestões, que produzem uma pequena lista de documentos correspondentes (por exemplo, retornar títulos de livros com um ID para que você possa vincular a uma página de detalhes sobre esse livro). Tanto o preenchimento automático quanto as sugestões são baseados em uma correspondência no índice. O serviço não oferece consultas preenchidas automaticamente ou sugestões que retornem resultados zero.

Para implementar estas experiências no Azure AI Search:

  • Adicione um suggester a um esquema de índice.
  • Crie uma consulta que chame a API de Preenchimento Automático ou a API de Sugestões na solicitação.
  • Adicione um controle de interface do usuário para lidar com interações de pesquisa conforme você digita em seu aplicativo cliente. Recomendamos o uso de uma biblioteca JavaScript existente para essa finalidade.

No Azure AI Search, consultas preenchidas automaticamente e resultados sugeridos são recuperados do índice de pesquisa, de campos selecionados que você registra com um sugestionador. Um sugeridor faz parte do índice e especifica quais campos fornecem conteúdo que conclui uma consulta, sugere um resultado ou faz as duas coisas. Quando o índice é criado e carregado, uma estrutura de dados sugestiva é criada internamente para armazenar prefixos usados para correspondência em consultas parciais. Para sugestões, escolher campos adequados que sejam únicos, ou pelo menos não repetitivos, é essencial para a experiência. Para obter mais informações, consulte Configurar um sugestão.

O restante deste artigo é focado em consultas e código do cliente. Ele usa JavaScript e C# para ilustrar pontos-chave. Exemplos de API REST são usados para apresentar de forma concisa cada operação. Para obter exemplos de código de ponta a ponta, consulte Adicionar pesquisa a um site com .NET.

Configurar um pedido

Os elementos de uma solicitação incluem uma das APIs de pesquisa conforme você digita, uma consulta parcial e um sugestão. O script a seguir ilustra componentes de uma solicitação, usando a API REST de preenchimento automático como exemplo.

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2024-07-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

O suggesterName parâmetro fornece os campos sensíveis a sugestões usados para completar termos ou sugestões. Para sugestões em particular, a lista de campos deve ser composta por sugestões que ofereçam escolhas claras entre os resultados correspondentes. Em um site que vende jogos de computador, o campo pode ser o título do jogo.

O search parâmetro fornece a consulta parcial, onde os caracteres são alimentados para a solicitação de consulta por meio do controle jQuery Autocomplete. No exemplo anterior, minecraf é uma ilustração estática do que o controle pode passar.

As APIs não impõem requisitos mínimos de comprimento na consulta parcial; pode ser tão pouco quanto um personagem. No entanto, o jQuery Autocomplete fornece um comprimento mínimo. Um mínimo de dois ou três caracteres é típico.

As correspondências estão no início de um termo em qualquer lugar na cadeia de caracteres de entrada. Dada a raposa castanha rápida, tanto o preenchimento automático como as sugestões correspondem em versões parciais da raposa, rápida, castanha ou raposa, mas não em termos parciais como apreensão ou boi. Além disso, cada partida define o escopo para expansões a jusante. Uma consulta parcial de correspondências rápidas em pão castanho rápido ou rápido, mas nem castanho ou pão por si só seria uma combinação, a menos que rápido* os preceda.

APIs para pesquisa conforme você digita

Siga estes links para as páginas de referência do REST e do SDK do .NET:

Estruturar uma resposta

As respostas para preenchimento automático e sugestões são o que você pode esperar para o padrão: O preenchimento automático retorna uma lista de termos, Sugestões retorna termos mais uma ID de documento para que você possa buscar o documento (use a API de documento de pesquisa para buscar o documento específico para uma página de detalhes).

As respostas são moldadas pelos parâmetros no pedido:

  • Para preenchimento automático, defina o autocompleteMode para determinar se a conclusão do texto ocorre em um ou dois termos.

  • Para sugestões, defina $select para retornar campos contendo valores exclusivos ou diferenciadores, como nomes e descrição. Evite campos que contenham valores duplicados (como uma categoria ou cidade).

Os parâmetros a seguir se aplicam ao preenchimento automático e às sugestões, mas são mais aplicáveis às sugestões, especialmente quando um sugeridor inclui vários campos.

Parâmetro Utilização
pesquisaCampos Restringir a consulta a campos específicos.
$filter Aplicar critérios de correspondência no conjunto de resultados ($filter=Category eq 'ActionAdventure').
$top Limitar os resultados a um número específico ($top=5).

Adicionar código de interação do usuário

O preenchimento automático de um termo de consulta ou a lista suspensa de uma lista de links correspondentes requer código de interação do usuário, geralmente JavaScript, que pode consumir solicitações de fontes externas, como preenchimento automático ou consultas de sugestão em um índice cognitivo da Pesquisa do Azure.

Embora você possa escrever esse código nativamente, é mais fácil usar funções da biblioteca JavaScript existente, como uma das seguintes.

  • O widget de preenchimento automático (jQuery UI) aparece no trecho de código de sugestão. Você pode criar uma caixa de pesquisa e, em seguida, fazer referência a ela em uma função JavaScript que usa o widget de preenchimento automático. As propriedades no widget definem a origem (uma função de preenchimento automático ou sugestões), o comprimento mínimo dos caracteres de entrada antes da ação ser tomada e o posicionamento.

  • O plug-in XDSoft Autocomplete aparece no trecho de código de preenchimento automático.

  • As sugestões aparecem no tutorial Adicionar pesquisa a sites e no exemplo de código.

Use essas bibliotecas no cliente para criar uma caixa de pesquisa que ofereça suporte a sugestões e preenchimento automático. As entradas recolhidas na caixa de pesquisa podem ser emparelhadas com sugestões e ações de preenchimento automático no serviço de pesquisa.

Sugestões

Esta seção orienta você por uma implementação de resultados sugeridos, começando com a definição da caixa de pesquisa. Ele também mostra como e o script que invoca a primeira biblioteca de preenchimento automático JavaScript mencionada neste artigo.

Supondo a biblioteca jQuery UI Autocomplete e um projeto MVC em C#, você pode definir a caixa de pesquisa usando JavaScript no arquivo Index.cshtml . A biblioteca adiciona a interação de pesquisa conforme você digita à caixa de pesquisa fazendo chamadas assíncronas para o controlador MVC para recuperar sugestões.

Em Index.cshtml dentro da pasta \Views\Home, uma linha para criar uma caixa de pesquisa pode ser a seguinte:

<input class="searchBox" type="text" id="searchbox1" placeholder="search">

Este exemplo é uma caixa de texto de entrada simples com uma classe para estilo, uma ID a ser referenciada pelo JavaScript e texto de espaço reservado.

Dentro do mesmo arquivo, incorpore JavaScript que faz referência à caixa de pesquisa. A função a seguir chama a API Suggest, que solicita documentos de correspondência sugeridos com base em entradas parciais de termos:

$(function () {
    $("#searchbox1").autocomplete({
        source: "/home/suggest?highlights=false&fuzzy=false&",
        minLength: 3,
        position: {
            my: "left top",
            at: "left-23 bottom+10"
        }
    });
});

O source informa à função de Preenchimento Automático da interface do usuário do jQuery onde obter a lista de itens a ser exibida na caixa de pesquisa. Como este projeto é um projeto MVC, ele chama a Suggest função em HomeController.cs que contém a lógica para retornar sugestões de consulta. Esta função também passa alguns parâmetros para controlar destaques, correspondência difusa e termo. A API JavaScript de preenchimento automático adiciona o parâmetro term.

O minLength: 3 garante que as recomendações só são mostradas quando há pelo menos três caracteres na caixa de pesquisa.

Ativar correspondência difusa

A pesquisa difusa permite-lhe obter os resultados com base em correspondências aproximadas, mesmo que o utilizador escreva uma palavra incorretamente na caixa de pesquisa. A distância de edição é 1, o que significa que pode haver uma discrepância máxima de um caractere entre a entrada do usuário e uma correspondência.

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

Ativar realce

O realce aplica o estilo de fonte aos caracteres no resultado que correspondem à entrada. Por exemplo, se a entrada parcial for micro, o resultado aparecerá como microsoft, microscope, e assim por diante. O realce é baseado nos HighlightPreTag parâmetros e HighlightPostTag definidos, em linha com a Suggest função.

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

Função Sugerir

Se você estiver usando C# e um aplicativo MVC, o arquivo HomeController.cs no diretório Controllers é onde você pode criar uma classe para os resultados sugeridos. No .NET, uma Suggest função é baseada no método SuggestAsync. Para obter mais informações sobre o SDK do .NET, consulte Como usar a Pesquisa de IA do Azure a partir de um aplicativo .NET.

O InitSearch método cria um cliente de índice HTTP autenticado para o serviço Azure AI Search. As propriedades na classe SuggestOptions determinam quais campos são pesquisados e retornados nos resultados, o número de correspondências e se a correspondência difusa é usada.

Para preenchimento automático, a correspondência difusa é limitada a uma distância de edição (um caractere omitido ou extraviado). A correspondência difusa em consultas de preenchimento automático às vezes pode produzir resultados inesperados, dependendo do tamanho do índice e de como ele é fragmentado.

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);
}

A SuggestAsync função usa dois parâmetros que determinam se os destaques de hit são retornados ou a correspondência difusa é usada, além da entrada do termo de pesquisa. Até oito partidas podem ser incluídas nos resultados sugeridos. O método cria um objeto SuggestOptions, que é passado para a API Suggest. Em seguida, o resultado é convertido em JSON, para que possa ser mostrado no cliente.

Preenchimento Automático

Até agora, o código UX de pesquisa tem sido centrado em sugestões. O próximo bloco de código mostra o preenchimento automático, usando a função XDSoft jQuery UI Autocomplete, passando uma solicitação para o preenchimento automático do Azure AI Search. Assim como nas sugestões, em um aplicativo C#, o código que suporta a interação do usuário vai em 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("");
        }
    });
});

Função de preenchimento automático

O preenchimento automático é baseado no método AutocompleteAsync. Tal como acontece com as sugestões, este bloco de código iria no arquivo 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);
}

A função Preenchimento automático recebe a entrada do termo de pesquisa. O método cria um objeto AutoCompleteParameters. Em seguida, o resultado é convertido em JSON, para que possa ser mostrado no cliente.

Próximo passo

O tutorial a seguir demonstra uma experiência de pesquisa conforme você digita.

Adicionar pesquisa a um site (C#)