Schnellstart: Semantische Rangfolge

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search-Clientbibliothek für .NET, um semantic ranking zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Ein Azure KI-Suchdienst mit aktiviertem semantischem Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable bezeichnet sind. In diesem Schnellstart wird davon ausgegangen, dass der Hotels-Beispielindex existiert.

• .NET 9 oder höher.

• Visual Studio Code.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In diesem Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

Um den empfohlenen rollenbasierten Zugriff zu konfigurieren:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Search-Dienst verfügt über einen endpoint, der eine eindeutige URL ist, die Netzwerkzugriff auf den Dienst identifiziert und bereitstellt. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die als searchable und retrievable.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

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

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel entspricht walkingwalk, und live und music entsprechen unabhängig voneinander, anstatt als Ausdruck.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-dotnet-samples/quickstart-semantic-ranking
   code .
   

3. Ersetzen Sie in BuildIndex/Program.cs den Platzhalterwert für endpoint durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Wiederholen Sie den vorherigen Schritt für QueryIndex/Program.cs.

5. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

Ausführen des Codes

1. Führen Sie das erste Projekt aus, um den Index mit einer semantischen Konfiguration zu aktualisieren.

   dotnet run --project BuildIndex
   

2. Führen Sie das zweite Projekt aus, um den Index abzufragen. Drücken Sie die EINGABETASTE zwischen Abfragen, um den Verlauf von einfacher Abfrage zu semantischer Abfrage mit Beschriftungen und Antworten anzuzeigen.

   dotnet run --project QueryIndex
   

Output

Das erste Projekt aktualisiert den Hotel-Beispielindex mit einer semantischen Konfiguration. Die Ausgabe enthält eine Bestätigung der semantischen Konfiguration.

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

Das zweite Projekt führt vier Abfragen aus. Die Ausgabe enthält die Suchergebnisse mit Relevanzbewertungen, Beschriftungen und Antworten.

Query 1: Simple query using the search string 'walking distance to live music'.
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.004435
----------------------------------------
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.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
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.555706
@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.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
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: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
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.
----------------------------------------
... // Trimmed for brevity

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Beide Projekte verwenden dasselbe Konfigurationsmuster. Die Program.cs Dateien definieren den Such-Endpunkt und verwenden DefaultAzureCredential für die schlüssellose Authentifizierung.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

Wichtige Erkenntnisse:

• DefaultAzureCredential stellt die schlüssellose Authentifizierung mithilfe von Microsoft Entra ID bereit. Sie verknüpft mehrere Anmeldeinformationstypen, einschließlich der Azure-CLI-Anmeldeinformationen von az login.
• SearchIndexClient verwaltet Vorgänge auf Indexebene, z. B. das Aktualisieren des Indexschemas.
• SearchClient behandelt Vorgänge auf Dokumentebene, z. B. Abfragen des Indexes.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Der folgende Code fügt BuildIndex/Program.cs dem vorhandenen Index eine semantische Konfiguration hinzu. Dieser Vorgang löscht keine Suchdokumente, und Ihr Index bleibt funktionsfähig, nachdem die Konfiguration hinzugefügt wurde.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    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
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

Wichtige Erkenntnisse:

• Eine semantische Konfiguration gibt die Felder an, die für die semantische Rangfolge verwendet werden.
• Semantische Konfigurationen können vorhandenen Indizes hinzugefügt werden, ohne neu zu erstellen.
• TitleField legt das Feld fest, das den Dokumenttitel darstellt.
• ContentFields legt die Felder fest, die den Hauptinhalt enthalten.
• KeywordsFields legt die Felder fest, die Schlüsselwörter oder Tags enthalten.

Abfragen des Indexes

Das QueryIndex Projekt führt vier Abfragen der Reihe nach aus, beginnend mit einer einfachen Schlüsselwortsuche bis hin zum semantischen Ranking mit Beschriftungen und Antworten.

Einfache Abfrage

Die erste Abfrage ist eine einfache Stichwortsuche, die keine semantische Rangfolge verwendet. Diese Abfrage dient als Basis für den Vergleich von Ergebnissen mit und ohne semantischen Umrankung.

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

Wichtige Erkenntnisse:

• SearchQueryType.Simple verwendet den standardmäßigen BM25-Bewertungsalgorithmus.
• Die Ergebnisse werden nur nach Schlüsselwortrelevanz (@search.score) bewertet.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Die nächste Abfrage fügt die semantische Rangfolge ohne Beschriftungen oder Antworten hinzu. Der folgende Code zeigt die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

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

Wichtige Erkenntnisse:

• SearchQueryType.Semantic aktiviert die semantische Rangfolge für die Abfrage.
• SemanticConfigurationName Gibt an, welche semantische Konfiguration verwendet werden soll.
• @search.rerankerScore gibt die semantische Relevanz an (höher ist besser).
• Die ersten Ergebnisse aus der Ausdrucksabfrage werden mithilfe von semantischen Bewertungsmodellen neu bewertet. Für dieses Dataset und diese Abfrage sind die Auswirkungen der semantischen Rangfolge in den ergebnissen mit niedrigerer Rangfolge stärker ausgeprägt.

Semantische Abfrage mit Beschriftungen

Der folgende Code fügt Beschriftungen hinzu, die helfen, die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei Trefferhervorhebungen auf die wichtigen Begriffe und Ausdrücke angewendet werden.

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"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

Wichtige Erkenntnisse:

• QueryCaption aktiviert extraktive Beschriftungen aus den Inhaltsfeldern.
• Beschriftungen heben die relevantesten Passagen hervor und fügen <em>-Markierungen zu wichtigen Begriffen hinzu.

Semantische Abfrage mit Antworten

