Sinonimi in Ricerca di Azure (anteprima)Synonyms in Azure Search (preview)

La funzionalità relativa ai sinonimi nei motori di ricerca associa termini equivalenti, che espandono in modo implicito l'ambito di una query, senza che l'utente debba fornire effettivamente il termine.Synonyms in search engines associate equivalent terms that implicitly expand the scope of a query, without the user having to actually provide the term. Ad esempio, dato il termine "cane" e le associazioni sinonimiche "canino" e "cucciolo", tutti i documenti contenenti "cane", "canino" o "cucciolo" saranno inclusi nella query.For example, given the term "dog" and synonym associations of "canine" and "puppy", any documents containing "dog", "canine" or "puppy" will fall within the scope of the query.

In Ricerca di Azure l'espansione sinonimica viene eseguita in fase di query.In Azure Search, synonym expansion is done at query time. È possibile aggiungere mappe sinonimiche a un servizio senza compromettere le operazioni esistenti.You can add synonym maps to a service with no disruption to existing operations. La proprietà synonymMaps può essere aggiunta alla definizione di un campo senza dover ricompilare l'indice.You can add a synonymMaps property to a field definition without having to rebuild the index.

Disponibilità delle funzionalitàFeature availability

La funzionalità relativa ai sinonimi è attualmente disponibile in anteprima ed è supportata solo nelle versioni API di anteprima più recenti (api-version=2016-09-01-Preview).The synonyms feature is currently in preview and only supported in the latest preview api-version (api-version=2016-09-01-Preview). Non è attualmente disponibile alcun supporto nel portale di Azure.There is no Azure portal support at this time. Poiché la versione dell'API è specificata nella richiesta, è possibile combinare API disponibili a livello generale (GA) e di anteprima nella stessa applicazione.Because the API version is specified on the request, it's possible to combine generally available (GA) and preview APIs in the same app. 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.However, preview APIs are not under SLA and features may change, so we do not recommend using them in production applications.

In Ricerca di Azure il supporto dei sinonimi si basa sulle mappe sinonimiche definite e caricate nel servizio.In Azure Search, synonym support is based on synonym maps that you define and upload to your service. Queste mappe costituiscono una risorsa indipendente (ad esempio indici o origini dati) e possono essere utilizzate da qualsiasi campo ricercabile in qualsiasi indice nel servizio di ricerca.These maps constitute an independent resource (like indexes or data sources), and can be used by any searchable field in any index in your search service.

Le mappe sinonimiche e gli indici vengono mantenuti in modo indipendente.Synonym maps and indexes are maintained independently. Dopo aver definito una mappa sinonimica e averla caricata nel servizio, è possibile abilitare la funzionalità relativa ai sinonimi per un campo tramite l'aggiunta della nuova proprietà synonymMaps nella definizione del campo.Once you define a synonym map and upload it to your service, you can enable the synonym feature on a field by adding a new property called synonymMaps in the field definition. La creazione, l'aggiornamento e l'eliminazione di una mappa sinonimica è sempre un'operazione che riguarda l'intero documento, perciò non è possibile creare, aggiornare o eliminare parti della mappa sinonimica in modo incrementale.Creating, updating, and deleting a synonym map is always a whole-document operation, meaning that you cannot create, update or delete parts of the synonym map incrementally. Se si aggiorna anche una singola voce è necessario ripetere il caricamento.Updating even a single entry requires a reload.

L'aggiunta di sinonimi in un'applicazione di ricerca è una procedura in due passaggi:Incorporating synonyms into your search application is a two-step process:

  1. Aggiungere una mappa sinonimica al servizio di ricerca tramite le API indicate di seguito.Add a synonym map to your search service through the APIs below.

  2. Configurare un campo ricercabile per l'uso della mappa sinonimica nella definizione dell'indice.Configure a searchable field to use the synonym map in the index definition.

API di risorsa SynonymMapsSynonymMaps Resource APIs

Aggiungere o aggiornare una mappa sinonimica nel servizio tramite POST o PUT.Add or update a synonym map under your service, using POST or PUT.

Le mappe sinonimiche vengono caricate nel servizio tramite POST o PUT.Synonym maps are uploaded to the service via POST or PUT. Ogni regola deve essere delimitata dal carattere nuova riga ('\n').Each rule must be delimited by the new line character ('\n'). È possibile definire fino a 5.000 regole per ogni mappa sinonimica in un servizio gratuito e 10.000 regole in tutti gli altri SKU.You can define up to 5,000 rules per synonym map in a free service and 10,000 rules in all other SKUs. Ogni regola può avere fino a 20 espansioni.Each rule can have up to 20 expansions.

