Freigeben über

Schnellstart: Semantische Rangfolge

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

In dieser Schnellstartanleitung verwenden Sie eine IDE und die Azure.Search.Documents-Clientbibliothek , um einem vorhandenen Suchindex eine semantische Rangfolge hinzuzufügen.

Wir empfehlen Visual Studio für diese Schnellstartanleitung.

Tipp

Sie können den Quellcode herunterladen, um mit einem fertigen Projekt zu beginnen, oder führen Sie die folgenden Schritte aus, um Eigene zu erstellen.

Installieren von Bibliotheken

  1. Starten Sie Visual Studio, und öffnen Sie die quickstart-semantic-search.sln , oder erstellen Sie ein neues Projekt mithilfe einer Konsolenanwendungsvorlage.

  2. Wählen Sie unter Tools>NuGet-Paket-Manager die Option NuGet-Pakete für Projektmappe verwalten... aus.

  3. Wählen Sie Durchsuchen aus.

  4. Suchen Sie nach dem Azure.Search.Documents-Paket, und wählen Sie die neueste stabile Version aus.

  5. Suchen Sie nach dem Azure.Identity-Paket , und wählen Sie die neueste stabile Version aus.

  6. Wählen Sie Installieren aus, um die Assembly Ihrem Projekt und Ihrer Projektmappe hinzuzufügen.

Anmelden bei Azure

Wenn Sie sich beim Azure-Portal angemeldet haben, sind Sie bei Azure angemeldet. Wenn Sie nicht sicher sind, verwenden Sie die Azure CLI oder Azure PowerShell, um sich anzumelden: az login oder az connect. Wenn Sie über mehrere Mandanten und Abonnements verfügen, lesen Sie "Schnellstart: Verbinden ohne Schlüssel", um Hilfe beim Herstellen einer Verbindung zu erhalten.

Aktualisieren des Indexes

In diesem Abschnitt aktualisieren Sie einen Suchindex so, dass er eine semantische Konfiguration enthält. Der Code ruft die Indexdefinition aus dem Suchdienst ab und fügt eine semantische Konfiguration hinzu.

  1. Öffnen Sie das BuildIndex-Projekt in Visual Studio. Das Programm besteht aus dem folgenden Code.

    Dieser Code verwendet einen SearchIndexClient, um einen Index für Ihren Suchdienst zu aktualisieren.

    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;
    }
}

  2. Ersetzen Sie die Suchdienst-URL durch einen gültigen Endpunkt.

  3. Führen Sie das Programm aus.

  4. Die Ausgabe wird in einem Konsolenfenster von Console.WriteLine protokolliert. Für jeden Schritt sollten Nachrichten angezeigt werden, einschließlich des JSON-Codes des Indexschemas mit der neuen semantischen Konfiguration.

Ausführen semantischer Abfragen

In diesem Abschnitt führt das Programm mehrere semantische Abfragen in Sequenz aus.

  1. Öffnen Sie das QueryIndex-Projekt in Visual Studio. Das Programm besteht aus dem folgenden Code.

    Dieser Code verwendet einen SearchClient zum Senden von Abfragen an einen 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}");
            }
        }
    }
}

  2. Ersetzen Sie die Suchdienst-URL durch einen gültigen Endpunkt.

  3. Führen Sie das Programm aus.

  4. Die Ausgabe wird in einem Konsolenfenster von Console.WriteLine protokolliert. Sie sollten Suchergebnisse für jede Abfrage sehen.

Ausgabe für semantische Abfrage (keine Beschriftungen oder Antworten)

Diese Ausgabe stammt aus der semantischen Abfrage ohne Beschriftungen oder Antworten. Die Abfragezeichenfolge lautet „walking distance to live music“ (Fußweg zu Livemusik).

Hier werden die anfänglichen Ergebnisse aus der Ausdrucksabfrage mithilfe der semantischen Bewertungsmodelle rescoret. Für diesen speziellen Datensatz und diese Abfrage befinden sich die ersten mehreren Ergebnisse an ähnlichen Positionen. Die Auswirkungen der semantischen Rangfolge sind im Restlichen der Ergebnisse stärker ausgeprägt.

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...

Ausgabe für eine Semantikabfrage mit Untertiteln

Im Folgenden finden Sie die Ergebnisse für die Abfrage, die Untertitel mit Treffermarkierung hinzufügt.

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...

Ausgabe für semantische Antworten

Die endgültige Abfrage gibt eine semantische Antwort zurück. Beachten Sie, dass wir die Abfragezeichenfolge für dieses Beispiel geändert haben: "Was ist ein gutes Hotel für Personen, die lesen möchten".

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten. Wenn die semantische Antwort für Ihr Szenario nicht hilfreich ist, können Sie das semantic_answers aus Ihrem Code weglassen.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

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
----------------------------------------

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