Die letzte Abfrage fügt semantische Antworten hinzu. Diese Abfrage verwendet eine andere Suchzeichenfolge (searchText2), da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Wenn Antworten für Ihr Szenario nicht hilfreich sind, lassen Sie QueryAnswer aus Ihrem Code. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

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

Wichtige Erkenntnisse:

• QueryAnswer ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search-Clientbibliothek für Java, um semantic ranking zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Ein Azure KI-Suchdienst mit aktiviertem semantischem Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable bezeichnet sind. In diesem Schnellstart wird davon ausgegangen, dass der Hotels-Beispielindex existiert.

• Java 21 (LTS) und Maven.

• Visual Studio Code.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In diesem Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

Um den empfohlenen rollenbasierten Zugriff zu konfigurieren:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Search-Dienst verfügt über einen endpoint, der eine eindeutige URL ist, die Netzwerkzugriff auf den Dienst identifiziert und bereitstellt. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die als searchable und retrievable.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

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

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel entspricht walkingwalk, und live und music entsprechen unabhängig voneinander, anstatt als Ausdruck.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-java-samples/quickstart-semantic-ranking
   code .
   

3. Ersetzen Sie in src/main/resources/application.properties den Platzhalterwert für azure.search.endpoint durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Kompilieren Sie das Projekt, um Abhängigkeiten zu beheben, einschließlich azure-search-documents.

   mvn compile
   

   Überprüfen Sie nach Abschluss des Builds, ob in der Ausgabe keine Fehler angezeigt werden.

5. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

Ausführen des Codes

1. Rufen Sie die vorhandenen Indexeinstellungen ab.

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

2. Aktualisieren Sie den Index mit einer semantischen Konfiguration.

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

3. Führen Sie eine semantische Abfrage aus.

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

4. Führen Sie eine semantische Abfrage mit Beschriftungen aus.

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

5. Führen Sie eine semantische Abfrage mit Antworten aus.

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

Output

Die Ausgabe von GetIndexSettings.java umfasst den Namen des Indexes, dessen Felder und semantische Konfigurationen. Bevor Sie eine neue Konfiguration hinzufügen, weist der Index nur die Standardkonfiguration auf.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

In der Ausgabe werden UpdateIndexSettings.java alle semantischen Konfigurationen im Index aufgelistet, einschließlich der vom Code hinzugefügten, gefolgt von einer Erfolgsmeldung.

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Die Ausgabe von SemanticQuery.java gibt alle übereinstimmenden Dokumente zurück, die nach dem semantischen Bewertungs-Re-Ranker-Score sortiert sind.

Search result #1:
  Re-ranker Score: 2.61
  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 result #2:
  Re-ranker Score: 2.27
  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 result #3:
  Re-ranker Score: 1.99
  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.
// Trimmed for brevity

Die Ausgabe von SemanticQueryWithCaptions.java fügt ein Captions-Element mit Treffermarkierung neben den Suchfeldern hinzu. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größeren Text enthält, helfen Beschriftungen beim Extrahieren der interessantesten Sätze.

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

  Caption text: 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.
------------------------------------------------------------
// Trimmed for brevity

Die Ausgabe von SemanticAnswer.java enthält eine semantische Antwort, die von einem der Ergebnisse abgerufen wird, die am besten mit der Frage übereinstimmen, gefolgt von Suchergebnissen mit Bildunterschriften.

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

Search Results:

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

Search result #2:
Re-ranker Score: 2.07
Hotel: 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.
// Trimmed for brevity

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Die SearchConfig.java Klasse lädt Eigenschaften aus application.properties und erstellt eine DefaultAzureCredential für die schlüssellose Authentifizierung.

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

Wichtige Erkenntnisse:

• DefaultAzureCredential stellt die schlüssellose Authentifizierung mithilfe von Microsoft Entra ID bereit. Es verbindet mehrere Anmeldedatentypen, einschließlich der Azure-CLI-Anmeldedaten von az login.
• Eigenschaften werden aus der application.properties Datei im Klassenpfad geladen.
• Statische Felder (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) werden für alle Klassen im project freigegeben.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Die UpdateIndexSettings.java Klasse fügt dem vorhandenen hotels-sample Index eine semantische Konfiguration hinzu. Dieser Vorgang löscht keine Suchdokumente, und Ihr Index bleibt funktionsfähig, nachdem die Konfiguration hinzugefügt wurde.

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;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

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

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

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

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Wichtige Erkenntnisse:

• SemanticPrioritizedFields definiert, welche Felder der semantische Rangfolger auswertet. setTitleField legt den Dokumenttitel fest, setContentFields legt den Hauptinhalt fest und setKeywordsFields legt das Schlüsselwort oder die Tagfelder fest.
• SemanticConfiguration koppelt einen Namen mit den priorisierten Feldern, die bestimmen, welche semantische Konfiguration zur Abfragezeit verwendet werden soll.
• createOrUpdateIndex verschiebt das aktualisierte Schema an die search service, ohne den Index neu zu erstellen oder Dokumente zu löschen.

Abfragen des Indexes

In den folgenden drei Klassen wird der Index in Reihenfolge abgefragt, wobei von einer einfachen semantischen Suche zu einer fortgeschrittenen semantischen Rangfolge mit Beschriftungen und Antworten fortgeschritten wird.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Die erste Abfrage fügt eine semantische Rangfolge ohne Beschriftungen oder Antworten hinzu. Die SemanticQuery.java Klasse zeigt die Mindestanforderung für das Aufrufen der semantischen Rangfolge an.

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;

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

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

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

Wichtige Erkenntnisse:

• QueryType.SEMANTIC aktiviert die semantische Rangfolge für die Abfrage.
• setSemanticConfigurationName Gibt an, welche semantische Konfiguration verwendet werden soll.
• SearchPagedIterable bietet eine Iterable über die neu geordneten Ergebnisse. Jeder SearchResult enthält einen getSemanticSearch() Accessor für die Rerankerbewertung.

Semantische Abfrage mit Beschriftungen

Die SemanticQueryWithCaptions.java-Klasse fügt Beschriftungen hinzu, um die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei Trefferhervorhebungen auf die wichtigen Begriffe und Ausdrücke angewendet werden.

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

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

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

Wichtige Erkenntnisse:

• QueryCaption(QueryCaptionType.EXTRACTIVE) aktiviert extraktive Beschriftungen aus den Inhaltsfeldern.
• setHighlightEnabled(true) Fügt <em> Tags zu wichtigen Begriffen in Beschriftungen hinzu.
• Jeder SearchResult stellt getQueryCaptions() für den semantischen Suchaccessor bereit.

Semantische Abfrage mit Antworten

Die SemanticAnswer.java Klasse fügt semantische Antworten hinzu. Diese Klasse verwendet eine Frage als Suchtext, da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Lassen Sie setQueryAnswer aus Ihrem Code aus, wenn Antworten für Ihr Szenario nicht hilfreich sind. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

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

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        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",
        answer.getScore());
}

Wichtige Erkenntnisse:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.
• results.getSemanticResults().getQueryAnswers() ruft die Antwortobjekte getrennt von den Suchergebnissen ab.

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search-Clientbibliothek für JavaScript, um semantic ranking zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Ein Azure AI Suchdienst mit aktiviertem semantischen Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable. Bei diesem Quickstart wird davon ausgegangen, dass der Hotels-Beispielindex vorhanden ist.

• Node.js 20 LTS oder höher.

• Visual Studio Code.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In diesem Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

So konfigurieren Sie den empfohlenen rollenbasierten Zugriff:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Suchdienst verfügt über einen Endpunkt, der eine eindeutige URL ist, die Netzwerkzugriff für den Dienst identifiziert und bereitstellt. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die mit searchable und retrievable bezeichnet sind.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

6. Fügen Sie den folgenden JSON-Code in den Query Editor ein.

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel walking entspricht walk, und live und music stimmen unabhängig überein, anstatt als Ausdruck.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-js
   code .
   

3. Ersetzen Sie in sample.env den Platzhalterwert für AZURE_SEARCH_ENDPOINT durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Benennen Sie sample.env in .env um.

   mv sample.env .env
   

5. Installieren Sie die Abhängigkeiten.

   npm install
   

   Nach Abschluss der Installation sollte im verzeichnis project ein ordner "node_modules" angezeigt werden.

6. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

Ausführen des Codes

1. Rufen Sie die vorhandenen Indexeinstellungen ab.

   node -r dotenv/config src/getIndexSettings.js
   

2. Aktualisieren Sie den Index mit einer semantischen Konfiguration.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Führen Sie eine semantische Abfrage aus.

   node -r dotenv/config src/semanticQuery.js
   

4. Führen Sie eine semantische Abfrage mit Beschriftungen aus.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Führen Sie eine semantische Abfrage mit Antworten aus.

   node -r dotenv/config src/semanticAnswer.js
   

Output

Das getIndexSettings.js Skript gibt den Namen des Indexes, dessen Felder und alle vorhandenen semantischen Konfigurationen zurück.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

Das updateIndexSettings.js Skript gibt alle semantischen Konfigurationen im Index zurück, einschließlich des hinzugefügten Codes, gefolgt von einer Erfolgsmeldung.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Das semanticQuery.js Skript gibt alle übereinstimmenden Dokumente zurück, die nach dem semantischen Rangfolgescore geordnet sind.

Search result #1:
  Re-ranker Score: 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 result #2:
  Re-ranker Score: 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 result #3:
  Re-ranker Score: 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.
// Trimmed for brevity

Das semanticQueryReturnCaptions.js Skript gibt ein Beschriftungselement mit Treffermarkierung zusammen mit Suchfeldern zurück. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größeren Text enthält, helfen Beschriftungen beim Extrahieren der interessantesten Sätze.

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

  Caption text: 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.
------------------------------------------------------------
// Trimmed for brevity

Das semanticAnswer.js Skript gibt eine semantische Antwort zurück, die von einem der Ergebnisse abgerufen wird, die am besten mit der Frage übereinstimmen, gefolgt von Suchergebnissen mit Beschriftungen.

Answers:

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

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
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.
// Trimmed for brevity

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Die config.js Datei lädt Umgebungsvariablen und erstellt ein DefaultAzureCredential für die Authentifizierung.

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

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";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

Wichtige Erkenntnisse:

• DefaultAzureCredential stellt die schlüssellose Authentifizierung mithilfe von Microsoft Entra ID bereit. Es verkettet mehrere Anmeldetypen, einschließlich der Azure CLI-Anmeldung von az login.
• Umgebungsvariablen werden aus der .env Datei mit dotenv geladen.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Die updateIndexSettings.js Datei fügt dem vorhandenen hotels-sample Index eine semantische Konfiguration hinzu. Dieser Vorgang löscht keine Suchdokumente, und Ihr Index bleibt funktionsfähig, nachdem die Konfiguration hinzugefügt wurde.

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

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

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Wichtige Erkenntnisse:

• Eine semantische Konfiguration gibt die Felder an, die für die semantische Rangfolge verwendet werden. titleField definiert den Dokumenttitel, contentFields definiert den Hauptinhalt und keywordsFields definiert das Schlüsselwort oder die Tagfelder.
• Sie erstellen ein Konfigurationsobjekt und übertragen es an das Array des vorhandenen Indexes semanticSearch.configurations .
• createOrUpdateIndex verschiebt das aktualisierte Schema an die search service, ohne den Index neu zu erstellen oder Dokumente zu löschen.

