Aggiungere una classificazione semantica alle query in Azure AI Search

Articolo
12/10/2024

È possibile applicare la classificazione semantica alle query di testo, alle query ibride e alle query vettoriali se i documenti di ricerca contengono campi stringa e la query vettoriale ha una rappresentazione di testo nel documento di ricerca.

Questo articolo illustra come richiamare il ranker semantico nelle query. Si presuppone che si usino le API stabili o di anteprima più recenti. Per informazioni su versioni precedenti, vedere Eseguire la migrazione del codice di classificazione semantica.

Prerequisiti

Un servizio di ricerca, livello Basic o superiore, con classificatore semantico abilitato.
Indice di ricerca esistente con una configurazione semantica e contenuto RTF.
Esaminare la classificazione semantica se è necessaria un'introduzione alla funzionalità.

Nota

I sottotitoli e le risposte vengono estratti verbatim dal testo nel documento di ricerca. Il sottosistema semantico usa la comprensione della lettura automatica per riconoscere il contenuto con le caratteristiche di una didascalia o di una risposta, ma non compone nuove frasi o frasi. Per questo motivo, il contenuto che include spiegazioni o definizioni funziona meglio per la classificazione semantica. Per l'interazione in stile chat con le risposte generate, vedere Retrieval Augmented Generation (RAG).

Scegliere un client

È possibile usare uno degli strumenti e degli SDK seguenti per compilare una query che usa la classificazione semantica:

Portale di Azure, usando progettazione indici per aggiungere una configurazione semantica.
Visual Studio Code con un client REST
Azure SDK per .NET
Azure SDK per Python
Azure SDK per Java
Azure SDK per JavaScript

Evitare funzionalità che ignorano l'assegnazione dei punteggi per pertinenza

Alcune funzionalità di query ignorano l'assegnazione dei punteggi di pertinenza, che li rende incompatibili con la classificazione semantica. Se la logica di query include le funzionalità seguenti, non è possibile classificare semanticamente i risultati:

Una query con search=* o una stringa di ricerca vuota, ad esempio una query di sola filtro pura, non funzionerà perché non esiste nulla per misurare la pertinenza semantica, per cui il punteggi risultanti sono zero. La query deve fornire termini o frasi che possono essere valutate durante l'elaborazione.
L'ordinamento (clausole orderBy) in campi specifici sostituisce i punteggi di ricerca e un punteggio semantico. Dato che il punteggio semantico dovrebbe fornire la classificazione, l'aggiunta di una clausola orderby genera un errore HTTP 400 se si applica la classificazione semantica sui risultati ordinati.

Configurare la query

Per impostazione predefinita, le query non usano la classificazione semantica. Per usare la classificazione semantica, è possibile usare due parametri diversi. Ogni parametro supporta un set diverso di scenari.

Le query semantiche, specificate tramite search più queryTypeo tramite semanticQuery, devono essere testo normale e non possono essere vuote. Le query vuote non comportano l'applicazione di una classificazione semantica ai risultati.

Parametro del ranker semantico	Ricerca testo normale	Sintassi di ricerca testo semplice	Sintassi di ricerca full-text	Ricerca vettoriale	Ricerca ibrida	Risposte semantiche e didascalie
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"`²	✅	✅	✅	✅	✅	✅

¹ queryType=semantic non può supportare valori espliciti simple o full perché il queryType parametro viene usato per semantic. I comportamenti effettivi delle query sono i valori predefiniti del parser semplice.

² Il semanticQuery parametro può essere usato per tutti i tipi di query. Tuttavia, non è supportato in Esplora ricerche portale di Azure.

Indipendentemente dal parametro scelto, l'indice deve contenere campi di testo con contenuto semantico avanzato e una configurazione semantica.

Esplora ricerche include opzioni per la classificazione semantica. Tenere presente che non è possibile impostare il semanticQuery parametro nella portale di Azure.

Accedere al portale di Azure.
Aprire un indice di ricerca e selezionare Esplora ricerche.
Selezionare Opzioni query. Se è già stata definita una configurazione semantica, è selezionata per impostazione predefinita. Se non è disponibile, creare una configurazione semantica per l'indice.
Immettere una query, ad esempio "hotel storico con buon cibo" e selezionare Cerca.

In alternativa, selezionare visualizzazione JSON e incollare le definizioni nell'editor di query. Il portale di Azure non supporta l'uso semanticQuerydi , quindi è necessaria l'impostazione queryType su"semantic":

Esempio JSON per impostare il tipo di query sulla semantica che è possibile incollare nella visualizzazione:

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

Usare Cerca documenti per formulare la richiesta.

Una risposta include automaticamente @search.rerankerScore. Se si desiderano sottotitoli o risposte nella risposta, abilitare la classificazione semantica impostando queryType semantic o impostando semanticQuery e aggiungendo sottotitoli e risposte alla richiesta.

Gli esempi seguenti in questa sezione usano hotels-sample-index per illustrare la classificazione semantica con risposte semantiche e didascalie.

Usare queryType=semantic

Se si vuole impostare su queryType semantic, incollare la richiesta seguente in un client Web come modello. Sostituire search-service-name con il nome del servizio di ricerca e sostituire hotels-sample-index se si dispone di un nome di indice diverso.

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

