Criar uma consulta de texto completo no Azure AI Search

  • Artigo

Se você estiver criando uma consulta para pesquisa texto completo, este artigo fornecerá etapas para configurar a solicitação. Ele também apresenta uma estrutura de consulta e explica como os atributos de campo e os analisadores linguísticos podem impactar os resultados da consulta.

Pré-requisitos

Exemplo de uma solicitação de consulta de texto completo

No Azure AI Search, uma consulta é uma solicitação somente leitura na coleção de documentos de um único índice de pesquisa, com parâmetros que informam a execução da consulta e moldam o retorno da resposta.

Uma consulta de texto completo é especificada em um parâmetro search e consiste em termos, frases entre aspas e operadores. Outros parâmetros adicionam mais definição à solicitação.

A chamada à API REST Search POST a seguir ilustra uma solicitação de consulta usando os parâmetros mencionados anteriormente.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": "10",
    "count": "true"
}

Pontos principais:

  • search fornece os critérios de correspondência, geralmente termos ou frases inteiras, com ou sem operadores. Qualquer campo atribuído como "pesquisável" no esquema de índice é um candidato para esse parâmetro.

  • queryTypeDefine o modo do analisador: simple, full. O analisador de consulta simples padrão é ideal para a pesquisa de texto completo. O analisador de consulta Lucene completo é para construções de consulta avançadas, como expressões regulares, pesquisa por proximidade, pesquisa difusa e curinga. Esse parâmetro também pode ser definido como semantic para classificação semântica para modelagem semântica avançada na resposta da consulta.

  • searchMode especifica se as correspondências são baseadas no critério "todos" (favorece a precisão) ou "qualquer" (favorece o recall) na expressão. O padrão é “qualquer”. Caso preveja o uso intensivo de operadores boolianos, o que é mais provável em índices que contêm blocos de texto Grandes (um campo de conteúdo ou descrições longas), certifique-se de testar as consultas com o searchMode=Any|All parâmetro para avaliar o impacto dessa configuração na pesquisa booliana.

  • searchFields restringe a execução da consulta a campos pesquisáveis específicos. Durante o desenvolvimento, é útil usar a mesma lista de campos para selecionar e pesquisar. Caso contrário, uma correspondência pode ter base em valores de campo que você não consegue ver nos resultados, criando incertezas sobre o motivo pelo qual o documento foi retornado.

Parâmetros usados para formar a resposta:

  • select especifica quais campos retornar na resposta. Somente os campos marcados como "recuperáveis" no índice podem ser usados em uma instrução selecionar.

  • top retorna o número especificado de documentos de melhor correspondência. Neste exemplo, apenas 10 ocorrências são retornadas. É possível usar top e ignorar (não mostrado) para paginar os resultados.

  • count informa quantos documentos em todo o índice correspondem em geral, o que pode ser maior que o retornado.

  • orderby será usado se você quiser classificar os resultados por um valor, como uma classificação ou um local. Caso contrário, o padrão é usar a pontuação de relevância para classificar os resultados. Um campo deve ser atribuído como "classificável" para ser um candidato para esse parâmetro.

Selecione um cliente

Para desenvolvimento antecipado e teste de prova de conceito, comece com o portal do Azure ou um cliente REST. Essas abordagens são interativas, úteis para testes direcionados e ajudam você a avaliar os efeitos de propriedades diferentes sem precisar escrever nenhum código.

Para chamar a pesquisa de dentro de um aplicativo, use as bibliotecas de cliente do Azure.Document.Search nos SDKs do Azure para .NET, Java, JavaScript e Python.

No portal, ao abrir um índice, você pode trabalhar com o Search Explorer junto com a definição JSON de índice em guias lado a lado para facilitar o acesso a atributos de campo. Verifique a tabela Campos para ver quais são pesquisáveis, classificáveis, filtradas e facetáveis durante o teste de consultas.

  1. Entre no portal do Azure e localize seu serviço de pesquisa.

  2. Abra Índices e selecione um índice.

  3. Um índice é aberto na guia Gerenciador de Pesquisa para que você possa consultar imediatamente. Alterne para exibição JSON para especificar a sintaxe da consulta.

    Aqui está uma expressão de consulta de pesquisa de texto completo que funciona para o índice de exemplo Hotéis:

       {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }

    A seguinte captura de tela ilustra a consulta e a resposta:

    Screenshot of Search Explorer with a full text query.

Selecione um tipo de consulta: simples | completa

