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

In Azure AI Search, un normalizer è un componente che pre-elabora il testo per la corrispondenza delle parole chiave sui campi contrassegnati come "filtrabili", "facetable" o "ordinabili". A differenza dei campi "ricercabili" full-text associati agli analizzatori di testo, il contenuto creato per le operazioni di filtraggio-facet-ordinamento non viene sottoposto ad analisi o tokenizzazione. L'omissione dell'analisi del testo può produrre risultati imprevisti quando si manifestano differenze di maiuscole, minuscole e di carattere, motivo per cui è necessaria la normalizzazione per omogeneizzare le variazioni nel contenuto.

Applicando un normalizzatore, è possibile ottenere trasformazioni di testo chiaro che migliorano i risultati:

• Casi di scrittura uniformi (ad esempio tutte minuscole o tutte 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 avviene su contenuto tokenizzato, come nel caso in cui si richiama "search", o su contenuto non tokenizzato se la richiesta è un filtro, una faccetta o un'operazione ordina per.

Poiché anche il contenuto non tokenizzato non viene analizzato, le piccole differenze nel contenuto vengono valutate come valori distintimente diversi. Si considerino gli esempi seguenti:

• $filter=City eq 'Las Vegas' restituirà solo i documenti che contengono il testo "Las Vegas" esatto ed escluderà i documenti con "LAS VEGAS" e "las vegas", che è inadeguato quando il caso d'uso richiede tutti i documenti indipendentemente dal maiuscolo/minuscolo.

• search=*&facet=City,count:5 restituirà "Las Vegas"e "LAS VEGAS""las vegas" come valori distinti nonostante sia la stessa città.

• search=usa&$orderby=City restituirà le città in ordine lessicografico: "Las Vegas", "Seattle", "las vegas", , anche se lo scopo è ordinare le stesse città insieme indipendentemente dal caso.

Un normalizzatore, richiamato durante l'indicizzazione e l'esecuzione di query, aggiunge trasformazioni leggere che consentono di uniformare le piccole differenze nel testo per scenari di filtro, 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 sono specificati in una definizione di indice, per campo, sui campi di testo (Edm.String e Collection(Edm.String)) che hanno almeno una delle proprietà "filtrabile", "ordinabile" o "facetable" impostata su true. L'impostazione di un normalizzatore è facoltativa ed è null per impostazione predefinita. È consigliabile valutare i normalizzatori predefiniti prima di configurarne uno personalizzato.

I normalizzatori possono essere specificati solo quando si aggiunge un nuovo campo all'indice, quindi, se possibile, provare a valutare le esigenze di normalizzazione prima e assegnare normalizzatori nelle fasi iniziali dello sviluppo durante l'eliminazione e la ricreazione degli indici è 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 "minuscolo" 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 un indice e aggiungere normalizzatori personalizzati.

   "fields": [
    {
      "name": "Description",
      "type": "Edm.String",
      "retrievable": true,
      "searchable": true,
      "analyzer": null,
      "normalizer": "my_custom_normalizer"
    },
   

Una buona soluzione alternativa per gli indici di produzione, in cui la ricompilazione degli 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 Update Index per incorporare il nuovo campo e mergeOrUpload per popolarlo. Successivamente, come parte della manutenzione pianificata dell'indice, è possibile pulire l'indice per rimuovere i campi obsoleti.

Normalizzatori predefiniti e personalizzati

Azure AI Search fornisce normalizzatori predefiniti per i casi d'uso comuni e la possibilità di personalizzare in base alle esigenze.

⁽¹⁾ I normalizzatori personalizzati non specificano tokenizzatori perché 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.

Richiesta

  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 su Normalizer

Normalizzatori predefiniti

Filtri char supportati

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

• Mapping
• pattern_replace

Filtri di token supportati

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

• arabic_normalization
• asciifolding
• cjk_width
• elisione
• german_normalization
• hindi_normalization
• indic_normalization
• persian_normalization
• scandinavian_normalization
• scandinavian_folding
• sorani_normalization
• minuscolo
• Maiuscolo

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 dei token sono i blocchi predefiniti per un normalizzatore personalizzato e responsabili dell'elaborazione del testo. Questi filtri vengono applicati da sinistra a destra.

token_filter_name_1 è il nome del filtro del token e char_filter_name_1char_filter_name_2 sono i nomi dei filtri char (vedere filtri di token supportati e tabelle di filtri char supportatidi seguito 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 versioni successive aggiornando uno esistente. Per aggiungere un normalizzatore personalizzato a un indice esistente è necessario specificare il flag "allowIndexDowntime" in Update Index e l'indice non sarà disponibile per alcuni secondi.

Esempio di normalizzatore personalizzato

L'esempio seguente illustra una definizione di normalizzatore personalizzata 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 e quindi viene fatto riferimento nella definizione di normalizer, come illustrato di seguito.

• Nella sezione "normalizer" della definizione dell'indice viene definito un normalizzatore personalizzato denominato "my_custom_normalizer".

• Il normalizer è composto da due filtri dei caratteri e tre filtri di token: filtro di elisione, convertitore in minuscolo e filtro di asciifolding personalizzato "my_asciifolding".

• Il primo filtro di caratteri "map_dash" sostituisce tutti i trattini con caratteri di sottolineatura 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 relativi a Querying in Azure AI Search

• Analizzatori per l'elaborazione linguistica e del testo

• API REST per la ricerca di documenti