Ajouter un classement sémantique aux requêtes dans Recherche Azure AI

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.

Vous pouvez appliquer le classement sémantique aux requêtes de texte, aux requêtes hybrides et aux requêtes vectorielles si vos documents de recherche contiennent des champs de chaîne et que la requête vectorielle a une représentation textuelle dans le document de recherche.

Cet article explique comment appeler le ranker sémantique sur les requêtes. Il part du principe que vous utilisez les API stables ou d’aperçu les plus récentes. Pour obtenir de l’aide sur les versions antérieures, consultez Migrer le code de classement sémantique.

Conditions préalables

Recherche Azure AI dans n’importe quelle region qui fournit un classement sémantique.
Index de recherche existant avec une configuration sémantique et du contenu de texte enrichi.
Connaissance du classement sémantique.

Note

Les légendes et les réponses sont extraites détaillées du texte dans le document de recherche. Le sous-système sémantique utilise la compréhension de lecture automatique pour reconnaître le contenu ayant les caractéristiques d’une légende ou d’une réponse, mais ne compose pas de nouvelles phrases ou expressions, sauf dans le cas de la réécriture de requête (préversion). Pour cette raison, le contenu qui inclut des explications ou des définitions fonctionne le mieux pour le classement sémantique. Si vous souhaitez une interaction de type chat avec des réponses générées, consultez Récupération agentique ou Génération augmentée par récupération (RAG).

Choisir un client

Vous pouvez utiliser l’un des outils et kits sdk suivants pour créer une requête qui utilise le classement sémantique :

Azure Portal, à l’aide de l'index designer pour ajouter une configuration sémantique.
Visual Studio Code avec un client REST
Kit de développement logiciel (SDK) Azure pour .NET
Kit de développement logiciel (SDK) Azure pour Python
Kit de développement logiciel (SDK) Azure pour Java
Kit de développement logiciel (SDK) Azure pour JavaScript

Éviter les fonctionnalités qui contournent le scoring de pertinence

Quelques fonctionnalités de requête contournent le scoring de pertinence, ce qui les rend incompatibles avec le classement sémantique. Si votre logique de requête inclut les fonctionnalités suivantes, vous ne pouvez pas classer sémantiquement vos résultats :

Une requête avec search=* ou une chaîne de recherche vide, telle que la requête pure filter-only, ne fonctionnera pas, car il n’y a rien à mesurer la pertinence sémantique par rapport à et donc les scores de recherche sont nuls. La requête doit fournir des termes ou des expressions qui peuvent être évalués pendant le traitement et qui produisent des documents de recherche marqués pour la pertinence. Les résultats évalués sont des entrées dans le classificateur sémantique.
Le tri (clauses orderBy) sur des champs spécifiques remplace les scores de recherche et un score sémantique. Étant donné que le score sémantique est censé fournir le classement, l’ajout d’une clause orderby entraîne une erreur HTTP 400 si vous appliquez le classement sémantique sur les résultats ordonnés.

Configurer la requête

Par défaut, les requêtes n’utilisent pas le classement sémantique. Pour utiliser le classement sémantique, deux paramètres différents peuvent être utilisés. Chaque paramètre prend en charge un ensemble différent de formats de requête.

Toutes les requêtes sémantiques, qu’elles soient spécifiées via search plus queryTypeou via semanticQuery, doivent être en texte brut et qu’elles ne peuvent pas être vides. Comme vous pouvez le voir dans le tableau ci-dessous, le queryType-semantic paramètre prend en charge un sous-ensemble de formats de requête.

Paramètre	Recherche en texte brut	Syntaxe de recherche de texte simple	Syntaxe de recherche en texte intégral	Recherche vectorielle	Recherche hybride	Réponses sémantiques et légendes
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

¹queryType=semantic ne peut pas prendre explicitement les valeurs simple ou full car le paramètre queryType est utilisé pour semantic. Les comportements de requête efficaces sont les valeurs par défaut de l’analyseur simple.

² Le semanticQuery paramètre peut être utilisé pour tous les types de requêtes. Toutefois, il n'est pas pris en charge dans le portail Azure Search Explorer.

Quel que soit le paramètre choisi, l’index doit contenir des champs de texte avec du contenu sémantique enrichi et une configuration sémantique.

L’Explorateur de recherche inclut des options de classement sémantique. Rappelez-vous que vous ne pouvez pas définir le paramètre semanticQuery dans le portail Azure.

