Normalizzazione del testo per filtraggio senza distinzione tra maiuscole e minuscole, facet e ordinamento

Articolo
12/10/2024

Importante

Questa funzionalità è disponibile in anteprima pubblica in Condizioni supplementari per l'utilizzo. L'API REST di anteprima supporta questa funzionalità.

In Azure AI Search. un normalizzatore è un componente che pre-elabora testo per la corrispondenza di parole chiave sui campi contrassegnati come "filtrabili", "facetabili" o "ordinabili". A differenza dei campi "ricercabili" full-text associati agli analizzatori di testo, il contenuto creato per operazioni di filtraggio, facet e ordinamento non viene sottoposto a analisi o tokenizzazione. L'omissione dell'analisi del testo può produrre risultati imprevisti quando compaiono differenze tra maiuscole e minuscole e caratteri; per questa ragione, è necessario un normalizzatore per omogeneizzare variazioni nel contenuto.

Applicando un normalizzatore, è possibile ottenere trasformazioni di testo leggere con migliori risultati:

Maiuscole e minuscole coerenti (ad esempio, tutte minuscole o maiuscole)
Normalizzare accenti e diacritici come ö o ê in caratteri equivalenti ASCII "o" e "e"
Mappare caratteri come - e spazi vuoti in un carattere specificato dall'utente

Vantaggi dei normalizzatori

La ricerca e il recupero di documenti da un indice di ricerca richiede la corrispondenza dell'input della query al contenuto del documento. La corrispondenza è basata su contenuto tokenizzato, come nel caso in cui si richiama "search", o su contenuto non tokenizzato se la richiesta è un filtro, un facet o un'operazione orderby.

Poiché anche il contenuto non tokenizzato non viene analizzato, piccole differenze nel contenuto vengono valutate come valori nettamente diversi. Vedi gli esempi seguenti:

$filter=City eq 'Las Vegas' restituirà solo documenti che contengono il testo esatto "Las Vegas" ed escluderà documenti con "LAS VEGAS" e "las vegas", il che risulta inadeguato quando il caso d'uso richiede tutti i documenti indipendentemente dalla combinazione di maiuscole e minuscole.
search=*&facet=City,count:5 restituirà "Las Vegas", "LAS VEGAS" e "las vegas" come valori distinti, nonostante siano la stessa città.
search=usa&$orderby=City restituirà le città in ordine lessicografico: "Las Vegas", "Seattle", "las vegas", anche se lo scopo è raggruppare le stesse città indipendentemente dal caso.

Un normalizzatore, richiamato durante l'indicizzazione e l'esecuzione di query, aggiunge lievi trasformazioni che consentono di uniformare piccole differenze nel testo per scenari di filtraggio, facet e ordinamento. Negli esempi precedenti, le varianti di "Las Vegas" verrebbero elaborate in base al normalizzatore selezionato (ad esempio, tutto il testo è minuscolo) per ottenere risultati più uniformi.

Come specificare un normalizzatore

I normalizzatori vengono specificati in una definizione di indice, per ciascun campo di testo (Edm.String e Collection(Edm.String)) con almeno una proprietà "filterable", "sortable" o "facetable" impostata su true. L'impostazione di un normalizzatore è facoltativa ed è null per impostazione predefinita. È consigliabile valutare l’uso di normalizzatori predefiniti prima di configurarne uno personalizzato.

I normalizzatori possono essere specificati solo quando si aggiunge un nuovo campo all'indice; per questa ragione, se possibile, valutare le proprie esigenze di normalizzazione in anticipo e assegnare normalizzatori nelle fasi iniziali di sviluppo, quando l'eliminazione e la ricreazione di indici sono di routine.

Quando si crea una definizione di campo nell'indice, impostare la proprietà "normalizer" su uno dei valori seguenti: un normalizzatore predefinito, ad esempio "lowercase", o un normalizzatore personalizzato (definito nello stesso schema di indice).
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "filterable": true,
   "analyzer": "en.microsoft",
   "normalizer": "lowercase"
   ...
 }
]
```
I normalizzatori personalizzati vengono definiti nella sezione "normalizer" dell'indice e quindi assegnati alla definizione del campo, come illustrato nel passaggio precedente. Per altre informazioni, vedere Creare indice e Aggiungere normalizzatori personalizzati.
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "analyzer": null,
   "normalizer": "my_custom_normalizer"
 },
```

Nota

Per modificare il normalizzatore di un campo esistente, ricompilare l'indice per intero (non è possibile ricompilare singoli campi).

Una valida soluzione alternativa per gli indici di produzione, in cui la ricompilazione di indici è costosa, consiste nel creare un nuovo campo identico a quello precedente ma con il nuovo normalizzatore e usarlo al posto di quello precedente. Usare Aggiornare un indice per incorporare il nuovo campo e mergeOrUpload per compilarlo. In un secondo momento, nell'ambito della manutenzione pianificata dell'indice, sarà possibile pulire l'indice per rimuovere i campi obsoleti.

