Semantische classificatie toevoegen aan query's in Azure AI Search

U kunt semantische classificatie toepassen op tekstquery's, hybride query's en vectorquery's als uw zoekdocumenten tekenreeksvelden bevatten en de vectorquery een tekstweergave heeft in het zoekdocument.

In dit artikel wordt uitgelegd hoe u de semantische ranker aanroept voor query's.

Vereisten

• Een zoekservice, Basic-laag of hoger, met semantische rangschikking ingeschakeld.

• Een bestaande zoekindex met een semantische configuratie en inhoud voor tekst met opmaak.

• Controleer de semantische rangschikking als u een inleiding tot de functie nodig hebt.

Notitie

Bijschriften en antwoorden worden letterlijk geëxtraheerd uit tekst in het zoekdocument. Het semantische subsysteem maakt gebruik van leesbegrip van machines om inhoud te herkennen die de kenmerken van een bijschrift of antwoord heeft, maar geen nieuwe zinnen of woordgroepen opstelt. Daarom werkt inhoud met uitleg of definities het beste voor semantische rangschikking. Zie Rag (Retrieval Augmented Generation) als u interactie in chatstijl met gegenereerde antwoorden wilt.

Een client kiezen

U kunt een van de volgende hulpprogramma's en SDK's gebruiken om een query te maken die gebruikmaakt van semantische classificatie:

• Azure Portal met behulp van de indexontwerper om een semantische configuratie toe te voegen.
• Visual Studio Code met een REST-client
• Azure-SDK voor .NET
• Azure-SDK voor Python
• Azure SDK voor Java
• Azure SDK voor JavaScript

Vermijd functies die relevantiescores omzeilen

Een paar querymogelijkheden omzeilen relevantiescores, waardoor ze niet compatibel zijn met semantische rangschikking. Als uw querylogica de volgende functies bevat, kunt u uw resultaten niet semantisch rangschikken:

• Een query met search=* of een lege zoekreeks, zoals een pure filterquery, werkt niet omdat er niets is om de semantische relevantie te meten, zodat de zoekscores nul zijn. De query moet termen of woordgroepen bevatten die tijdens de verwerking kunnen worden geëvalueerd.

• Als u sorteert (orderBy-componenten) voor specifieke velden, worden zoekscores en een semantische score overschreven. Aangezien de semantische score de classificatie moet leveren, resulteert het toevoegen van een orderby-component in een HTTP 400-fout als u semantische classificatie toepast op geordende resultaten.

De query instellen

Standaard gebruiken query's geen semantische classificatie. Als u semantische classificatie wilt gebruiken, kunnen twee verschillende parameters worden gebruikt. Elke parameter ondersteunt een andere set scenario's.

Semantische query's, opgegeven via search plus queryTypeof via semanticQuery, moeten tekst zonder opmaak zijn en kunnen niet leeg zijn. Lege query's leiden ertoe dat er geen semantische classificatie wordt toegepast op de resultaten.

Semantische rangschikkingsparameter	Zoeken in tekst zonder opmaak	Eenvoudige zoeksyntaxis voor tekst	Zoeksyntaxis voor volledige tekst	Vector zoeken	Hybride zoekopdracht	Semantische antwoorden en bijschriften
queryType-semantic 1	✅	❌	❌	❌	✅	✅
semanticQuery="<your plain text query>"2	✅	✅	✅	✅	✅	✅

¹ queryType=semantic biedt geen ondersteuning voor expliciete simple waarden of full waarden omdat de queryType parameter wordt gebruikt voor semantic. Het effectieve querygedrag is de standaardwaarde van de eenvoudige parser.

² De semanticQuery parameter kan worden gebruikt voor alle querytypen. Het wordt echter niet ondersteund in de Portal Search Explorer.

Ongeacht de gekozen parameter moet de index tekstvelden bevatten met uitgebreide semantische inhoud en een semantische configuratie.

Azure-portal

Search Explorer bevat opties voor semantische rangschikking. Zoals u weet, kunt u de semanticQuery parameter niet instellen in Azure Portal.

1. Meld u aan bij het Azure-portaal.

2. Open een zoekindex en selecteer Search Explorer.