Abfragen des Indexes

Die Abfrageskripts führen drei Abfragen nacheinander aus, beginnend mit einer einfachen semantischen Suche und fortschreitend bis zu einer semantischen Rangfolge, die durch Beschriftungen und Antworten ergänzt wird.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Der folgende Code zeigt 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"
        ]
    }
);

Wichtige Erkenntnisse:

• queryType: "semantic" aktiviert die semantische Rangfolge für die Abfrage.
• semanticSearchOptions.configurationName Gibt an, welche semantische Konfiguration verwendet werden soll.
• Das rerankerScore-Ergebnis zeigt die semantische Relevanz an, höher ist besser.

Semantische Abfrage mit Beschriftungen

Der folgende Code fügt Beschriftungen hinzu, die helfen, die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei Trefferhervorhebungen auf die wichtigen Begriffe und Ausdrücke angewendet werden.

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

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Wichtige Erkenntnisse:

• captions.captionType: "extractive" aktiviert extraktive Beschriftungen aus den Inhaltsfeldern.
• Beschriftungen bringen die relevantesten Passagen hervor und fügen "Tags" um wichtige Begriffe hinzu.

Semantische Abfrage mit Antworten

Die letzte Abfrage fügt semantische Antworten hinzu. Diese Abfrage verwendet eine Frage als Suchtext, da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Wenn Antworten für Ihr Szenario nicht hilfreich sind, lassen Sie answers aus Ihrem Code weg. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

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

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Wichtige Erkenntnisse:

• answers.answerType: "extractive" ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.
• results.answers ruft die Antwortobjekte getrennt von den Suchergebnissen ab.

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search-Clientbibliothek für Python, um semantic ranking zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Ein Azure KI-Suchdienst mit aktiviertem semantischem Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable bezeichnet sind. In diesem Schnellstart wird davon ausgegangen, dass der Hotels-Beispielindex existiert.

• Python 3.10 oder höher.

• Visual Studio Code mit der erweiterung Python.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In diesem Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

Um den empfohlenen rollenbasierten Zugriff zu konfigurieren:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Search-Dienst verfügt über einen endpoint, der eine eindeutige URL ist, die Netzwerkzugriff auf den Dienst identifiziert und bereitstellt. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die als searchable und retrievable.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

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

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel entspricht walkingwalk, und live und music entsprechen unabhängig voneinander, anstatt als Ausdruck.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Semantic-Ranking
   code .
   

3. Ersetzen Sie in sample.env den Platzhalterwert für AZURE_SEARCH_ENDPOINT durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Benennen Sie sample.env in .env um.

   mv sample.env .env
   

5. Öffnen Sie semantic-ranking-quickstart.ipynb.

6. Drücken Sie STRG+UMSCHALT+P, wählen Sie Notizbuch: Notizbuch-Kernel auswählen, und folgen Sie den Anweisungen, um eine virtuelle Umgebung zu erstellen. Wählen Sie requirements.txt für die Abhängigkeiten aus.

   Nach Abschluss sollten Sie einen Ordner ".venv" im Projektverzeichnis sehen.

7. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

Ausführen des Codes

1. Führen Sie die Install packages and set variables Zellen aus, um die erforderlichen Pakete zu installieren und Umgebungsvariablen zu laden.

2. Führen Sie die verbleibenden Zellen sequenziell aus, um eine semantische Konfiguration hinzuzufügen und den Index abzufragen.

Output

Die Ausgabe der Get the index definition Zelle ist der Name des Indexes, der zugehörigen Felder und aller vorhandenen semantischen Konfigurationen.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

Die Ausgabe der Add a semantic configuration to the index Zelle listet alle semantischen Konfigurationen im Index auf, einschließlich des Codes, der hinzugefügt wurde, gefolgt von einer Erfolgsmeldung.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

Die Ausgabe der Run a term query-Zelle gibt alle passenden Dokumente zurück, die nach BM25-Score sortiert sind. Diese Basisplanabfrage verwendet keine semantische Rangfolge.

5.360838
4
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.
4.691083
2
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.
// Trimmed for brevity

Die Ausgabe der Run a semantic query Zelle gibt alle übereinstimmenden Dokumente zurück, die nach dem semantischen Re-Ranker-Score sortiert sind.

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.
2.271434783935547
2
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.
// Trimmed for brevity

Die Return captions-Zelle fügt in der Ausgabe ein Beschriftungselement mit Treffermarkierung neben den Suchfeldern hinzu. Beschriftungen sind die relevantesten Passagen in einem Ergebnis. Wenn Ihr Index größeren Text enthält, helfen Beschriftungen beim Extrahieren der interessantesten Sätze.

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.
// Trimmed for brevity

Die Ausgabe der Return semantic answers Zelle enthält eine semantische Antwort, die aus einem der Ergebnisse abgerufen wird, die am besten mit der Frage übereinstimmen, gefolgt von Suchergebnissen mit Beschriftungen.

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

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Die Install packages and set variables Zelle lädt Umgebungsvariablen und richtet einen Authentifizierungsprozess ein.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

Wichtige Erkenntnisse:

• DefaultAzureCredential stellt die schlüssellose Authentifizierung mithilfe von Microsoft Entra ID bereit. Sie verknüpft mehrere Anmeldeinformationstypen, einschließlich der Azure-CLI-Anmeldeinformationen von az login.
• Umgebungsvariablen werden von der .env Datei mithilfe python-dotenv geladen.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Die Add a semantic configuration to the index Zelle fügt dem vorhandenen hotels-sample Index eine semantische Konfiguration hinzu. Dieser Vorgang löscht keine Suchdokumente, und Ihr Index bleibt funktionsfähig, nachdem die Konfiguration hinzugefügt wurde.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

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

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

