Démarrage rapide : Classement sémantique

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, vous utilisez un IDE et la bibliothèque cliente Azure.Search.Documents pour ajouter un classement sémantique à un index de recherche existant.

Nous vous recommandons visual Studio pour ce guide de démarrage rapide.

Conseil / Astuce

Vous pouvez télécharger le code source pour commencer par un projet terminé ou suivre ces étapes pour créer votre propre code.

Installer des bibliothèques

Démarrez Visual Studio et ouvrez le quickstart-semantic-search.sln ou créez un projet à l’aide d’un modèle d’application console.
Dans Outils>Gestionnaire de package NuGet, sélectionnez Gérer les packages NuGet pour la solution....
Sélectionnez Parcourir.
Recherchez le package Azure.Search.Documents et sélectionnez la dernière version stable.
Recherchez le package Azure.Identity et sélectionnez la dernière version stable.
Sélectionnez Installer pour ajouter l’assembly à votre projet et à votre solution.

Si vous vous êtes connecté au portail Azure, vous êtes connecté à Azure. Si vous n’êtes pas sûr, utilisez Azure CLI ou Azure PowerShell pour vous connecter : az login ou az connect. Si vous avez plusieurs locataires et abonnements, consultez démarrage rapide : Se connecter sans clé pour obtenir de l’aide sur la connexion.

Mettre à jour l’index

Dans cette section, vous mettez à jour un index de recherche pour inclure une configuration sémantique. Le code obtient la définition d’index du service de recherche et ajoute une configuration sémantique.

Ouvrez le projet BuildIndex dans Visual Studio. Le programme se compose du code suivant.

Ce code utilise un SearchIndexClient pour mettre à jour un index sur votre service de recherche.

class BuildIndex
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        await ListIndexesAsync(endpoint, credential);
        await UpdateIndexAsync(endpoint, credential, indexName);
    }

    // Print a list of all indexes on the search service
    // You should see hotels-sample-index in the list
    static async Task ListIndexesAsync(string endpoint, Azure.Core.TokenCredential credential)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            var indexes = indexClient.GetIndexesAsync();

            Console.WriteLine("Here's a list of all indexes on the search service. You should see hotels-sample-index:");
            await foreach (var index in indexes)
            {
                Console.WriteLine(index.Name);
            }
            Console.WriteLine(); // Add an empty line for readability
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error listing indexes: {ex.Message}");
        }
    }

    static async Task UpdateIndexAsync(string endpoint, Azure.Core.TokenCredential credential, string indexName)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            // Get the existing definition of hotels-sample-index
            var indexResponse = await indexClient.GetIndexAsync(indexName);
            var index = indexResponse.Value;

            // Add a semantic configuration
            const string semanticConfigName = "semantic-config";
            AddSemanticConfiguration(index, semanticConfigName);

            // Update the index with the new information
            var updatedIndex = await indexClient.CreateOrUpdateIndexAsync(index);
            Console.WriteLine("Index updated successfully.");

            // Print the updated index definition as JSON
            var refreshedIndexResponse = await indexClient.GetIndexAsync(indexName);
            var refreshedIndex = refreshedIndexResponse.Value;
            var jsonOptions = new JsonSerializerOptions { WriteIndented = true };
            string indexJson = JsonSerializer.Serialize(refreshedIndex, jsonOptions);
            Console.WriteLine($"Here is the revised index definition:\n{indexJson}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error updating index: {ex.Message}");
        }
    }

    // This is the semantic configuration definition
    static void AddSemanticConfiguration(SearchIndex index, string semanticConfigName)
    {
        if (index.SemanticSearch == null)
        {
            index.SemanticSearch = new SemanticSearch();
        }
        var configs = index.SemanticSearch.Configurations;
        if (configs == null)
        {
            throw new InvalidOperationException("SemanticSearch.Configurations is null and cannot be assigned. Your service must be Basic tier or higher.");
        }
        if (!configs.Any(c => c.Name == semanticConfigName))
        {
            var prioritizedFields = new SemanticPrioritizedFields
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields = { new SemanticField("Description") },
                KeywordsFields = { new SemanticField("Tags") }
            };

            configs.Add(
                new SemanticConfiguration(
                    semanticConfigName,
                    prioritizedFields
                )
            );
            Console.WriteLine($"Added new semantic configuration '{semanticConfigName}' to the index definition.");
        }
        else
        {
            Console.WriteLine($"Semantic configuration '{semanticConfigName}' already exists in the index definition.");
        }
        index.SemanticSearch.DefaultConfigurationName = semanticConfigName;
    }
}

Remplacez l’URL du service de recherche par un point de terminaison valide.
Exécutez le programme.
La sortie est enregistrée dans une fenêtre de console à partir de Console.WriteLine. Vous devez voir les messages pour chaque étape, y compris le JSON du schéma d’index avec la nouvelle configuration sémantique incluse.

Exécuter des requêtes sémantiques

Dans cette section, le programme exécute plusieurs requêtes sémantiques dans la séquence.

Ouvrez le projet QueryIndex dans Visual Studio. Le programme se compose du code suivant.

Ce code utilise un SearchClient pour envoyer des requêtes à un index.

class SemanticQuery
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        var client = new SearchClient(new Uri(endpoint), indexName, credential);

        // Query 1: Simple query
        string searchText = "walking distance to live music";
        Console.WriteLine("\nQuery 1: Simple query using the search string 'walking distance to live music'.");
        await RunQuery(client, searchText, new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Simple,
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        });
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 2: Semantic query (no captions, no answers)
        Console.WriteLine("\nQuery 2: Semantic query (no captions, no answers) for 'walking distance to live music'.");
        var semanticOptions = new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Semantic,
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config"
            },
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        };
        await RunQuery(client, searchText, semanticOptions);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 3: Semantic query with captions
        Console.WriteLine("\nQuery 3: Semantic query with captions.");
        var captionsOptions = new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Semantic,
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config",
                QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
                {
                    HighlightEnabled = true
                }
            },
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        };
        // Add the field(s) you want captions for to the QueryCaption.Fields collection
        captionsOptions.HighlightFields.Add("Description");
        await RunQuery(client, searchText, captionsOptions, showCaptions: true);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 4: Semantic query with answers
        // This query uses different search text designed for an answers scenario
        string searchText2 = "what's a good hotel for people who like to read";
        searchText = searchText2; // Update searchText for the next query
        Console.WriteLine("\nQuery 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.");
        var answersOptions = new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Semantic,
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config",
                QueryAnswer = new QueryAnswer(QueryAnswerType.Extractive)
            },
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        };
        await RunQuery(client, searchText2, answersOptions, showAnswers: true);

        static async Task RunQuery(
        SearchClient client,
        string searchText,
        SearchOptions options,
        bool showCaptions = false,
        bool showAnswers = false)
        {
            try
            {
                var response = await client.SearchAsync<SearchDocument>(searchText, options);

                if (showAnswers && response.Value.SemanticSearch?.Answers != null)
                {
                    Console.WriteLine("Extractive Answers:");
                    foreach (var answer in response.Value.SemanticSearch.Answers)
                    {
                        Console.WriteLine($"  {answer.Highlights}");
                    }
                    Console.WriteLine(new string('-', 40));
                }

                await foreach (var result in response.Value.GetResultsAsync())
                {
                    var doc = result.Document;
                    // Print captions first if available
                    if (showCaptions && result.SemanticSearch?.Captions != null)
                    {
                        foreach (var caption in result.SemanticSearch.Captions)
                        {
                            Console.WriteLine($"Caption: {caption.Highlights}");
                        }
                    }
                    Console.WriteLine($"HotelId: {doc.GetString("HotelId")}");
                    Console.WriteLine($"HotelName: {doc.GetString("HotelName")}");
                    Console.WriteLine($"Description: {doc.GetString("Description")}");
                    Console.WriteLine($"@search.score: {result.Score}");

                    // Print @search.rerankerScore if available
                    if (result.SemanticSearch != null && result.SemanticSearch.RerankerScore.HasValue)
                    {
                        Console.WriteLine($"@search.rerankerScore: {result.SemanticSearch.RerankerScore.Value}");
                    }
                    Console.WriteLine(new string('-', 40));
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error querying index: {ex.Message}");
            }
        }
    }
}