Accédez à votre service de recherche dans le portail Azure.
Ouvrez un index de recherche et sélectionnez Explorateur de recherche.
Sélectionnez les options de requête. Si vous avez déjà défini une configuration sémantique, elle est sélectionnée par défaut. Si vous n’en avez pas, créez une configuration sémantique pour votre index.
Entrez une requête, telle que « hôtel historique avec de bons aliments », puis sélectionnez Rechercher.

Vous pouvez également sélectionner la vue JSON et coller les définitions dans l’éditeur de requête. Le portail Azure ne prend pas en charge l'utilisation de semanticQuery. La définition de queryType sur "semantic" est requise :

Exemple JSON pour définir le type de requête sur « semantic » que vous pouvez coller dans la vue :

{
  "search": "funky or interesting hotel with good food on site",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "captions": "extractive|highlight-true",
  "answers": "extractive|count-3",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}

Utilisez les documents de recherche pour formuler la requête.

Une réponse inclut automatiquement un @search.rerankerScore. Si vous souhaitez des légendes ou des réponses dans la réponse, activez le classement sémantique en définissant queryTypesemantic ou en définissant semanticQuery et en ajoutant des légendes et des réponses à la demande.

Les exemples suivants de cette section utilisent l’index hotels-sample pour illustrer le classement sémantique avec des réponses sémantiques et des légendes.

Utiliser queryType=semantic

Si vous souhaitez définir queryType sur semantic, collez la requête suivante dans un client web comme modèle. Remplacez par search-service-name le nom de votre service de recherche et remplacez hotels-sample si vous avez un autre nom d’index.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

Définissez queryType à semantic. Cela améliore la précision des résultats de recherche en reclassant les 50 premières correspondances à l’aide d’un modèle de classement formé sur le corpus Bing pour les requêtes exprimées en langage naturel, par opposition aux mots clés. Si vous définissez le type de requête sur sémantique, vous devez également définir semanticConfiguration. Vous pouvez éventuellement définir des réponses si vous souhaitez également renvoyer les 3 premières réponses si l’entrée de requête a été formulée en langage naturel (« qu’est-ce qu’un ...), et vous pouvez éventuellement définir des légendes pour extraire les passages clés des documents classés les plus élevés.
Définissez search comme une requête de texte brut simple. Étant donné que la queryType est définie sur semantic, la syntaxe simple ou la syntaxe Lucene complète ne sont pas prises en charge. Utiliser * ou une chaîne vide n'entraîne aucun classement sémantique de la requête.
Définissez semanticConfiguration sur une configuration sémantique prédéfinie intégrée dans votre index.
Définissez answers pour spécifier si les réponses sémantiques sont incluses dans le résultat. Les valeurs valides pour ce paramètre sont extractive et none. Ce paramètre est valide uniquement si le type de requête est « sémantique ». Lorsqu'il est défini sur « extractif », la requête formule et retourne des réponses à partir des passages clés dans les documents les mieux classés sémantiquement. La valeur par défaut est une réponse, mais vous pouvez spécifier jusqu’à 10 en ajoutant un nombre. Par exemple, "answers": "extractive|count-3" retourne trois réponses. Pour qu’une réponse soit retournée, il doit y avoir du contenu détaillé dans le champ ciblé qui ressemble à une réponse. Les modèles de langage utilisés pour les réponses sont formés pour reconnaître les réponses, et ne les génèrent pas. En outre, la requête elle-même doit ressembler à une question.
Définissez captions pour spécifier si les légendes sémantiques sont incluses dans le résultat. Les valeurs valides sont « none » et « extractif ». La valeur par défaut est « none ». Ce paramètre est valide uniquement si le type de requête est « sémantique ». Lorsqu’elle est définie sur « extractif », la requête retourne des légendes extraites des passages clés dans les documents classés les plus élevés.

Lorsque les légendes sont définies sur « extractive », la mise en surbrillance est activée par défaut et peut être configurée en ajoutant le caractère « | » suivi de l'option highlight-<true/false>, par exemple extractive|highlight-true. Cet exemple retourne des légendes sans surbrillance : extractive|highlight-false.

