Snelle Start: Semantische Rangschikking - Azure AI Search

In deze quickstart gebruikt u de Azure AI Zoeken-clientbibliotheek voor .NET om semantische rangschikking toe te voegen aan een bestaande zoekindex en een query uit te voeren op de index.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
.NET 9 of hoger.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een zin.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap.

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

Vervang in BuildIndex/Program.cs de tijdelijke aanduidingswaarde voor endpoint met de URL die u hebt verkregen in Get endpoint.
Herhaal de vorige stap voor QueryIndex/Program.cs.
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

De code uitvoeren

Voer het eerste project uit om de index bij te werken met een semantische configuratie.
```
dotnet run --project BuildIndex
```
Voer het tweede project uit om een query uit te voeren op de index. Druk op Enter tussen query's om de voortgang van eenvoudige query's tot semantische query's met bijschriften en antwoorden weer te geven.
```
dotnet run --project QueryIndex
```

Output

Het eerste project werkt de index hotels-sample bij met een semantische configuratie. De uitvoer bevat een bevestiging van de semantische configuratie.

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

In het tweede project worden vier query's uitgevoerd. De uitvoer bevat de zoekresultaten met relevantiescores, bijschriften en antwoorden.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

Beide projecten delen hetzelfde configuratiepatroon. De Program.cs bestanden definiëren het zoekeindpunt en gebruiken DefaultAzureCredential voor sleutelloze verificatie.

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

Belangrijke punten:

DefaultAzureCredential biedt sleutelloze verificatie met behulp van Microsoft Entra ID. Het koppelt meerdere referentietypen, inclusief de Azure CLI referentie uit az login.
SearchIndexClient beheert bewerkingen op indexniveau, zoals het bijwerken van het indexschema.
SearchClient verwerkt bewerkingen op documentniveau, zoals het uitvoeren van query's op de index.

De index bijwerken met een semantische configuratie

Met de volgende code wordt BuildIndex/Program.cs een semantische configuratie toegevoegd aan de bestaande index. Met deze bewerking worden geen zoekdocumenten verwijderd en blijft uw index operationeel nadat de configuratie is toegevoegd.

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

Belangrijke punten:

Een semantische configuratie geeft de velden op die worden gebruikt voor semantische rangschikking.
Semantische configuraties kunnen worden toegevoegd aan bestaande indexen zonder opnieuw te bouwen.
TitleField stelt het veld in dat de documenttitel vertegenwoordigt.
ContentFields stelt de velden in die de hoofdinhoud bevatten.
KeywordsFields stelt de velden met trefwoorden of tags in.

Query's uitvoeren op de index

In het QueryIndex project worden vier query's op volgorde uitgevoerd, waarbij een eenvoudige trefwoordzoekopdracht wordt uitgevoerd naar een semantische rangschikking met bijschriften en antwoorden.

Eenvoudige query

De eerste query is een eenvoudige trefwoordzoekopdracht die geen semantische rangschikking gebruikt. Deze query fungeert als basislijn voor het vergelijken van resultaten met en zonder semantische herrankering.

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

Belangrijke punten:

SearchQueryType.Simple maakt gebruik van het standaard-BM25-classificatie-algoritme.
Resultaten worden alleen gerangschikt op relevantie voor trefwoorden (@search.score).

Semantische query (geen bijschriften, geen antwoorden)

De volgende query voegt semantische rangschikking toe zonder bijschriften of antwoorden. De volgende code toont de minimale vereiste voor het aanroepen van semantische rangschikking.

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

Belangrijke punten:

SearchQueryType.Semantic maakt semantische classificatie voor de query mogelijk.
SemanticConfigurationName geeft aan welke semantische configuratie moet worden gebruikt.
@search.rerankerScore geeft semantische relevantie aan (hoger is beter).
De eerste resultaten van de termquery worden opnieuw gescored met behulp van semantische classificatiemodellen. Voor deze gegevensset en query zijn de effecten van semantische rangschikking duidelijker in de lagere resultaten.

Semantische query met beschrijvingen

Met de volgende code worden bijschriften toegevoegd om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

QueryCaption schakelt geëxtraheerde bijschriften uit de inhoudsvelden in.
Bijschriften laten de meest relevante passages zien en voeg tags toe  rond belangrijke termen.

Semantische query met antwoorden

Met de laatste query worden semantische antwoorden toegevoegd. Deze query maakt gebruik van een andere zoekreeks (searchText2) omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een exacte passage die is geëxtraheerd uit uw index, niet een samengesteld antwoord van een chatvoltooiingsmodel.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen retourneren. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat dan QueryAnswer weg uit uw code. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

QueryAnswer maakt antwoorden die uit de tekst gehaald worden voor query's die op vragen lijken mogelijk.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.

In deze quickstart gebruikt u de Azure AI Zoeken-clientbibliotheek voor Java om semantische rangschikking toe te voegen aan een bestaande zoekindex en een query uit te voeren op de index.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
Java 21 (LTS) en Maven.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een woordgroep.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap.

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