Remplacez l’URL du service de recherche par un point de terminaison valide.
Exécutez le programme.
La sortie est enregistrée dans une fenêtre de console à partir de Console.WriteLine. Vous devez voir les résultats de recherche pour chaque requête.

Sortie pour la requête sémantique (aucune légende ou réponse)

Cette sortie provient de la requête sémantique, sans légendes ni réponses. La chaîne de requête est « concert de musique proche à pied ».

Ici, les résultats initiaux de la requête de terme sont rescorés à l’aide des modèles de rang sémantique. Pour ce jeu de données et cette requête particuliers, les premiers résultats sont dans des positions similaires. Les effets du classement sémantique sont plus prononcés dans le reste des résultats.

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.
@search.score: 5.074317
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
HotelId: 4
HotelName: Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Sortie d’une requête sémantique avec légendes

Voici les résultats de la requête qui ajoute des légendes avec mise en évidence des réponses pertinentes.

Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>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.
@search.score: 5.074317
@search.rerankerScore: 2.613231658935547
----------------------------------------
Caption:
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
Caption: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within<em> short walking distance </em>to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort,.
HotelId: 4
HotelName: Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
Caption: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend<em> evening entertainment </em>on the patio features special<em> guest musicians </em>or.
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
Caption: Book now and Save up to 30%. Central location. <em>Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood.</em> Brand new rooms. Impeccable service.
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Sortie pour les réponses sémantiques

La requête finale retourne une réponse sémantique. Notez que nous avons modifié la chaîne de requête pour cet exemple : « quel est un bon hôtel pour les personnes qui aiment lire ».

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation. Si la réponse sémantique n’est pas utile pour votre scénario, vous pouvez omettre semantic_answers de votre code.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.

Extractive Answers:
  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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
HotelId: 1
HotelName: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
@search.score: 2.0361428
@search.rerankerScore: 2.124817371368408
----------------------------------------
HotelId: 16
HotelName: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
@search.score: 3.759768
@search.rerankerScore: 2.0705394744873047
----------------------------------------
HotelId: 38
HotelName: Lakeside B & B
Description: 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.
@search.score: 0.7308748
@search.rerankerScore: 2.041472911834717
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 3.391012
@search.rerankerScore: 2.0231292247772217
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.3198771
@search.rerankerScore: 2.021622657775879
----------------------------------------

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, vous utilisez un IDE et la bibliothèque de client @azure/search-documents pour ajouter un classement sémantique à un index de recherche existant.

Le démarrage rapide suppose que les éléments suivants sont disponibles sur votre ordinateur :

Visual Studio Code pour ce guide de démarrage rapide.
Node.js (LTS) pour l’exécution de l’exemple.

Conseil / Astuce

Vous pouvez télécharger le code source pour commencer par un projet terminé ou suivre ces étapes pour créer votre propre code.

Configurer un environnement de développement local

Démarrez Visual Studio Code dans un nouveau répertoire.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Créez un package pour les modules ESM dans votre répertoire de projet.
```
npm init -y
npm pkg set type=module
```

Installez des packages, y compris azure-search-documents.

npm install @azure/identity @azure/search-documents dotenv

Créez .env et fournissez votre point de terminaison de service de recherche. Vous pouvez obtenir le point de terminaison à partir du portail Azure sur la page Vue d’ensemble du service de recherche.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Créez un répertoire src dans le répertoire de votre projet.
```
mkdir src
```

Si vous vous êtes connecté au portail Azure, vous êtes connecté à Azure. Si vous n’êtes pas sûr, utilisez Azure CLI ou Azure PowerShell pour vous connecter : az login ou az connect. Si vous avez plusieurs locataires et abonnements, consultez démarrage rapide : Se connecter sans clé pour obtenir de l’aide sur la connexion.

Créer un fichier d’authentification commun

Créez un fichier dans ./src appelé config.ts pour lire le fichier .env et conserver les variables d’environnement et les informations d’identification d’authentification. Copiez-le dans code suivant ; ne le modifiez pas. Ce fichier sera utilisé par tous les autres fichiers de ce guide de démarrage rapide.

import { DefaultAzureCredential } from "@azure/identity";

// Configuration - use environment variables
export const searchEndpoint = process.env.AZURE_SEARCH_ENDPOINT || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName = process.env.AZURE_SEARCH_INDEX_NAME || "hotels-sample-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

Obtenir le schéma d’index

Dans cette section, vous obtenez les paramètres de l’index hotels-sample-index existant sur votre service de recherche.

Créez un fichier dans ./src appelé getIndexSettings.js et copiez-le dans le code suivant.

import {
    SearchIndexClient
} from "@azure/search-documents";
import { searchEndpoint, indexName, credential } from "./config.js";

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Getting semantic search index settings...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Exécutez le code.

node -r dotenv/config src/getIndexSettings.js

La sortie est le nom de l’index, de la liste des champs et d’une instruction indiquant si une configuration sémantique existe. Pour les besoins de ce guide de démarrage rapide, le message doit indiquer No semantic configuration exists for this index.

Mettre à jour l’index avec une configuration sémantique

Créez un fichier dans ./src appelé updateIndexSettings.js et copiez-le dans le code suivant pour ajouter une configuration sémantique à l’index hotels-sample-index existant sur votre service de recherche. Aucun document de recherche n’est supprimé par cette opération et votre index est toujours opérationnel une fois la configuration ajoutée.

import {
    SearchIndexClient
} from "@azure/search-documents";
import { searchEndpoint, indexName, credential, semanticConfigurationName } from "./config.js";

try {

    const indexClient = new SearchIndexClient(searchEndpoint, credential);

    const existingIndex = await indexClient.getIndex(indexName);

    const fields = {
        titleField: {
            name: "HotelName"
        },
        keywordsFields: [{
            name: "Tags"
        }],
        contentFields: [{
            name: "Description"
        }]
    };

    const newSemanticConfiguration = {
        name: semanticConfigurationName,
        prioritizedFields: fields
    };

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Exécutez le code.

node -r dotenv/config src/updateIndexSettings.js

La sortie est la configuration sémantique que vous venez d’ajouter, Semantic configuration updated successfully..

Exécuter des requêtes sémantiques

Une fois que l’index hotels-sample-index a une configuration sémantique, vous pouvez exécuter des requêtes qui incluent des paramètres sémantiques.

Créez un fichier dans ./src appelé semanticQuery.js et copiez-le dans le code suivant pour créer une requête sémantique de l’index. Il s’agit de la condition minimale requise pour appeler le classement sémantique.

import { SearchClient } from "@azure/search-documents";
import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint,
    indexName,
    credential
);

const results = await searchClient.search("walking distance to live music", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName
    },
    select: ["HotelId", "HotelName", "Description"]
});

let rowNumber = 1;
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Exécutez le code.

node -r dotenv/config src/semanticQuery.js

La sortie doit contenir 13 documents, classés par rerankerScoreDisplay.

Retour des sous-titres

Si vous le souhaitez, vous pouvez ajouter des annotations pour mieux comprendre les parties du texte et appliquer une mise en évidence aux termes et expressions importants. Cette requête ajoute des légendes.

Créez un fichier dans ./src appelé semanticQueryReturnCaptions.js et copiez-le dans le code suivant pour ajouter des légendes à la requête.

import { SearchClient } from "@azure/search-documents";
import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint,
    indexName,
    credential
);

console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

const results = await searchClient.search("walking distance to live music", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName,
        captions: {
            captionType: "extractive",
            highlight: true
        }
    },
    select: ["HotelId", "HotelName", "Description"],
});

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Exécutez le code.

node -r dotenv/config src/semanticQueryReturnCaptions.js

La sortie doit inclure un nouvel élément de légende en même temps que le champ de recherche. Les légendes sont les passages les plus pertinents dans un résultat. Si votre index inclut des blocs de texte plus volumineux, une légende est utile pour extraire les phrases les plus intéressantes.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.

