Reescrever consultas com o classificador semântico no Pesquisa de IA do Azure (pré-visualização)

Nota

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Importante

Funcionalidades, capacidades ou propriedades assinaladas (pré-visualização) não são abrangidas por um acordo de nível de serviço, não são recomendadas para cargas de trabalho em produção e podem mudar ou ser limitadas antes de se tornarem geralmente disponíveis. Os termos de pré-visualização do Pesquisa de IA do Azure aplicam-se a todas as funcionalidades de pré-visualização, sejam independentes ou parte de uma funcionalidade geralmente disponível.

A reescrita de consultas (pré-visualização) é o processo de transformar a consulta de um utilizador numa mais eficaz, adicionando mais termos e refinando os resultados de 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 consultas melhora os resultados da classificação semântica ao corrigir erros tipográficos ou ortográficos nas consultas dos utilizadores e expandir consultas com sinónimos.

A pesquisa com reescrita de consultas funciona assim:

  • A consulta do utilizador é enviada pela propriedade search na requisiçã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 utiliza a consulta original e as consultas reescritas para recuperar os resultados da pesquisa.

A reescrita de consultas é uma funcionalidade opcional. Sem reescrita de consultas, o serviço de pesquisa usa apenas a consulta original para recuperar os resultados.

Nota

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

Pré-requisitos

Dica

Conteúdos que incluem explicações ou definições funcionam melhor para a classificação semântica.

Faça um pedido de pesquisa com reformulações de consulta

Neste exemplo da API REST, use Documentos de Pesquisa (pré-visualização) para formular o pedido.

  1. Cole o pedido seguinte num cliente web como 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 seu serviço de pesquisa.

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

    • Defina "pesquisar" para uma consulta de pesquisa em texto completo. A propriedade de pesquisa é necessária para reescrita de consultas, a menos que especifique consultas vetoriais. Se especificar consultas vetoriais, então o texto de "pesquisa" deve corresponder à "text" propriedade do "vectorQueries" objeto. A sua cadeia de pesquisa pode suportar tanto a sintaxe simples como a sintaxe completa Lucene.

    • Defina "semanticConfiguration" para uma configuração semântica pré-definida embutida no seu índice.

    • Defina "queryType" para "semantic". Ou tens de definir "queryType" como "semantic" ou incluir uma propriedade "semanticQuery" não vazia na requisição. A classificação semântica é necessária para a reescrita de consultas.

    • Definir "queryRewrites" para "generative|count-5" para obter até cinco reformulações de consulta. Podes definir a contagem para qualquer valor entre 1 e 10.

    • Como solicitou reescritas de consultas definindo a propriedade "queryRewrites", deve definir "queryLanguage" como o idioma do texto de pesquisa. O serviço de pesquisa utiliza a mesma linguagem para as reescritas das consultas. Neste exemplo, usas "en-US". Os locais suportados 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 "debug" como "queryRewrites" para obter as reescritas da consulta na resposta.

      Dica

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

    • Defina "topo" para 1 para devolver apenas o resultado principal da pesquisa.

  2. Envie o pedido para executar a consulta e devolva os resultados.

A seguir, avalia os resultados da pesquisa com as alterações na consulta.

Avaliar a resposta

Aqui está um exemplo de resposta que inclui a reformulação de consultas.

"@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-chave a ter em conta:

  • Como definiste a propriedade "debug" para "queryRewrites" durante os testes, a resposta inclui um @search.debug objeto com a consulta de texto de entrada e as reescritas de consultas.
  • Como definiste a propriedade "queryRewrites" para "generative|count-5", a resposta inclui até cinco reformulações de consulta.
  • O "inputQuery" valor é a consulta enviada ao modelo generativo para reescrita da consulta. A consulta de entrada nem sempre é a mesma que a consulta do "search" utilizador.

Aqui está um exemplo de resposta sem reescrições de perguntas.

"@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 vetoriais com reescrita de consultas

Pode incluir consultas vetoriais no seu pedido de pesquisa para combinar a pesquisa por palavras-chave e a pesquisa vetorial num único pedido e uma resposta unificada.

Aqui está um exemplo de uma consulta que inclui uma consulta vetorial com reformulações da consulta. Modificar um exemplo anterior para incluir uma consulta vetorial.

  • Adicione um objeto "vectorQueries" ao pedido. Este objeto inclui uma consulta vetorial com o "tipo" definido como "text".
  • O valor "texto" é o mesmo que o valor "pesquisa". Estes valores devem ser idênticos para que a reescrita de consultas 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 reescritas de consultas tanto para a consulta de texto como para a consulta vetorial.

Reescrever consultas de teste para depuração

Deve testar as reescritas das suas consultas para garantir que estão a funcionar como esperado. Defina a "debug": "queryRewrites" propriedade no seu pedido de consulta para que a consulta seja reescrita na resposta. A configuração "debug" é opcional para fins de teste. Para melhor desempenho, não defina esta propriedade em produção.

Razões de resposta parcial

Pode observar que a resposta de depuração (teste) inclui um array vazio 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 valor de "Transitório". Esta mensagem significa que pelo menos uma das consultas não foi concluída.
  • A resposta inclui também uma @search.semanticQueryRewriteResultType propriedade com o valor "OriginalQueryOnly". Esta mensagem significa que as reescritas das consultas não estão disponíveis. Apenas a consulta original é usada para recuperar os resultados da pesquisa.

Próximos passos

A classificação semântica pode ser usada em consultas híbridas que combinam pesquisa por palavras-chave e pesquisa vetorial num único pedido e numa resposta unificada.

Consulta híbrida com classificador semântico

  • Última atualização a