Criar uma consulta de texto completo na Pesquisa de IA do Azure

  • Artigo

Se você estiver criando uma consulta para pesquisa texto completo, este artigo fornecerá etapas para configurar a solicitação. Ela 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 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.

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-chave

  • 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.

  • queryType define o analisador: simples e completo. 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 semântico para classificação semântica para modelagem semântica avançada na resposta da consulta.

  • searchMode especifica se as correspondências são baseadas em todos os critérios (favorece a precisão) ou em qualquer critério (favorece o recall) na expressão. O padrão é qualquer. Caso você preveja o uso intensivo de operadores boolianos, o que é mais provável em índices que contêm grandes blocos de texto (um campo de conteúdo ou descrições longas), certifique-se de testar as consultas com o parâmetro searchMode=Any|All 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 inicial e testes 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 o serviço de pesquisa.

  2. Em 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 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:

    Captura de tela do Gerenciador de Pesquisa com uma consulta de texto completo.

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 (AND, OR, NOT) para pesquisas de termos e frases, e 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 em que ambas dão suporte ao mesmo prefixo e operações boolianas, mas a sintaxe completa fornece mais operadores. No total, há mais operadores para expressões boolianas 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 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 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 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 selecionará 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 selecionará uma delas e o documento correspondente será 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 pesquisáveis e recuperáveis 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 a seguir do índice de exemplo de hotéis, somente os dois últimos campos LastRenovationDate e Rating podem ser classificáveis, um requisito para uso em uma cláusula somente "$orderby".

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

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 ponto principal é que o que você acha que seu índice contém e o que realmente está nele podem ser diferentes. 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 efeito nas consultas, confira Pesquisa de termo parcial e padrões com caracteres especiais.

Conteúdo relacionado

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.