In diesem Schnellstart verwenden Sie eine integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) und die Clientbibliothek @azure/search-documents, um einem vorhandenen Suchindex eine semantische Rangfolge hinzuzufügen.

Der Schnellstart setzt voraus, dass Folgendes auf Ihrem Computer verfügbar ist:

Tipp

Sie können den Quellcode herunterladen, um mit einem fertigen Projekt zu beginnen, oder führen Sie die folgenden Schritte aus, um Eigene zu erstellen.

Einrichten der lokalen Entwicklungsumgebung

  1. Starten Sie Visual Studio Code in einem neuen Verzeichnis.

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

  2. Erstellen Sie ein neues Paket für ESM-Module in Ihrem Projektverzeichnis.

    npm init -y
npm pkg set type=module

  3. Installieren Sie Pakete, einschließlich azure-search-documents.

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

  4. Erstellen Sie .env, und geben Sie Ihren Suchdienstendpunkt an. Sie können den Endpunkt über das Azure-Portal auf der Seite "Übersicht" des Suchdiensts abrufen.

    AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config

  5. Erstellen Sie ein src-Verzeichnis in Ihrem Projektverzeichnis.

    mkdir src

Anmelden bei Azure

Wenn Sie sich beim Azure-Portal angemeldet haben, sind Sie bei Azure angemeldet. Wenn Sie nicht sicher sind, verwenden Sie die Azure CLI oder Azure PowerShell, um sich anzumelden: az login oder az connect. Wenn Sie über mehrere Mandanten und Abonnements verfügen, lesen Sie "Schnellstart: Verbinden ohne Schlüssel", um Hilfe beim Herstellen einer Verbindung zu erhalten.

Erstellen einer allgemeinen Authentifizierungsdatei

Erstellen Sie in ./src eine Datei namens config.ts, die die .env-Datei liest sowie die Umgebungsvariablen und Anmeldeinformationen für die Authentifizierung enthält. Kopieren Sie den folgenden Code in die Datei (ändern Sie ihn nicht). Diese Datei wird von allen anderen Dateien in diesem Schnellstart verwendet.

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`);

Abrufen des Indexschemas

In diesem Abschnitt rufen Sie Einstellungen für den vorhandenen Index hotels-sample-index für Ihren Suchdienst ab.

  1. Erstellen Sie in ./src eine Datei namens getIndexSettings.js, und kopieren Sie den folgenden Code in die Datei.

    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.");
}

  2. Führen Sie den Code aus.

    node -r dotenv/config src/getIndexSettings.js

  3. Die Ausgabe ist der Name des Indexes, der Liste der Felder und einer Anweisung, die angibt, ob eine semantische Konfiguration vorhanden ist. Für die Zwecke dieses Schnellstarts sollte die Nachricht No semantic configuration exists for this index lauten.

Aktualisieren des Indexes mit einer semantischen Konfiguration

  1. Erstellen Sie in ./src eine Datei namens updateIndexSettings.js, und kopieren Sie den folgenden Code in die Datei, um dem vorhandenen Index hotels-sample-index für ihren Suchdienst eine semantische Konfiguration hinzuzufügen. Durch diesen Vorgang werden keine Suchdokumente gelöscht, und Ihr Index ist nach dem Hinzufügen der Konfiguration weiterhin funktionsfähig.

    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);
}

  2. Führen Sie den Code aus.

    node -r dotenv/config src/updateIndexSettings.js

  3. Die Ausgabe ist die semantische Konfiguration, die Sie soeben hinzugefügt haben – Semantic configuration updated successfully..

Ausführen semantischer Abfragen

Sobald der Index hotels-sample-index über eine semantische Konfiguration verfügt, können Sie Abfragen mit semantischen Parametern ausführen.

  1. Erstellen Sie in ./src eine Datei namens semanticQuery.js, und kopieren Sie den folgenden Code in die Datei, um eine Semantikabfrage des Indexes zu erstellen. Dies ist die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

    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`);
}

  2. Führen Sie den Code aus.

    node -r dotenv/config src/semanticQuery.js

  3. Die Ausgabe sollte aus 13 Dokumenten bestehen, sortiert nach rerankerScoreDisplay.

Zurückgeben von Beschriftungen