La base des légendes et des réponses est les champs référencés dans la « semanticConfiguration ». Ces champs sont soumis à une limite combinée de 2 000 tokens ou environ 20 000 caractères. Si vous prévoyez un nombre de jetons dépassant cette limite, envisagez une étape de segmentation des données à l’aide de la compétence fractionnement de texte. Cette approche introduit une dépendance vis-à-vis d’un pipeline d’enrichissement par IA et d’indexeurs.
Définissez highlightPreTag et highlightPostTag si vous souhaitez remplacer la mise en forme de mise en surbrillance par défaut appliquée aux légendes.

Les légendes appliquent la mise en surbrillance sur les passages clés du document qui résument la réponse. La valeur par défaut est <em>. Si vous souhaitez spécifier le type de mise en forme (par exemple, arrière-plan jaune), vous pouvez définir la mise en surbrillancePreTag et highlightPostTag.
Définissez la sélection pour spécifier les champs retournés dans la réponse et « count » pour renvoyer le nombre de correspondances dans l’index. Ces paramètres améliorent la qualité de la demande et la lisibilité de la réponse.
Envoyez la requête pour exécuter la requête et renvoyer les résultats.

Utiliser semanticQuery

En utilisant semanticQuery, vous pouvez appliquer explicitement une syntaxe de texte simple ou une syntaxe de texte intégral, ce qui signifie que vous pouvez désormais effectuer une recherche en champ, une amélioration des termes et une recherche de proximité. Vous pouvez également spécifier une requête vectorielle pure au lieu d’une simple requête hybride.

Ajustez votre requête selon le JSON suivant afin d’utiliser semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

Définissez queryType la syntaxe de recherche que vous utilisez, simple ou complète.
Définissez semanticQuery la requête de texte brut simple que vous souhaitez utiliser pour le classement sémantique. Les requêtes vides ne sont pas prises en charge. Évitez les opérateurs ou toute syntaxe de requête à l’intérieur de la chaîne elle-même.

Utilisez QueryType ou SemanticQuery pour appeler un ranker sémantique sur une requête sémantique. L’exemple following provient de l’équipe Kit de développement logiciel (SDK) Azure.

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

Pour utiliser semanticQuery au lieu de définir queryType et semantic, vous pouvez remplacer l'extrait de code de recherche par l'extrait de code suivant :

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

Évaluer la réponse

Seules les 50 meilleures correspondances des résultats initiaux peuvent être classées selon leur pertinence sémantique. Comme pour toutes les requêtes, une réponse est composée de tous les champs marqués comme récupérables, ou simplement de ces champs répertoriés dans le select paramètre. Une réponse inclut le score de pertinence d’origine et peut également inclure un nombre ou des résultats par lots, selon la façon dont vous avez formulé la demande.

Dans le classement sémantique, la réponse comporte plus d’éléments : un nouveau score de pertinence classé sémantiquement, une légende facultative en texte brut et avec des points forts et une réponse facultative. Si vos résultats n’incluent pas ces éléments supplémentaires, votre requête peut être mal configurée. Pour résoudre le problème, vérifiez la configuration sémantique pour vous assurer qu’elle est spécifiée à la fois dans la définition d’index et la requête.

Dans une application cliente, vous pouvez structurer la page de recherche pour inclure une légende comme description de la correspondance, plutôt que le contenu entier d’un champ spécifique. Cette approche est utile lorsque les champs individuels sont trop denses pour la page des résultats de la recherche.

La réponse de l’exemple de requête ci-dessus (« hôtel intéressant avec restaurant sur site et salle confortable ou zone partagée ») retourne trois réponses ("answers": "extractive|count-e"). Les légendes sont retournées, car la propriété « captions » est définie, avec du texte brut et des versions mises en surbrillance. Si une réponse ne peut pas être déterminée, elle est omise de la réponse. Pour des raisons de concision, cet exemple montre uniquement les trois réponses et les trois résultats de scoring les plus élevés de la requête.

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

Charges de travail attendues

Pour le classement sémantique, attendez-vous à ce qu'un service de recherche prenne en charge jusqu'à 10 requêtes simultanées par réplica.

Le service limite les demandes de classement sémantique si les volumes sont trop élevés. Un message d’erreur contenant ces expressions indique que le service a atteint sa capacité maximale pour le classement sémantique.

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

Si vous prévoyez des exigences de débit cohérentes proches, à ou supérieures à ce niveau, envoyez un ticket de support afin que nous puissions provisionner votre charge de travail.

É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

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-12