Vervang in src/main/resources/application.properties de tijdelijke aanduidingswaarde voor azure.search.endpoint met de URL die u hebt verkregen in Get endpoint.
Compileer het project om afhankelijkheden op te lossen, waaronder azure-search-documents.
```
mvn compile
```
Wanneer de build is voltooid, controleert u of er geen fouten worden weergegeven in de uitvoer.
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

De code uitvoeren

Haal de bestaande indexinstellingen op.

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

Werk de index bij met een semantische configuratie.

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

Voer een semantische query uit.

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

Voer een semantische query uit met bijschriften.

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

Voer een semantische query uit met antwoorden.

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

Output

De uitvoer van GetIndexSettings.java is de naam van de index, de velden ervan en de semantische configuraties. Voordat u een nieuwe configuratie toevoegt, heeft de index slechts de standaardconfiguratie.

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

De uitvoer van UpdateIndexSettings.java geeft een lijst van alle semantische configuraties op de index, inclusief degene die de code heeft toegevoegd, vergezeld van een succesbericht.

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

De uitvoer van SemanticQuery.java retourneert alle overeenkomende documenten, geordend op basis van de semantische rangschikkingsscore.

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

De uitvoer van SemanticQueryWithCaptions.java voegt een bijschriftelement toe met treffermarkering naast de zoekvelden. Bijschriften zijn de meest relevante passages in een resultaat. Als uw index grotere tekst bevat, helpen bijschriften de meest interessante zinnen te extraheren.

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

De uitvoer van SemanticAnswer.java bevat een semantisch antwoord dat is opgehaald uit een van de resultaten die het beste overeenkomt met de vraag, gevolgd door zoekresultaten met bijschriften.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

De SearchConfig.java klasse laadt eigenschappen van application.properties en maakt een DefaultAzureCredential voor sleutelloze verificatie.

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

Belangrijke punten:

DefaultAzureCredential biedt sleutelloze verificatie met behulp van Microsoft Entra ID. Het koppelt meerdere referentietypen, inclusief de Azure CLI referentie uit az login.
Eigenschappen worden geladen vanuit het application.properties bestand in het klassepad.
Statische velden (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) worden gedeeld in alle klassen in het project.

De index bijwerken met een semantische configuratie

De UpdateIndexSettings.java klasse voegt een semantische configuratie toe aan de bestaande hotels-sample index. Met deze bewerking worden geen zoekdocumenten verwijderd en blijft uw index operationeel nadat de configuratie is toegevoegd.

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

Belangrijke punten:

SemanticPrioritizedFields definieert welke velden de semantische ranker evalueert. setTitleField stelt de titel van het document in, setContentFields stelt de hoofdinhoud in en setKeywordsFields stelt het trefwoord of de tagvelden in.
SemanticConfiguration koppelt een naam aan de velden met prioriteit, waarmee wordt opgegeven welke semantische configuratie moet worden gebruikt tijdens het uitvoeren van query's.
createOrUpdateIndex Pusht het bijgewerkte schema naar de zoekservice zonder de index opnieuw op te bouwen of documenten te verwijderen.

Query's uitvoeren op de index

De volgende drie klassen voeren een query uit op de index in volgorde, waarbij een eenvoudige semantische zoekopdracht wordt uitgevoerd naar een semantische rangschikking met bijschriften en antwoorden.

Semantische query (geen bijschriften, geen antwoorden)

De eerste query voegt semantische rangschikking toe zonder bijschriften of antwoorden. De SemanticQuery.java klasse toont de minimale vereiste voor het aanroepen van semantische classificatie.

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

Belangrijke punten:

QueryType.SEMANTIC maakt semantische classificatie voor de query mogelijk.
setSemanticConfigurationName geeft aan welke semantische configuratie moet worden gebruikt.
SearchPagedIterable biedt een iterator over de opnieuw gerangschikte resultaten. Elk SearchResult bevat een getSemanticSearch() accessor voor de herrankerscore.

Semantische query met beschrijvingen

De SemanticQueryWithCaptions.java klasse voegt bijschriften toe om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

QueryCaption(QueryCaptionType.EXTRACTIVE) schakelt geëxtraheerde bijschriften uit de inhoudsvelden in.
setHighlightEnabled(true) voegt tags toe  rond belangrijke termen in bijschriften.
Elk SearchResult biedt getQueryCaptions() als toegangsmiddel tot de semantische zoekfunctie.

Semantische query met antwoorden

De SemanticAnswer.java klasse voegt semantische antwoorden toe. Deze klasse gebruikt een vraag als zoektekst, omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een exacte passage die is geëxtraheerd uit uw index, niet een samengesteld antwoord van een chatvoltooiingsmodel.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen retourneren. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat dan setQueryAnswer weg uit uw code. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

QueryAnswer(QueryAnswerType.EXTRACTIVE) maakt antwoorden die uit de tekst gehaald worden voor query's die op vragen lijken mogelijk.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.
results.getSemanticResults().getQueryAnswers() haalt de antwoordobjecten afzonderlijk van de zoekresultaten op.