Impostare queryType su semantic.
Impostare search su una query di testo normale semplice. queryType Poiché è impostato su semantic, la sintassi semplice o la sintassi Lucene completa non sono supportate. Se si specifica * o una stringa vuota, non viene applicata alcuna classificazione semantica alla query.
Impostare semanticConfiguration su una configurazione semantica predefinita incorporata nell'indice.
Impostare answers per specificare se le risposte semantiche vengono incluse nel risultato. Attualmente l'unico valore valido per questa chiave è extractive. Le risposte possono essere configurate per restituire un massimo di 10. Il valore predefinito è uno. Questo esempio mostra un conteggio di tre risposte: extractive|count-3.

Le risposte non sono garantite per ogni richiesta. Per ottenere una risposta, la query deve essere simile a una domanda e il contenuto deve includere testo simile a una risposta.
Impostare captions per specificare se i sottotitoli semantici vengono inclusi nel risultato. Attualmente l'unico valore valido per questa chiave è extractive. Le didascalie possono essere configurate per restituire risultati con o senza evidenziazioni. Il valore predefinito è per le evidenziazioni da restituire. In questo esempio vengono restituite le didascalie senza evidenziazioni: extractive|highlight-false.

La base per didascalie e risposte sono i campi a cui si fa riferimento in "semanticConfiguration". Questi campi sono sotto un limite combinato nell'intervallo di 2.000 token o circa 20.000 caratteri. Se si prevede che un numero di token superi questo limite, prendere in considerazione un passaggio di suddivisione dei dati usando la funzionalità Suddivisione testo. Questo approccio introduce una dipendenza da una pipeline di arricchimento tramite intelligenza artificiale e indicizzatori.
Impostare highlightPreTag e highlightPostTag se si desidera eseguire l'override della formattazione di evidenziazione predefinita applicata alle didascalie.

Le didascalie applicano la formattazione dell'evidenziazione sui passaggi chiave del documento che riepilogano la risposta. Il valore predefinito è <em>. Se vuoi specificare il tipo di formattazione (ad esempio, sfondo giallo), puoi impostare l'evidenziazionePreTag e l'evidenziazionePostTag.
Impostare select per specificare i campi restituiti nella risposta e "count" per restituire il numero di corrispondenze nell'indice. Questi parametri migliorano la qualità della richiesta e la leggibilità della risposta.
Inviare la richiesta per eseguire la query e restituire i risultati.

Usare semanticQuery

Usando semanticQuery, è possibile applicare in modo esplicito la sintassi di testo semplice o la sintassi full-text, il che significa che è ora possibile eseguire ricerche in campi, boosting dei termini e ricerca di prossimità. È anche possibile specificare una query vettoriale pura anziché semplicemente ibrida.

Modificare la richiesta nel codice JSON seguente per usare 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"
}

Impostare queryType sulla sintassi di ricerca in uso, semplice o completa.
Impostare semanticQuery sulla query di testo normale semplice da usare per la classificazione semantica. Le query vuote non sono supportate. Evitare operatori o qualsiasi sintassi di query all'interno della stringa stessa.

Usare QueryType o SemanticQuery per richiamare il classificatore semantico in una query semantica. L'esempio seguente proviene dal team di Azure SDK.

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

Per usare semanticQuery invece di impostare queryType su semantic, il frammento di codice di ricerca può essere sostituito con il frammento di codice seguente:

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

Valutare la risposta

Solo le prime 50 corrispondenze dei risultati iniziali possono essere classificate semanticamente. Come per tutte le query, una risposta è costituita da tutti i campi contrassegnati come recuperabili o solo da tali campi elencati nel parametro select. Una risposta include il punteggio di pertinenza originale e può includere anche un conteggio o risultati in batch, a seconda del modo in cui è stata formulata la richiesta.

Nella classificazione semantica, la risposta ha più elementi: un nuovo punteggio di pertinenza classificato semanticamente, una didascalia facoltativa in testo normale e con evidenziazioni e una risposta facoltativa. Se i risultati non includono questi elementi aggiuntivi, la query potrebbe non essere configurata correttamente. Come primo passaggio per la risoluzione del problema, controllare la configurazione semantica per assicurarsi che sia specificata sia nella definizione dell'indice che nella query.

In un'app client è possibile strutturare la pagina di ricerca in modo da includere una didascalia come descrizione della corrispondenza, anziché l'intero contenuto di un campo specifico. Questo approccio è utile quando i singoli campi sono troppo densi per la pagina dei risultati della ricerca.

La risposta per la query di esempio precedente ("hotel interessante con ristorante in loco e accogliente lobby o area condivisa") restituisce tre risposte ("answers": "extractive|count-e"). Le didascalie vengono restituite perché la proprietà "captions" è impostata, con testo normale e versioni evidenziate. Se non è possibile determinare una risposta, viene omessa dalla risposta. Per brevità, questo esempio mostra solo le tre risposte e i tre risultati di punteggio più alti della 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"
    },
   . . .
  ]
}

Carichi di lavoro previsti

Per la classificazione semantica, è consigliabile che un servizio di ricerca supporti fino a 10 query simultanee per replica.

Il servizio limita le richieste di classificazione semantica se i volumi sono troppo elevati. Un messaggio di errore che include queste frasi indica che il servizio è in fase di classificazione semantica:

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

Se si prevedono requisiti di velocità effettiva coerenti vicino, a o superiore a questo livello, inviare un ticket di supporto in modo che sia possibile effettuare il provisioning per il carico di lavoro.

Passaggi successivi

La classificazione semantica può essere usata nelle query ibride che combinano la ricerca di parole chiave e la ricerca vettoriale in una singola richiesta e in una risposta unificata.

Query ibrida con classificatore semantico

Condividi tramite