Condividi tramite

Guida introduttiva: classificazione semantica con .NET o Python

  • Articolo

In Azure AI Search, la classificazione semantica è una funzionalità lato query che usa la comprensione della lettura automatica da Microsoft per rivalutare i risultati della ricerca, promuovendo le corrispondenze più pertinenti semanticamente all'inizio dell'elenco. A seconda del contenuto e della query, la classificazione semantica può migliorare significativamente la pertinenza della ricerca, con un lavoro minimo da parte dello sviluppatore.

Questa guida introduttiva illustra le modifiche all'indice e alle query che richiamano il classificatore semantico.

Nota

Per un esempio di soluzione Ricerca intelligenza artificiale di Azure con l'interazione con ChatGPT, vedere questa demo o questo acceleratore.

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. È possibile creare un account gratuitamente.

  • Una risorsa di Ricerca intelligenza artificiale di Azure, al livello Basic o superiore, con il ranker semantico abilitato.

  • Una chiave API e un endpoint del servizio di ricerca. Accedere al portale di Azure e trovare il servizio di ricerca.

    In Panoramica copiare l'URL e salvarlo per un passaggio successivo. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.

    In Chiavi, copiare e salvare una chiave amministratore per i diritti completi per creare ed eliminare oggetti. Vengono visualizzate due chiavi intercambiabili: la chiave primaria e quella secondaria. Scegliere una delle due.

    Screenshot che mostra dove trovare l'endpoint HTTP e la chiave di accesso del servizio di ricerca.

Aggiungi classificazione semantica

Per usare il classificatore semantico, aggiungere una configurazione semantica a un indice di ricerca e aggiungere parametri a una query. Se si dispone di un indice esistente, è possibile apportare queste modifiche senza dover reindicizzare il contenuto perché non c'è alcun impatto sulla struttura del contenuto ricercabile.

  • Una configurazione semantica imposta un ordine di priorità per i campi che contribuiscono a un titolo, parole chiave e contenuto usati nella riclassificazione semantica. La definizione delle priorità dei campi consente un'elaborazione più rapida.

  • Le query che richiamano il classificatore semantico includono parametri per il tipo di query e indicano se vengono restituiti sottotitoli e risposte. È possibile aggiungere questi parametri alla logica di query esistente. Non esiste alcun conflitto con altri parametri.

Compilare un'applicazione console usando la libreria client Azure.Search.Documents per aggiungere una classificazione semantica a un indice di ricerca esistente.

In alternativa, è possibile scaricare il codice sorgente per iniziare con un progetto completato.

Configurazione dell'ambiente

  1. Avviare Visual Studio e creare un nuovo progetto per un'app console.

  2. In Strumenti>Gestione pacchetti NuGet, selezionare Gestisci pacchetti NuGet per la soluzione.

  3. Selezionare Sfoglia.

  4. Cercare il pacchetto Azure.Search.Documents e selezionare la versione stabile più recente.

  5. Selezionare Installa per aggiungere l'assembly al progetto e alla soluzione.

Creare un client di ricerca

  1. In Program.cs aggiungere le seguenti direttive using.

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  2. Creare due client: SearchIndexClient crea l'indice, mentre SearchClient carica un indice esistente ed esegue query su un indice esistente.

    Entrambi i client necessitano dell'endpoint di servizio e di una chiave API amministratore per l'autenticazione con diritti di creazione/eliminazione. Tuttavia, il codice compila automaticamente l'URI, quindi specificare solo il nome del servizio di ricerca per la serviceName proprietà . Non includere https:// o .search.windows.net.

     static void Main(string[] args)
 {
     string serviceName = "<YOUR-SEARCH-SERVICE-NAME>";
     string apiKey = "<YOUR-SEARCH-ADMIN-API-KEY>";
     string indexName = "hotels-quickstart";


     // Create a SearchIndexClient to send create/delete index commands
     Uri serviceEndpoint = new Uri($"https://{serviceName}.search.windows.net/");
     AzureKeyCredential credential = new AzureKeyCredential(apiKey);
     SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

     // Create a SearchClient to load and query documents
     SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, credential);
     . . . 
 }

Creare un indice

Creare o aggiornare uno schema di indice per includere un oggetto SemanticConfiguration. Se si aggiorna un indice esistente, questa modifica non richiede una reindicizzazione perché la struttura dei documenti rimane invariata.

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient adminClient)
{

    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);
    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);
    definition.SemanticSearch = new SemanticSearch
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description"),
                    new SemanticField("Description_fr")
                },
                KeywordsFields =
                {
                    new SemanticField("Tags"),
                    new SemanticField("Category")
                }
            })
        }
    };

    adminClient.CreateOrUpdateIndex(definition);
}

Il codice seguente crea l'indice nel servizio di ricerca:

// Create index
Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, adminClient);

SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

Caricare i documenti

Azure AI Search esegue ricerche sul contenuto archiviato nel servizio. Il codice per il caricamento dei documenti è identico a quello della guida introduttiva C# per la ricerca full-text, quindi non è necessario duplicarlo qui. Dovrebbero essere presenti quattro hotel con nomi, indirizzi e descrizioni. La soluzione deve avere tipi per Hotel e Indirizzi.

Eseguire la ricerca in un indice

Ecco una query che richiama il classificatore semantico, con opzioni di ricerca per specificare i parametri:

Console.WriteLine("Example of a semantic query.");

options = new SearchOptions()
{
    QueryType = Azure.Search.Documents.Models.SearchQueryType.Semantic,
    SemanticSearch = new()
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new(QueryCaptionType.Extractive)
    }
};
options.Select.Add("HotelName");
options.Select.Add("Category");
options.Select.Add("Description");

// response = srchclient.Search<Hotel>("*", options);
response = srchclient.Search<Hotel>("what hotel has a good restaurant on site", options);
WriteDocuments(response);

Per un confronto, ecco i risultati di una query che usa la classificazione BM25 predefinita, in base alla frequenza dei termini e alla prossimità. Data la query "quale hotel ha un buon ristorante in loco", l'algoritmo di classificazione BM25 restituisce corrispondenze nell'ordine illustrato in questo screenshot:

Screenshot che mostra le corrispondenze classificate da BM25.

Al contrario, quando la classificazione semantica viene applicata alla stessa query ("quale hotel ha un buon ristorante in loco"), i risultati vengono classificati nuovamente in base alla pertinenza semantica della query. Questa volta, il risultato principale è l'hotel con il ristorante, che si allinea meglio alle aspettative degli utenti.

Screenshot che mostra le corrispondenze classificate in base alla classificazione semantica.

Eseguire il programma

Premere F5 per ricompilare l'app ed eseguire il programma completo.

L'output include i messaggi restituiti da Console.WriteLine, con l'aggiunta di informazioni sulle query e i risultati.

Pulire le risorse

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

È possibile trovare e gestire le risorse nella portale di Azure, usando il collegamento Tutte le risorse o Gruppi di risorse nel riquadro di spostamento a sinistra.

Passaggi successivi

In questa guida introduttiva si è appreso come richiamare la classificazione semantica in un indice esistente. È consigliabile provare la classificazione semantica sui propri indici come passaggio successivo. Tuttavia, se si desidera continuare con le demo, visitare il collegamento seguente.

Esercitazione: Aggiungere la ricerca alle app Web