Wichtige Erkenntnisse:

• Eine semantische Konfiguration gibt die Felder an, die für die semantische Rangfolge verwendet werden. title_field legt den Dokumenttitel fest, content_fields legt den Hauptinhalt fest und keywords_fields legt das Schlüsselwort oder die Tagfelder fest.
• Sie erstellen die Konfiguration mit SemanticConfiguration und dem zugehörigen SemanticPrioritizedFields Modell, und fügen sie dann an den vorhandenen Index an.
• create_or_update_index verschiebt das aktualisierte Schema an die search service, ohne den Index neu zu erstellen oder Dokumente zu löschen.

Abfragen des Indexes

Die Abfragezellen führen vier Abfragen nacheinander aus: eine grundlegende Schlüsselwortsuche gefolgt von drei semantischen Rangfolgevariationen mit zunehmender Funktionalität.

Term-Abfrage (Baseline)

Die Run a term query-Zelle führt eine Schlüsselwortsuche mithilfe des BM25-Scorings durch. Diese Basisplanabfrage verwendet keine semantische Rangfolge und dient als Vergleichspunkt.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

Wichtige Erkenntnisse:

• query_type='simple' Gibt eine Schlüsselwortsuche mithilfe des BM25-Scorings an.
• Die @search.score in den Ergebnissen angezeigte Bewertung steht für den BM25-Relevanzwert.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Die Run a semantic query Zelle zeigt die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

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

Wichtige Erkenntnisse:

• query_type='semantic' aktiviert die semantische Rangfolge für die Abfrage.
• semantic_configuration_name Gibt an, welche semantische Konfiguration verwendet werden soll.
• Die @search.reranker_score ergebnisse deuten auf die semantische Relevanz hin (höher ist besser).

Semantische Abfrage mit Beschriftungen

Die Return captions Zelle fügt Beschriftungen hinzu, um die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei die Trefferheraushebung auf die wichtigen Begriffe und Ausdrücke angewendet wird.

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:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

Wichtige Erkenntnisse:

• query_caption='extractive' aktiviert extraktive Beschriftungen aus den Inhaltsfeldern.
• Beschriftungen heben die relevantesten Passagen hervor und fügen <em>-Tags um wichtige Begriffe hinzu.

Semantische Abfrage mit Antworten

Die Return semantic answers Zelle fügt semantische Antworten hinzu. Diese Abfrage verwendet eine Frage als Suchtext, da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Wenn die Antworten für Ihr Szenario nicht hilfreich sind, lassen Sie query_answer aus dem Code weg. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

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

Wichtige Erkenntnisse:

• query_answer="extractive" ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.
• results.get_answers() ruft die Antwortobjekte getrennt von den Suchergebnissen ab.

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search-Clientbibliothek für JavaScript (kompatibel mit TypeScript), um semantische Rangfolge zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Eine Azure KI-Suchdienst mit aktiviertem semantischen Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable attribuiert sind. In diesem Schnellstart wird angenommen, dass der hotels-sample index vorhanden ist.

• Node.js 20 LTS oder höher, um den kompilierten Code auszuführen.

• TypeScript zum Kompilieren von TypeScript in JavaScript.

• Visual Studio Code.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In dieser Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

So konfigurieren Sie den empfohlenen rollenbasierten Zugriff:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Suchdienst verfügt über einen Endpoint, welcher eine eindeutige URL ist, die Netzwerkzugriff bereitstellt und den Dienst im Netzwerk identifiziert. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die als searchable und retrievable.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

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

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel entspricht walkingwalk, und live und music entsprechen unabhängig voneinander, anstatt als Ausdruck.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
   code .
   

3. Ersetzen Sie in sample.env den Platzhalterwert für AZURE_SEARCH_ENDPOINT durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Benennen Sie sample.env in .env um.

   mv sample.env .env
   

5. Installieren Sie die Abhängigkeiten.

   npm install
   

   Nach Abschluss der Installation sollte im verzeichnis project ein ordner "node_modules" angezeigt werden.

6. Erstellen Sie die TypeScript-Dateien.

   npm run build
   

7. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

Ausführen des Codes

1. Rufen Sie die vorhandenen Indexeinstellungen ab.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Aktualisieren Sie den Index mit einer semantischen Konfiguration.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Führen Sie eine semantische Abfrage aus.

   node -r dotenv/config dist/semanticQuery.js
   

4. Führen Sie eine semantische Abfrage mit Beschriftungen aus.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Führen Sie eine semantische Abfrage mit Antworten aus.

   node -r dotenv/config dist/semanticAnswer.js
   

   Hinweis

   Diese Befehle führen Dateien aus dem Ordner dist aus, da zuvor mit npm run build von TypeScript in JavaScript transpiliert wurde.

Output

Das getIndexSettings.js Skript gibt den Indexnamen, die Feldanzahl, Felddetails mit Typ und durchsuchbaren Status sowie alle vorhandenen semantischen Konfigurationen zurück.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

Das updateIndexSettings.js Skript gibt alle semantischen Konfigurationen zurück, einschließlich des von Ihnen hinzugefügten.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

Das semanticQuery.js Skript gibt Ergebnisse zurück, die nach dem Reranker-Score sortiert sind.

Search result #1:
  Re-ranker Score: 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 result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