Se sua consulta for pesquisa de texto completo, um analisador de consulta será usado para processar qualquer texto passado como termos e frases de pesquisa. O Azure AI Search oferece dois analisadores de consulta.

  • O analisador simples entende a sintaxe de consulta simples. Este analisador foi selecionado como o padrão para sua velocidade e eficácia em consultas de texto de forma livre. A sintaxe dá suporte a operadores de pesquisa comuns (e, ou, não) para pesquisas de termo e frase, e a pesquisa de prefixo (*) (como em "Sea*" para Seattle e Seaside). Uma recomendação geral é testar o analisador simples primeiro e, em seguida, passar para o analisador completo se os requisitos do aplicativo exigirem consultas mais poderosas.

  • A sintaxe de consulta Lucene completa, habilitada quando você adiciona queryType=full à solicitação, é baseada no analisador do Apache Lucene.

A sintaxe completa e a sintaxe simples se sobrepõem na medida que ambos dão suporte ao mesmo prefixo e às operações booleanas, mas a sintaxe completa fornece mais operadores. No total, há mais operadores para expressões booleanas e mais operadores para consultas avançadas, como pesquisa difusa, pesquisa de caracteres curinga, pesquisa de proximidade e expressões regulares.

Escolher métodos de consulta

A pesquisa é fundamentalmente um exercício controlado pelo usuário, em que os termos ou frases são coletados de uma caixa de pesquisa ou de eventos de clique em uma página. A tabela a seguir resume os mecanismos pelos quais você pode coletar entradas do usuário, juntamente com a experiência de pesquisa esperada.

Entrada Experiência
Método Search Um usuário digita termos ou frases em uma caixa de pesquisa, com ou sem operadores, e clica em Pesquisar para enviar a solicitação. A pesquisa pode ser usada com filtros na mesma solicitação, mas não com preenchimento automático ou sugestões.
Método de Preenchimento automático Um usuário digita alguns caracteres e as consultas são iniciadas após a entrada de cada novo caractere. A resposta é uma cadeia de caracteres completa do índice. Se a cadeia de caracteres fornecida for válida, o usuário clicará em Pesquisar para enviar essa consulta ao serviço.
Método Sugestões Assim como acontece com o preenchimento automático, um usuário digita alguns caracteres e as consultas incrementais são geradas. A resposta é uma lista suspensa de documentos correspondentes, normalmente representada por alguns campos exclusivos ou descritivos. Se qualquer uma das seleções for válida, o usuário clica em uma e o documento correspondente é retornado.
Navegação facetada Uma página mostra links de navegação clicáveis ou trilhas que restringem o escopo da pesquisa. Uma estrutura de navegação facetada é composta dinamicamente com base em uma consulta inicial. Por exemplo, search=* para popular uma árvore de navegação facetada composta de todas as categorias possíveis. Uma estrutura de navegação facetada é criada a partir de uma resposta de consulta, mas também é um mecanismo para expressar a próxima consulta. Na referência da API REST, facets está documentado como um parâmetro de consulta de uma operação Pesquisa de documentos, mas pode ser usado sem o parâmetro search.
Método Filtro Os filtros são usados com facetas para restringir os resultados. Você também pode implementar um filtro por trás da página, por exemplo, para inicializar a página com campos específicos do idioma. Na referência da API REST, $filter é documentado como um parâmetro de consulta de uma operação Pesquisar documentos, mas pode ser usado sem o parâmetro search.

Efeito de atributos de campo em consultas

Se você estiver familiarizado com os tipos de consulta e a composição, talvez se lembre de que os parâmetros na solicitação de consulta dependem dos atributos de campo em um índice. Por exemplo, somente os campos marcados como searchable e retrievable podem ser usados em consultas e resultados da pesquisa. Ao definir os search, filtere orderby parâmetros em sua solicitação, você deve verificar os atributos para evitar resultados inesperados.

Na captura de tela do portal abaixo do índice de ex hotéis, somente os dois últimos campos "LastRenovationDate" e "Rating" são sortable, um requisito para uso em uma cláusula somente "$orderby".

Index definition for the hotel sample

Para definições de atributo de campo, consulte Criar índice (API REST).

Efeito de tokens em consultas

Durante a indexação, o mecanismo de pesquisa usa um analisador de texto em cadeias de caracteres para maximizar o potencial para localizar uma correspondência no momento da consulta. No mínimo, as cadeias de caracteres estão em letras minúsculas, mas também podem passar por lematização e remoção de palavra irrelevante. Cadeias de caracteres maiores ou palavras compostas normalmente são divididas por espaço em branco, hifens ou traços e indexadas como tokens separados.

O importante aqui é que o que você considera que o índice contém e o que realmente está nele pode ser diferente. Se as consultas não retornarem os resultados esperados, você poderá inspecionar os tokens criados pelo analisador por meio do Analisar texto (API REST). Para obter mais informações sobre a geração de tokens e o impacto nas consultas, consulte Pesquisa de termo parcial e padrões com caracteres especiais.

Próximas etapas

Agora que você tem uma melhor compreensão de como as solicitações de consulta funcionam, experimente os guias de início rápido a seguir para obter experiência prática.