Partilhar via

Criar uma consulta de texto completo no Azure AI Search

  • Artigo

Se você estiver criando uma consulta para pesquisa de texto completo, este artigo fornece 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 afetar 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 a resposta que retorna.

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

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

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-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 inteiros, com ou sem operadores. Qualquer campo atribuído como pesquisável no esquema de índice é um candidato para este parâmetro.

  • queryType define o analisador: simples, completo. O analisador de consulta simples padrão é ideal para pesquisa de texto completo. O analisador de consulta Lucene completo destina-se a construções de consulta avançadas, como expressões regulares, pesquisa de proximidade, pesquisa difusa e curinga. Esse parâmetro também pode ser definido como semântico para classificação semântica para modelagem semântica avançada na resposta da consulta.

  • searchModeespecifica se as correspondências são baseadas em todos os critérios (favorece a precisão) ou em quaisquer critérios (favorece a recordação) na expressão. A predefinição é qualquer. Se você prevê o uso intenso de operadores booleanos, 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 consultas com o searchMode=Any|All parâmetro para avaliar o impacto dessa configuração na pesquisa booleana.

  • 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 ser baseada em valores de campo que você não pode ver nos resultados, criando incerteza sobre o motivo pelo qual o documento foi retornado.

Parâmetros usados para moldar a resposta:

  • select Especifica quais campos devem ser retornados na resposta. Somente os campos marcados como recuperáveis no índice podem ser usados em uma instrução select.

  • top Devolve o número especificado de documentos com melhor correspondência. Neste exemplo, apenas 10 acertos são retornados. Você pode usar top e pular (não mostrado) para paginar os resultados.

  • count informa quantos documentos em todo o índice correspondem no geral, o que pode ser mais do que o que é retornado.

  • orderby é usado se você quiser classificar os resultados por um valor, como uma classificação ou 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 a este parâmetro.

Escolha um cliente

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

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

No portal do Azure, ao abrir um índice, você pode trabalhar com o Gerenciador de Pesquisa ao lado da definição JSON do índice em guias lado a lado para facilitar o acesso aos atributos de campo. Verifique a tabela Campos para ver quais são pesquisáveis, classificáveis, filtráveis e faceiros durante o teste de consultas.

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

  2. No seu serviço, selecione Índices e escolha um índice.

  3. Um índice é aberto na guia Gerenciador de pesquisa para que você possa consultar imediatamente. Alterne para o modo de 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 captura de tela a seguir ilustra a consulta e a resposta:

    Captura de ecrã do Explorador de Pesquisa com uma consulta de texto completo.

Escolha um tipo de consulta: simples | cheio

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

  • O analisador simples compreende a sintaxe de consulta simples. Este analisador foi selecionado como padrão por sua velocidade e eficácia em consultas de texto de forma livre. A sintaxe suporta operadores de pesquisa comuns (AND, OR, NOT) para pesquisas de termos e frases, e pesquisa de prefixo (*) (como em sea* Seattle e Seaside). Uma recomendação geral é experimentar 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, ativada quando você adiciona queryType=full à solicitação, é baseada no Apache Lucene Parser.

A sintaxe completa e a sintaxe simples se sobrepõem na medida em que ambas suportam o mesmo prefixo e operações booleanas, mas a sintaxe completa fornece mais operadores. Na íntegra, há mais operadores para expressões booleanas e mais operadores para consultas avançadas, como pesquisa difusa, pesquisa curinga, pesquisa de proximidade e expressões regulares.

Escolher métodos de consulta

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

Entrada Experiência
Método de pesquisa Um usuário digita os termos ou frases em uma caixa de pesquisa, com ou sem operadores, e seleciona 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 depois que cada novo caractere é digitado. A resposta é uma cadeia de caracteres concluída do índice. Se a cadeia de caracteres fornecida for válida, o usuário selecionará Pesquisar para enviar essa consulta ao serviço.
Método de sugestões Assim como no preenchimento automático, um usuário digita alguns caracteres e consultas incrementais são geradas. A resposta é uma lista suspensa de documentos correspondentes, normalmente representados por alguns campos exclusivos ou descritivos. Se qualquer uma das seleções for válida, o usuário selecionará uma e o documento correspondente será retornado.
Navegação por facetas 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 preencher uma árvore de navegação facetada composta por 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. n A referência facets da API REST é documentada como um parâmetro de consulta de uma operação de Pesquisa de Documentos, mas pode ser usada sem o search parâmetro.
Método de filtragem Os filtros são usados com facetas para estreitar os resultados. Você também pode implementar um filtro atrá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 de Pesquisa de Documentos, mas pode ser usado sem o search parâmetro.

Efeito dos atributos de campo nas consultas

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

Na captura de tela a seguir do índice de amostra de hotéis, apenas os dois últimos campos LastRenovationDate e Rating são classificáveis, um requisito para uso em uma "$orderby" cláusula only.

Captura de tela que mostra a definição de índice para a amostra de hotel.

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

Efeito dos tokens nas consultas

Durante a indexação, o mecanismo de pesquisa usa um analisador de texto em cadeias de caracteres para maximizar o potencial de encontrar uma correspondência no momento da consulta. No mínimo, as cadeias de caracteres são minúsculas, mas dependendo do analisador, também podem sofrer lemmatização e remoção de palavras paradas. Cadeias de caracteres maiores ou palavras compostas são normalmente divididas por espaços em branco, hífenes ou traços e indexadas como tokens separados.

O ponto-chave é que o que você acha que seu í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 da API REST (Analisar texto). Para obter mais informações sobre tokenização e o efeito em consultas, consulte Pesquisa parcial de termos e padrões com caracteres especiais.

Conteúdos relacionados

Agora que você já entendeu melhor como as solicitações de consulta funcionam, tente os seguintes guias de início rápido para obter uma experiência prática.