Das semanticQueryReturnCaptions.js Skript gibt extrahierende Beschriftungen mit Treffermarkierung zurück. Beschriftungen sind die relevantesten Passagen in einem Ergebnis.

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.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

Das semanticAnswer.js Skript gibt eine semantische Antwort (Verbatim-Inhalt) aus dem Ergebnis zurück, das am besten mit der Frage übereinstimmt.

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

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Die config.ts Datei lädt Umgebungsvariablen, erstellt eine DefaultAzureCredential Authentifizierung und definiert eine HotelDocument Schnittstelle für die Typsicherheit.

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

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";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

Wichtige Erkenntnisse:

• DefaultAzureCredential stellt die schlüssellose Authentifizierung mithilfe von Microsoft Entra ID bereit. Sie verknüpft mehrere Anmeldeinformationstypen, einschließlich der Azure-CLI-Anmeldeinformationen von az login.
• Die HotelDocument Schnittstelle bietet eine Kompilierungszeit-Typüberprüfung für Suchergebnisse, um einen typsicheren Zugriff auf Dokumentfelder zu gewährleisten.
• Umgebungsvariablen werden von der .env Datei mithilfe dotenv geladen.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Die updateIndexSettings.ts Datei fügt dem vorhandenen hotels-sample Index eine semantische Konfiguration hinzu. Dieser Vorgang löscht keine Suchdokumente, und Ihr Index bleibt funktionsfähig, nachdem die Konfiguration hinzugefügt wurde. TypeScript-Typanmerkungen stellen sicher, dass die Konfiguration mit dem erwarteten Schema übereinstimmt.

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

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

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Wichtige Erkenntnisse:

• TypeScript-Typen wie SemanticPrioritizedFields, SemanticConfigurationund SemanticField stellen eine Kompilierungszeitüberprüfung für die Konfigurationsstruktur bereit.
• titleField legt den Dokumenttitel fest, contentFields legt den Hauptinhalt fest und keywordsFields legt das Schlüsselwort oder die Tagfelder fest.
• createOrUpdateIndex verschiebt das aktualisierte Schema an die search service, ohne den Index neu zu erstellen oder Dokumente zu löschen.

Abfragen des Indexes

Die Abfrageskripts führen drei Abfragen nacheinander aus, beginnend mit einer einfachen semantischen Suche und fortschreitend bis zu einer semantischen Rangfolge, die durch Beschriftungen und Antworten ergänzt wird.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Das semanticQuery.ts Skript zeigt die Mindestanforderung für das Aufrufen der semantischen Rangfolge mit typsicheren Ergebnissen.

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

Wichtige Erkenntnisse:

• SearchClient<HotelDocument> bietet typsicheren Zugriff für den Zugriff auf Dokumentfelder in den Ergebnissen, mit Autovervollständigung für Feldnamen in select und result.document.
• queryType: "semantic" aktiviert die semantische Rangfolge für die Abfrage.
• semanticSearchOptions.configurationName Gibt an, welche semantische Konfiguration verwendet werden soll.

Semantische Abfrage mit Beschriftungen

Das semanticQueryReturnCaptions.ts Skript fügt Beschriftungen hinzu, um die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei trefferheraushebungen auf die wichtigen Begriffe und Ausdrücke angewendet werden.

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

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Wichtige Erkenntnisse:

• captions.captionType: "extractive" aktiviert extraktive Beschriftungen aus den Inhaltsfeldern.
• Beschriftungen heben die relevantesten Passagen hervor und fügen <em>-Markierungen zu wichtigen Begriffen hinzu.

Semantische Abfrage mit Antworten

Das semanticAnswer.ts Skript fügt semantische Antworten hinzu. Sie verwendet eine Frage als Suchtext, da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Wenn Antworten für Ihr Szenario nicht hilfreich sind, lassen Sie answers aus Ihrem Code. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

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

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Wichtige Erkenntnisse:

• answers.answerType: "extractive" ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.
• results.answers ruft die Antwortobjekte getrennt von den Suchergebnissen ab.

In dieser Schnellstartanleitung verwenden Sie die Azure AI Search REST-APIs um semantic ranking zu einem vorhandenen Suchindex hinzuzufügen und den Index abzufragen.

Bei der semantischen Rangfolge handelt es sich um abfrageseitige Funktionen, die maschinelle Leseverständnis verwenden, um Suchergebnisse neu zu bewerten und die semantisch relevantesten Übereinstimmungen am Anfang der Liste zu fördern. Sie können einem vorhandenen Index eine semantische Konfiguration hinzufügen, ohne dass eine Neuerstellung erforderlich ist. Die semantische Rangfolge ist für informations- oder beschreibenden Text am effektivsten.

Voraussetzungen

• Ein Azure Konto mit einem aktiven Abonnement. Ein Konto kostenlos erstellen.

• Ein Azure KI-Suchdienst mit aktiviertem semantischem Ranker.

• Ein Index mit beschreibenden Textfeldern, die als searchable und retrievable bezeichnet sind. In diesem Schnellstart wird davon ausgegangen, dass der Hotels-Beispielindex existiert.

• Visual Studio Code mit der REST-Clienterweiterung.

• Git zum Klonen des Beispiel-Repositorys.

• Die Azure CLI für die schlüssellose Authentifizierung mit Microsoft Entra ID.

Zugriff konfigurieren

Bevor Sie beginnen, stellen Sie sicher, dass Sie über berechtigungen zum access von Inhalten und Vorgängen in Azure AI Search verfügen. In diesem Schnellstart werden Microsoft Entra ID für die Authentifizierung und rollenbasierter Zugriff für die Autorisierung verwendet. Sie müssen ein Owner oder User Access Administrator sein, um Rollen zuzuweisen. Wenn Rollen nicht zugewiesen werden können, verwenden Sie stattdessen die schlüsselbasierte Authentifizierung.

