Réécrire des requêtes avec un ranker sémantique dans Recherche Azure AI (préversion)

Note

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Important

Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.

La réécriture des requêtes (préversion) est le processus de transformation de la requête d’un utilisateur en une requête plus efficace, en ajoutant d’autres termes et en affinant les résultats de la recherche. Le service de recherche envoie la requête de recherche (ou une variante) à un modèle de génération qui génère d’autres requêtes.

La réécriture des requêtes améliore les résultats du classement sémantique en corrigeant les fautes de frappe ou les erreurs d’orthographe dans les requêtes utilisateur et en développant les requêtes avec des synonymes.

La recherche avec la réécriture des requêtes fonctionne comme suit :

  • La requête utilisateur est envoyée via la search propriété dans la requête.
  • Le service de recherche envoie la requête de recherche (ou une variante) à un modèle de génération qui génère d’autres requêtes.
  • Le service de recherche utilise la requête d’origine et les requêtes réécrites pour récupérer les résultats de la recherche.

La réécriture des requêtes est une fonctionnalité facultative. Sans réécriture de requête, le service de recherche utilise simplement la requête d’origine pour récupérer les résultats de la recherche.

Note

Les requêtes réécrites peuvent ne pas contenir tous les termes exacts que la requête d’origine avait. Cela peut avoir un impact sur les résultats de la recherche si la requête était très spécifique et exigeait des correspondances exactes pour les identificateurs uniques ou les codes de produit.

Conditions préalables

Conseil

Le contenu qui inclut des explications ou des définitions fonctionne le mieux pour le classement sémantique.

Effectuer une requête de recherche avec des réécritures de requête

Dans cet exemple d’API REST, utilisez Search Documents (aperçu) pour formuler la requête.

  1. Collez la requête suivante dans un client web en tant que modèle.

    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
}

    • Remplacez par search-service-name le nom de votre service de recherche.

    • Remplacez hotels-sample par votre nom d’index s’il est différent.

    • Définissez « search » sur une requête de recherche en texte intégral. La propriété de recherche est requise pour la réécriture des requêtes, sauf si vous spécifiez des requêtes vectorielles. Si vous spécifiez des requêtes vectorielles, le texte « search » doit correspondre à la "text" propriété de l’objet "vectorQueries" . Votre chaîne de recherche peut prendre en charge la syntaxe simple ou la syntaxe Lucene complète.

    • Définissez « semanticConfiguration » sur une configuration sémantique prédéfinie incorporée dans votre index.

    • Définissez « queryType » sur « sémantique ». Vous devez soit définir « queryType » sur « semantic », soit inclure une propriété « semanticQuery » non vide dans la requête. Le classement sémantique est requis pour la réécriture des requêtes.

    • Définissez « queryRewrites » sur « générative|count-5 » pour obtenir jusqu’à cinq réécritures de requête. Vous pouvez définir le nombre sur n’importe quelle valeur comprise entre 1 et 10.

    • Étant donné que vous avez demandé des réécritures de requête en définissant la propriété « queryRewrites », vous devez définir « queryLanguage » sur la langue du texte de recherche. Le service de recherche utilise la même langue pour les réécritures de requête. Dans cet exemple, vous utilisez «en-US». Les paramètres régionaux pris en charge sont : 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.

    • Définissez « debug » sur « queryRewrites » pour obtenir les réécritures de requête dans la réponse.

      Conseil

      "debug": "queryRewrites" Défini uniquement à des fins de test. Pour de meilleures performances, n’utilisez pas de débogage en production.

    • Définissez « top » sur 1 pour renvoyer uniquement le résultat de recherche supérieur.

  2. Envoyez la requête pour exécuter la requête et renvoyer les résultats.

Ensuite, vous évaluez les résultats de la recherche avec les réécritures de requête.

Évaluer la réponse

Voici un exemple de réponse qui inclut des réécritures de requête :

"@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
  }
]

Voici quelques points clés à noter :

  • Étant donné que vous définissez la propriété « debug » sur « queryRewrites » pour le test, la réponse inclut un @search.debug objet avec la requête d’entrée de texte et les réécritures de requête.
  • Étant donné que vous définissez la propriété « queryRewrites » sur « générative|count-5 », la réponse inclut jusqu’à cinq réécritures de requête.
  • La "inputQuery" valeur est la requête envoyée au modèle génératif pour la réécriture des requêtes. La requête d’entrée n’est pas toujours la même que celle de l’utilisateur "search".

Voici un exemple de réponse sans réécriture de requête.

"@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
  }
]

Requêtes vectorielles avec réécriture de requête

Vous pouvez inclure des requêtes vectorielles dans votre requête de recherche pour combiner la recherche de mots clés et la recherche vectorielle dans une seule requête et une réponse unifiée.

Voici un exemple de requête qui inclut une requête vectorielle avec des réécritures de requête. Modifiez un exemple précédent pour inclure une requête vectorielle.

  • Ajoutez un objet « vectorQueries » à la requête. Cet objet inclut une requête vectorielle avec le « type » défini sur « text ».
  • La valeur « text » est identique à la valeur « search ». Ces valeurs doivent être identiques pour que la réécriture des requêtes fonctionne.
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
}

La réponse inclut les réécritures de requête pour la requête de texte et la requête vectorielle.

Tester les réécritures de requête avec débogage

Vous devez tester vos réécritures de requête pour vous assurer qu’elles fonctionnent comme prévu. Définissez la propriété "debug": "queryRewrites" dans votre requête pour obtenir les réécritures de requête dans la réponse. Le paramètre "debug" est facultatif à des fins de test. Pour de meilleures performances, ne définissez pas cette propriété en environnement de production.

Raisons de réponse partielle

Vous pouvez observer que la réponse de débogage (test) inclut un tableau vide pour les propriétés text.rewrites et 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
}

Dans l’exemple précédent :

  • La réponse inclut une @search.semanticPartialResponseReason propriété avec la valeur « Temporaire ». Ce message signifie qu’au moins une des requêtes n’a pas pu être terminée.
  • La réponse inclut également une @search.semanticQueryRewriteResultType propriété avec la valeur « OriginalQueryOnly ». Ce message signifie que les réécritures de requête ne sont pas disponibles. Seule la requête d’origine est utilisée pour récupérer les résultats de la recherche.

Étapes suivantes

Le classement sémantique peut être utilisé dans les requêtes hybrides qui combinent la recherche de mots clés et la recherche vectorielle dans une seule requête et une réponse unifiée.

Requête hybride avec classement sémantique

  • Last updated on