Optional können Sie Beschriftungen hinzufügen, um Teile des Texts zu extrahieren und Treffermarkierungen auf die wichtigen Begriffe und Ausdrücke anzuwenden. Diese Abfrage fügt Beschriftungen hinzu.

  1. Erstellen Sie in ./src eine Datei namens semanticQueryReturnCaptions.js, und kopieren Sie den folgenden Code in die Datei, um der Abfrage Beschriftungen hinzuzufügen.

    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));
}

  2. Führen Sie den Code aus.

    node -r dotenv/config src/semanticQueryReturnCaptions.js

  3. Die Ausgabe sollte neben dem Suchfeld ein neues Beschriftungselement enthalten. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größere Textabschnitte enthält, ist eine Beschriftung hilfreich, um die interessantesten Sätze zu extrahieren.

    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.

Zurückgeben semantischer Antworten

Geben Sie in dieser letzten Abfrage semantische Antworten zurück.

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten. Wenn die semantische Antwort für Ihr Szenario nicht hilfreich ist, können Sie das semantic_answers aus Ihrem Code weglassen.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

  1. Erstellen Sie in ./src eine Datei namens semanticAnswer.js, und kopieren Sie den folgenden Code in die Datei, um semantische Antworten zu erhalten.

    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`);
        }
    }
}

  2. Führen Sie den Code aus.

    node -r dotenv/config src/semanticAnswer.js

  3. Die Ausgabe sollte dem folgenden Beispiel ähneln, bei dem die beste Antwort auf Frage aus einem der Ergebnisse abgerufen wird.

    Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

    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<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

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

In diesem Schnellstart verwenden Sie eine IDE und die Clientbibliothek Azure AI Search Java SDK, um einem vorhandenen Suchindex eine semantische Rangfolge hinzuzufügen.

Der Schnellstart setzt voraus, dass Folgendes auf Ihrem Computer verfügbar ist:

Einrichten der lokalen Entwicklungsumgebung

  1. Erstellen Sie ein neues Maven-Projektverzeichnis.

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

  2. Erstellen Sie eine pom.xml-Datei mit erforderlichen Abhängigkeiten.

    <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>

  3. Kompilieren Sie das Projekt, um die Abhängigkeiten aufzulösen.

    mvn compile

  4. Erstellen Sie die Quellverzeichnisstruktur.

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

  5. Erstellen Sie eine application.properties Datei im src/main/resources Verzeichnis, und stellen Sie Ihren Suchdienstendpunkt bereit. Sie können den Endpunkt über das Azure-Portal auf der Seite "Übersicht" des Suchdiensts abrufen.

    azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
azure.search.index.name=hotels-sample-index
semantic.configuration.name=semantic-config

Anmelden bei Azure

Wenn Sie sich beim Azure-Portal angemeldet haben, sind Sie bei Azure angemeldet. Falls Sie nicht sicher sind, verwenden Sie die Azure-Befehlszeilenschnittstelle (Command Line Interface, CLI), um sich anzumelden: az login. Wenn Sie über mehrere Mandanten und Abonnements verfügen, lesen Sie "Schnellstart: Verbinden ohne Schlüssel", um Hilfe beim Herstellen einer Verbindung zu erhalten.

Erstellen einer allgemeinen Konfigurationsklasse

Erstellen Sie eine SearchConfig.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis, um die Eigenschaftendatei zu lesen und die Konfigurationswerte und Authentifizierungsanmeldeinformationen zu speichern.

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");
    }
}

Abrufen des Indexschemas

In diesem Abschnitt rufen Sie Einstellungen für den vorhandenen Index hotels-sample-index für Ihren Suchdienst ab.

  1. Erstellen Sie eine GetIndexSettings.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis.

    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);
    }
}

  2. Kompilieren sie den Code, und führen Sie den Code aus.

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

  3. Die Ausgabe ist der Name des Indexes, der Liste der Felder und einer Anweisung, die angibt, ob eine semantische Konfiguration vorhanden ist. Für die Zwecke dieses Schnellstarts sollte die Nachricht No semantic configuration exists for this index lauten.

Aktualisieren des Indexes mit einer semantischen Konfiguration

  1. Erstellen Sie eine UpdateIndexSettings.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis, um dem vorhandenen hotels-sample-index Index ihres Suchdiensts eine semantische Konfiguration hinzuzufügen.

    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());
        }
    }
}

  2. Kompilieren sie den Code, und führen Sie den Code aus.

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

  3. Die Ausgabe ist die semantische Konfiguration, die Sie soeben hinzugefügt haben – Semantic configuration updated successfully..

Ausführen semantischer Abfragen

Nachdem der hotels-sample-index Index über eine semantische Konfiguration verfügt, können Sie Abfragen ausführen, die semantische Parameter enthalten.

  1. Erstellen Sie eine SemanticQuery.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis, um eine semantische Abfrage des Indexes zu erstellen.

    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);
    }
}

  2. Kompilieren sie den Code, und führen Sie den Code aus.

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

  3. Die Ausgabe sollte aus 13 Dokumenten bestehen, die nach der semantischen Neubewertung sortiert sind.

Zurückgeben von Beschriftungen

Optional können Sie Beschriftungen hinzufügen, um Teile des Texts zu extrahieren und Treffermarkierungen auf die wichtigen Begriffe und Ausdrücke anzuwenden.

  1. Erstellen Sie eine SemanticQueryWithCaptions.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis.

    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);
    }
}

  2. Kompilieren sie den Code, und führen Sie den Code aus.

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

  3. Die Ausgabe sollte neben dem Suchfeld ein neues Beschriftungselement enthalten. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größere Textabschnitte enthält, ist eine Beschriftung hilfreich, um die interessantesten Sätze zu extrahieren.

    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.

Zurückgeben semantischer Antworten

Geben Sie in dieser letzten Abfrage semantische Antworten zurück.

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

  1. Erstellen Sie eine SemanticAnswer.java Datei im src/main/java/com/azure/search/quickstart Verzeichnis.

    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);
    }
}

  2. Kompilieren sie den Code, und führen Sie den Code aus.

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

  3. Die Ausgabe sollte dem folgenden Beispiel ähneln, bei dem die beste Antwort auf Frage aus einem der Ergebnisse abgerufen wird.

    Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

    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<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

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

Verwenden Sie in dieser Schnellstartanleitung ein Jupyter-Notizbuch und die Azure-Search-Dokumentbibliothek im Azure SDK für Python, um mehr über die semantische Rangfolge zu erfahren.

Wir empfehlen Visual Studio Code mit Python 3.10 oder höher und der Python-Erweiterung für diese Schnellstartanleitung.

Tipp

Sie können ein fertiges Notizbuch herunterladen , um mit einem fertigen Projekt zu beginnen, oder führen Sie diese Schritte aus, um eigene Zu erstellen.

Wir empfehlen eine virtuelle Umgebung für diesen Schnellstart:

  1. Starten Sie Visual Studio Code.

  2. Öffnen Sie die Datei "semantic-search-quickstart.ipynb ", oder erstellen Sie ein neues Notizbuch.

  3. Öffnen Sie die Befehlspalette mithilfe von STRG+UMSCHALT+P.

  4. Suchen Sie nach Python: Umgebung erstellen.

  5. Venv. auswählen

  6. Wählen Sie einen Python-Interpreter aus. Wählen Sie 3.10 oder höher aus.

Die Einrichtung kann eine Minute dauern. Wenn Probleme auftreten, sehen Sie unter Python-Umgebungen in VS Code nach.

Installieren von Paketen und Festlegen von Umgebungsvariablen

  1. Installieren Sie Pakete, einschließlich azure-search-documents.

    ! pip install -r requirements.txt --quiet

  2. Benennen Sie sample.env in .env um, und stellen Sie Ihren Suchdienstendpunkt bereit. Sie können den Endpunkt über das Azure-Portal auf der Seite "Übersicht" des Suchdiensts abrufen.

    AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX_NAME=hotels-sample-index

Anmelden bei Azure

Wenn Sie sich beim Azure-Portal angemeldet haben, sind Sie bei Azure angemeldet. Wenn Sie nicht sicher sind, verwenden Sie die Azure CLI oder Azure PowerShell, um sich anzumelden: az login oder az connect. Wenn Sie über mehrere Mandanten und Abonnements verfügen, lesen Sie "Schnellstart: Verbinden ohne Schlüssel", um Hilfe beim Herstellen einer Verbindung zu erhalten.

Aktualisieren des Indexes

In diesem Abschnitt aktualisieren Sie einen Suchindex so, dass er eine semantische Konfiguration enthält. Der Code ruft die Indexdefinition aus dem Suchdienst ab und fügt eine semantische Konfiguration hinzu.

  1. Öffnen Sie die Datei "semantic-search-quickstart.ipynb " in Visual Studio Code, oder erstellen Sie eine neue Datei.

  2. Geben Sie die variablen an, die in der Lösung verwendet werden.

    # 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")

  3. Erstellen Sie einen SearchIndexClient, und rufen Sie den vorhandenen Hotels-Sample-Index ab.

    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}")

  4. Führen Sie den Code aus.

  5. Die Ausgabe ist der Name des Indexes, der Liste der Felder und einer Anweisung, die angibt, ob eine semantische Konfiguration vorhanden ist. Für diese Schnellstartanleitung sollte die Meldung "Für diesen Index ist keine semantische Konfiguration vorhanden" sagen.

  6. Fügen Sie eine semantische Konfiguration zu einem vorhandenen Hotelsbeispielindex in Ihrem Suchdienst hinzu. Durch diesen Vorgang werden keine Suchdokumente gelöscht, und Ihr Index ist nach dem Hinzufügen der Konfiguration weiterhin funktionsfähig.

    # 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}")

  7. Führen Sie den Code aus.

  8. Die Ausgabe ist die semantische Konfiguration, die Sie soeben hinzugefügt haben.

Ausführen semantischer Abfragen

Sobald der Index über eine semantische Konfiguration verfügt, können Sie Abfragen ausführen, die semantische Parameter enthalten.

  1. Erstellen Sie einen SearchClient und eine Abfrageanforderung, die den semantischen Abfragetyp und die semantische Konfiguration enthält. Dies ist die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

    # 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']}")

  2. Führen Sie den Code aus.

  3. Die Ausgabe sollte aus 13 Dokumenten bestehen, sortiert nach "@search.reranker_score".

Zurückgeben von Beschriftungen

Optional können Sie Beschriftungen hinzufügen, um Teile des Texts zu extrahieren und Treffermarkierungen auf die wichtigen Begriffe und Ausdrücke anzuwenden. Diese Abfrage fügt Beschriftungen hinzu.

  1. Zur Abfrage captions hinzufügen.

    # 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")

  2. Führen Sie den Code aus.

  3. Die Ausgabe sollte neben dem Suchfeld ein neues Beschriftungselement enthalten. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größere Textabschnitte enthält, ist eine Beschriftung hilfreich, um die interessantesten Sätze zu extrahieren.

    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.

Zurückgeben semantischer Antworten

Geben Sie in dieser letzten Abfrage semantische Antworten zurück.

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten. Wenn die semantische Antwort für Ihr Szenario nicht hilfreich ist, können Sie das semantic_answers aus Ihrem Code weglassen.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

  1. Zur Abfrage answers hinzufügen.

    # 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")

  2. Führen Sie den Code aus.

  3. Die Ausgabe sollte dem folgenden Beispiel ähneln, bei dem die beste Antwort auf Frage aus einem der Ergebnisse abgerufen wird.

    Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

    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.

...

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

In dieser Schnellstartanleitung verwenden Sie einen REST-Client und die Azure AI Search-REST-APIs , um einen semantischen Rangfolger zu konfigurieren und zu verwenden.

Wir empfehlen Visual Studio Code mit einer REST-Clienterweiterung für diese Schnellstartanleitung.

Tipp

Sie können den Quellcode herunterladen, um mit einem fertigen Projekt zu beginnen, oder führen Sie die folgenden Schritte aus, um Eigene zu erstellen.

  1. Starten Sie Visual Studio Code, und öffnen Sie die Datei "semantic-search-index-update.rest ", oder erstellen Sie eine neue Datei.

  2. Legen Sie oben Umgebungsvariablen für Ihren Suchdienst, die Autorisierung und den Indexnamen fest.

    • Melden Sie sich für @searchURL beim Azure-Portal an, und kopieren Sie die URL von der Seite Übersicht des Suchdiensts.

    • Befolgen Sie für @personalAccessToken die Anweisungen unter Herstellen einer Verbindung ohne Schlüssel, um Ihr persönliches Zugriffstoken abzurufen.

  3. Um die Verbindung zu testen, senden Sie Ihre erste Anforderung.

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

  4. Wählen Sie Anforderung senden aus.

    Screenshot des Links zum Senden von Anfragen mit dem REST-Client.

  5. Die Ausgabe für diese GET-Anforderung gibt eine Liste vorhandener Indizes zurück. Sie sollten einen HTTP 200-Erfolgsstatuscode und eine Liste der Indizes abrufen, einschließlich hotels-sample-index, der in dieser Schnellstartanleitung verwendet wird.

Aktualisieren des Indexes

Um einen Index mithilfe der REST-API zu aktualisieren, müssen Sie das gesamte Schema sowie die Änderungen bereitstellen, die Sie vornehmen möchten. Diese Anfrage stellt das "hotels-sample-index"-Schema sowie die semantische Konfiguration bereit. Die Änderung besteht aus dem folgenden JSON.

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

  1. Formulieren sie eine PUT-Anforderung, die den Indexnamen, den Vorgang und das vollständige JSON-Schema angibt. Alle erforderlichen Elemente des Schemas müssen vorhanden sein. Diese Anforderung enthält das vollständige Schema für hotels-sample-index plus die semantische Konfiguration.

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

  2. Wählen Sie Anforderung senden aus.

  3. Die Ausgabe für diese POST-Anforderung ist eine HTTP 200 Success Statusmeldung.

Ausführen semantischer Abfragen

Erforderliche semantische Parameter enthalten query_type und semantic_configuration_name. Hier ist ein Beispiel für eine einfache semantische Abfrage mit den Minimalparametern.

  1. Öffnen Sie die Datei "semantic-search-query.rest ", oder erstellen Sie eine neue Datei.

  2. Legen Sie oben in der Datei Umgebungsvariablen für Ihren Suchdienst, die Autorisierung und den Indexnamen fest.

    • Melden Sie sich für @searchURL beim Azure-Portal an, und kopieren Sie die URL von der Seite Übersicht des Suchdiensts.

    • Befolgen Sie für @personalAccessToken die Anweisungen unter Herstellen einer Verbindung ohne Schlüssel, um Ihr persönliches Zugriffstoken abzurufen.

  3. Testen Sie die Verbindung mit einer GET-Anforderung, die den Hotels-Sample-Index zurückgibt.

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

  4. Senden Sie eine Abfrage, die den semantischen Abfragetyp und den Konfigurationsnamen enthält.

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

  5. Die Ausgabe besteht aus JSON-Suchergebnissen. Dreizehn Hotels stimmen mit der Abfrage überein. Die obersten sieben sind in diesem Beispiel enthalten.

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

Zurückgeben von Beschriftungen

Optional können Sie Beschriftungen hinzufügen, um Teile des Texts zu extrahieren und Treffermarkierungen auf die wichtigen Begriffe und Ausdrücke anzuwenden. Diese Abfrage fügt Untertitel hinzu, die auch Treffermarkierungen enthalten.

  1. Fügen Sie den captions Parameter hinzu, und senden Sie die Anforderung.

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

  2. Die Ausgabe besteht aus denselben Ergebnissen und zusätzlich "@search.captions". Hier sehen Sie den JSON-Code für ein einzelnes Dokument. Zu jeder Übereinstimmung gibt es Suchbewertungen, Nur-Text-Untertitel und Hervorhebungsformatierung sowie die Auswahlfelder.

    {
   "@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."
}

Zurückgeben semantischer Antworten

Geben Sie in dieser letzten Abfrage semantische Antworten zurück.

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten. Wenn die semantische Antwort für Ihr Szenario nicht hilfreich ist, können Sie das semantic_answers aus Ihrem Code weglassen.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

  1. Formulieren Sie die Anforderung mithilfe einer Suchzeichenfolge, die eine Frage stellt.

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

  2. Die Ausgabe besteht aus 41 Ergebnissen für die neue Abfrage mit „@search.answers“ für die Frage in der Abfrage zu Hotels für Personen, die gerne lesen.

    Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

    In diesem Beispiel wird die Antwort als sehr passend zur Frage angesehen.

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

In dieser Schnellstartanleitung erfahren Sie, wie Sie die semantische Rangfolge verwenden, indem Sie einem Suchindex eine semantische Konfiguration hinzufügen und einer Abfrage semantische Parameter hinzufügen. Sie können den Hotels-Sample-Index oder einen Ihrer eigenen verwenden.

In Azure AI Search ist die semantische Rangfolge abfrageseitige Funktionalität, die maschinelle Leseverständnis von Microsoft verwendet, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Je nach Inhalt und Abfrage kann die semantische Rangfolge die Suchrelevanz mit minimalem Entwickleraufwand erheblich verbessern.

Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist am effektivsten für Text, der informations- oder beschreibend ist.

Voraussetzungen

Konfigurieren des Zugriffs

Sie können eine Verbindung mit Ihrem Azure AI Search-Dienst über API-Schlüssel oder Microsoft Entra-ID mit Rollenzuweisungen herstellen. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen.

So konfigurieren Sie den rollenbasierten Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich Einstellungen>Schlüssel aus.

  3. Wählen Sie unter API-Zugriffssteuerung die rollenbasierte Zugriffssteuerung oder "Beide" aus, wenn Sie Zeit benötigen, um Clients auf rollenbasierten Zugriff umzustellen.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

  6. Weisen Sie Ihrem Benutzerkonto die Rollen Suchdienst-Teilnehmer und Suchindex-Daten-Teilnehmer zu.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird davon ausgegangen, dass ein vorhandener Index vorhanden ist, und es wird so geändert, dass er eine semantische Konfiguration enthält. Wir empfehlen den Hotels-Beispielindex , den Sie in Minuten mit einem Azure-Portal-Assistenten erstellen können.

So beginnen Sie mit einem vorhandenen Index:

  1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

  2. Wählen Sie unter Suchverwaltungsindizes> den Hotels-Beispielindex aus.

  3. Wählen Sie semantische Konfigurationen aus, um sicherzustellen, dass der Index nicht über eine semantische Konfiguration verfügt.

    Screenshot einer leeren Semantikkonfigurationsseite im Azure-Portal.

  4. Wählen Sie den Such-Explorer und dann die JSON-Ansicht aus.

  5. Fügen Sie den folgenden JSON-Code in den Abfrage-Editor ein.

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

    Screenshot einer Abfrage im Such-Explorer im Portal.

  6. Wählen Sie "Suchen" aus, um die Abfrage auszuführen.

    Diese Abfrage ist eine Stichwortsuche. Die Antwort sollte mit dem folgenden Beispiel vergleichbar sein, wie sie vom standardmäßigen BM25 L1-Rangfolger für die Volltextsuche bewertet wurde.

    Um die Lesbarkeit zu verbessern, wählt das Beispiel nur die Felder HotelId, HotelName und Description aus. Die Ergebnisse enthalten Verbatim-Übereinstimmungen für die Abfragebegriffe (walking, distance, , livemusic) oder sprachliche Varianten (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."
  }
]

Diese Abfrage zeigt, wie die Antwort aussieht , bevor die semantische Rangfolge angewendet wird. Später können Sie dieselbe Abfrage ausführen, nachdem die semantische Rangfolge konfiguriert wurde, um zu sehen, wie sich die Antwort ändert.

Tipp

Sie können eine semantische Konfiguration im Azure-Portal hinzufügen. Wenn Sie jedoch erfahren möchten, wie Sie eine semantische Konfiguration programmgesteuert hinzufügen, fahren Sie mit dieser Schnellstartanleitung fort.

Einrichten des Clients

In diesem Schnellstart verwenden Sie eine integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) und die Clientbibliothek @azure/search-documents, um einem vorhandenen Suchindex eine semantische Rangfolge hinzuzufügen.

Der Schnellstart setzt voraus, dass Folgendes auf Ihrem Computer verfügbar ist:

Tipp

Sie können den Quellcode herunterladen, um mit einem fertigen Projekt zu beginnen, oder führen Sie die folgenden Schritte aus, um Eigene zu erstellen.

Einrichten der lokalen Entwicklungsumgebung

  1. Starten Sie Visual Studio Code in einem neuen Verzeichnis.

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

  2. Erstellen Sie ein neues Paket für ESM-Module in Ihrem Projektverzeichnis.

    npm init -y
npm pkg set type=module

  3. Installieren Sie Entwicklungspakete, einschließlich azure-search-documents.

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

  4. Installieren Sie Entwicklungsabhängigkeitspakete.

    npm install dotenv @types/node --save-dev

  5. Erstellen Sie in Ihrem Projektverzeichnis eine Datei tsconfig.json, um ESM-Module zu aktivieren und die Modulauflösung festzulegen.

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

  6. Aktualisieren Sie package.json, um ein Skript zum Erstellen von TypeScript-Dateien einzuschließen. Fügen Sie die folgende Zeile zum scripts Abschnitt hinzu.

    "build": "tsc"

  7. Erstellen Sie .env, und geben Sie Ihren Suchdienstendpunkt an. Sie können den Endpunkt über das Azure-Portal auf der Seite "Übersicht" des Suchdiensts abrufen.

    AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config

  8. Erstellen Sie ein src-Verzeichnis in Ihrem Projektverzeichnis.

    mkdir src

Anmelden bei Azure

Wenn Sie sich beim Azure-Portal angemeldet haben, sind Sie bei Azure angemeldet. Wenn Sie nicht sicher sind, verwenden Sie die Azure CLI oder Azure PowerShell, um sich anzumelden: az login oder az connect. Wenn Sie über mehrere Mandanten und Abonnements verfügen, lesen Sie "Schnellstart: Verbinden ohne Schlüssel", um Hilfe beim Herstellen einer Verbindung zu erhalten.

Erstellen einer allgemeinen Authentifizierungsdatei

Erstellen Sie in ./src eine Datei namens config.ts, die die .env-Datei liest sowie die Umgebungsvariablen und Anmeldeinformationen für die Authentifizierung enthält. Kopieren Sie den folgenden Code in die Datei (ändern Sie ihn nicht). Diese Datei wird von allen anderen Dateien in diesem Schnellstart verwendet.

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;
    };
}

Abrufen des Indexschemas

In diesem Abschnitt rufen Sie Einstellungen für den vorhandenen Index hotels-sample-index für Ihren Suchdienst ab.

  1. Erstellen Sie in ./src eine Datei namens getIndexSettings.ts, und kopieren Sie den folgenden Code in die Datei.

    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.");
}

  2. Führen Sie den Code aus.

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

  3. Die Ausgabe ist der Name des Indexes, der Liste der Felder und einer Anweisung, die angibt, ob eine semantische Konfiguration vorhanden ist. Für die Zwecke dieses Schnellstarts sollte die Nachricht No semantic configuration exists for this index lauten.

Aktualisieren des Indexes mit einer semantischen Konfiguration

  1. Erstellen Sie in ./src eine Datei namens updateIndexSettings.ts, und kopieren Sie den folgenden Code in die Datei, um dem vorhandenen Index hotels-sample-index für ihren Suchdienst eine semantische Konfiguration hinzuzufügen. Durch diesen Vorgang werden keine Suchdokumente gelöscht, und Ihr Index ist nach dem Hinzufügen der Konfiguration weiterhin funktionsfähig.

    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);
}

  2. Führen Sie den Code aus.

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

  3. Die Ausgabe ist die semantische Konfiguration, die Sie soeben hinzugefügt haben – Semantic configuration updated successfully..

Ausführen semantischer Abfragen

Sobald der Index hotels-sample-index über eine semantische Konfiguration verfügt, können Sie Abfragen mit semantischen Parametern ausführen.

  1. Erstellen Sie in ./src eine Datei namens semanticQuery.ts, und kopieren Sie den folgenden Code in die Datei, um eine Semantikabfrage des Indexes zu erstellen. Dies ist die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

    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`);
}

  2. Führen Sie den Code aus.

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

  3. Die Ausgabe sollte aus 13 Dokumenten bestehen, sortiert nach rerankerScoreDisplay.