In deze quickstart gebruikt u de Azure AI Zoeken-clientbibliotheek voor JavaScript om semantische rangschikking toe te voegen aan een bestaande zoekindex en een query uit te voeren op de index.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
Node.js 20 LTS of hoger.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een zin.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap.

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

Vervang in sample.env de tijdelijke aanduidingswaarde voor AZURE_SEARCH_ENDPOINT met de URL die u hebt verkregen in Get endpoint.
Wijzig de naam sample.env in .env.
```
mv sample.env .env
```
Installeer de afhankelijkheden.
```
npm install
```
Wanneer de installatie is voltooid, ziet u een node_modules map in de projectmap.
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

De code uitvoeren

Haal de bestaande indexinstellingen op.

node -r dotenv/config src/getIndexSettings.js

Werk de index bij met een semantische configuratie.
```
node -r dotenv/config src/updateIndexSettings.js
```

Voer een semantische query uit.

node -r dotenv/config src/semanticQuery.js

Voer een semantische query uit met bijschriften.

node -r dotenv/config src/semanticQueryReturnCaptions.js

Voer een semantische query uit met antwoorden.
```
node -r dotenv/config src/semanticAnswer.js
```

Output

Het getIndexSettings.js script retourneert de naam van de index, de bijbehorende velden en eventuele bestaande semantische configuraties.

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

Het updateIndexSettings.js script retourneert alle semantische configuraties op de index, inclusief de configuratie die is toegevoegd aan de code, gevolgd door een geslaagd bericht.

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.

Het semanticQuery.js script retourneert alle overeenkomende documenten die zijn geordend op basis van de semantische rangschikkingsscore voor opnieuw rangschikken.

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

Het semanticQueryReturnCaptions.js script retourneert een bijschriftelement met treffermarkeringen naast zoekvelden. Bijschriften zijn de meest relevante passages in een resultaat. Als uw index grotere tekst bevat, helpen bijschriften de meest interessante zinnen te extraheren.

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

Het semanticAnswer.js script retourneert een semantisch antwoord dat is opgehaald uit een van de resultaten die het beste overeenkomt met de vraag, gevolgd door zoekresultaten met bijschriften.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

Het config.js bestand laadt omgevingsvariabelen en maakt een DefaultAzureCredential voor verificatie.

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

Belangrijke punten:

DefaultAzureCredential biedt sleutelloze verificatie met behulp van Microsoft Entra ID. Het koppelt meerdere referentietypen, inclusief de Azure CLI referentie uit az login.
Omgevingsvariabelen worden geladen vanuit het .env bestand met behulp van dotenv.

De index bijwerken met een semantische configuratie

Het updateIndexSettings.js bestand voegt een semantische configuratie toe aan de bestaande hotels-sample index. Met deze bewerking worden geen zoekdocumenten verwijderd en blijft uw index operationeel nadat de configuratie is toegevoegd.

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

Belangrijke punten:

Een semantische configuratie geeft de velden op die worden gebruikt voor semantische rangschikking. titleField definieert de documenttitel, contentFields definieert de hoofdinhoud en keywordsFields definieert het trefwoord- of tagvelden.
U maakt een configuratieobject en pusht dit naar de matrix van semanticSearch.configurations de bestaande index.
createOrUpdateIndex Pusht het bijgewerkte schema naar de zoekservice zonder de index opnieuw op te bouwen of documenten te verwijderen.

Query's uitvoeren op de index

Met de queryscripts worden drie query's op volgorde uitgevoerd, waarbij een eenvoudige semantische zoekopdracht wordt uitgevoerd naar een semantische rangschikking met bijschriften en antwoorden.

Semantische query (geen bijschriften, geen antwoorden)

De volgende code toont de minimale vereiste voor het aanroepen van semantische rangschikking.

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

Belangrijke punten:

queryType: "semantic" maakt semantische classificatie voor de query mogelijk.
semanticSearchOptions.configurationName geeft aan welke semantische configuratie moet worden gebruikt.
De rerankerScore resultaten geven semantische relevantie aan (hoger is beter).

Semantische query met bijschriften

Met de volgende code worden bijschriften toegevoegd om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

captions.captionType: "extractive" schakelt geëxtraheerde bijschriften uit de inhoudsvelden in.
Bijschriften laten de meest relevante passages zien en voeg tags toe  rond belangrijke termen.

Semantische query met antwoorden

Met de laatste query worden semantische antwoorden toegevoegd. Deze query maakt gebruik van een vraag als zoektekst, omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een letterlijke passage die is geëxtraheerd uit uw index, niet een gegenereerd antwoord van een model voor chatvoltooiing.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen geven. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat dan answers weg uit uw code. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

answers.answerType: "extractive" maakt extraheerbare antwoorden voor vraagachtige query's mogelijk.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.
results.answers haalt de antwoordobjecten afzonderlijk van de zoekresultaten op.