In questa anteprima le mappe sinonimiche devono essere nel formato Apache Solr descritto di seguito.In this preview, synonym maps must be in the Apache Solr format which is explained below. Se si ha un dizionario di sinonimi in un formato diverso e si desidera usarlo direttamente, segnalarlo mediante UserVoice.If you have an existing synonym dictionary in a different format and want to use it directly, please let us know on UserVoice.

È possibile creare una nuova mappa sinonimica usando HTTP POST, come nell'esempio seguente:You can create a new synonym map using HTTP POST, as in the following example:

POST https://[servicename].search.windows.net/synonymmaps?api-version=2016-09-01-Preview
api-key: [admin key]

{  
   "name":"mysynonymmap",
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}

In alternativa è possibile usare PUT e specificare il nome della mappa sinonimica nell'URI.Alternatively, you can use PUT and specify the synonym map name on the URI. Se la mappa sinonimica non esiste, verrà creata.If the synonym map does not exist, it will be created.

PUT https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

{  
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}
Formato dei sinonimi Apache SolrApache Solr synonym format

Il formato Solr supporta il mapping sinonimico equivalente ed esplicito.The Solr format supports equivalent and explicit synonym mappings. Le regole del mapping aderiscono alla specifica di filtro dei sinonimi open source di Apache Solr descritta in questo documento: SynonymFilter.Mapping rules adhere to the open source synonym filter specification of Apache Solr, described in this document: SynonymFilter. Di seguito è riportata una regola di esempio per sinonimi equivalenti.Below is a sample rule for equivalent synonyms.

USA, United States, United States of America

Con la regola precedente, la query di ricerca "USA" si espanderà in "USA" OR "Stati Uniti" OR "Stati Uniti d'America".With the rule above, a search query "USA" will expand to "USA" OR "United States" OR "United States of America".

Il mapping esplicito è indicato da una freccia "=>".Explicit mapping is denoted by an arrow "=>". Quando è specificato, una sequenza di termini di una query di ricerca che corrisponde al lato sinistro di "= >" verrà sostituita con le alternative sul lato destro.When specified, a term sequence of a search query that matches the left hand side of "=>" will be replaced with the alternatives on the right hand side. Data la regola seguente, le query di ricerca "Washington", "Wash."Given the rule below, search queries "Washington", "Wash." o "WA" saranno riscritte tutte come "WA".or "WA" will all be rewritten to "WA". Il mapping esplicito si applica solo nella direzione specificata e, in questo caso, non riscrivere la query "WA" come "Washington".Explicit mapping only applies in the direction specified and does not rewrite the query "WA" to "Washington" in this case.

Washington, Wash., WA => WA

Elencare le mappe sinonimiche del proprio servizio.List synonym maps under your service.

GET https://[servicename].search.windows.net/synonymmaps?api-version=2016-09-01-Preview
api-key: [admin key]

Aggiungere una mappa sinonimica al proprio servizio.Get a synonym map under your service.

GET https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

Eliminare una mappa sinonimica dal proprio servizio.Delete a synonyms map under your service.

DELETE https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

Configurare un campo ricercabile per l'uso della mappa sinonimica nella definizione dell'indice.Configure a searchable field to use the synonym map in the index definition.

La nuova proprietà di campo synonymMaps consente di specificare una mappa sinonimica da usare per un campo ricercabile.A new field property synonymMaps can be used to specify a synonym map to use for a searchable field. Le mappe sinonimiche sono risorse a livello di servizio e possono essere referenziate da qualsiasi campo di un indice del servizio.Synonym maps are service level resources and can be referenced by any field of an index under the service.

POST https://[servicename].search.windows.net/indexes?api-version=2016-09-01-Preview
api-key: [admin key]

{
   "name":"myindex",
   "fields":[
      {
         "name":"id",
         "type":"Edm.String",
         "key":true
      },
      {
         "name":"name",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"en.lucene",
         "synonymMaps":[
            "mysynonymmap"
         ]
      },
      {
         "name":"name_jp",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"ja.microsoft",
         "synonymMaps":[
            "japanesesynonymmap"
         ]
      }
   ]
}

