Configurar um sugeridor para preenchimento automático e correspondências sugeridas em uma consulta

Na Pesquisa de IA do Azure, digitação antecipada (preenchimento automático) ou "pesquisa conforme você digita" é habilitada por meio de um sugestionador. Um sugestor é uma configuração em um índice que especifica quais campos devem ser usados para preencher o preenchimento automático e sugestões. Esses campos passam por tokenização extra, gerando sequências de prefixos para suportar correspondências em termos parciais. Por exemplo, um sugestor que inclui um campo de Cidade com o valor "Seattle" terá combinações de prefixo "sea", "seat", "seatt" e "seattl" para dar suporte ao preenchimento automático.

As correspondências de termos parciais podem ser uma consulta com preenchimento automático ou uma correspondência sugerida. O mesmo sugestor dá suporte às duas experiências.

Experiências de preenchimento automático na IA do Azure Search

As opções são o preenchimento automático, que completa uma entrada parcial para uma consulta de termo inteiro (ou as sugestões) que convidam a clicar em uma correspondência específica. O preenchimento automático produz uma consulta. As sugestões produzem um documento correspondente.

A captura de tela a seguir ilustra ambos. O preenchimento automático prevê um termo potencial, completando "tw" com "in". Sugestões são versões menores de resultados da pesquisa, em que um campo como nome de hotel representa um documento de pesquisa de hotel correspondente do índice. Para as sugestões, você pode utilizar qualquer campo que forneça informações descritivas.

Você pode usar esses recursos separadamente ou em conjunto. Para implementar esses comportamentos na IA do Azure Search, há um componente de índice e de consulta.

• Adicionar um sugestor a uma definição de índice de pesquisa. O restante deste artigo se concentra na criação de um sugestor.

• Chame uma consulta habilitada para sugestionante, na forma de uma solicitação de Sugestão ou solicitação de Preenchimento Automático, usando uma das APIs listadas em uma seção posterior.

A pesquisa conforme você digita é habilitada por campo para campos de cadeia de caracteres. Você pode implementar os dois comportamentos na mesma solução de pesquisa se desejar uma experiência semelhante à ilustrada na captura de tela. Ambas as solicitações têm como alvo a coleção de documentos de índice específico e as respostas são retornadas depois que um usuário fornece pelo menos uma cadeia de caracteres de entrada de três caracteres.

Como criar um sugestor

Para criar um sugestor, adicione um a uma definição de índice. Um sugestor usa um nome e uma coleção de campos nos quais a experiência de preenchimento automático é habilitada. O melhor momento para criar um sugeridor é quando você também está definindo o campo que o usa.

• Use somente campos de cadeia de caracteres.