In deze quickstart gebruikt u de Azure AI Zoeken-clientbibliotheek voor Python om semantische rangschikking toe te voegen aan een bestaande zoekindex en een query uit te voeren op de index.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
Python 3.10 of hoger.
Visual Studio Code met de extensie Python.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een zin.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap en open deze in Visual Studio Code.

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

Vervang in sample.env de tijdelijke aanduidingswaarde voor AZURE_SEARCH_ENDPOINT met de URL die u hebt verkregen in Get endpoint.
Wijzig de naam sample.env in .env.
```
mv sample.env .env
```
Open semantic-ranking-quickstart.ipynb.
Druk op Ctrl+Shift+P, selecteer Notebook: Selecteer Notebook Kernel en volg de aanwijzingen om een virtuele omgeving te maken. Selecteer requirements.txt voor de afhankelijkheden.

Als u klaar bent, ziet u een .venv map in de projectmap.
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

De code uitvoeren

Voer de Install packages and set variables cellen uit om de vereiste pakketten te installeren en omgevingsvariabelen te laden.
Voer de resterende cellen opeenvolgend uit om een semantische configuratie toe te voegen en een query uit te voeren op de index.

Output

De uitvoer van de Get the index definition cel is de naam van de index, de bijbehorende velden en eventuele bestaande semantische configuraties.

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

De uitvoer van de Add a semantic configuration to the index cel bevat alle semantische configuraties in de index, inclusief degene die door de code is toegevoegd, gevolgd door een succesvol bericht.

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!

De uitvoer van de Run a term query cel retourneert alle overeenkomende documenten die zijn gerangschikt op BM25-score. Deze basislijnquery maakt geen gebruik van semantische classificatie.

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

De uitvoer van de Run a semantic query cel retourneert alle overeenkomende documenten die zijn gerangschikt op basis van de semantische herrangeerscore.

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

De uitvoer van de Return captions cel voegt een bijschriftelement toe met treffermarkeringen naast zoekvelden. Bijschriften zijn de meest relevante passages in een resultaat. Als uw index grotere tekst bevat, helpen bijschriften de meest interessante zinnen te extraheren.

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

De uitvoer van de Return semantic answers cel bevat een semantisch antwoord dat is opgehaald uit een van de resultaten die het beste overeenkomt met de vraag, gevolgd door zoekresultaten met bijschriften.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

De Install packages and set variables cel laadt omgevingsvariabelen en maakt een DefaultAzureCredential voor verificatie.

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

Belangrijke punten:

DefaultAzureCredential biedt sleutelloze verificatie met behulp van Microsoft Entra ID. Het koppelt meerdere referentietypen, inclusief de Azure CLI referentie uit az login.
Omgevingsvariabelen worden geladen vanuit het .env bestand met behulp van python-dotenv.

De index bijwerken met een semantische configuratie

De Add a semantic configuration to the index cel voegt een semantische configuratie toe aan de bestaande hotels-sample index. Met deze bewerking worden geen zoekdocumenten verwijderd en blijft uw index operationeel nadat de configuratie is toegevoegd.

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)

Belangrijke punten:

Een semantische configuratie geeft de velden op die worden gebruikt voor semantische rangschikking. title_field stelt de titel van het document in, content_fields stelt de hoofdinhoud in en keywords_fields stelt het trefwoord of de tagvelden in.
U maakt de configuratie met SemanticConfiguration en het bijbehorende SemanticPrioritizedFields model en voegt deze vervolgens toe aan de bestaande index.
create_or_update_index Pusht het bijgewerkte schema naar de zoekservice zonder de index opnieuw op te bouwen of documenten te verwijderen.

Query's uitvoeren op de index

In de querycellen worden vier query's op volgorde uitgevoerd: een trefwoordzoekopdracht volgens basislijn, gevolgd door drie semantische classificatievariaties met toenemende functionaliteit.

Termquery (basislijn)

De Run a term query cel voert een trefwoordzoekopdracht uit met behulp van de BM25-score. Deze basislijnquery maakt geen gebruik van semantische classificatie en fungeert als een vergelijkingspunt.

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
)

Belangrijke punten:

query_type='simple' geeft een trefwoordzoekopdracht op met behulp van BM25-score.
De @search.score- in de resultaten geeft de BM25-relevantiescore aan.

Semantische query (geen bijschriften, geen antwoorden)

In Run a semantic query de cel wordt de minimale vereiste voor het aanroepen van semantische rangschikking weergegeven.

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

Belangrijke punten:

query_type='semantic' maakt semantische classificatie voor de query mogelijk.
semantic_configuration_name geeft aan welke semantische configuratie moet worden gebruikt.
De @search.reranker_score resultaten geven semantische relevantie aan (hoger is beter).

Semantische query met beschrijvingen

De Return captions cel voegt bijschriften toe om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

query_caption='extractive' schakelt geëxtraheerde bijschriften uit de inhoudsvelden in.
Bijschriften laten de meest relevante passages zien en voeg tags toe  rond belangrijke termen.