Um den empfohlenen rollenbasierten Zugriff zu konfigurieren:

1. Aktivieren Sie rollenbasierten Zugriff für Ihren Suchdienst.

2. Weisen Sie Ihrem Benutzerkonto die folgenden Rollen zu.

   • Search Service Mitwirkender

   • Suchindexdatenleser

Endpunkt abrufen

Jeder Azure AI-Search-Dienst verfügt über einen endpoint, der eine eindeutige URL ist, die Netzwerkzugriff auf den Dienst identifiziert und bereitstellt. In einem späteren Abschnitt geben Sie diesen Endpunkt an, um eine programmgesteuerte Verbindung mit Ihrem search service herzustellen.

So rufen Sie den Endpunkt ab:

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

2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

3. Notieren Sie sich den Endpunkt, der wie https://my-service.search.windows.net aussehen soll.

Beginnen mit einem Index

In dieser Schnellstartanleitung wird ein vorhandener Index 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.

Um einen anderen Index zu verwenden, ersetzen Sie den Indexnamen, Feldnamen in der semantischen Konfiguration und Feldnamen in Abfrageanweisungen select im gesamten Beispielcode. Ihr Index sollte beschreibende Textfelder enthalten, die als searchable und retrievable.

So überprüfen und abfragen Sie den Hotels-Beispielindex vor der semantischen Rangfolge:

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

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

3. Wählen Sie hotels-sample aus.

4. Wählen Sie semantische Konfigurationen aus, um vorhandene Konfigurationen anzuzeigen. Wenn Sie die semantische Rangfolge während des Assistentenerstellungsablaufs aktiviert haben, sollte eine Standardkonfiguration vorhanden sein.

   

5. Wählen Sie den Such-Explorer und dann dieJSON-Ansicht anzeigen> aus.

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

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

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

   Die Antwort sollte dem folgenden Beispiel ähneln. Dies ist eine Volltextabfrage, die von BM25 bewertet wird, sodass die Ergebnisse auf einzelnen Abfragebegriffen und sprachlichen Varianten und nicht auf die Gesamtbedeutung der Abfrage übereinstimmen. Zum Beispiel passt walking zu walk, und live und music passen unabhängig voneinander und nicht als Ausdruck zusammen.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "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.555706,
       "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": 3.5625167,
       "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."
     },
     ... // Trimmed for brevity
   ]
   

   Tipp

   Diese Abfrage zeigt, wie die Antwort aussieht, bevor die semantische Rangfolge angewendet wird. Nachdem Sie eine semantische Konfiguration konfiguriert haben, fügen Sie hinzu "queryType": "semantic" , und "semanticConfiguration": "semantic-config" um zu sehen, wie dieselbe Abfrage nach semantischer Rangfolge unterschiedlich bewertet wird.

Einrichten der Umgebung

1. Verwenden Sie Git, um das Beispiel-Repository zu klonen.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. Navigieren Sie zum Schnellstartordner, und öffnen Sie ihn in Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-semantic-ranking
   code .
   

3. Ersetzen Sie in semantic-index-update.rest den Platzhalterwert für @searchUrl durch die URL, die Sie im Get-Endpunkt abgerufen haben.

4. Wiederholen Sie den vorherigen Schritt für semantic-query.rest.

5. Melden Sie sich für die schlüssellose Authentifizierung mit Microsoft Entra ID bei Ihrem Azure-Konto an. Wenn Sie über mehrere Abonnements verfügen, wählen Sie das Abonnement aus, das Ihre Azure AI-Search service enthält.

   az login
   

6. Generieren Sie für die schlüssellose Authentifizierung mit Microsoft Entra ID ein access-Token.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

7. Ersetzen Sie in beiden .rest Dateien den Platzhalterwert für @personalAccessToken durch das Token aus dem vorherigen Schritt.

Ausführen des Codes

1. Öffnen Sie semantic-index-update.rest.

2. Wählen Sie " Anforderung senden" für die erste GET-Anforderung aus, um Ihre Verbindung zu überprüfen.

   Im angrenzenden Bereich sollte eine Antwort angezeigt werden. Wenn Sie über vorhandene Indizes verfügen, werden sie anhand des Namens aufgelistet. Wenn der HTTP-Code lautet 200 OK, können Sie fortfahren.

3. Senden Sie die ### Update the hotels-sample index to include a semantic configuration Anforderung, um dem Index eine semantische Konfiguration hinzuzufügen.

   Wenn sie einen 400 Bad Request Fehler erhalten, unterscheidet sich Ihr Indexschema vom Beispiel. Senden Sie die ### Get the schema of the index Anforderung, kopieren Sie den Antwort-JSON-Code, fügen Sie den semantic Abschnitt aus dem Quellcode zum JSON hinzu, und ersetzen Sie den PUT-Anforderungstext durch Ihr zusammengeführtes Schema.

4. Wechseln Sie zu semantic-query.rest und senden Sie die Anfragen nacheinander: Eine einfache Abfrage zum Vergleich der Ausgangsbasis und dann semantische Abfragen mit Rangfolge, Beschriftungen und Antworten.

Output

Die Send a search query to the hotels-sample index Anforderung gibt Ergebnisse zurück, die nach BM25-Relevanz bewertet wurden, was durch das @search.score Feld angegeben wird.

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

Die Send a search query to the hotels-sample index with semantic ranking Anforderung fügt @search.rerankerScore hinzu. Beachten Sie, dass sich die Reihenfolge aus der einfachen Abfrage ändert.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

Die Return captions in the query Anforderung fügt @search.captions mit extrahiertem Text und Hervorhebungen hinzu.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@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...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

