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

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. Si considerino 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.

1. 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"
      ...
    }
   ]
   

2. 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"
    },
   

Note

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.

Category	Descrizione
Normalizzatori predefiniti	Fornito pronto all’uso, può essere usato senza alcuna configurazione.
Normalizzatori personalizzati1	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.

Testare un normalizzatore

È possibile usare l'analizzatore di test (REST) per vedere come un normalizzatore elabora un input.

Richiedi

  POST https://[search service name].search.windows.net/indexes/[index name]/analyze?api-version=[api-version]
    Content-Type: application/json
    api-key: [admin key]

  {
     "normalizer":"asciifolding",
     "text": "Vis-à-vis means Opposite"
  }

risposta

HTTP/1.1 200 OK

{
  "tokens": [
    {
      "token": "Vis-a-vis means Opposite",
      "startOffset": 0,
      "endOffset": 24,
      "position": 0
    }
  ]
}

Informazioni di riferimento sui normalizzatori

Normalizzatori predefiniti

Nome	Descrizione e opzioni
standard	Rende minuscolo il testo seguito da asciifolding.
lettere minuscole	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.
elisione	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:

• mappatura
• pattern_replace

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.

• normalizzazione_arabica
• asciifolding
• cjk_width
• elision
• german_normalization
• hindi_normalization
• indic_normalization
• normalizzazione_persiana
• normalizzazione_scandinava
• scandinavian_folding
• sorani_normalization
• lowercase
• uppercase

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
        }
     ]
  }

Vedere 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)