Semantische query met antwoorden

De Return semantic answers cel voegt semantische antwoorden toe. Deze query maakt gebruik van een vraag als zoektekst, omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een exacte passage die is geëxtraheerd uit uw index, niet een samengesteld antwoord van een chatvoltooiingsmodel.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen retourneren. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat dan query_answer weg uit uw code. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

query_answer="extractive" maakt antwoorden die uit de tekst gehaald worden voor query's die op vragen lijken mogelijk.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.
results.get_answers() haalt de antwoordobjecten afzonderlijk van de zoekresultaten op.

In deze quickstart gebruikt u de Azure AI Zoeken-clientbibliotheek voor JavaScript (compatibel met TypeScript) om semantische classificatie toe te voegen aan een bestaande zoekindex en de index op te vragen.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
Node.js 20 LTS of hoger om de gecompileerde code uit te voeren.
TypeScript om TypeScript naar JavaScript te compileren.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een zin.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap.

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

Vervang in sample.env de tijdelijke aanduidingswaarde voor AZURE_SEARCH_ENDPOINT met de URL die u hebt verkregen in Get endpoint.
Wijzig de naam sample.env in .env.
```
mv sample.env .env
```
Installeer de afhankelijkheden.
```
npm install
```
Wanneer de installatie is voltooid, ziet u een node_modules map in de projectmap.
Compileer de TypeScript-bestanden naar JavaScript.
```
npm run build
```
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

De code uitvoeren

Haal de bestaande indexinstellingen op.

node -r dotenv/config dist/getIndexSettings.js

Werk de index bij met een semantische configuratie.

node -r dotenv/config dist/updateIndexSettings.js

Voer een semantische query uit.

node -r dotenv/config dist/semanticQuery.js

Voer een semantische query uit met bijschriften.

node -r dotenv/config dist/semanticQueryReturnCaptions.js

Voer een semantische query uit met antwoorden.
```
node -r dotenv/config dist/semanticAnswer.js
```
Opmerking

Met deze opdrachten worden de gecompileerde .js bestanden uit de dist map uitgevoerd. TypeScript-code moet worden getranspileerd naar JavaScript voordat Node.js deze kan uitvoeren. Daarom hebt u deze eerder uitgevoerd npm run build.

Output

Het getIndexSettings.js script retourneert de indexnaam, het aantal velden, velddetails met de type- en doorzoekbare status en eventuele bestaande semantische configuraties.

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

Het updateIndexSettings.js script retourneert alle semantische configuraties, inclusief de configuratie die u hebt toegevoegd.

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.

Het semanticQuery.js-script retourneert resultaten die zijn gerangschikt op basis van de herordening-score.

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

Het semanticQueryReturnCaptions.js script retourneert extraheerbare bijschriften met treffermarkeringen. Bijschriften zijn de meest relevante passages in een resultaat.

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

Het semanticAnswer.js script retourneert een semantisch antwoord (exacte inhoud) dat is opgehaald uit het resultaat dat het beste overeenkomt met de vraag.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

Het config.ts bestand laadt omgevingsvariabelen, maakt een DefaultAzureCredential voor verificatie en definieert een HotelDocument interface voor typeveiligheid.

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

Belangrijke punten:

DefaultAzureCredential biedt sleutelloze verificatie met behulp van Microsoft Entra ID. Het koppelt meerdere referentietypen, inclusief de Azure CLI referentie uit az login.
De HotelDocument interface biedt controle van het type compileertijd voor zoekresultaten, waardoor typeveilige toegang tot documentvelden wordt gegarandeerd.
Omgevingsvariabelen worden geladen vanuit het .env bestand met behulp van dotenv.

De index bijwerken met een semantische configuratie

Het updateIndexSettings.ts bestand voegt een semantische configuratie toe aan de bestaande hotels-sample index. Met deze bewerking worden geen zoekdocumenten verwijderd en blijft uw index operationeel nadat de configuratie is toegevoegd. TypeScript-aantekeningen zorgen ervoor dat de configuratie overeenkomt met het verwachte schema.

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

Belangrijke punten:

TypeScript-typen zoals SemanticPrioritizedFields, SemanticConfigurationen SemanticField bieden compileertijdvalidatie voor de configuratiestructuur.
titleField stelt de titel van het document in, contentFields stelt de hoofdinhoud in en keywordsFields stelt het trefwoord of de tagvelden in.
createOrUpdateIndex Pusht het bijgewerkte schema naar de zoekservice zonder de index opnieuw op te bouwen of documenten te verwijderen.

Query's uitvoeren op de index

Met de queryscripts worden drie query's op volgorde uitgevoerd, waarbij een eenvoudige semantische zoekopdracht wordt uitgevoerd naar een semantische rangschikking met bijschriften en antwoorden.

Semantische query (geen bijschriften, geen antwoorden)

Het semanticQuery.ts script toont de minimale vereiste voor het aanroepen van semantische classificatie met typeveilige resultaten.

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

