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

  • Artigo

O Search-as-Type é uma técnica comum para melhorar a produtividade da consulta. Na Pesquisa de IA do Azure, essa experiência tem suporte por meio do preenchimento automático, que conclui um termo ou frase com base na entrada parcial (por exemplo, concluindo micro com microchip, microscópio, microsoft e quaisquer outras micro correspondências). Uma segunda experiência do usuário são sugestões, que produz uma pequena lista de documentos correspondentes (por exemplo, retornando títulos de livro com uma ID para que você possa vincular a uma página de detalhes sobre esse livro). O preenchimento automático e as sugestões são predicadas em uma correspondência no índice. O serviço não oferece consultas autocompletadas ou sugestões que retornam zero resultados.

Para implementar essas experiências na IA do Azure Search:

  • Adicionar um suggester a um esquema de índice.
  • Crie uma consulta que chame a API de Preenchimento Automático ou API de Sugestões na solicitação.
  • Adicionar um controle de interface do usuário para tratar interações de pesquisa ao digitar no aplicativo cliente. É recomendável usar uma biblioteca JavaScript existente para essa finalidade.

Na Pesquisa de IA do Azure, as consultas preenchidas automaticamente e os resultados sugeridos são recuperados do índice de pesquisa, dos campos selecionados que você registrou em um sugestor. Um sugestor faz parte do índice e especifica quais campos fornecerão conteúdo que completa uma consulta, sugere um resultado ou ambos. Quando o índice é criado e carregado, uma estrutura de dados de sugestão é criada internamente para armazenar prefixos usados para correspondência em consultas parciais. Para sugestões, escolher campos adequados que sejam exclusivos, ou pelo menos não repetitivo, é essencial para a experiência. Para obter mais informações, consulte Configurar um sugestor.

O restante deste artigo tem como foco as consultas e o código do cliente. Ele usa JavaScript e C# para ilustrar os principais pontos. Exemplos de API REST são usados para representar de forma concisa cada operação. Para obter exemplos de código de ponta a ponta, consulte Adicionar pesquisa a um site com o .NET.

Configurar uma solicitação

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

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

O parâmetro suggesterName fornece os campos com reconhecimento de sugestão usados para concluir termos ou sugestões. Para sugestões em particular, a lista de campos deve ser composta de sugestões que oferecem opções claras entre os resultados correspondentes. Em um site que vende jogos de computador, o campo pode ser o título do jogo.

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

As APIs não impõem requisitos de comprimento mínimo na consulta parcial. Ela pode ser tão pequena quanto um caractere. No entanto, a autocompletação do jQuery 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. Dado a raposa marrom rápida, o preenchimento automático e as sugestões correspondem às versões parciais de a, raposa, marrom ou rápida, mas não em termos parciais infixos como arr ou pos. Além disso, cada correspondência define o escopo para expansões downstream. Uma consulta parcial de raposa ma corresponde a raposa marrom ou raposa macho, mas nem marrom nem macho por si só seriam correspondentes, a menos que raposa* os preceda.

APIs para pesquisa conforme o tipo

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

Estruturar uma resposta

As respostas para preenchimento automático e sugestões são as que você pode esperar para o padrão: o preenchimento automático retorna uma lista de termos, as sugestões retornam 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 na solicitação:

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

  • Para sugestões, defina $select para retornar campos que contenham valores exclusivos ou diferenciais, 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 sugestor inclui vários campos.

Parâmetro Uso
searchFields 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 remoção de uma lista de links correspondentes requer o código de interação do usuário, normalmente o JavaScript, que pode consumir solicitações de fontes externas, como preenchimento automático ou consultas de sugestão em um índice cognitivo do Azure Search.

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

Use essas bibliotecas no cliente para criar uma caixa de pesquisa que dê suporte a sugestões e preenchimento automático. As entradas coletadas 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ê pela implementação de resultados sugeridos, começando com a definição da caixa de pesquisa. Ele também mostra como e script que invoca a primeira biblioteca de preenchimento automático de JavaScript referenciada neste artigo.

Supondo que a biblioteca de preenchimento automático da interface do usuário do jQuery e um projeto do MVC em C#, você pode definir a caixa de pesquisa usando JavaScript no arquivo index. cshtml. A biblioteca adiciona a interação de pesquisa enquanto digita à caixa de pesquisa fazendo chamadas assíncronas ao controlador MVC a fim de recuperar as 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">

Esse exemplo é uma caixa de texto de entrada simples com uma classe para definir o estilo, uma ID para referência pelo JavaScript e o texto de espaço reservado.

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

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

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

O minLength: 3 garante que as recomendações sejam mostradas somente quando houver pelo menos três caracteres na caixa de pesquisa.

Habilitar correspondência difusa

A pesquisa difusa permite que você obtenha resultados com base em correspondências próximas, mesmo se o usuário errou a escrita de uma palavra 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&",

Habilite o Realce

O realce aplica o estilo da fonte aos caracteres no resultado que correspondem à entrada. Por exemplo, se a entrada parcial for micro, o resultado apareceria como microsoft, microscópio e assim por diante. O realce baseia-se nos parâmetros HighlightPreTag e HighlightPostTag, definidos embutidos com a função Suggest.

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

Função de sugestão

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

O método InitSearch cria um cliente de índice HTTP autenticado para o serviço da IA do Azure Search. As propriedades na classe sugiraoptions 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 de local incorreto). A correspondência difusa em consultas de preenchimento automático pode, às vezes, 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 função SuggestAsync utiliza dois parâmetros que determinam se os destaques de ocorrências são retornados ou se correspondência difusa é usada em conjunto com o termo de pesquisa de entrada. Até oito correspondências podem ser incluídas nos resultados sugeridos. O método cria um objeto SuggestOptions, que é passado para a API de Sugestão. O resultado, em seguida, é convertido em JSON para que ele possa ser exibido no cliente.

Preenchimento automático

Até agora, o código da experiência do usuário de pesquisa estava centralizado em sugestões. O próximo bloco de código mostra o preenchimento automático, usando a função de preenchimento automático da interface do usuário do XDSoft jQuery, passando uma solicitação para a IA do Azure Search preencher automaticamente. Assim como nas sugestões, em um aplicativo C#, o código que dá suporte à 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. Assim como acontece com as sugestões, esse bloco de código ficaria 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 Autocomplete usa a entrada do termo de pesquisa. O método cria um objeto AutoCompleteParameters. O resultado, em seguida, é convertido em JSON para que ele possa ser exibido no cliente.

Próxima etapa

O tutorial a seguir demonstra uma experiência de pesquisar ao digitar.

Adicionar pesquisa a um site (C#)