Zurückgeben von Beschriftungen

Optional können Sie Beschriftungen hinzufügen, um Teile des Texts zu extrahieren und Treffermarkierungen auf die wichtigen Begriffe und Ausdrücke anzuwenden. Diese Abfrage fügt Beschriftungen hinzu.

  1. Erstellen Sie in ./src eine Datei namens semanticQueryReturnCaptions.ts, und kopieren Sie den folgenden Code in die Datei, um der Abfrage Beschriftungen hinzuzufügen.

    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));
}

  2. Führen Sie den Code aus.

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

  3. Die Ausgabe sollte neben dem Suchfeld ein neues Beschriftungselement enthalten. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größere Textabschnitte enthält, ist eine Beschriftung hilfreich, um die interessantesten Sätze zu extrahieren.

    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.

Zurückgeben semantischer Antworten

Geben Sie in dieser letzten Abfrage semantische Antworten zurück.

Der semantische Rangierer kann eine Antwort auf eine Abfragezeichenfolge mit den Merkmalen einer Frage erzeugen. Die generierte Antwort wird aus Ihren Inhalten extrahiert, sodass sie nicht zusammengesetzte Inhalte wie das, was Sie von einem Chat-Vervollständigungsmodell erwarten können, enthalten. Wenn die semantische Antwort für Ihr Szenario nicht hilfreich ist, können Sie das semantic_answers aus Ihrem Code weglassen.

