Esercitazione sui sinonimi (anteprima) in C# per Ricerca di AzureSynonym (preview) C# tutorial for Azure Search

I sinonimi espandono una query tramite la corrispondenza con termini considerati semanticamente uguali al termine di input.Synonyms expand a query by matching on terms considered semantically equivalent to the input term. È ad esempio possibile che si voglia che il termine "auto" consenta di rilevare corrispondenze con documenti contenenti i termini "automobile" o "veicolo".For example, you might want "car" to match documents containing the terms "automobile" or "vehicle".

In Ricerca di Azure i sinonimi sono definiti in una mappa di sinonimi tramite regole di mapping che associano termini equivalenti.In Azure Search, synonyms are defined in a synonym map, through mapping rules that associate equivalent terms. È possibile creare più mappe di sinonimi, inserirle come risorse a livello di servizio disponibili per qualsiasi indice e quindi fare riferimento alla mappa da usare a livello di campo.You can create multiple synonym maps, post them as a service-wide resource available to any index, and then reference which one to use at the field level. In fase di query, oltre a eseguire ricerche in un indice, Ricerca di Azure esegue una ricerca in una mappa di sinonimi, se tale mappa viene specificata nei campi usati nella query.At query time, in addition to searching an index, Azure Search does a lookup in a synonym map, if one is specified on fields used in the query.

Nota

La funzionalità relativa ai sinonimi è attualmente disponibile in anteprima ed è supportata solo nelle versioni più recenti dell'anteprima di API e SDK (api-version=2016-09-01-Preview, SDK versione 4.x-anteprima).The synonyms feature is currently in preview and only supported in the latest preview API and SDK versions (api-version=2016-09-01-Preview, SDK version 4.x-preview). Non è attualmente disponibile alcun supporto nel portale di Azure.There is no Azure portal support at this time. Le API disponibili in anteprima non rientrano nel Contratto di servizio e le funzionalità disponibili in anteprima possono subire modifiche, quindi non è consigliabile usarle nelle applicazioni di produzione.Preview APIs are not under SLA and preview features may change, so we do not recommend using them in production applications.

PrerequisitiPrerequisites

I requisiti per l'esercitazione includono i seguenti:Tutorial requirements include the following:

PanoramicaOverview

Le query di tipo "prima e dopo" illustrano il valore dei sinonimi.Before-and-after queries demonstrate the value of synonyms. In questa esercitazione viene usata un'applicazione di esempio che esegue query e restituisce risultati in un indice di esempio.In this tutorial, we use a sample application that executes queries and returns results on a sample index. L'applicazione di esempio crea un indice di dimensioni ridotte denominato "hotels", popolato con due documenti.The sample application creates a small index named "hotels" populated with two documents. L'applicazione esegue query di ricerca usando termini e frasi non visualizzati nell'indice, abilita la funzionalità relativa ai sinonimi e quindi esegue di nuovo le stesse ricerche.The application executes search queries using terms and phrases that do not appear in the index, enables the synonyms feature, then issues the same searches again. Il codice seguente illustra il flusso complessivo.The code below demonstrates the overall flow.

  static void Main(string[] args)
  {
      SearchServiceClient serviceClient = CreateSearchServiceClient();

      Console.WriteLine("{0}", "Cleaning up resources...\n");
      CleanupResources(serviceClient);

      Console.WriteLine("{0}", "Creating index...\n");
      CreateHotelsIndex(serviceClient);

      ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

      Console.WriteLine("{0}", "Uploading documents...\n");
      UploadDocuments(indexClient);

      ISearchIndexClient indexClientForQueries = CreateSearchIndexClient();

      RunQueriesWithNonExistentTermsInIndex(indexClientForQueries);

      Console.WriteLine("{0}", "Adding synonyms...\n");
      UploadSynonyms(serviceClient);
      EnableSynonymsInHotelsIndex(serviceClient);
      Thread.Sleep(10000); // Wait for the changes to propagate

      RunQueriesWithNonExistentTermsInIndex(indexClientForQueries);

      Console.WriteLine("{0}", "Complete.  Press any key to end application...\n");

      Console.ReadKey();
  }

Per informazioni sulla procedura per la creazione e il popolamento dell'indice di esempio, vedere Come utilizzare Ricerca di Azure da un'applicazione .NET.The steps to create and populate the sample index are explained in How to use Azure Search from a .NET Application.

Query di tipo "prima""Before" queries

In RunQueriesWithNonExistentTermsInIndex vengono eseguite query di ricerca con i termini "five star", "internet" ed "economy AND hotel".In RunQueriesWithNonExistentTermsInIndex, we issue search queries with "five star", "internet", and "economy AND hotel".

Console.WriteLine("Search the entire index for the phrase \"five star\":\n");
results = indexClient.Documents.Search<Hotel>("\"five star\"", parameters);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the term 'internet':\n");
results = indexClient.Documents.Search<Hotel>("internet", parameters);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the terms 'economy' AND 'hotel':\n");
results = indexClient.Documents.Search<Hotel>("economy AND hotel", parameters);
WriteDocuments(results);

Nessuno dei due documenti indicizzati contiene questi termini, quindi si ottiene l'output seguente dal primo comando RunQueriesWithNonExistentTermsInIndex.Neither of the two indexed documents contain the terms, so we get the following output from the first RunQueriesWithNonExistentTermsInIndex.

