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

Article
12/10/2024

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

Cet article explique comment appeler le classeur 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.

Prérequis

Un service de recherche, de niveau Essentiel ou supérieur, disposant du classeur sémantique activé.
Un index de recherche existant avec une configuration sémantique et du contenu de texte enrichi.
Passez en revue Classement sémantique si vous avez besoin d’une introduction à la fonctionnalité.

Remarque

Les légendes et réponses sont extraites du texte littéral du document de recherche. Le sous-système sémantique utilise la compréhension de la lecture automatique pour reconnaître le contenu ayant les caractéristiques d’une légende ou d’une réponse, mais il ne compose pas de nouvelles phrases ou expressions. Pour cette raison, le contenu qui comprend des explications ou des définitions est le mieux adapté au classement sémantique. Si vous voulez une interaction de type conversation avec des réponses générées, consultez RAG (Génération Augmentée de Récupération).

Choisissez un client

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

Portail Azure, avec le concepteur d’index 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) pour JavaScript

Éviter les fonctionnalités qui ignorent le score de pertinence

Quelques interrogations des données par requête contournent le scoring de pertinence, ce qui les rend incompatibles avec le classement sémantique. Si la logique de votre requête comprend 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, comme une requête de filtrage uniquement, ne va pas fonctionner, car il n’y a rien à quoi mesurer la pertinence sémantique. Les scores de la recherche ont ainsi la valeur zéro. La requête doit contenir des expressions ou des termes pouvant être évalués au cours du traitement.
Le tri (clauses orderBy) sur des champs spécifiques l’emporte sur les scores de recherche et un score sémantique. Comme 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 des 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 scénarios.

Les requêtes sémantiques, qu’elles soient spécifiées via search plus queryTypeou semanticQuery, doivent être du texte brut et ne peuvent pas être vides. Les requêtes vides n’entraînent pas d’application de classement sémantique aux résultats.

Paramètre de l’éditeur de classement sémantique	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 en charge les valeurs de simple ou de full explicites, 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 paramètre semanticQuery peut être utilisé pour tous les types de requêtes. Toutefois, il n’est pas pris en charge dans le portail Azure Explorateur de recherche.

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.

Connectez-vous au portail Azure.
Ouvrez un index de recherche et sélectionnez Explorateur de recherche.
Sélectionnez 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 une bonne nourriture », puis sélectionnez Rechercher.

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

Exemple JSON pour définir le type de requête sur sémantique 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 Recherche dans des documents pour formuler la demande.

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 queryType à semantic ou en définissant semanticQuery et en ajoutant des légendes et des réponses à la demande.

Les exemples suivants de cette section utilisent les hotels-sample-index 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 en tant que modèle. Remplacez search-service-name par le nom de votre service de recherche, puis remplacez hotels-sample-index si vous avez un autre nom d’index.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-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"
}

Affectez la valeur queryType à semantic.
Définissez search sur une requête de texte brut simple. Étant donné que la queryType est définie sur semantic, syntaxe simple ou syntaxe Lucene complète ne sont pas prises en charge. L’approvisionnement de * ou d’une chaîne vide n’entraîne pas d’application de classement sémantique à la requête.
Définissez semanticConfiguration sur une configuration sémantique prédéfinieincorporée dans votre index.
Définissez answers pour spécifier si réponses sémantiques sont incluses dans le résultat. Actuellement, la seule valeur valide pour ce paramètre est extractive. Les réponses peuvent être configurées pour être retournées au nombre de 10 maximum. La valeur par défaut est 1. Cet exemple montre un nombre de trois réponses :extractive|count-3.

Les réponses ne sont pas garanties à chaque demande. Pour obtenir une réponse, la requête doit ressembler à une question, et le contenu doit inclure du texte qui ressemble à une réponse.
Définissez captions pour spécifier si les légendes sémantiques sont incluses dans le résultat. Actuellement, la seule valeur valide pour ce paramètre est extractive. Les légendes peuvent être configurées pour renvoyer des résultats avec ou sans surbrillance. Par défaut, les légendes sont renvoyées avec surbrillance. Cet exemple renvoie des légendes sans surbrillance : extractive|highlight-false.

Les légendes et les réponses sont basées sur les champs référencés dans « semanticConfiguration ». Ces champs sont soumis à une limite combinée de l’ordre de 2 000 jetons ou environ 20 000 caractères. Si vous prévoyez un nombre de jetons supérieur à cette limite, envisagez une étape de fractionnement des données en blocs en utilisant 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 le format de surbrillance aux passages importants dans le document qui résument la réponse. Par défaut, il s’agit de <em>. Si vous souhaitez spécifier le type de mise en forme (par exemple un arrière-plan jaune), vous pouvez définir highlightPreTag et highlightPostTag.
Définissez sélectionnez 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 requête et la lisibilité de la réponse.
Envoyez la demande d’exécution de la requête et retournez les résultats.

Utiliser semanticQuery

À l’aide de semanticQuery, vous pouvez appliquer explicitement syntaxe de texte simple ou 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 un erequête vectorielle pure au lieu d’un simple hybride.

Ajustez votre requête au code JSON suivant pour utiliser semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-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 sur la syntaxe de recherche que vous utilisez, simple ou complète.
Définissez semanticQuery sur 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 le classeur sémantique sur une requête sémantique. L’exemple suivant provient de l’équipe 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 sur semantic, l’extrait de code de recherche peut être remplacé 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 premières correspondances des résultats initiaux peuvent être classées de façon sémantique. Comme pour toutes les requêtes, une réponse est composée de tous les champs marqués comme étant récupérables, ou uniquement des champs listés dans le paramètre select. Une réponse inclut le score de pertinence d’origine et peut également inclure un nombre, ou des résultats par lot, en fonction de 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 mise en évidence ainsi qu’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 dans un premier temps, vérifiez la configuration sémantique pour vous assurer qu’elle est spécifiée 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 l’intégralité du contenu 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 pour l’exemple de requête ci-dessus (« interesting hotel with restaurant on site and cozy lobby or shared area » (hôtel intéressant avec restaurant sur place et hall d’entrée ou espace commun confortable)) 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 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 seulement 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, vous devez vous attendre à ce qu’un service de recherche prenne en charge jusqu’à 10 requêtes simultanées par réplica.

Le service limite les requêtes de classement sémantique si les volumes sont trop élevés. Un message d’erreur qui inclut ces expressions indique que le service a atteint sa capacité 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 de ce niveau, à ce niveau ou supérieures à ce niveau, envoyez un ticket de support afin que nous puissions approvisionner votre charge de travail.

Étapes suivantes

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

Requête hybride avec classeur sémantique

Partager via