Um eine semantische Antwort zu erzeugen, muss die Frage und Antwort eng ausgerichtet sein, und das Modell muss Inhalte finden, die die Frage eindeutig beantworten. Wenn potenzielle Antworten einen Konfidenzschwellenwert nicht erreichen, gibt das Modell keine Antwort zurück. Zur Veranschaulichung ist die Frage in diesem Beispiel so gestaltet, dass Sie eine Antwort erhalten, damit Sie die Syntax sehen können.

  1. Erstellen Sie in ./src eine Datei namens semanticAnswer.ts, und kopieren Sie den folgenden Code in die Datei, um semantische Antworten zu erhalten.

    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`);
        }
    }
}

  2. Führen Sie den Code aus.

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

  3. Die Ausgabe sollte dem folgenden Beispiel ähneln, bei dem die beste Antwort auf Frage aus einem der Ergebnisse abgerufen wird.

    Bedenken Sie, dass Antworten direkt aus Ihrem Index stammen und wortwörtliche Inhalte sind und möglicherweise Ausdrücke fehlen, die ein Benutzer erwarten würde. Um durch ein Chatvervollständigungsmodell generierte Antworten zu erhalten, können Sie ein RAG-Muster oder den Agent-Abruf in Erwägung ziehen.

    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<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

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Geld kosten. Sie können entweder einzelne Ressourcen oder aber die Ressourcengruppe löschen, um den gesamten Ressourcensatz zu entfernen.

Sie können Ressourcen im Azure-Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich suchen und verwalten.

Verwandte Inhalte

In diesem Schnellstart haben Sie erfahren, wie Sie die Zuweisung einer semantischen Rangfolge für einen vorhandenen Index aufrufen. Es wird empfohlen, als nächsten Schritt die Zuweisung einer semantischen Rangfolge für Ihre eigenen Indizes auszuprobieren. Die folgenden Artikel können Ihnen bei den ersten Schritten helfen.

  • Last updated on