Search the entire index for the phrase "five star":

no document matched

Search the entire index for the term 'internet':

no document matched

Search the entire index for the terms 'economy' AND 'hotel':

no document matched

Abilitare i sinonimiEnable synonyms

L'abilitazione dei sinonimi è un processo in due passaggi.Enabling synonyms is a two-step process. Vengono prima di tutto definite e caricate le regole dei sinonimi e quindi vengono configurati i campi per usarle.We first define and upload synonym rules and then configure fields to use them. Il processo viene illustrato in UploadSynonyms e EnableSynonymsInHotelsIndex.The process is outlined in UploadSynonyms and EnableSynonymsInHotelsIndex.

  1. Aggiungere una mappa di sinonimi al servizio di ricerca.Add a synonym map to your search service. In UploadSynonyms vengono definite quattro regole nella mappa di sinonimi 'desc-synonymmap' e viene eseguito il caricamento nel servizio.In UploadSynonyms, we define four rules in our synonym map 'desc-synonymmap' and upload to the service.

     var synonymMap = new SynonymMap()
     {
         Name = "desc-synonymmap",
         Format = "solr",
         Synonyms = "hotel, motel\n
                     internet,wifi\n
                     five star=>luxury\n
                     economy,inexpensive=>budget"
     };
    
     serviceClient.SynonymMaps.CreateOrUpdate(synonymMap);
    

    Una mappa di sinonimi deve essere conforme al formato solr dello standard open source.A synonym map must conform to the open source standard solr format. Il formato viene illustrato in Synonyms in Azure Search (Sinonimi in Ricerca di Azure) nella sezione Apache Solr synonym format.The format is explained in Synonyms in Azure Search under the section Apache Solr synonym format.

  2. Configurare i campi disponibili per la ricerca per l'uso della mappa di sinonimi nella definizione dell'indice.Configure searchable fields to use the synonym map in the index definition. In EnableSynonymsInHotelsIndex vengono abilitati i sinonimi in due campi, category e tags, tramite l'impostazione della proprietà synonymMaps sul nome della mappa di sinonimi appena caricata.In EnableSynonymsInHotelsIndex, we enable synonyms on two fields category and tags by setting the synonymMaps property to the name of the newly uploaded synonym map.

    Index index = serviceClient.Indexes.Get("hotels");
    index.Fields.First(f => f.Name == "category").SynonymMaps = new[] { "desc-synonymmap" };
    index.Fields.First(f => f.Name == "tags").SynonymMaps = new[] { "desc-synonymmap" };
    
    serviceClient.Indexes.CreateOrUpdate(index);
    

    Quando si aggiunge una mappa di sinonimi, non è necessario ricompilare l'indice.When you add a synonym map, index rebuilds are not required. È possibile aggiungere una mappa di sinonimi al servizio e quindi correggere le definizioni di campi esistenti in qualsiasi indice in modo da usare la nuova mappa di sinonimi.You can add a synonym map to your service, and then amend existing field definitions in any index to use the new synonym map. L'aggiunta di nuovi attributi non ha alcun impatto sulla disponibilità dell'indice.The addition of new attributes has no impact on index availability. Ciò vale anche per la disabilitazione dei sinonimi per un campo.The same applies in disabling synonyms for a field. È possibile impostare semplicemente la proprietà synonymMaps su un elenco vuoto.You can simply set the synonymMaps property to an empty list.

    index.Fields.First(f => f.Name == "category").SynonymMaps = new List<string>();
    

Query di tipo "dopo""After" queries

Dopo il caricamento della mappa di sinonimi e l'aggiornamento dell'indice per l'uso della mappa di sinonimi, la seconda chiamata RunQueriesWithNonExistentTermsInIndex restituisce quanto segue:After the synonym map is uploaded and the index is updated to use the synonym map, the second RunQueriesWithNonExistentTermsInIndex call outputs the following:

Search the entire index for the phrase "five star":

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the term 'internet':

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the terms 'economy' AND 'hotel':

Name: Roach Motel       Category: Budget        Tags: [motel, budget]

La prima query trova il documento dalla regola five star=>luxury.The first query finds the document from the rule five star=>luxury. La seconda query espande la ricerca usando internet,wifi e la terza usando hotel, motel e economy,inexpensive=>budget nell'individuazione di documenti corrispondenti.The second query expands the search using internet,wifi and the third using both hotel, motel and economy,inexpensive=>budget in finding the documents they matched.

L'aggiunta di sinonimi modifica completamente l'esperienza di ricerca.Adding synonyms completely changes the search experience. In questa esercitazione le query originali non sono in grado di restituire risultati significativi, anche se i documenti nell'indice sono rilevanti.In this tutorial, the original queries failed to return meaningful results even though the documents in our index were relevant. Abilitando i sinonimi, è possibile espandere un indice in modo da includere termini di uso comune, senza modifiche ai dati sottostanti dell'indice.By enabling synonyms, we can expand an index to include terms in common use, with no changes to underlying data in the index.

Esempio di codice sorgente dell'applicazioneSample application source code

Il codice sorgente completo dell'applicazione di esempio utilizzata è disponibile in questa procedura dettagliata su GitHub.You can find the full source code of the sample application used in this walk through on GitHub.

Passaggi successiviNext steps