Belangrijke punten:

SearchClient<HotelDocument> biedt typeveilige toegang tot documentvelden in resultaten, met automatisch aanvullen voor veldnamen in select en result.document.
queryType: "semantic" maakt semantische classificatie voor de query mogelijk.
semanticSearchOptions.configurationName geeft aan welke semantische configuratie moet worden gebruikt.

Semantische query met beschrijvingen

Het semanticQueryReturnCaptions.ts script voegt bijschriften toe om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

captions.captionType: "extractive" schakelt geëxtraheerde bijschriften uit de inhoudsvelden in.
Bijschriften laten de meest relevante passages zien en voeg tags toe  rond belangrijke termen.

Semantische query met antwoorden

Het semanticAnswer.ts script voegt semantische antwoorden toe. Er wordt een vraag gebruikt als zoektekst, omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een exacte passage die is geëxtraheerd uit uw index, niet een samengesteld antwoord van een chatvoltooiingsmodel.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen retourneren. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat dan answers weg uit uw code. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

answers.answerType: "extractive" maakt antwoorden die uit de tekst gehaald worden voor query's die op vragen lijken mogelijk.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.
results.answers haalt de antwoordobjecten afzonderlijk van de zoekresultaten op.

In deze quickstart gebruikt u de Azure AI Zoeken REST API's om semantische rangschikking toe te voegen aan een bestaande zoekindex en een query uit te voeren op de index.

Semantische classificatie is functionaliteit aan de queryzijde die gebruikmaakt van leesbegrip van machine om zoekresultaten opnieuw te scoren, waardoor de meest semantisch relevante overeenkomsten boven aan de lijst worden gepromoot. U kunt een semantische configuratie toevoegen aan een bestaande index zonder dat u deze opnieuw hoeft op te bouwen. Semantische rangschikking is het meest effectief voor informatieve of beschrijvende tekst.

Tip

Wilt u meteen aan de slag? Download de sourcecode op GitHub.

Voorwaarden

Een Azure-account met een actief abonnement. Maak gratis een account.
Een Azure AI Zoeken-service.
Een index met beschrijvende tekstvelden die zijn toegeschreven als searchable en retrievable. In deze quickstart wordt ervan uitgegaan dat de index hotels-sample is.
Visual Studio Code met de REST-clientextensie.
Git om de voorbeeldopslagplaats te klonen.
De Azure CLI voor sleutelloze verificatie met Microsoft Entra ID.

Toegang configureren

Voordat u begint, moet u ervoor zorgen dat u gemachtigd bent om toegang te krijgen tot inhoud en bewerkingen in Azure AI Zoeken. In deze quickstart wordt gebruikgemaakt van Microsoft Entra ID voor verificatie en op rollen gebaseerde toegang voor autorisatie. U moet eigenaar of beheerder van gebruikerstoegang zijn om rollen toe te wijzen. Als rollen niet haalbaar zijn, gebruikt u verificatie op basis van sleutels in plaats daarvan.

De aanbevolen op rollen gebaseerde toegang configureren:

Schakel op rollen gebaseerde toegang in voor uw zoekservice.
Wijs de volgende rollen toe aan uw gebruikersaccount.
- Inzender voor zoekservice
- Zoekindexgegevenslezer

Opmerking

In tegenstelling tot andere quickstarts waarmee een index wordt gemaakt en geladen, wordt in deze quickstart uitgegaan van een bestaande index die al gegevens bevat, dus u hebt de rol Inzender voor zoekindexgegevens niet nodig.

Eindpunt ophalen

Elke Azure AI Zoeken-service heeft een endpoint, een unieke URL die netwerktoegang tot de service identificeert en biedt. In een latere sectie geeft u dit eindpunt op om programmatisch verbinding te maken met uw zoekservice.

Volg deze stappen om het eindpunt te verkrijgen:

Ga naar uw zoekservice in de Azure portal.
Selecteer Overzicht in het linkerdeelvenster.
Noteer het eindpunt, dat er als https://my-service.search.windows.net uit moet zien.

Beginnen met een index

In deze quickstart wordt een bestaande index gewijzigd om een semantische configuratie op te nemen. We raden de voorbeeldindex hotels aan, die u in enkele minuten kunt maken met behulp van een wizard Azure portal.

Als u een andere index wilt gebruiken, vervangt u de indexnaam, veldnamen in de semantische configuratie en veldnamen in queryinstructies select in de voorbeeldcode. Uw index moet beschrijvende tekstvelden bevatten die worden toegeschreven als searchable en retrievable.

De voorbeeldindex hotels controleren en er query's op uitvoeren vóór de semantische classificatie:

Ga naar uw zoekservice in de Azure portal.
Selecteerzoekbeheerindexen> in het linkerdeelvenster.
Kies hotels-sample.
Selecteer Semantische configuraties om bestaande configuraties weer te geven. Als u semantische rangschikking hebt ingeschakeld tijdens de stroom voor het maken van de wizard, moet er een standaardconfiguratie zijn.
Selecteer Search Explorer en selecteer vervolgens JSON-weergave>weergeven.