Retourner des réponses sémantiques

Dans cette dernière requête, renvoyez des réponses sémantiques.

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation. Si la réponse sémantique n’est pas utile pour votre scénario, vous pouvez omettre semantic_answers de votre code.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Créez un fichier dans ./src appelé semanticAnswer.js et copiez-le dans le code suivant pour obtenir des réponses sémantiques.

import { SearchClient } from "@azure/search-documents";
import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint,
    indexName,
    credential
);

const results = await searchClient.search("What's a good hotel for people who like to read", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName,
        captions: {
            captionType: "extractive"
        },
        answers: {
            answerType: "extractive"
        }
    },
    select: ["HotelName", "Description", "Category"]
});

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Exécutez le code.

node -r dotenv/config src/semanticAnswer.js

La sortie doit ressembler à l’exemple suivant, où la meilleure réponse à la question est extraite de l’un des résultats.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.
```
Semantic answer result #1:
Semantic Answer: 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.
Semantic Answer Score: 0.9829999804496765
```

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, vous utilisez un IDE et la bibliothèque de client Kit de développement logiciel (SDK) Java Recherche Azure AI pour ajouter un classement sémantique à un index de recherche existant.

Le démarrage rapide suppose que les éléments suivants sont disponibles sur votre ordinateur :

Visual Studio Code avec des extensions Java ou IntelliJ IDEA
Java 21 (LTS).
Maven.

Configurer un environnement de développement local

Créez un répertoire de projet Maven.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Créez un pom.xml fichier avec les dépendances requises.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.azure.search</groupId>
    <artifactId>semantic-ranking-quickstart</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.8</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.17.0</version>
        </dependency>
    </dependencies>
</project>

Compilez le projet pour résoudre les dépendances.
```
mvn compile
```

Créez la structure du répertoire source.

mkdir -p src/main/java/com/azure/search/quickstart
mkdir -p src/main/resources

Créez un application.properties fichier dans le src/main/resources répertoire et fournissez votre point de terminaison de service de recherche. Vous pouvez obtenir le point de terminaison à partir du portail Azure sur la page Vue d’ensemble du service de recherche.
```
azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
azure.search.index.name=hotels-sample-index
semantic.configuration.name=semantic-config
```

Si vous vous êtes connecté au portail Azure, vous êtes connecté à Azure. Si vous n’êtes pas sûr, utilisez l’interface de ligne de commande Azure pour vous connecter : az login. Si vous avez plusieurs locataires et abonnements, consultez démarrage rapide : Se connecter sans clé pour obtenir de l’aide sur la connexion.

Créer une classe de configuration commune

Créez un SearchConfig.java fichier dans le src/main/java/com/azure/search/quickstart répertoire pour lire le fichier de propriétés et contenir les valeurs de configuration et les informations d’identification d’authentification.