Die Return semantic answers in the query Anfrage liefert eine extraktive Antwort in @search.answers, wenn die Abfrage als Frage formuliert wird.

{
  "@odata.count": 46,
  "@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...",
      "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...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Grundlegendes zum Code

Nachdem Sie den Code ausgeführt haben, lassen Sie uns die wichtigsten Schritte aufschlüsseln:

1. Konfiguration und Authentifizierung
2. Aktualisieren des Indexes mit einer semantischen Konfiguration
3. Abfragen des Indexes

Konfiguration und Authentifizierung

Beide .rest Dateien definieren Variablen oben für die Wiederverwendung für alle Anforderungen.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2025-09-01

Wichtige Erkenntnisse:

• @searchUrl ist der Endpunkt Ihres search service.
• @personalAccessToken ist ein Microsoft Entra ID Token, das vom Azure CLI abgerufen wird. Dadurch werden API-Schlüssel durch die schlüssellose Authentifizierung ersetzt.
• Authorization: Bearer {{personalAccessToken}} ist in jedem Anforderungsheader für die Authentifizierung enthalten.

Aktualisieren des Indexes mit einer semantischen Konfiguration

Die ### Update the hotels-sample index to include a semantic configuration Anforderung in semantic-index-update.rest sendet das vollständige Indexschema zusammen mit einem neuen semantic Abschnitt. Die REST-API erfordert das vollständige Schema für jeden Updatevorgang, sodass Sie nicht nur die semantische Konfiguration senden können.

Die Schlüsselzugabe ist der semantic Abschnitt:

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

Wichtige Erkenntnisse:

• titleField gibt an, welches Feld den Dokumenttitel für die semantische Auswertung enthält.
• prioritizedContentFields identifiziert die Hauptinhaltsfelder. Der semantische Rangierer wertet diese zuerst aus, wenn die Relevanz bewertet wird.
• prioritizedKeywordsFields identifiziert Schlüsselwort- oder Tagfelder für zusätzlichen Kontext.
• rankingOrder: BoostedRerankerScore kombiniert den BM25-Bewertungscore mit dem semantischen Reranking-Score.
• Die REST-API erfordert das vollständige Schema für PUT-Vorgänge. Nur der semantic Abschnitt ist neu. Alle anderen Felder sind unverändert.

Abfragen des Indexes

Die Anforderungen in semantic-query.rest entwickeln sich von einer einfachen Schlüsselwortsuche zu einer semantischen Einordnung mit Untertiteln und Antworten. Alle Abfragen sind POST-Anforderungen an die Dokumente - Search Post (REST-API).

Einfache Abfrage

Die ### Send a search query to the hotels-sample index Anforderung ist eine einfache Schlüsselwortsuche, die keine semantische Rangfolge verwendet. Sie dient als Basis für den Vergleich von Ergebnissen mit und ohne semantischen Neuranking.

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

Wichtige Erkenntnisse:

• queryType: "simple" verwendet den standardmäßigen BM25-Bewertungsalgorithmus.
• Die Ergebnisse werden nur nach Schlüsselwortrelevanz (@search.score) bewertet.

Semantische Abfrage (keine Beschriftungen, keine Antworten)

Die ### Send a search query to the hotels-sample index with semantic ranking Anforderung fügt semantische Rangfolge hinzu. Der folgende JSON-Code zeigt die Mindestanforderung für das Aufrufen der semantischen Rangfolge.

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

Wichtige Erkenntnisse:

• queryType: "semantic" aktiviert die semantische Rangfolge für die Abfrage.
• semanticConfiguration Gibt an, welche semantische Konfiguration verwendet werden soll.

Semantische Abfrage mit Beschriftungen

Die ### Return captions in the query Anforderung fügt Beschriftungen hinzu, um die relevantesten Passagen aus jedem Ergebnis zu extrahieren, wobei die Trefferheraushebung auf die wichtigen Begriffe und Ausdrücke angewendet wird.

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

Wichtige Erkenntnisse:

• captions: "extractive|highlight-true" ermöglicht extraktive Beschriftungen mit <em> Tags um wichtige Begriffe herum.
• Beschriftungen werden im @search.captions Array für jedes Ergebnis angezeigt.

Semantische Abfrage mit Antworten

Die ### Return semantic answers in the query Anforderung fügt semantische Antworten hinzu. Sie verwendet eine Frage als Suchtext, da semantische Antworten am besten funktionieren, wenn die Abfrage als Frage formuliert wird. Die Antwort ist eine aus Ihrem Index extrahierte Verbatim-Passage, keine zusammengesetzte Antwort aus einem Chat-Vervollständigungsmodell.

Die Abfrage und der indizierte Inhalt müssen eng ausgerichtet sein, damit eine Antwort zurückgegeben wird. Wenn kein Kandidat den Konfidenzschwellenwert erfüllt, enthält die Antwort keine Antwort. In diesem Beispiel wird eine Frage verwendet, die bekannt ist, um ein Ergebnis zu erzeugen, damit Sie die Syntax sehen können. Wenn Antworten für Ihr Szenario nicht hilfreich sind, lassen Sie den answers Parameter aus Ihrer Anforderung weg. Berücksichtigen Sie für zusammengesetzte Antworten ein RAG-Muster oder einen agentischen Abruf.

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

Wichtige Erkenntnisse:

• answers: "extractive" ermöglicht extrahierende Antworten für fragenähnliche Abfragen.
• Antworten werden im Array der obersten Ebene @search.answers angezeigt, getrennt von einzelnen Ergebnissen.
• Antworten sind aus Ihrem Index extrahierte Inhalte, nicht generierter Text.