Reescrever consultas com o classificador semântico na Pesquisa de IA do Azure (versão prévia)

A reescrita de consulta é o processo de transformar a consulta de um usuário em uma mais eficaz, adicionando mais termos e refinando os resultados da pesquisa. O serviço de pesquisa envia a consulta de pesquisa (ou uma variação dela) para um modelo generativo que gera consultas alternativas.

A reescrita de consulta melhora os resultados de classificação semântica corrigindo erros de digitação ou ortografia nas consultas de usuário e expandindo consultas com sinônimos.

A pesquisa com a reescrita de consulta funciona da seguinte maneira:

• A consulta de usuário é enviada por meio da propriedade search na solicitação.
• O serviço de pesquisa envia a consulta de pesquisa (ou uma variação dela) para um modelo generativo que gera consultas alternativas.
• O serviço de pesquisa usa a consulta original e as consultas reescritas para recuperar os resultados da pesquisa.

A reescrita de consulta é um recurso opcional. Sem a reescrita de consulta, o serviço de pesquisa usa apenas a consulta original para recuperar os resultados da pesquisa.

Pré-requisitos

• Um serviço de pesquisa, camada básica ou superior, no Norte da Europa ou Sudeste Asiático.

• O classificador semântico deve estar habilitado. Ele está habilitado por padrão em serviços de pesquisa mais recentes. Examine a classificação semântica se você precisar de uma introdução ao recurso.

• Um índice de pesquisa existente com uma configuração semântica e conteúdo de rich text. Os exemplos neste guia usam os dados de exemplo hotels-sample-index para demonstrar a reescrita da consulta. Você pode usar seus próprios dados e índice para testar a reescrita de consulta.

• Para seguir as instruções neste artigo, você precisa de um cliente Web que dê suporte a solicitações da API REST. Os exemplos neste guia foram testados com o Visual Studio Code com a extensão cliente REST.

Fazer uma solicitação de pesquisa com reescritas de consulta

Neste exemplo de API REST, use Documentos de Pesquisa (versão prévia) para formular a solicitação.

1. Cole a solicitação a seguir em um cliente Web como um modelo.

   POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-03-01-preview
   {
       "search": "newer hotel near the water with a great restaurant",
       "semanticConfiguration":"en-semantic-config",
       "queryType":"semantic",
       "queryRewrites":"generative|count-5",
       "queryLanguage":"en-US",
       "debug":"queryRewrites",
       "top": 1
   }
   

   • Substitua search-service-name pelo nome do serviço de pesquisa.

   • Substitua hotels-sample-index pelo nome do índice se ele for diferente.

   • Defina "pesquisa" como uma consulta de pesquisa de texto completo. A propriedade de pesquisa é necessária para a reescrita de consulta, a menos que você especifique consultas de vetor. Se você especificar consultas de vetor, o texto de "search" deverá corresponder à propriedade "text" do objeto "vectorQueries". Sua cadeia de caracteres de pesquisa pode dar suporte à sintaxe simples ou sintaxe Lucene completa.

   • Defina "semanticConfiguration" como uma configuração semântica predefinida inserida em seu índice.

   • Defina "queryType" como "semantic". Você precisa definir "queryType" como "semântico" ou incluir uma propriedade "semanticQuery" não úmida na solicitação. A classificação semântica é necessária para a reescrita de consulta.

   • Defina "queryRewrites" como "generative|count-5" para obter até cinco regravações de consulta. Você pode definir a contagem para qualquer valor entre 1 e 10.

   • Como solicitamos reescritas de consulta definindo a propriedade "queryRewrites", devemos definir "queryLanguage" como a linguagem de texto de pesquisa. O serviço de pesquisa usa o mesmo idioma para as reformulações de consulta. Neste exemplo, você usa "en-US". As localidades com suporte são: en-AU, en-CA, en-GB, en-IN, en-US, ar-EG, ar-JO, ar-KW, ar-MA, ar-SA, bg-BG, bn-IN, ca-ES, cs-CZ, da-DK, de-DE, el-GR, es-ES, es-MX, et-EE, eu-ES, fa-AE, fi-FI, fr-CA, fr-FR, ga-IE, gl-ES, gu-IN, he-IL, hi-IN, hr-BA, hr-HR, hu-HU, hy-AM, id-ID, is-IS, it-IT, ja-JP, kn-IN, ko-KR, lt-LT, lv-LV, ml-IN, mr-IN, ms-BN, ms-MY, nb-NO, nl-BE, nl-NL, no-NO, pa-IN, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SL, sr-BA, sr-ME, sr-RS, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, ur-PK, vi-VN, zh-CN, zh-TW.

   • Defina "depuração" como "queryRewrites" para obter as reescritas de consulta na resposta.

     Dica

     Defina apenas "debug": "queryRewrites" para fins de teste. Para melhorar o desempenho, não use debug em produção.

   • Defina "top" como 1 para retornar apenas o resultado da pesquisa superior.