Plak de volgende JSON in de query-editor.

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

Selecteer Zoeken om de query uit te voeren.

Het antwoord moet er ongeveer uitzien als in het volgende voorbeeld. Dit is een volledige-tekstquery gerangschikt op BM25, dus resultaten komen overeen met afzonderlijke querytermen en taalkundige varianten in plaats van de algehele betekenis van de query. Bijvoorbeeld, walking komt overeen met walk, en live en music komen onafhankelijk overeen in plaats van als een woordgroep.

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

Tip

Deze query laat zien hoe het antwoord eruitziet voordat semantische rangschikking wordt toegepast. Nadat u een semantische configuratie hebt geconfigureerd, voegt u deze toe "queryType": "semantic" en "semanticConfiguration": "semantic-config" om te zien hoe dezelfde query anders wordt gerangschikt op semantische classificatie.

De omgeving instellen

Gebruik Git om de voorbeeldopslagplaats te klonen.

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

Navigeer naar de snelstartmap en open deze in Visual Studio Code.

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

Vervang in semantic-index-update.rest de tijdelijke aanduidingswaarde voor @searchUrl met de URL die u hebt verkregen in Get endpoint.
Herhaal de vorige stap voor semantic-query.rest.
Voor sleutelloze verificatie met Microsoft Entra ID meldt u zich aan bij uw Azure-account. Als u meerdere abonnementen hebt, selecteert u het abonnement dat uw Azure AI Zoeken-service bevat.
```
az login
```

Genereer een toegangstoken voor sleutelloze verificatie met Microsoft Entra ID.

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

Vervang in beide .rest bestanden de tijdelijke aanduiding voor @personalAccessToken, met het token uit de vorige stap.

De code uitvoeren

Open semantic-index-update.rest.
Selecteer Aanvraag verzenden bij de eerste GET-aanvraag om uw verbinding te verifiëren.

Er moet een antwoord worden weergegeven in een aangrenzend deelvenster. Als u bestaande indexen hebt, worden deze op naam weergegeven. Als de HTTP-code is 200 OK, kunt u doorgaan.
Verzend de ### Update the hotels-sample index to include a semantic configuration aanvraag om een semantische configuratie toe te voegen aan de index.

Als er een 400 Bad Request fout optreedt, verschilt uw indexschema van het voorbeeld. Verzend de ### Get the schema of the index aanvraag, kopieer de antwoord-JSON, voeg de semantic sectie uit de broncode toe aan de JSON en vervang de HOOFDtekst van de PUT-aanvraag door uw samengevoegde schema.
Schakel over naar semantic-query.rest en verzend de aanvragen opeenvolgend: een eenvoudige query voor basislijnvergelijking en vervolgens semantische query's met classificatie, bijschriften en antwoorden.

Output

De Send a search query to the hotels-sample index aanvraag retourneert resultaten gerangschikt op BM25 relevantie, die wordt aangegeven door het @search.score veld.

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

De Send a search query to the hotels-sample index with semantic ranking verzoek voegt @search.rerankerScore toe. U ziet dat de volgorde verandert van de eenvoudige query.

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

De Return captions in the query verzoek voegt @search.captions toe met geëxtraheerde tekst en markeringen.

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

De aanvraag retourneert een extractief antwoord in @search.answers wanneer de query als een vraag wordt opgegeven.

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

De code begrijpen

Opmerking

De codefragmenten in deze sectie zijn mogelijk gewijzigd voor leesbaarheid. Zie de broncode voor een volledig werkvoorbeeld.

Nu u de code hebt uitgevoerd, gaan we de sleutelstappen opsplitsen:

Configuratie en verificatie
De index bijwerken met een semantische configuratie
Query's uitvoeren op de index

Configuratie en verificatie

Beide .rest bestanden definiëren bovenaan variabelen voor hergebruik in alle aanvragen.

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

Belangrijke punten:

@searchUrl is het eindpunt van uw zoekservice.
@personalAccessToken is een Microsoft Entra ID token dat is verkregen uit de Azure CLI. Hierdoor worden API-sleutels vervangen door sleutelloze verificatie.
Authorization: Bearer {{personalAccessToken}} is opgenomen in elke aanvraagheader voor verificatie.

De index bijwerken met een semantische configuratie

De aanvraag in ### Update the hotels-sample index to include a semantic configuration verzendt semantic-index-update.rest het volledige indexschema, samen met een nieuwe sectie in semantic. De REST API vereist het volledige schema voor elke updatebewerking, zodat u niet alleen de semantische configuratie kunt verzenden.

De belangrijkste toevoeging is de semantic sectie.

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

Belangrijke punten:

titleField geeft aan welk veld de documenttitel voor semantische evaluatie bevat.
prioritizedContentFields identificeert de hoofdinhoudsvelden. Semantische rangschikking evalueert deze eerst bij het scoren van relevantie.
prioritizedKeywordsFields identificeert trefwoord- of tagvelden voor extra context.
rankingOrder: BoostedRerankerScore combineert de BM25-score met de semantische rerankerscore.
De REST API vereist het volledige schema voor PUT-bewerkingen. Alleen de semantic sectie is nieuw; alle andere velden zijn ongewijzigd.

Query's uitvoeren op de index

De aanvragen ontwikkelen zich semantic-query.rest van een eenvoudige trefwoordzoekopdracht naar semantische rangschikking met bijschriften en antwoorden. Alle query's zijn POST-aanvragen voor de documenten - Zoekpost (REST API).

Eenvoudige query

De ### Send a search query to the hotels-sample index aanvraag is een eenvoudige trefwoordzoekopdracht die geen semantische rangschikking gebruikt. Het fungeert als basislijn voor het vergelijken van resultaten met en zonder semantische herrankering.

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

Belangrijke punten:

queryType: "simple" maakt gebruik van het standaard-BM25-classificatie-algoritme.
Resultaten worden alleen gerangschikt op relevantie voor trefwoorden (@search.score).

Semantische query (geen bijschriften, geen antwoorden)

De ### Send a search query to the hotels-sample index with semantic ranking aanvraag voegt semantische rangschikking toe. In de volgende JSON ziet u de minimale vereiste voor het aanroepen van semantische classificatie.

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

Belangrijke punten:

queryType: "semantic" maakt semantische classificatie voor de query mogelijk.
semanticConfiguration geeft aan welke semantische configuratie moet worden gebruikt.

Semantische query met beschrijvingen

De ### Return captions in the query aanvraag voegt bijschriften toe om de meest relevante passages uit elk resultaat te extraheren, waarbij treffermarkeringen worden toegepast op de belangrijke termen en woordgroepen.

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

Belangrijke punten:

captions: "extractive|highlight-true" maakt uittrekbare bijschriften mogelijk met  tags die rond belangrijke termen staan.
Bijschriften worden weergegeven in de @search.captions matrix voor elk resultaat.

Semantische query met antwoorden

De ### Return semantic answers in the query aanvraag voegt semantische antwoorden toe. Er wordt een vraag gebruikt als zoektekst, omdat semantische antwoorden het beste werken wanneer de query als een vraag wordt opgegeven. Het antwoord is een exacte passage die is geëxtraheerd uit uw index, niet een samengesteld antwoord van een chatvoltooiingsmodel.

De query en de geïndexeerde inhoud moeten nauw op elkaar zijn afgestemd om een antwoord te kunnen retourneren. Als er geen kandidaat voldoet aan de betrouwbaarheidsdrempel, bevat het antwoord geen antwoord. In dit voorbeeld wordt een vraag gebruikt die bekend is om een resultaat te produceren, zodat u de syntaxis kunt zien. Als antwoorden niet nuttig zijn voor uw scenario, laat u de answers parameter weg uit uw aanvraag. Voor samengestelde antwoorden kunt u een RAG-patroon of agentisch ophalen overwegen.

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

Belangrijke punten:

answers: "extractive" maakt antwoorden die uit de tekst gehaald worden voor query's die op vragen lijken mogelijk.
Antwoorden worden weergegeven in de matrix op het hoogste niveau @search.answers , gescheiden van afzonderlijke resultaten.
Antwoorden zijn exacte inhoud die is geëxtraheerd uit uw index, niet gegenereerde tekst.

Quickstart: Semantische rangschikking

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output

De code begrijpen

Configuratie en verificatie

De index bijwerken met een semantische configuratie

Query's uitvoeren op de index

Eenvoudige query

Semantische query (geen bijschriften, geen antwoorden)

Semantische query met beschrijvingen

Semantische query met antwoorden

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output

De code begrijpen

Configuratie en verificatie

De index bijwerken met een semantische configuratie

Query's uitvoeren op de index

Semantische query (geen bijschriften, geen antwoorden)

Semantische query met beschrijvingen

Semantische query met antwoorden

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output

De code begrijpen

Configuratie en verificatie

De index bijwerken met een semantische configuratie

Query's uitvoeren op de index

Semantische query (geen bijschriften, geen antwoorden)

Semantische query met bijschriften

Semantische query met antwoorden

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output

De code begrijpen

Configuratie en verificatie

De index bijwerken met een semantische configuratie

Query's uitvoeren op de index

Termquery (basislijn)

Semantische query (geen bijschriften, geen antwoorden)

Semantische query met beschrijvingen

Semantische query met antwoorden

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output

De code begrijpen

Configuratie en verificatie

De index bijwerken met een semantische configuratie

Query's uitvoeren op de index

Semantische query (geen bijschriften, geen antwoorden)

Semantische query met beschrijvingen

Semantische query met antwoorden

Voorwaarden

Toegang configureren

Eindpunt ophalen

Beginnen met een index

De omgeving instellen

De code uitvoeren

Output