Share via

Guida introduttiva: Classificazione semantica con .NET o Python

  • Articolo

In Ricerca di intelligenza artificiale di Azure, la classificazione semantica è una funzionalità lato query che usa la comprensione della lettura automatica da Microsoft per riprimere 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 per lo sviluppatore.

Questa guida introduttiva illustra le modifiche all'indice e alle query che richiamano la classificazione semantica.

Nota

Cercare una soluzione ricerca di intelligenza artificiale di Azure con l'interazione con ChatGPT? Per informazioni dettagliate, vedere questa demo o questo acceleratore .

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.

  • Ricerca di intelligenza artificiale di Azure, al livello Basic o superiore, con classificazione semantica abilitata.

  • 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 in Blocco note 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.

    Get an HTTP endpoint and access key

Aggiungere una classificazione semantica

Per usare la classificazione semantica, 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 reranking semantica. La definizione delle priorità dei campi consente un'elaborazione più rapida.

  • Le query che richiamano la classificazione semantica includono parametri per il tipo di query e se vengono restituite didascalia e risposte. È possibile aggiungere questi parametri alla logica di query esistente. Non esiste alcun conflitto con altri parametri.

Creare 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 o seguire questi passaggi per crearne uno personalizzato.

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 direttive seguenti 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 e SearchClient carica ed esegue query su un indice esistente. Per entrambi è necessario l'endpoint di servizio e una chiave API amministratore per l'autenticazione con diritti di creazione/eliminazione.

    Poiché il codice compila automaticamente l'URI, specificare solo il nome del servizio di ricerca nella proprietà "serviceName".

     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

Ricerca di intelligenza artificiale di Azure cerca il contenuto archiviato nel servizio. Il codice per il caricamento di documenti è identico all'argomento di avvio rapido 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 la classificazione semantica, 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 il 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 "what hotel has a good restaurant on site", l'algoritmo di classificazione BM25 restituisce corrispondenze nell'ordine illustrato in questo screenshot:

Screenshot showing matches ranked by BM25.

Al contrario, quando la classificazione semantica viene applicata alla stessa query ("che 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 allinea meglio alle aspettative degli utenti.

Screenshot showing matches ranked based on semantic ranking.

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.

Per trovare e gestire le risorse nel portale, usare 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