2. Envie a solicitação para executar a consulta e retornar os resultados.

Em seguida, avaliamos os resultados da pesquisa com as reescritas de consulta.

Avaliar a resposta

Aqui está um exemplo de uma resposta que inclui reescritas de consulta:

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "newer hotel near the water with a great restaurant",
      "rewrites": [
        "new waterfront hotels with top-rated eateries",
        "new waterfront hotels with top-rated restaurants",
        "new waterfront hotels with excellent dining",
        "new waterfront hotels with top-rated dining",
        "new water-side hotels with top-rated restaurants"
      ]
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 58.992092,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, ___location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

Aqui estão alguns pontos importantes a serem observados:

• Como definimos a propriedade "depurar" como "queryRewrites" para teste, a resposta inclui um objeto @search.debug com a consulta de entrada de texto e regravações de consulta.
• Como você define a propriedade "queryRewrites" como "generative|count-5", a resposta inclui até cinco regravações de consulta.
• O valor "inputQuery" é a consulta enviada ao modelo generativo para reescrita de consulta. A consulta de entrada nem sempre é igual à consulta "search" do usuário.

Aqui está um exemplo de uma resposta sem reescritas de consulta.

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "",
      "rewrites": []
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 7.774868,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, ___location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

Consultas de vetor com reescrita de consulta

É possível incluir consultas de vetor em sua solicitação de pesquisa para combinar pesquisa de palavra-chave e busca em vetores em uma única solicitação e uma resposta unificada.

Aqui está um exemplo de uma consulta que inclui uma consulta de vetor com reescritas de consulta. Modifique um exemplo anterior para incluir uma consulta de vetor.

• Adicione um objeto "vectorQueries" à solicitação. Esse objeto inclui uma consulta de vetor com "kind" definido como "text".
• O valor "text" é o mesmo que o valor "search". Esses valores devem ser idênticos para que a reescrita de consulta funcione.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-03-01-preview
{
    "search": "newer hotel near the water with a great restaurant",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "newer hotel near the water with a great restaurant",
            "k": 50,
            "fields": "Description",
            "queryRewrites": "generative|count-3"
        }
    ],
    "semanticConfiguration":"en-semantic-config",
    "queryType":"semantic",
    "queryRewrites":"generative|count-5",
    "queryLanguage":"en-US",
    "top": 1
}

A resposta inclui reformulações de consulta tanto para a consulta de texto quanto para a consulta de vetor.

Testar regravações de consulta com depuração

Você deve testar as reescritas de consulta para garantir que elas estejam funcionando conforme o esperado. Defina a propriedade "debug": "queryRewrites" em sua solicitação de consulta para obter as reescritas de consulta na resposta. Definir "debug" é opcional para fins de teste. Para obter melhor desempenho, não configure essa propriedade em ambiente de produção.

Motivos parciais de resposta

Você pode observar que a resposta de depuração (teste) inclui uma matriz vazia para as propriedades text.rewrites e vectors.

{
  "@odata.context": "https://demo-search-svc.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
  "@search.debug": {
    "semantic": null,
    "queryRewrites": {
      "text": {
        "rewrites": []
      },
      "vectors": []
    }
  },
  "@search.semanticPartialResponseReason": "Transient",
  "@search.semanticQueryRewriteResultType": "OriginalQueryOnly",
  //... more properties redacted for brevity
}

No exemplo anterior:

• A resposta inclui uma propriedade @search.semanticPartialResponseReason com um valor de "Transitório". Essa mensagem significa que pelo menos uma das consultas não foi concluída.
• A resposta também inclui uma propriedade @search.semanticQueryRewriteResultType com um valor "OriginalQueryOnly". Essa mensagem significa que as reescritas de consulta não estão disponíveis. Somente a consulta original é usada para recuperar os resultados da pesquisa.

Próximas etapas

A classificação semântica pode ser usada em consultas híbridas que combinam busca de palavra-chave e busca em vetores em uma única solicitação e uma resposta unificada.