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

Nota

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

A reescrita de consulta (versão prévia) é 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 gerador que gera consultas alternativas.

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

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

  • A consulta do usuário é enviada por meio da search propriedade na solicitação.
  • O serviço de pesquisa envia a consulta de pesquisa (ou uma variação dela) para um modelo gerador 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.

Nota

As consultas reescritas podem não conter todos os termos exatos que a consulta original tinha. Isso poderá afetar os resultados da pesquisa se a consulta for altamente específica e exigir correspondências exatas para identificadores exclusivos ou códigos de produto.

Pré-requisitos

Dica

O conteúdo que inclui explicações ou definições funciona melhor para classificação semântica.

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/docs/search?api-version=2026-08-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 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 vetoriais. Se você especificar consultas de vetor, o texto de "pesquisa" deverá corresponder à "text" propriedade do "vectorQueries" objeto. 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 "semântico". 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 da 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 nas regravaçõ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

      "debug": "queryRewrites" Definido apenas para fins de teste. Para melhorar o desempenho, não use a depuração 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, você avalia os resultados da pesquisa com as reformulações 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 para o modelo generativo para reescrita de consulta. A consulta de entrada nem sempre é igual à consulta do usuário "search".

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

Você pode incluir consultas vetoriais em sua solicitação de pesquisa para combinar pesquisa de palavra-chave e pesquisa de vetor 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 o "tipo" definido como "texto".
  • O valor "texto" é igual ao valor de "pesquisa". Esses valores devem ser idênticos para que a reescrita de consulta funcione.
POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-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 para a consulta de texto e a consulta vetorial.

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

Você deve testar as regravações de consulta para garantir funcionem conforme o esperado. Defina a propriedade "debug": "queryRewrites" em sua solicitação de consulta para obter as reescritas de consulta na resposta. A configuração "debug" é opcional para fins de teste. Para obter melhor desempenho, não configure esta 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')/$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 @search.semanticPartialResponseReason propriedade com um valor de "Transient". Essa mensagem significa que pelo menos uma das consultas não foi concluída.
  • A resposta também inclui uma @search.semanticQueryRewriteResultType propriedade com um valor de "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 pesquisa de palavra-chave e pesquisa de vetor em uma única solicitação e uma resposta unificada.

Consulta híbrida com rankeador semântico

  • Última atualização em