Normalizzatori predefiniti e personalizzati

Azure AI Search offre normalizzatori predefiniti per casi d'uso comuni e la possibilità di crearne di personalizzati in base alle esigenze.

Categoria	Descrizione
Normalizzatori predefiniti	Fornito pronto all’uso, può essere usato senza alcuna configurazione.
Normalizzatori personalizzati ¹	Per scenari avanzati. Richiede la configurazione definita dall'utente di una combinazione di elementi esistenti, costituiti da filtri char e token.

⁽¹⁾ I normalizzatori personalizzati non specificano tokenizzatori poiché i normalizzatori producono sempre un singolo token.

Informazioni di riferimento sui normalizzatori

Normalizzatori predefiniti

Nome	Descrizione e opzioni
standard	Rende minuscolo il testo seguito da asciifolding.
lowercase	Trasforma caratteri in minuscole.
uppercase	Trasforma caratteri in maiuscole.
asciifolding	Trasforma i caratteri che non si trovano nel blocco Unicode latino di base nell'equivalente ASCII, se esistente. Ad esempio, trasformando `à` in `a`.
elision	Rimuove l'elisione dall'inizio dei token.

Filtri char supportati

I normalizzatori supportano due filtri di caratteri identici alle rispettive controparti nei filtri di caratteri dell'analizzatore personalizzato:

Filtri di token supportati

L'elenco seguente mostra i filtri di token supportati per normalizzatori ed è un subset dei filtri di token complessivi usati in analizzatori personalizzati.

Aggiungere normalizzatori personalizzati

I normalizzatori personalizzati vengono definiti all'interno dello schema dell'indice. La definizione include un nome, un tipo, uno o più filtri di caratteri e filtri token. I filtri di caratteri e i filtri di token sono gli elementi costitutivi di un normalizzatore personalizzato e sono responsabili dell'elaborazione del testo. Questi filtri vengono applicati da sinistra a destra.

token_filter_name_1 è il nome del filtro token, e char_filter_name_1 e char_filter_name_2 sono i nomi dei filtri char (vedere le seguenti tabelle filtri token supportati e filtri char supportati per i valori validi).

"normalizers":(optional)[
   {
      "name":"name of normalizer",
      "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenFilters":[
         "token_filter_name_1"
      ]
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name_1",
      "@odata.type":"#char_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name_1",
      "@odata.type":"#token_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
]

I normalizzatori personalizzati possono essere aggiunti durante la creazione dell'indice o in seguito, aggiornandone uno esistente. Per aggiungere un normalizzatore personalizzato a un indice esistente, è necessario specificare il flag "allowIndexDowntime" in Aggiorna indice e l'indice non sarà disponibile per alcuni secondi.

Esempio di normalizzatore personalizzato

L'esempio seguente illustra una definizione di normalizzatore personalizzato con filtri di caratteri e filtri token corrispondenti. Le opzioni personalizzate per i filtri di caratteri e i filtri token vengono specificate separatamente come costrutti denominati; quindi, vi viene fatto riferimento nella definizione del normalizzatore, come illustrato di seguito.

Un normalizzatore personalizzato denominato "my_custom_normalizer" viene definito nella sezione “normalizers” della definizione dell’indice.
Il normalizzatore è composto da due filtri di caratteri e tre filtri di token: elisione, minuscola e filtro di asciifolding personalizzato "my_asciifolding".
Il primo filtro di caratteri "map_dash" sostituisce tutti i trattini con trattini bassi, mentre il secondo "remove_whitespace" rimuove tutti gli spazi.

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false,
        },
        {
           "name":"city",
           "type":"Edm.String",
           "filterable": true,
           "facetable": true,
           "normalizer": "my_custom_normalizer"
        }
     ],
     "normalizers":[
        {
           "name":"my_custom_normalizer",
           "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
           "charFilters":[
              "map_dash",
              "remove_whitespace"
           ],
           "tokenFilters":[              
              "my_asciifolding",
              "elision",
              "lowercase",
           ]
        }
     ],
     "charFilters":[
        {
           "name":"map_dash",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["-=>_"]
        },
        {
           "name":"remove_whitespace",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["\\u0020=>"]
        }
     ],
     "tokenFilters":[
        {
           "name":"my_asciifolding",
           "@odata.type":"#Microsoft.Azure.Search.AsciiFoldingTokenFilter",
           "preserveOriginal":true
        }
     ]
  }

Vedi anche

Concetti di query in Azure AI Search
Analizzatori per l'elaborazione linguistica e del testo
Search Documents REST API (API REST di Ricerca di documenti)

Condividi tramite