package com.azure.search.quickstart;

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties = new Properties();

    static {
        try (InputStream input = SearchConfig.class.getClassLoader()
            .getResourceAsStream("application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties", e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty("azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty("azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty("semantic.configuration.name");

    public static final DefaultAzureCredential CREDENTIAL =
        new DefaultAzureCredentialBuilder().build();

    static {
        System.out.println("Using Azure Search endpoint: " + SEARCH_ENDPOINT);
        System.out.println("Using index name: " + INDEX_NAME + "\n");
    }
}

Obtenir le schéma d’index

Dans cette section, vous obtenez les paramètres de l’index hotels-sample-index existant sur votre service de recherche.

Créez un GetIndexSettings.java fichier dans le src/main/java/com/azure/search/quickstart répertoire.

package com.azure.search.quickstart;

import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models.SearchField;
import com.azure.search.documents.indexes.models.SearchIndex;
import com.azure.search.documents.indexes.models.SemanticConfiguration;
import com.azure.search.documents.indexes.models.SemanticField;
import com.azure.search.documents.indexes.models.SemanticSearch;

public class GetIndexSettings {
    public static void main(String[] args) {
        var indexClient = new SearchIndexClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Getting semantic search index settings...");

        SearchIndex index = indexClient.getIndex(SearchConfig.INDEX_NAME);

        System.out.println("Index name: " + index.getName());
        System.out.println("Number of fields: " + index.getFields().size());

        for (SearchField field : index.getFields()) {
            System.out.printf("Field: %s, Type: %s, Searchable: %s%n",
                field.getName(), field.getType(), field.isSearchable());
        }

        SemanticSearch semanticSearch = index.getSemanticSearch();
        if (semanticSearch != null &&
            semanticSearch.getConfigurations() != null) {
            System.out.println("Semantic search configurations: " +
                semanticSearch.getConfigurations().size());
            for (SemanticConfiguration config :
                semanticSearch.getConfigurations()) {
                System.out.println("Configuration name: " + config.getName());
                SemanticField titleField = config.getPrioritizedFields().getTitleField();
                if (titleField != null) {
                    System.out.println("Title field: " +
                        titleField.getFieldName());
                }
            }
        } else {
            System.out.println(
                "No semantic configuration exists for this index.");
        }

        System.exit(0);
    }
}

Compilez et exécutez le code.

mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.GetIndexSettings"

La sortie est le nom de l’index, de la liste des champs et d’une instruction indiquant si une configuration sémantique existe. Pour les besoins de ce guide de démarrage rapide, le message doit indiquer No semantic configuration exists for this index.

Mettre à jour l’index avec une configuration sémantique

Créez un UpdateIndexSettings.java fichier dans le src/main/java/com/azure/search/quickstart répertoire pour ajouter une configuration sémantique à l’index existant hotels-sample-index sur votre service de recherche.

package com.azure.search.quickstart;

import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models.SearchIndex;
import com.azure.search.documents.indexes.models.SemanticConfiguration;
import com.azure.search.documents.indexes.models.SemanticField;
import com.azure.search.documents.indexes.models.SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models.SemanticSearch;

import java.util.ArrayList;
import java.util.List;

public class UpdateIndexSettings {
    public static void main(String[] args) {
        try {
            var indexClient = new SearchIndexClientBuilder()
                .endpoint(SearchConfig.SEARCH_ENDPOINT)
                .credential(SearchConfig.CREDENTIAL)
                .buildClient();

            SearchIndex existingIndex =
                indexClient.getIndex(SearchConfig.INDEX_NAME);

            // Create prioritized fields for semantic configuration
            var prioritizedFields = new SemanticPrioritizedFields()
                .setTitleField(new SemanticField("HotelName"))
                .setKeywordsFields(List.of(new SemanticField("Tags")))
                .setContentFields(List.of(new SemanticField("Description")));

            var newSemanticConfiguration = new SemanticConfiguration(
                SearchConfig.SEMANTIC_CONFIG_NAME, prioritizedFields);

            // Add the semantic configuration to the index
            SemanticSearch semanticSearch = existingIndex.getSemanticSearch();
            if (semanticSearch == null) {
                semanticSearch = new SemanticSearch();
                existingIndex.setSemanticSearch(semanticSearch);
            }

            List<SemanticConfiguration> configurations =
                semanticSearch.getConfigurations();
            if (configurations == null) {
                configurations = new ArrayList<>();
                semanticSearch.setConfigurations(configurations);
            }

            // Check if configuration already exists
            boolean configExists = configurations.stream()
                .anyMatch(config -> SearchConfig.SEMANTIC_CONFIG_NAME
                    .equals(config.getName()));

            if (!configExists) {
                configurations.add(newSemanticConfiguration);
            }

            indexClient.createOrUpdateIndex(existingIndex);

            SearchIndex updatedIndex =
                indexClient.getIndex(SearchConfig.INDEX_NAME);

            System.out.println("Semantic configurations:");
            System.out.println("-".repeat(40));

            SemanticSearch updatedSemanticSearch =
                updatedIndex.getSemanticSearch();
            if (updatedSemanticSearch != null &&
                updatedSemanticSearch.getConfigurations() != null) {
                for (SemanticConfiguration config :
                    updatedSemanticSearch.getConfigurations()) {
                    System.out.println("Configuration name: " + config.getName());

                    SemanticPrioritizedFields fields =
                        config.getPrioritizedFields();
                    if (fields.getTitleField() != null) {
                        System.out.println("Title field: " +
                            fields.getTitleField().getFieldName());
                    }
                    if (fields.getKeywordsFields() != null) {
                        List<String> keywords = fields.getKeywordsFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Keywords fields: " +
                            String.join(", ", keywords));
                    }
                    if (fields.getContentFields() != null) {
                        List<String> content = fields.getContentFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Content fields: " +
                            String.join(", ", content));
                    }
                    System.out.println("-".repeat(40));
                }
            } else {
                System.out.println("No semantic configurations found.");
            }

            System.out.println("Semantic configuration updated successfully.");

            System.exit(0);
        } catch (Exception e) {
            System.err.println("Error updating semantic configuration: " +
                e.getMessage());
        }
    }
}

Compilez et exécutez le code.

mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.UpdateIndexSettings"

La sortie est la configuration sémantique que vous venez d’ajouter, Semantic configuration updated successfully..

Exécuter des requêtes sémantiques

Une fois que l’index hotels-sample-index a une configuration sémantique, vous pouvez exécuter des requêtes qui incluent des paramètres sémantiques.

Créez un SemanticQuery.java fichier dans le src/main/java/com/azure/search/quickstart répertoire pour créer une requête sémantique de l’index.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models.SemanticSearchOptions;
import com.azure.search.documents.util.SearchPagedIterable;

public class SemanticQuery {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        var searchOptions = new SearchOptions()
            .setQueryType(QueryType.SEMANTIC)
            .setSemanticSearchOptions(new SemanticSearchOptions()
                .setSemanticConfigurationName(SearchConfig.SEMANTIC_CONFIG_NAME))
            .setSelect("HotelId", "HotelName", "Description");

        SearchPagedIterable results = searchClient.search(
            "walking distance to live music", searchOptions, null);

        int rowNumber = 1;
        for (SearchResult result : results) {
            var document = result.getDocument(SearchDocument.class);
            double rerankerScore = result.getSemanticSearch().getRerankerScore();

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("  Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("  HotelId: %s%n", document.get("HotelId"));
            System.out.printf("  HotelName: %s%n", document.get("HotelName"));
            System.out.printf("  Description: %s%n%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");
        }

        System.exit(0);
    }
}

Compilez et exécutez le code.

mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticQuery"

La sortie doit contenir 13 documents, classés par le score de reclassement.

Retour des sous-titres

Si vous le souhaitez, vous pouvez ajouter des annotations pour mieux comprendre les parties du texte et appliquer une mise en évidence aux termes et expressions importants.

Créez un SemanticQueryWithCaptions.java fichier dans le src/main/java/com/azure/search/quickstart répertoire.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models.SemanticSearchOptions;
import com.azure.search.documents.util.SearchPagedIterable;
import java.util.List;

public class SemanticQueryWithCaptions {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Using semantic configuration: " +
            SearchConfig.SEMANTIC_CONFIG_NAME);
        System.out.println("Search query: walking distance to live music");

        var searchOptions = new SearchOptions()
            .setQueryType(QueryType.SEMANTIC)
            .setSemanticSearchOptions(new SemanticSearchOptions()
                .setSemanticConfigurationName(SearchConfig.SEMANTIC_CONFIG_NAME)
                .setQueryCaption(new QueryCaption(QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
            .setSelect("HotelId", "HotelName", "Description");

        SearchPagedIterable results = searchClient.search(
            "walking distance to live music", searchOptions, null);

        System.out.printf("Found results with semantic search%n%n");
        int rowNumber = 1;

        for (SearchResult result : results) {
            var document = result.getDocument(SearchDocument.class);
            double rerankerScore = result.getSemanticSearch().getRerankerScore();

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("  Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("  HotelName: %s%n", document.get("HotelName"));
            System.out.printf("  Description: %s%n%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");

            // Handle captions
            List<QueryCaptionResult> captions =
                result.getSemanticSearch().getQueryCaptions();
            if (captions != null && !captions.isEmpty()) {
                QueryCaptionResult caption = captions.get(0);

                if (caption.getHighlights() != null &&
                    !caption.getHighlights().trim().isEmpty()) {
                    System.out.printf("  Caption with highlights: %s%n",
                        caption.getHighlights());
                } else if (caption.getText() != null &&
                    !caption.getText().trim().isEmpty()) {
                    System.out.printf("  Caption text: %s%n",
                        caption.getText());
                } else {
                    System.out.println(
                        "  Caption exists but has no text or highlights content");
                }
            } else {
                System.out.println("  No captions found for this result");
            }
            System.out.println("-".repeat(60));
        }

        System.exit(0);
    }
}

Compilez et exécutez le code.

mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticQueryWithCaptions"

La sortie doit inclure un nouvel élément de légende en même temps que le champ de recherche. Les légendes sont les passages les plus pertinents dans un résultat. Si votre index inclut des blocs de texte plus volumineux, une légende est utile pour extraire les phrases les plus intéressantes.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.

Retourner des réponses sémantiques

Dans cette dernière requête, renvoyez des réponses sémantiques.

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Créez un SemanticAnswer.java fichier dans le src/main/java/com/azure/search/quickstart répertoire.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryAnswer;
import com.azure.search.documents.models.QueryAnswerResult;
import com.azure.search.documents.models.QueryAnswerType;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models.SemanticSearchOptions;
import com.azure.search.documents.util.SearchPagedIterable;

import java.util.List;

public class SemanticAnswer {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        var searchOptions = new SearchOptions()
            .setQueryType(QueryType.SEMANTIC)
            .setSemanticSearchOptions(new SemanticSearchOptions()
                .setSemanticConfigurationName(SearchConfig.SEMANTIC_CONFIG_NAME)
                .setQueryCaption(new QueryCaption(QueryCaptionType.EXTRACTIVE))
                .setQueryAnswer(new QueryAnswer(QueryAnswerType.EXTRACTIVE)))
            .setSelect("HotelName", "Description", "Category");

        SearchPagedIterable results = searchClient.search(
            "What's a good hotel for people who like to read",
            searchOptions, null);

        System.out.println("Answers:\n");

        // Extract semantic answers
        List<QueryAnswerResult> semanticAnswers =
            results.getSemanticResults().getQueryAnswers();
        int answerNumber = 1;

        if (semanticAnswers != null) {
            for (QueryAnswerResult answer : semanticAnswers) {
                System.out.printf("Semantic answer result #%d:%n",
                    answerNumber++);

                if (answer.getHighlights() != null &&
                    !answer.getHighlights().trim().isEmpty()) {
                    System.out.printf("Semantic Answer: %s%n",
                        answer.getHighlights());
                } else {
                    System.out.printf("Semantic Answer: %s%n", answer.getText());
                }
                System.out.printf("Semantic Answer Score: %.2f%n%n",
                    answer.getScore());
            }
        }

        System.out.println("Search Results:\n");
        int rowNumber = 1;

        // Iterate through search results
        for (SearchResult result : results) {
            var document = result.getDocument(SearchDocument.class);
            double rerankerScore = result.getSemanticSearch().getRerankerScore();

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("Hotel: %s%n", document.get("HotelName"));
            System.out.printf("Description: %s%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");

            List<QueryCaptionResult> captions =
                result.getSemanticSearch().getQueryCaptions();
            if (captions != null && !captions.isEmpty()) {
                QueryCaptionResult caption = captions.get(0);
                if (caption.getHighlights() != null &&
                    !caption.getHighlights().trim().isEmpty()) {
                    System.out.printf("Caption: %s%n%n",
                        caption.getHighlights());
                } else {
                    System.out.printf("Caption: %s%n%n", caption.getText());
                }
            } else {
                System.out.println();
            }
        }

        System.exit(0);
    }
}

Compilez et exécutez le code.

mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticAnswer"

La sortie doit ressembler à l’exemple suivant, où la meilleure réponse à la question est extraite de l’un des résultats.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.
```
Semantic answer result #1:
Semantic Answer: 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.
Semantic Answer Score: 0.9829999804496765
```

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, utilisez un notebook Jupyter et la bibliothèque azure-search-documents dans le Kit de développement logiciel (SDK) Azure pour Python pour en savoir plus sur le classement sémantique.

Nous vous recommandons Visual Studio Code avec Python 3.10 ou version ultérieure et l’extension Python pour ce guide de démarrage rapide.

Conseil / Astuce

Vous pouvez télécharger un bloc-notes terminé pour commencer par un projet terminé ou suivre ces étapes pour créer votre propre bloc-notes.

Nous vous recommandons un environnement virtuel pour ce démarrage rapide :

Démarrez Visual Studio Code.
Ouvrez le fichier semantic-search-quickstart.ipynb ou créez un notebook.
Ouvrez la palette de commandes en utilisant Ctrl+Maj+P.
Recherchez Python : Créer un environnement.
Sélectionnez Venv.
Sélectionnez un interpréteur Python. Choisissez la version 3.10 ou ultérieure.

La configuration peut prendre une minute. Si vous rencontrez des problèmes, consultez Environnements Python dans VS Code.

Installer des packages et définir des variables d’environnement

Installez des packages, y compris azure-search-documents.
```
! pip install -r requirements.txt --quiet
```
Renommez sample.env en .env, et fournissez votre point de terminaison de service de recherche. Vous pouvez obtenir le point de terminaison à partir du portail Azure sur la page Vue d’ensemble du service de recherche.
```
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
```

Si vous vous êtes connecté au portail Azure, vous êtes connecté à Azure. Si vous n’êtes pas sûr, utilisez Azure CLI ou Azure PowerShell pour vous connecter : az login ou az connect. Si vous avez plusieurs locataires et abonnements, consultez démarrage rapide : Se connecter sans clé pour obtenir de l’aide sur la connexion.

Mettre à jour l’index

Dans cette section, vous mettez à jour un index de recherche pour inclure une configuration sémantique. Le code obtient la définition d’index du service de recherche et ajoute une configuration sémantique.

Ouvrez le fichier semantic-search-quickstart.ipynb dans Visual Studio Code ou créez un fichier.

Fournissez les variables utilisées dans la solution.

# Provide variables
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import os

load_dotenv(override=True) # Take environment variables from .env.

# The following variables from your .env file are used in this notebook
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://search.azure.com/.default")
index_name = os.getenv("AZURE_SEARCH_INDEX", "hotels-sample-index")

Créez un SearchIndexClient et obtenez l’index des hôtels existants.

from azure.search.documents.indexes import SearchIndexClient
from azure.identity import DefaultAzureCredential
import os

# Initialize the client (similar to what you already have)
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = "hotels-sample-index"  # or use your existing index_name variable

# Create the SearchIndexClient
index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    # Get the existing index schema
    index = index_client.get_index(index_name)

    print(f"Index name: {index.name}")
    print(f"Number of fields: {len(index.fields)}")

    # Print field details
    for field in index.fields:
        print(f"Field: {field.name}, Type: {field.type}, Searchable: {field.searchable}")

    # Access semantic configuration if it exists
    if index.semantic_search and index.semantic_search.configurations:
        for config in index.semantic_search.configurations:
            print(f"Semantic config: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"Title field: {config.prioritized_fields.title_field.field_name}")
    else:
        print("No semantic configuration exists for this index")

except Exception as ex:
    print(f"Error retrieving index: {ex}")

Exécutez le code.
La sortie est le nom de l’index, de la liste des champs et d’une instruction indiquant si une configuration sémantique existe. Dans le cadre de ce guide de démarrage rapide, le message doit indiquer « Aucune configuration sémantique n’existe pour cet index ».

Ajoutez une configuration sémantique à un hotels-sample-index existant sur votre service de recherche. Aucun document de recherche n’est supprimé par cette opération et votre index est toujours opérationnel une fois la configuration ajoutée.

# Add semantic configuration to hotels-sample-index and display updated index details
from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

try:
    # Get the existing index
    existing_index = index_client.get_index(index_name)

    # Create a new semantic configuration
    new_semantic_config = SemanticConfiguration(
        name="semantic-config",
        prioritized_fields=SemanticPrioritizedFields(
            title_field=SemanticField(field_name="HotelName"),
            keywords_fields=[SemanticField(field_name="Tags")],
            content_fields=[SemanticField(field_name="Description")]
        )
    )

    # Add semantic configuration to the index
    if existing_index.semantic_search is None:
        existing_index.semantic_search = SemanticSearch(configurations=[new_semantic_config])
    else:
        # Check if configuration already exists
        config_exists = any(config.name == "semantic-config" 
                          for config in existing_index.semantic_search.configurations)
        if not config_exists:
            existing_index.semantic_search.configurations.append(new_semantic_config)

    # Update the index
    result = index_client.create_or_update_index(existing_index)

    # Get the updated index and display detailed information
    updated_index = index_client.get_index(index_name)

    print("Semantic configurations:")
    print("-" * 40)
    if updated_index.semantic_search and updated_index.semantic_search.configurations:
        for config in updated_index.semantic_search.configurations:
            print(f"  Configuration: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"    Title field: {config.prioritized_fields.title_field.field_name}")
            if config.prioritized_fields.keywords_fields:
                keywords = [kf.field_name for kf in config.prioritized_fields.keywords_fields]
                print(f"    Keywords fields: {', '.join(keywords)}")
            if config.prioritized_fields.content_fields:
                content = [cf.field_name for cf in config.prioritized_fields.content_fields]
                print(f"    Content fields: {', '.join(content)}")
            print()
    else:
        print("  No semantic configurations found")

    print("✅ Semantic configuration successfully added!")

except Exception as ex:
    print(f"❌ Error adding semantic configuration: {ex}")

Exécutez le code.
La sortie est la configuration sémantique que vous venez d’ajouter.

Exécuter des requêtes sémantiques

Une fois que l’index a une configuration sémantique, vous pouvez exécuter des requêtes qui incluent des paramètres sémantiques.

Créez un SearchClient et une demande de requête qui inclut le type de requête sémantique et la configuration sémantique. Il s’agit de la condition minimale requise pour appeler le classement sémantique.

# Set up the search client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Runs a semantic query (runs a BM25-ranked query, rescoring and promoting the most semantically relevant matches to the top)
results =  search_client.search(query_type='semantic', semantic_configuration_name='semantic-config',
    search_text="walking distance to live music", 
    select='HotelId,HotelName,Description', query_caption='extractive')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

Exécutez le code.
La sortie doit contenir 13 documents, classés par "@search.reranker_score".

Retour des sous-titres

Si vous le souhaitez, vous pouvez ajouter des annotations pour mieux comprendre les parties du texte et appliquer une mise en évidence aux termes et expressions importants. Cette requête ajoute des légendes.

Ajouter captions à la requête.

# Runs a semantic query that returns captions
results =  search_client.search(query_type='semantic', semantic_configuration_name='semantic-config',
    search_text="walking distance to live music", 
    select='HotelName,HotelId,Description', query_caption='extractive')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")
        else:
            print(f"Caption: {caption.text}\n")

Exécutez le code.

La sortie doit inclure un nouvel élément de légende en même temps que le champ de recherche. Les légendes sont les passages les plus pertinents dans un résultat. Si votre index inclut des blocs de texte plus volumineux, une légende est utile pour extraire les phrases les plus intéressantes.

2.613231658935547
24
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.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.

Retourner des réponses sémantiques

Dans cette dernière requête, renvoyez des réponses sémantiques.

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation. Si la réponse sémantique n’est pas utile pour votre scénario, vous pouvez omettre semantic_answers de votre code.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Ajouter answers à la requête.

# Run a semantic query that returns semantic answers  
results =  search_client.search(query_type='semantic', semantic_configuration_name='semantic-config',
 search_text="what's a good hotel for people who like to read",
 select='HotelName,Description,Category', query_caption='extractive', query_answer="extractive",)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")
        else:
            print(f"Caption: {caption.text}\n")

Exécutez le code.

La sortie doit ressembler à l’exemple suivant, où la meilleure réponse à la question est extraite de l’un des résultats.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.

Semantic Answer: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

2.124817371368408
1
Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

2.0705394744873047
16
Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.

2.041472911834717
38
Lakeside B & B
Description: 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.
Caption: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.

2.084540843963623
Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the<em> city. #1 </em>Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.

...

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, vous utilisez un client REST et les API REST Recherche Azure AI pour configurer et utiliser un ranker sémantique.

Nous vous recommandons Visual Studio Code avec une extension de client REST pour ce guide de démarrage rapide.

Conseil / Astuce

Vous pouvez télécharger le code source pour commencer par un projet terminé ou suivre ces étapes pour créer votre propre code.

Démarrez Visual Studio Code et ouvrez le fichier semantic-search-index-update.rest ou créez un fichier.
En haut, définissez des variables d’environnement pour votre service de recherche, votre autorisation et votre nom d’index.
- Pour @searchURL, connectez-vous au portail Azure et copiez l’URL à partir de la page Vue d’ensemble du service de recherche.
- Pour @personalAccessToken, suivez les instructions de Connexion sans clés pour obtenir votre jeton d’accès personnel.

Pour tester la connexion, envoyez votre première requête.

### List existing indexes by name (verify the connection)
 GET  {{searchUrl}}/indexes?api-version=2025-09-01&$select=name  HTTP/1.1
 Authorization: Bearer {{personalAccessToken}}

Sélectionnez Envoyer une demande.
La sortie de cette requête GET retourne une liste d’index existants. Vous devriez obtenir un code d’état de réussite HTTP 200 et une liste d’index, y compris hotels-sample-index utilisé dans ce guide de démarrage rapide.

Mettre à jour l’index

Pour mettre à jour un index à l’aide de l’API REST, vous devez fournir l’intégralité du schéma, ainsi que les modifications que vous souhaitez apporter. Cette requête fournit un schéma hotels-sample-index, ainsi que la configuration sémantique. La modification se compose du code JSON suivant.

"semantic": {
   "configurations": [
   {
      "name": "semantic-config",
      "rankingOrder": "BoostedRerankerScore",
      "prioritizedFields": {
         "titleField": { "fieldName": "HotelName" },
         "prioritizedContentFields": [{ "fieldName": "Description" }],
         "prioritizedKeywordsFields": [{ "fieldName": "Tags" }]
      }
   }
   ]
}

Formulez une requête PUT spécifiant le nom d’index, l’opération et le schéma JSON complet. Tous les éléments requis du schéma doivent être présents. Cette requête inclut le schéma complet pour hotels-sample-index ainsi que la configuration sémantique.

PUT {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
   "name": "hotels-sample-index",
   "fields": [
       { "name": "HotelId", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "key": true },
       { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
       { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "ParkingIncluded", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
       { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rating", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": true },
       { "name": "Address", "type": "Edm.ComplexType", "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "Location", "type": "Edm.GeographyPoint", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rooms", "type": "Collection(Edm.ComplexType)", "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
          { "name": "Type", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "BaseRate", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "SleepsCount", "type": "Edm.Int64", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "id", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false },
       { "name": "rid", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false }],
  "scoringProfiles": [],
  "suggesters": [],
  "analyzers": [],
  "normalizers": [],
  "tokenizers": [],
  "tokenFilters": [],
  "charFilters": [],
  "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
  },
  "semantic": {
    "configurations": [
      {
        "name": "semantic-config",
        "rankingOrder": "BoostedRerankerScore",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "HotelName"
          },
          "prioritizedContentFields": [
            {
              "fieldName": "Description"
            }
          ],
          "prioritizedKeywordsFields": [
            {
              "fieldName": "Tags"
            }
          ]
        }
      }
    ]
  }
}

Sélectionnez Envoyer une demande.
La sortie de cette requête POST est un message d’état HTTP 200 Success .

Exécuter des requêtes sémantiques

Les paramètres sémantiques requis incluent query_type et semantic_configuration_name. Voici un exemple de requête sémantique de base utilisant les paramètres minimaux.

Ouvrez le fichier semantic-search-query.rest ou créez un fichier.
En haut du fichier, définissez des variables d’environnement pour votre service de recherche, votre autorisation et votre nom d’index.
- Pour @searchURL, connectez-vous au portail Azure et copiez l’URL à partir de la page Vue d’ensemble du service de recherche.
- Pour @personalAccessToken, suivez les instructions de Connexion sans clés pour obtenir votre jeton d’accès personnel.

Testez la connexion avec une requête GET qui retourne l’index hotels-sample.

GET {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Authorization: Bearer {{personalAccessToken}}

Envoyez une requête qui inclut le type de requête sémantique et le nom de configuration.

 POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{personalAccessToken}}

 {
   "search": "walking distance to live music",
   "select": "HotelId, HotelName, Description",
   "count": true,
   "top": 7,
   "queryType": "simple"
 }

La sortie se compose des résultats de la recherche JSON. Treize hôtels correspondent à la requête. Les sept premiers sont inclus dans cet exemple.

{
   "@odata.count": 13,
   "@search.answers": [],
   "value": [
     {
       "@search.score": 5.074317,
       "@search.rerankerScore": 2.613231658935547,
       "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."
     },
     {
       "@search.score": 5.5153193,
       "@search.rerankerScore": 2.271434783935547,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.8959594,
       "@search.rerankerScore": 1.9861756563186646,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     {
       "@search.score": 0.7334347,
       "@search.rerankerScore": 1.9615401029586792,
       "HotelId": "39",
       "HotelName": "White Mountain Lodge & Suites",
       "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
     },
     {
       "@search.score": 1.5502293,
       "@search.rerankerScore": 1.9085469245910645,
       "HotelId": "15",
       "HotelName": "By the Market Hotel",
       "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
     },
     {
       "@search.score": 1.7595702,
       "@search.rerankerScore": 1.90234375,
       "HotelId": "49",
       "HotelName": "Swirling Currents Hotel",
       "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
     },
     {
       "@search.score": 2.0364518,
       "@search.rerankerScore": 1.9012802839279175,
       "HotelId": "31",
       "HotelName": "Country Residence Hotel",
       "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
     }
   ]
 }

Retour des sous-titres

Si vous le souhaitez, vous pouvez ajouter des annotations pour mieux comprendre les parties du texte et appliquer une mise en évidence aux termes et expressions importants. Cette requête ajoute des légendes qui incluent la mise en surbrillance des résultats.

Ajoutez le captions paramètre et envoyez la requête.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "semantic-config",
  "captions": "extractive|highlight-true"
}

La sortie se compose des mêmes résultats, avec l’ajout de "@search.captions". Voici le JSON d’un document unique. Chaque correspondance inclut les scores de recherche, les légendes en texte brut et la mise en forme de mise en évidence, ainsi que les champs sélectionnés.

{
   "@search.score": 5.074317,
   "@search.rerankerScore": 2.613231658935547,
   "@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. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>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."
}

Retourner des réponses sémantiques

Dans cette dernière requête, renvoyez des réponses sémantiques.

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation. Si la réponse sémantique n’est pas utile pour votre scénario, vous pouvez omettre semantic_answers de votre code.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Formulez la requête à l’aide d’une chaîne de recherche qui pose une question.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
  "search": "what's a good hotel for people who like to read",
  "select": "HotelId, HotelName, Description",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "semantic-config"
  "answers": "extractive"
}

Le résultat se compose de 41 résultats pour la nouvelle requête, avec « @search.answers » pour la question dans la requête sur les hôtels pour les personnes qui aiment lire.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.

Dans cet exemple, la réponse est considérée comme un élément fort adapté à la question.

{
  "@odata.count": 41,
  "@search.answers": [
    {
      "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 shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.0361428,
      "@search.rerankerScore": 2.124817371368408,
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel",
      "Description": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
    },
    {
      "@search.score": 3.759768,
      "@search.rerankerScore": 2.0705394744873047,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Description": "5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room."
    },
    {
      "@search.score": 0.7308748,
      "@search.rerankerScore": 2.041472911834717,
      "HotelId": "38",
      "HotelName": "Lakeside B & B",
      "Description": "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."
    },
    {
      "@search.score": 3.391012,
      "@search.rerankerScore": 2.0231292247772217,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
    },
    {
      "@search.score": 1.3198771,
      "@search.rerankerScore": 2.021622657775879,
      "HotelId": "15",
      "HotelName": "By the Market Hotel",
      "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
    },
    {
      "@search.score": 1.3983066,
      "@search.rerankerScore": 2.005582809448242,
      "HotelId": "5",
      "HotelName": "Red Tide Hotel",
      "Description": "On entering this charming hotel in Scarlet Harbor, you'll notice an uncommon blend of antiques, original artwork, and contemporary comforts that give this hotel its signature look. Each suite is furnished to accentuate the views and unique characteristics of the building's classic architecture. No two suites are alike. However, all guests are welcome in the mezzanine plaza, the surrounding gardens, and the northside terrace for evening refreshments."
    },
    {
      "@search.score": 1.4815493,
      "@search.rerankerScore": 1.9739465713500977,
      "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."
    }
  ]
}

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser le classement sémantique en ajoutant une configuration sémantique à un index de recherche et en ajoutant des paramètres sémantiques à une requête. Vous pouvez utiliser hotels-sample-index ou l’un des vôtres.

Dans Azure Cognitive Search, le classement sémantique est une fonctionnalité côté requête qui utilise la compréhension automatique de la lecture de Microsoft pour réévaluer les résultats de recherche, en mettant en avant les correspondances les plus pertinentes sur le plan sémantique en haut de la liste. En fonction du contenu et de la requête, le classement sémantique peut améliorer considérablement la pertinence de la recherche avec un effort minimal pour les développeurs.

Vous pouvez ajouter une configuration sémantique à un index existant sans exigence de reconstruction. Le classement sémantique est plus efficace sur le texte qui est informationnel ou descriptif.

Prérequis

Compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un service Recherche d’IA Azure avec l’éditeur de classement sémantique activé.
Index nouveau ou existant avec des champs de texte descriptifs ou détaillés qui sont attribués comme récupérables. Ce guide de démarrage rapide s’appuie sur hotels-sample-index.

Configurer l’accès

Vous pouvez vous connecter à votre service Recherche d’IA Azure à l’aide de clés API ou d’ID Microsoft Entra avec des attributions de rôles. Les clés sont plus faciles à utiliser, mais les rôles sont plus sécurisés. Pour plus d’informations, consultez Se connecter à la Recherche Azure AI à l’aide des rôles.

Pour configurer l’accès en fonction du rôle :

Connectez-vous au portail Azure et sélectionnez votre service de recherche.
Dans le volet de gauche, sélectionnez Paramètres>Clés.
Sous Contrôle d’accès à l’API, sélectionnez contrôle d’accès en fonction du rôle ou les deux si vous avez besoin de temps pour passer des clients à l’accès en fonction du rôle.
Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .
Sélectionnez Ajouter>Ajouter une attribution de rôle.
Attribuez les rôles Contributeur du service de recherche et Contributeurde données d’index de recherche à votre compte d’utilisateur.

Commencer par un index

Ce guide de démarrage rapide suppose qu’un index existant et le modifie pour inclure une configuration sémantique. Nous vous recommandons l’index exemple d'hôtels hotels-sample-index que vous pouvez créer en quelques minutes en utilisant un assistant dans le Portail Azure.

Pour commencer avec un index existant :

Connectez-vous au portail Azure, puis trouvez votre service de recherche.
SousGestion de recherche>Index, sélectionnez l’index hotels-sample-index.
Sélectionnez des configurations sémantiques pour vous assurer que l’index n’a pas de configuration sémantique.
Sélectionnez l’Explorateur de recherche, puis sélectionnez la vue JSON.

Collez le code JSON suivant dans l’éditeur de requête.

{
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

Sélectionnez Rechercher pour exécuter la requête.

Cette requête est une recherche par mot clé. La réponse doit être similaire à l’exemple suivant, comme indiqué par le classement BM25 L1 par défaut pour la recherche en texte intégral.

Pour la lisibilité, l’exemple sélectionne uniquement les champs HotelId, HotelName et Description. Les résultats contiennent des correspondances verbatim sur les termes de la requête (walking, distance, live, music) ou sur les variantes linguistiques (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 5.074317,
    "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."
  },
  {
    "@search.score": 4.8959594,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Cette requête montre comment la réponse semble avant l’application du classement sémantique. Plus tard, vous pouvez exécuter la même requête après la configuration du classement sémantique pour voir comment la réponse change.

Conseil / Astuce

Vous pouvez ajouter une configuration sémantique dans le portail Azure. Toutefois, si vous souhaitez apprendre à ajouter une configuration sémantique par programmation, poursuivez avec ce guide de démarrage rapide.

Configurer le client

Dans ce guide de démarrage rapide, vous utilisez un IDE et la bibliothèque de client @azure/search-documents pour ajouter un classement sémantique à un index de recherche existant.

Le démarrage rapide suppose que les éléments suivants sont disponibles sur votre ordinateur :

Visual Studio Code pour ce guide de démarrage rapide.
Node.js (LTS) pour l’exécution de l’exemple.
TypeScript pour l’écriture de l’exemple de code.

Conseil / Astuce

Vous pouvez télécharger le code source pour commencer par un projet terminé ou suivre ces étapes pour créer votre propre code.

Configurer un environnement de développement local

Démarrez Visual Studio Code dans un nouveau répertoire.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Créez un package pour les modules ESM dans votre répertoire de projet.
```
npm init -y
npm pkg set type=module
```
Installez des packages de développement, y compris azure-search-documents.
```
npm install @azure/identity @azure/search-documents dotenv
```
Installez les packages de dépendances de développement.
```
npm install dotenv @types/node --save-dev
```

Créez un fichier tsconfig.json dans le répertoire de votre projet pour activer les modules ESM et définir la résolution des modules.

 {
   "compilerOptions": {
     "target": "es2022",
     "module": "esnext",
     "moduleResolution": "bundler",
     "rootDir": "./src",
     "outDir": "./dist/",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
     "declaration": true,
     "sourceMap": true,
     "resolveJsonModule": true,
     "moduleDetection": "force",
     "allowSyntheticDefaultImports": true,
     "verbatimModuleSyntax": false
   },
   "include": [
     "src/**/*.ts"
   ],
   "exclude": [
     "node_modules/**/*",
     "**/*.spec.ts"
   ]
 }

Mettez à jour package.json pour inclure un script pour la génération de fichiers TypeScript. Ajoutez la ligne suivante à la scripts section.
```
"build": "tsc"
```
Créez .env et fournissez votre point de terminaison de service de recherche. Vous pouvez obtenir le point de terminaison à partir du portail Azure sur la page Vue d’ensemble du service de recherche.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Créez un répertoire src dans le répertoire de votre projet.
```
mkdir src
```

Si vous vous êtes connecté au portail Azure, vous êtes connecté à Azure. Si vous n’êtes pas sûr, utilisez Azure CLI ou Azure PowerShell pour vous connecter : az login ou az connect. Si vous avez plusieurs locataires et abonnements, consultez démarrage rapide : Se connecter sans clé pour obtenir de l’aide sur la connexion.

Créer un fichier d’authentification commun

Créez un fichier dans ./src appelé config.ts pour lire le fichier .env et conserver les variables d’environnement et les informations d’identification d’authentification. Copiez-le dans code suivant ; ne le modifiez pas. Ce fichier sera utilisé par tous les autres fichiers de ce guide de démarrage rapide.

import { DefaultAzureCredential } from "@azure/identity";

// Configuration - use environment variables
export const searchEndpoint = process.env.AZURE_SEARCH_ENDPOINT || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName = process.env.AZURE_SEARCH_INDEX_NAME || "hotels-sample-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

// Hotel document interface
export interface HotelDocument {
    "@search.action"?: string;
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
    ParkingIncluded: string;
    LastRenovationDate: string;
    Rating: number;
    Address: {
        StreetAddress: string;
        City: string;
        StateProvince: string;
        PostalCode: string;
        Country: string;
    };
}

Obtenir le schéma d’index

Dans cette section, vous obtenez les paramètres de l’index hotels-sample-index existant sur votre service de recherche.

Créez un fichier dans ./src appelé getIndexSettings.ts et copiez-le dans le code suivant.

import {
    SearchIndexClient
} from "@azure/search-documents";
import { searchEndpoint, indexName, credential } from "./config.js";

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Updating semantic search index...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {

    // @ts-ignore
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Exécutez le code.

npm run build && node -r dotenv/config dist/getIndexSettings.js

La sortie est le nom de l’index, de la liste des champs et d’une instruction indiquant si une configuration sémantique existe. Pour les besoins de ce guide de démarrage rapide, le message doit indiquer No semantic configuration exists for this index.

Mettre à jour l’index avec une configuration sémantique

Créez un fichier dans ./src appelé updateIndexSettings.ts et copiez-le dans le code suivant pour ajouter une configuration sémantique à l’index hotels-sample-index existant sur votre service de recherche. Aucun document de recherche n’est supprimé par cette opération et votre index est toujours opérationnel une fois la configuration ajoutée.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import { searchEndpoint, indexName, credential, semanticConfigurationName } from "./config.js";

try {

    const indexClient = new SearchIndexClient(searchEndpoint, credential);

    const existingIndex = await indexClient.getIndex(indexName);

    const fields: SemanticPrioritizedFields = {
        titleField: {
            name: "HotelName"
        },
        keywordsFields: [{
            name: "Tags"
        }] as SemanticField[],
        contentFields: [{
            name: "Description"
        }] as SemanticField[]
    }

    const newSemanticConfiguration: SemanticConfiguration = {
        name: semanticConfigurationName,
        prioritizedFields: fields
    };

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Exécutez le code.

npm run build && node -r dotenv/config dist/updateIndexSettings.js

La sortie est la configuration sémantique que vous venez d’ajouter, Semantic configuration updated successfully..

Exécuter des requêtes sémantiques

Une fois que l’index hotels-sample-index a une configuration sémantique, vous pouvez exécuter des requêtes qui incluent des paramètres sémantiques.

Créez un fichier dans ./src appelé semanticQuery.ts et copiez-le dans le code suivant pour créer une requête sémantique de l’index. Il s’agit de la condition minimale requise pour appeler le classement sémantique.

import { SearchClient } from "@azure/search-documents";
import { HotelDocument, credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient<HotelDocument>(
    searchEndpoint,
    indexName,
    credential
);

const results = await searchClient.search("walking distance to live music", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName
    },
    select: ["HotelId", "HotelName", "Description"]
});

let rowNumber = 1;
for await (const result of results.results) {

    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Exécutez le code.

npm run build && node -r dotenv/config dist/semanticQuery.js

La sortie doit contenir 13 documents, classés par rerankerScoreDisplay.

Retour des sous-titres

Si vous le souhaitez, vous pouvez ajouter des annotations pour mieux comprendre les parties du texte et appliquer une mise en évidence aux termes et expressions importants. Cette requête ajoute des légendes.

Créez un fichier dans ./src appelé semanticQueryReturnCaptions.ts et copiez-le dans le code suivant pour ajouter des légendes à la requête.

import { SearchClient } from "@azure/search-documents";
import { HotelDocument, credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient<HotelDocument>(
    searchEndpoint,
    indexName,
    credential
);

// Debug info
console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

const results = await searchClient.search("walking distance to live music", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName,
        captions: {
            captionType: "extractive",
            highlight: true
        }
    },
    select: ["HotelId", "HotelName", "Description"],
});

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Exécutez le code.

npm run build && node -r dotenv/config dist/semanticQueryReturnCaptions.js

La sortie doit inclure un nouvel élément de légende en même temps que le champ de recherche. Les légendes sont les passages les plus pertinents dans un résultat. Si votre index inclut des blocs de texte plus volumineux, une légende est utile pour extraire les phrases les plus intéressantes.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.

Retourner des réponses sémantiques

Dans cette dernière requête, renvoyez des réponses sémantiques.

Le ranker sémantique peut produire une réponse à une chaîne de requête qui a les caractéristiques d’une question. La réponse générée est extraite détaillée de votre contenu afin qu’elle n’inclue pas de contenu composé comme ce que vous pourriez attendre d’un modèle d’achèvement de conversation. Si la réponse sémantique n’est pas utile pour votre scénario, vous pouvez omettre semantic_answers de votre code.

Pour produire une réponse sémantique, la question et la réponse doivent être étroitement alignées, et le modèle doit trouver du contenu qui répond clairement à la question. Si les réponses potentielles ne parviennent pas à atteindre un certain seuil de confiance, le modèle ne retourne pas de réponse. À des fins de démonstration, la question de cet exemple renvoie une réponse vous permettant d’examiner la syntaxe.

Créez un fichier dans ./src appelé semanticAnswer.ts et copiez-le dans le code suivant pour obtenir des réponses sémantiques.

import { SearchClient } from "@azure/search-documents";
import { HotelDocument, credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";

const searchClient = new SearchClient<HotelDocument>(
    searchEndpoint,
    indexName,
    credential
);

const results = await searchClient.search("What's a good hotel for people who like to read", {
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: semanticConfigurationName,
        captions: {
            captionType: "extractive"
        },
        answers: {
            answerType: "extractive"
        }
    },
    select: ["HotelName", "Description", "Category"]
});

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {


    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;
    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Exécutez le code.

npm run build && node -r dotenv/config dist/semanticAnswer.js

La sortie doit ressembler à l’exemple suivant, où la meilleure réponse à la question est extraite de l’un des résultats.

Rappelez-vous que les réponses sont du contenu détaillé extrait de votre index et peut être des expressions manquantes qu’un utilisateur s’attend à voir. Pour obtenir des réponses composées générées par un modèle d’achèvement de conversation, envisagez d’utiliser un modèle RAG ou une récupération agentique.
```
Semantic answer result #1:
Semantic Answer: 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.
Semantic Answer Score: 0.9829999804496765
```

Partager via

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Installer des bibliothèques

Connexion à Azure

Mettre à jour l’index

Exécuter des requêtes sémantiques

Sortie pour la requête sémantique (aucune légende ou réponse)

Sortie d’une requête sémantique avec légendes

Sortie pour les réponses sémantiques

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Configurer un environnement de développement local

Connexion à Azure

Créer un fichier d’authentification commun

Obtenir le schéma d’index

Mettre à jour l’index avec une configuration sémantique

Exécuter des requêtes sémantiques

Retour des sous-titres

Retourner des réponses sémantiques

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Configurer un environnement de développement local

Connexion à Azure

Créer une classe de configuration commune

Obtenir le schéma d’index

Mettre à jour l’index avec une configuration sémantique

Exécuter des requêtes sémantiques

Retour des sous-titres

Retourner des réponses sémantiques

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Installer des packages et définir des variables d’environnement

Connexion à Azure

Mettre à jour l’index

Exécuter des requêtes sémantiques

Retour des sous-titres

Retourner des réponses sémantiques

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Mettre à jour l’index

Exécuter des requêtes sémantiques

Retour des sous-titres

Retourner des réponses sémantiques

Prérequis

Configurer l’accès

Commencer par un index

Configurer le client

Configurer un environnement de développement local

Connexion à Azure

Créer un fichier d’authentification commun

Obtenir le schéma d’index

Mettre à jour l’index avec une configuration sémantique

Exécuter des requêtes sémantiques

Retour des sous-titres

Retourner des réponses sémantiques

Nettoyer les ressources

Contenu connexe

Commentaires

Ressources supplémentaires