Configurare il ranker semantico e restituire didascalie nei risultati della ricerca

La classificazione semantica esegue l'iterazione su un set di risultati iniziale, applicando una metodologia di classificazione L2 che promuove i risultati più pertinenti semanticamente all'inizio dello stack. È anche possibile ottenere didascalie semantiche, con evidenziazioni sui termini e sulle frasi più rilevanti e risposte semantiche.

Questo articolo illustra come configurare un indice di ricerca per il reranking semantico.

Prerequisiti

• Azure AI Search in qualsiasi regione che offre classificazione semantica.

• Indice di ricerca esistente con contenuto di testo avanzato. La classificazione semantica si applica ai campi stringhe (nonvector) e funziona meglio sul contenuto informativo o descrittivo.

• Autorizzazione per creare e usare oggetti in Azure AI Search. È consigliabile usare l'accesso in base al ruolo, ma è possibile usare le chiavi API se un'assegnazione di ruolo non è fattibile. Per altre informazioni, vedere Connettersi a un servizio di ricerca.

• Versione 2026-08-01-preview dell'API REST del servizio di ricerca.

Scegliere un client

È possibile specificare una configurazione semantica in indici nuovi o esistenti, usando uno degli strumenti e degli SDK seguenti per aggiungere una configurazione semantica:

• Azure portal usando il designer dell'indice per aggiungere una configurazione semantica.
• Visual Studio Code con il client REST e un Create or Update Index (REST) API.
• Azure SDK per .NET
• Azure SDK per Python
• Azure SDK per Java
• Azure SDK per JavaScript

Aggiungere una configurazione semantica

Alcuni carichi di lavoro creano automaticamente una configurazione semantica. Se si usa il recupero agentico e un'origine della conoscenza che indicizza il contenuto in Azure AI Search, l'indice generato ha già una configurazione semantica che funziona per il tuo contenuto.

Per altri carichi di lavoro, è possibile configurare manualmente una configurazione semantica. Una configurazione semantica è una sezione dell'indice che stabilisce gli input di campo usati per la classificazione semantica. È possibile aggiungere o aggiornare una configurazione semantica in qualsiasi momento, senza alcuna ricompilazione necessaria. Se si creano più configurazioni, è possibile specificare un valore predefinito. In fase di query specificare una configurazione semantica in una richiesta di query o lasciarla vuota per usare l'impostazione predefinita.

È possibile creare fino a 100 configurazioni semantiche in un singolo indice.

Una configurazione semantica ha un nome e le proprietà seguenti:

È possibile specificare un solo campo titolo, ma è possibile avere il numero di campi di contenuto e parola chiave desiderati. Per i campi contenuto e parola chiave, elencare i campi in ordine di priorità perché i campi con priorità inferiore potrebbero essere troncati.

In tutte le proprietà di configurazione semantica, i campi assegnati devono essere:

• Attribuito come searchable e retrievable
• Stringhe di tipo Edm.String, Collection(Edm.String), sottocampi della stringa di Edm.ComplexType

string indexName = "hotel";
SearchIndex searchIndex = new(indexName)
{
    Fields =
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true, IsFacetable = true },
        new SearchableField("HotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("Description") { IsFilterable = true },
        new SearchableField("Category") { IsFilterable = true, IsSortable = true, IsFacetable = true },
    },
    SemanticSearch = new()
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description")
                },
                KeywordsFields =
                {
                    new SemanticField("Category")
                }
            })
        }
    }
};

Acconsentire esplicitamente ai modelli di classificazione semantica non definitiva (anteprima)

Usando le API REST in anteprima e gli SDK di Azure in anteprima che includono la proprietà, è possibile configurare facoltativamente un indice per usare modelli di ranking semantico pre-rilascio, se ne è stato distribuito uno nella propria area geografica. Non esiste alcun meccanismo per sapere se è disponibile una versione preliminare o se è stato usato in una query specifica. Per questo motivo, è consigliabile usare questa proprietà negli ambienti di test e solo se si è interessati a provare i modelli di classificazione semantica più recenti.

La proprietà di configurazione è "flightingOptIn": truee viene impostata nella sezione di configurazione semantica di un indice. La proprietà è impostata a null o false per impostazione predefinita. È possibile impostare la proprietà su vero in una richiesta di creazione o aggiornamento in qualsiasi momento, e ciò influenzerà le query semantiche che si effettuano successivamente, supponendo che la query stipuli una configurazione semantica che includa la proprietà.

PUT https://myservice.search.windows.net/indexes('hotels')?allowIndexDowntime=False&api-version=2026-08-01-preview

{
  "name": "hotels",
  "fields": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": "geo",
  "suggesters": [ ],
  "analyzers": [ ],
  "corsOptions": { },
  "encryptionKey": { },
  "similarity": { },
  "semantic": {
    "configurations": [
      {
        "name": "semanticHotels",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "hotelName"
          },
        "prioritizedContentFields": [
            {
              "fieldName": "description"
            },
            {
              "fieldName": "description_fr"
            }
          ],
        "prioritizedKeywordsFields": [
            {
              "fieldName": "tags"
            },
            {
              "fieldName": "category"
            }
          ],
        "flightingOptIn": true
        }
      }
    ]
  },
  "vectorSearch": {  }
}

Passaggi successivi

Verifica la configurazione semantica eseguendo una query semantica.