3. Selecteer Queryopties. Als u al een semantische configuratie hebt gedefinieerd, wordt deze standaard geselecteerd. Als u er nog geen hebt, maakt u een semantische configuratie voor uw index.

   

4. Voer een query in, zoals 'historisch hotel met goed eten' en selecteer Zoeken.

5. U kunt ook JSON-weergave selecteren en definities in de queryeditor plakken. Azure Portal biedt geen ondersteuning voor het gebruik van semanticQuery, dus de instelling queryType "semantic" hiervoor is vereist:

   

   JSON-voorbeeld voor het instellen van het querytype op semantisch dat u in de weergave kunt plakken:

   {
     "search": "funky or interesting hotel with good food on site",
     "count": true,
     "queryType": "semantic",
     "semanticConfiguration": "my-semantic-config",
     "captions": "extractive|highlight-true",
     "answers": "extractive|count-3",
     "highlightPreTag": "<strong>",
     "highlightPostTag": "</strong>",
     "select": "HotelId,HotelName,Description,Category"
   }
   

REST API

Gebruik Zoekdocumenten om de aanvraag te formuleren.

Een antwoord bevat automatisch een @search.rerankerScore . Als u bijschriften of antwoorden in het antwoord wilt, schakelt u semantische rangschikking in door bijschriften en antwoorden in te stellen queryType of in te semantic stellen semanticQuery en bijschriften en antwoorden toe te voegen aan de aanvraag.

In de volgende voorbeelden in deze sectie wordt de hotels-sample-index gebruikt om semantische rangschikking te demonstreren met semantische antwoorden en bijschriften.

QueryType=semantisch gebruiken

Als u dit wilt instellen queryType semantic, plakt u de volgende aanvraag in een webclient als sjabloon. Vervang search-service-name door de naam van uw zoekservice en vervang hotels-sample-index deze als u een andere indexnaam hebt.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

1. Stel queryType in op semantic.

2. Ingesteld search op een eenvoudige query voor tekst zonder opmaak. Omdat de queryType syntaxis is ingesteld op semantic, worden eenvoudige syntaxis of volledige Lucene-syntaxis niet ondersteund. * Het opgeven of een lege tekenreeks resulteert in geen semantische classificatie die wordt toegepast op de query.

3. Ingesteld semanticConfiguration op een vooraf gedefinieerde semantische configuratie die is ingesloten in uw index.

4. Instellen answers om op te geven of semantische antwoorden worden opgenomen in het resultaat. Momenteel is extractivede enige geldige waarde voor deze parameter. Antwoorden kunnen worden geconfigureerd om maximaal 10 te retourneren. De standaardwaarde is er een. In dit voorbeeld ziet u een telling van drie antwoorden: extractive|count-3.

   Antwoorden worden niet gegarandeerd op elke aanvraag. Als u een antwoord wilt krijgen, moet de query eruitzien als een vraag en moet de inhoud tekst bevatten die eruitziet als een antwoord.

5. Instellen captions om op te geven of semantische bijschriften worden opgenomen in het resultaat. Momenteel is extractivede enige geldige waarde voor deze parameter. Bijschriften kunnen worden geconfigureerd om resultaten te retourneren met of zonder markeringen. De standaardwaarde is dat markeringen worden geretourneerd. In dit voorbeeld worden bijschriften geretourneerd zonder markeringen: extractive|highlight-false.

   De basis voor bijschriften en antwoorden zijn de velden waarnaar wordt verwezen in de 'semanticConfiguration'. Deze velden liggen onder een gecombineerde limiet in het bereik van 20.000 tokens of ongeveer 20.000 tekens. Als u verwacht dat een tokenaantal deze limiet overschrijdt, kunt u een stap voor het segmenteren van gegevens overwegen met behulp van de vaardigheid Tekst splitsen. Deze benadering introduceert een afhankelijkheid van een AI-verrijkingspijplijn en indexeerfuncties.

6. Instellen highlightPreTag en highlightPostTag als u de standaardopmaak voor markeringen wilt overschrijven die wordt toegepast op bijschriften.

   Bijschriften passen markeringsopmaak toe op belangrijke passages in het document waarin het antwoord wordt samengevat. De standaardwaarde is <em>. Als u het type opmaak wilt opgeven (bijvoorbeeld gele achtergrond), kunt u de highlightPreTag en highlightPostTag instellen.