• Se o campo de cadeia de caracteres fizer parte de um tipo complexo (por exemplo, um campo Cidade dentro do Endereço), inclua o pai no caminho do campo: "Address/City" (REST, C# e Python) ou ["Address"]["City"] (JavaScript).

• Use o analisador Lucene padrão ("analyzer": null) ou um analisador de idioma (por exemplo, "analyzer": "en.Microsoft") no campo.

Se você tentar criar um sugeridor usando campos pré-existentes, a API não o permitirá. Os prefixos são gerados durante a indexação, quando termos parciais em duas ou mais combinações de caracteres são indexados em conjunto com os termos inteiros. Dado que os campos existentes já estão tokenizados, você precisa reconstruir o índice se quiser adicioná-los a um sugestionador. Para obter mais informações, confira Como recompilar um índice da IA do Azure Search.

Selecionar campos

Embora um sugestor tenha várias propriedades, ele é basicamente uma coleção de campos de cadeia de caracteres para os quais você está habilitando uma experiência de pesquisar enquanto digita. Há um sugestor para cada índice, portanto, a lista do sugestor deve incluir todos os campos que contribuem com conteúdo para as sugestões e o preenchimento automático.

O preenchimento automático se beneficia de um pool maior de campos para extrair porque o conteúdo extra tem mais potencial de conclusão de termos.

As sugestões, por outro lado, produzem resultados melhores quando a opção de campo é seletiva. Lembre-se de que a sugestão é um proxy para um documento de pesquisa, portanto, escolha os campos que melhor representam um único resultado. Nomes, títulos ou outros campos exclusivos que distinguem entre várias correspondências funcionam melhor. Se os campos consistirem em valores repetitivos, as sugestões consistirão em resultados idênticos e um usuário não saberá qual escolher.

Para satisfazer as experiências de pesquisa conforme você digita, adicione todos os campos necessários para o preenchimento automático, mas use select, , topfiltere searchFields para controlar os resultados das sugestões.

Escolher analisadores

A escolha de um analisador determina como os campos são tokenizados e prefixados. Por exemplo, para uma cadeia de caracteres hifenizada como "sensível ao contexto", o uso de um analisador de linguagem resulta nessas combinações de tokens: "context", "sensitive", "context-sensitive". Se você tivesse usado o analisador Lucene padrão, a cadeia de caracteres com hífen não existiria.

Ao avaliar os analisadores, considere usar a API de Análise de Texto para saber como os termos são processados. Depois compilar um índice, você pode experimentar vários analisadores em uma cadeia de caracteres para ver a saída do token.

Os campos que usam analisadores personalizados ou analisadores internos (exceto o Lucene padrão) são explicitamente proibidos para evitar resultados ruins.

Observação

Se você precisar contornar a restrição do analisador, por exemplo, se precisar de um analisador de ngram ou palavra-chave para determinados cenários de consulta, use dois campos separados para o mesmo conteúdo. Isso permitirá que um dos campos tenha um sugestor enquanto o outro pode ter uma configuração personalizada do analisador.

Criar usando o Portal

Ao usar o assistente Adicionar Índice ou Importar dados para criar um índice, você tem a opção de habilitar um sugestor:

1. Na definição do índice, insira um nome para o sugestor.

2. Em cada definição de campo para novos campos, marque uma caixa de seleção na coluna Sugestor. A caixa de seleção está disponível somente em campos de cadeia de caracteres.

Conforme observado anteriormente, a opção do analisador afeta a geração de tokens e a prefixação. Considere a definição de campo inteira ao habilitar sugestores.

Criar usando REST

Na API REST, adicione sugestores por meio de Criar Índice ou Atualizar Índice.

{
  "name": "hotels-sample-index",
  "fields": [
    . . .
        {
            "name": "HotelName",
            "type": "Edm.String",
            "facetable": false,
            "filterable": false,
            "key": false,
            "retrievable": true,
            "searchable": true,
            "sortable": false,
            "analyzer": "en.microsoft",
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "synonymMaps": [],
            "fields": []
        },
  ],
  "suggesters": [
    {
      "name": "sg",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["HotelName"]
    }
  ],
  "scoringProfiles": [
    . . .
  ]
}

Criar usando .NET

Em C#, defina um objeto SearchSuggester. Suggesters é uma coleção em um objeto SearchIndex, mas só pode usar um item. Adicione um sugestor à definição do índice.

private static void CreateIndex(string indexName, SearchIndexClient indexClient)
{
    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);

    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);

    indexClient.CreateOrUpdateIndex(definition);
}

Referência de propriedade

Propriedade	Descrição
name	Especificado na definição do sugestor, mas também chamado em uma solicitação de Preenchimento Automático ou de Sugestões.
sourceFields	Especificado na definição do sugestor. É uma lista de um ou mais campos no índice que são a fonte do conteúdo para obter sugestões. Os campos devem ser do tipo Edm.String. Se um analisador for especificado no campo, deverá ser um analisador léxico nomeado desta lista (não um analisador personalizado). Como melhor prática, especifique somente campos oferecem respostas esperadas e apropriadas, seja uma cadeia de caracteres completa em uma barra de pesquisa ou uma lista suspensa. Um nome de hotel é um bom candidato porque tem precisão. Campos detalhados, como descrições e comentários, são muito densos. De maneira semelhante, campos repetitivos, como categorias e marcas, são menos eficazes. Nos exemplos, incluímos "category" de qualquer forma para demonstrar que você pode incluir vários campos.
searchMode	Parâmetro somente REST, mas também visível no portal. Esse parâmetro não está disponível no SDK do .NET. Ele indica a estratégia usada para pesquisar frases candidatas. O único modo com suporte no momento é analyzingInfixMatching, que corresponde ao início de um termo.

Usar um sugestor

Um sugestor é usado em uma consulta. Depois que um sugestor for criado, chame uma das seguintes APIs para uma experiência de pesquisar enquanto digita:

• API REST de Sugestões
• API REST de Preenchimento Automático
• Método SuggestAsync
• Método AutocompleteAsync

Em um aplicativo de pesquisa, o código do cliente deve usar uma biblioteca, como jQuery UI Autocomplete, para coletar a consulta parcial e fornecer a correspondência. Para saber mais sobre essa tarefa, confira Adicionar preenchimento automático ou resultados sugeridos ao código do cliente.

O uso da API é ilustrado na chamada a seguir para a API REST de Preenchimento Automático. Há dois aprendizados neste exemplo. Primeiro, como acontece com todas as consultas, a operação é contra a coleção de documentos de um índice e a consulta inclui um search parâmetro, que neste caso fornece a consulta parcial. Em segundo lugar, você deve adicionar suggesterName à solicitação. Se um sugeridor não estiver definido no índice, as chamadas para preenchimento automático ou sugestões falharão.

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

Código de exemplo

• Adicionar pesquisa a um site (JavaScript) usa um pacote de Sugestões de software livre para preenchimento de termo parcial no aplicativo cliente.

Próximas etapas

Saiba mais sobre solicitações e formulação.

Adicionar preenchimento automático e sugestões ao código do cliente