È possibile specificare synonymMaps per i campi ricercabili di tipo "Edm. String" o "Collection".synonymMaps can be specified for searchable fields of the type 'Edm.String' or 'Collection(Edm.String)'.

Nota

In questa versione di anteprima è possibile avere solo una mappa sinonimica per campo.In this preview, you can only have one synonym map per field. Se si vuole usare più mappe sinonimiche, segnalarlo tramite UserVoice.If you want to use multiple synonym maps, please let us know on UserVoice.

Impatto dei sinonimi sulle altre funzionalità di ricercaImpact of synonyms on other search features

La funzionalità relativa ai sinonimi riscrive la query originale con sinonimi usando l'operatore OR.The synonyms feature rewrites the original query with synonyms with the OR operator. Per questo motivo, l'evidenziazione dei risultati e i profili di punteggio trattano il termine originale e i sinonimi come equivalenti.For this reason, hit highlighting and scoring profiles treat the original term and synonyms as equivalent.

La funzionalità relativa ai sinonimi si applica alle query di ricerca e non ai filtri o ai facet.Synonym feature applies to search queries and does not apply to filters or facets. Analogamente, i suggerimenti sono basati solo sul termine originale; le corrispondenze sinonimiche non compaiono nella risposta.Similarly, suggestions are based only on the original term; synonym matches do not appear in the response.

Le espansioni dei sinonimi non si applicano ai termini di ricerca con caratteri jolly; i termini con prefisso, fuzzy e regex non vengono espansi.Synonym expansions do not apply to wildcard search terms; prefix, fuzzy, and regex terms aren't expanded.

Suggerimenti per la creazione di una mappa sinonimicaTips for building a synonym map

  • Una mappa sinonimica concisa e ben progettata è più efficiente rispetto a un elenco completo delle possibili corrispondenze.A concise, well-designed synonym map is more efficient than an exhaustive list of possible matches. I dizionari eccessivamente grandi o complessi richiedono più tempo di analisi e influenzano la latenza della query se la query si espande in molti sinonimi.Excessively large or complex dictionaries take longer to parse and affect the query latency if the query expands to many synonyms. Invece di indovinare quali termini potrebbero essere usati, è possibile ottenere i termini effettivi tramite un report di analisi del traffico di ricerca.Rather than guess at which terms might be used, you can get the actual terms via a search traffic analysis report.

  • Come esercizio sia preliminare che di convalida, abilitare e usare questo report per determinare con precisione quali termini trarranno vantaggio da una corrispondenza sinonimica e quindi continuare a usarlo per verificare che la mappa sinonimica sta generando risultati migliori.As both a preliminary and validation exercise, enable and then use this report to precisely determine which terms will benefit from a synonym match, and then continue to use it as validation that your synonym map is producing a better outcome. Nel report predefinito il riquadro delle query di ricerca più comuni e il riquadro delle query di ricerca senza risultati forniranno le informazioni necessarie.In the predefined report, the tiles "Most common search queries" and "Zero-result search queries" will give you the necessary information.

  • È possibile creare più mappe sinonimiche per l'applicazione di ricerca (ad esempio in base alla lingua se l'applicazione supporta clienti multilingue).You can create multiple synonym maps for your search application (for example, by language if your application supports a multi-lingual customer base). Attualmente un campo può usarne una sola.Currently, a field can only use one of them. È possibile aggiornare la proprietà synonymMaps di un campo in qualsiasi momento.You can update a field's synonymMaps property at any time.

Passaggi successiviNext steps

  • Se si ha un indice esistente in un ambiente di sviluppo (non di produzione), provare con un piccolo dizionario per vedere come l'aggiunta di sinonimi cambia l'esperienza di ricerca, compreso l'impatto sui profili di punteggio, l'evidenziazione dei risultati e i suggerimenti.If you have an existing index in a development (non-production) environment, experiment with a small dictionary to see how the addition of synonyms changes the search experience, including impact on scoring profiles, hit highlighting, and suggestions.

  • Abilitare l'analisi del traffico di ricerca e usare i report predefiniti di Power BI per ottenere informazioni su quali termini sono più utilizzati e quali non restituiscono documenti.Enable search traffic analytics and use the predefined Power BI report to learn which terms are used the most, and which ones return zero documents. In base a queste informazioni, modificare il dizionario per includere i sinonimi per le query improduttive che devono risolversi in documenti nell'indice.Armed with these insights, revise the dictionary to include synonyms for unproductive queries that should be resolving to documents in your index.