7. Stel deze optie in om op te geven welke velden worden geretourneerd in het antwoord en aantal om het aantal overeenkomsten in de index te retourneren. Deze parameters verbeteren de kwaliteit van de aanvraag en leesbaarheid van het antwoord.

8. Verzend de aanvraag om de query uit te voeren en retourneer resultaten.

SemanticQuery gebruiken

Met behulp van semanticQuerykunt u expliciet eenvoudige tekstsyntaxis of volledige tekstsyntaxis toepassen, wat betekent dat u nu zoeken in velden, termenverhoging en nabijheidszoekopdrachten kunt uitvoeren. U kunt ook een pure vectorquery opgeven in plaats van alleen hybride.

Pas uw aanvraag aan op de volgende JSON die u wilt gebruiken semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

1. Stel queryType in op de zoeksyntaxis die u gebruikt, eenvoudig of volledig.

2. Stel semanticQuery deze in op de eenvoudige query voor tekst zonder opmaak die u wilt gebruiken voor semantische classificatie. Lege query's worden niet ondersteund. Vermijd operatoren of querysyntaxis in de tekenreeks zelf.

.NET SDK

Gebruik QueryType of SemanticQuery om een semantische ranker aan te roepen voor een semantische query. Het volgende voorbeeld is afkomstig van het Azure SDK-team.

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

Als u het codefragment wilt gebruiken semanticQuery in plaats van dit in te semanticstellenqueryType, kunt u het codefragment vervangen door het volgende codefragment:

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

Het antwoord evalueren

Alleen de top 50 overeenkomsten uit de eerste resultaten kunnen semantisch worden gerangschikt. Net als bij alle query's bestaat een antwoord uit alle velden die zijn gemarkeerd als ophaalbaar of alleen die velden die in de select parameter worden vermeld. Een antwoord bevat de oorspronkelijke relevantiescore en kan ook een telling of batchresultaten bevatten, afhankelijk van de wijze waarop u de aanvraag hebt geformuleerd.

In semantische rangschikking heeft het antwoord meer elementen: een nieuwe semantisch gerangschikte relevantiescore, een optioneel bijschrift in tekst zonder opmaak en met markeringen en een optioneel antwoord. Als uw resultaten deze extra elementen niet bevatten, is uw query mogelijk onjuist geconfigureerd. Als eerste stap voor het oplossen van het probleem controleert u de semantische configuratie om ervoor te zorgen dat deze is opgegeven in zowel de indexdefinitie als de query.

In een client-app kunt u de zoekpagina structuren om een bijschrift op te nemen als de beschrijving van de overeenkomst, in plaats van de volledige inhoud van een specifiek veld. Deze methode is handig wanneer afzonderlijke velden te dicht zijn voor de pagina met zoekresultaten.

Het antwoord voor de bovenstaande voorbeeldquery ('interessant hotel met restaurant op locatie en gezellige lobby of gedeelde ruimte') retourneert drie antwoorden ("answers": "extractive|count-e"). Bijschriften worden geretourneerd omdat de eigenschap 'bijschriften' is ingesteld, met tekst zonder opmaak en gemarkeerde versies. Als een antwoord niet kan worden bepaald, wordt dit weggelaten uit het antwoord. Ter beknoptheid toont dit voorbeeld alleen de drie antwoorden en de drie hoogste scoreresultaten van de query.

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

Verwachte workloads

Voor semantische classificatie moet u verwachten dat een zoekservice maximaal 10 gelijktijdige query's per replica ondersteunt.

De service beperkt semantische classificatieaanvragen als volumes te hoog zijn. Een foutbericht met deze woordgroepen geeft aan dat de service capaciteit heeft voor semantische rangschikking:

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

Als u verwacht dat de vereisten voor consistente doorvoer bijna, op of hoger dan dit niveau zijn, dient u een ondersteuningsticket in, zodat we uw workload kunnen inrichten.

Volgende stappen

Semantische classificatie kan worden gebruikt in hybride query's die trefwoordzoekopdrachten en vectorzoekopdrachten combineren in één aanvraag en een uniform antwoord.

Hybride query met semantische ranker