Analizzatori per l'elaborazione del testo in Azure AI Search

Un analizzatore è un componente del motore di ricerca a tutto testo responsabile dell'elaborazione di stringhe durante l'indicizzazione e l'esecuzione di query. L'elaborazione del testo (nota anche come analisi lessicale) è trasformativa e modifica una stringa tramite azioni come le seguenti:

• Rimozione di parole non essenziali (parole non significative) e punteggiatura.
• Suddividere frasi e parole sillabate in parti
• Rendere minuscole tutte le parole con lettere maiuscole
• Ridurre le parole in forme radice primitive per efficienza di archiviazione e in modo che le corrispondenze possano essere trovate indipendentemente dalla coniugazione

L'analisi si applica ai campi Edm.String contrassegnati come "ricercabili", il che indica la ricerca a tutto testo.

Per i campi di questa configurazione, l'analisi viene eseguita durante l'indicizzazione, quando vengono creati i token, e quindi di nuovo durante l'esecuzione delle query, quando vengono analizzate le query e il motore cerca token corrispondenti. È più probabile che si verifichi una corrispondenza quando lo stesso analizzatore viene usato sia per l'indicizzazione che per le query, ma è possibile impostare l'analizzatore per ogni carico di lavoro in modo indipendente, a seconda dei requisiti.

I tipi di query non di ricerca a tutto testo, ad esempio filtri o ricerca fuzzy, non passano la fase di analisi sul lato query. Il parser invia invece tali stringhe direttamente al motore di ricerca, usando il modello fornito come base per la corrispondenza. In genere, questi moduli di query richiedono token di stringa intera perché la corrispondenza di criteri di ricerca possa funzionare. Per garantire che i token completi vengano mantenuti durante l'indicizzazione, potrebbero essere necessari analizzatori personalizzati. Per altre informazioni su quando e perché vengano analizzati i termini di query, vedere Ricerca a tutto testo in Azure AI Search.

Per altre informazioni sull'analisi lessicale, vedere il video clip seguente contenente una breve spiegazione.

Analizzatore predefinito

In Azure AI Search, un analizzatore viene richiamato automaticamente in tutti i campi stringa contrassegnati come ricercabili.

Per impostazione predefinita, Azure AI Search usa l'analizzatore Apache Lucene Standard (lucene standard), che suddivide il testo in elementi sulla base delle regole di "segmentazione del testo Unicode". L'analizzatore standard converte tutti i caratteri nel rispettivo formato minuscolo. I documenti indicizzati e i termini di ricerca vengono sottoposti ad analisi durante l'indicizzazione e l'elaborazione delle query.

È possibile eseguire l'override del valore predefinito nei singoli campi. Le alternative di analizzatori includono:

• analizzatore del linguaggio per l'elaborazione linguistica
• analizzatore personalizzato per configurazioni personalizzate
• analizzatori predefiniti da usare come sono

Tipi di analizzatori

Nell'elenco seguente sono descritti gli analizzatori disponibili in Azure AI Search.

Alcuni analizzatori predefiniti, ad esempio, Pattern o Stop, supportano un insieme limitato di opzioni di configurazione. Per impostare queste opzioni, creare un analizzatore personalizzato costituito dall'analizzatore predefinito e da una delle opzioni alternative incluse in Analizzatori predefiniti. Come per qualsiasi configurazione personalizzata, attribuire un nome alla nuova configurazione, ad esempio myPatternAnalyzer, per distinguerla dall'analizzatore Pattern Lucene.

Specificare analizzatori

L'impostazione di un analizzatore è facoltativa. Come regola generale, provare prima a usare l'analizzatore Lucene standard predefinito e verificarne le prestazioni. Se le query non restituiscono i risultati previsti, il passaggio a un analizzatore diverso è spesso la soluzione corretta.

1. Se si usa un analizzatore personalizzato, aggiungerlo all'indice di ricerca nella sezione "analizzatore". Per altre informazioni, vedere Creare un indice e Aggiungere analizzatori personalizzati.

2. Quando si definisce un campo, impostare la proprietà "analyzer" su una delle opzioni seguenti: un analizzatore predefinito (come una parola chiave), un analizzatore del linguaggio (come en.microsoft), o un analizzatore personalizzato (definito nello stesso schema di indice).

     "fields": [
    {
      "name": "Description",
      "type": "Edm.String",
      "retrievable": true,
      "searchable": true,
      "analyzer": "en.microsoft",
      "indexAnalyzer": null,
      "searchAnalyzer": null
    },
   

3. Se si sta usando un analizzatore del linguaggio, è necessario usare la proprietà "analyzer" per specificarlo. Le proprietà "searchAnalyzer" e "indexAnalyzer" non si applicano agli analizzatori del linguaggio.

4. In alternativa, impostare "indexAnalyzer" e "searchAnalyzer" per variare l'analizzatore per ogni carico di lavoro. Queste proprietà combinate fungono da sostituto della proprietà "analizzatore", che deve essere null. È possibile usare analizzatori diversi per indicizzazione e query se una di queste attività richiede una trasformazione specifica non necessaria per l'altra.

     "fields": [
    {
      "name": "ProductGroup",
      "type": "Edm.String",
      "retrievable": true,
      "searchable": true,
      "analyzer": null,
      "indexAnalyzer": "keyword",
      "searchAnalyzer": "standard"
    },
   

Quando aggiungere analizzatori

Il momento migliore per aggiungere e assegnare gli analizzatori è durante lo sviluppo attivo, quando eliminare e ricreare gli indici è routine.

Poiché gli analizzatori vengono usati per tokenizzare termini, è necessario assegnare un analizzatore al momento della creazione del campo. Infatti, l'assegnazione di un analizzatore o di un indexAnalyzer a un campo già creato fisicamente non è consentita (anche se è possibile modificare la proprietà searchAnalyzer in qualsiasi momento senza alcun impatto sull'indice).

Per modificare l'analizzatore di un campo esistente, è necessario eliminare e ricreare l'intero indice (non è possibile ricompilare singoli campi). Per indici nell'ambiente di produzione, è possibile evitare una ricompilazione creando un nuovo campo con la nuova assegnazione dell'analizzatore e iniziare a 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.

Per aggiungere un nuovo campo a un indice esistente, chiamare Aggiorna indice per aggiungere il campo e mergeOrUpload per popolarlo.

Per aggiungere un analizzatore personalizzato a un indice esistente, passare il flag "allowIndexDowntime" in Update Index se si vuole evitare questo errore:

"Index update not allowed because it would cause downtime. In order to add new analyzers, tokenizers, token filters, or character filters to an existing index, set the 'allowIndexDowntime' query parameter to 'true' in the index update request. Note that this operation will put your index offline for at least a few seconds, causing your indexing and query requests to fail. Performance and write availability of the index can be impaired for several minutes after the index is updated, or longer for very large indexes."

Consigli per l'utilizzo degli analizzatori

Questa sezione offre consigli su come usare gli analizzatori.

Usare un unico analizzatore in lettura-scrittura, a meno che non si disponga di requisiti specifici

Azure AI Search consente di specificare analizzatori diversi per l'indicizzazione e la ricerca tramite le proprietà del campo "indexAnalyzer" e "searchAnalyzer". Se non è specificato, l'analizzatore impostato con la proprietà analizzatore viene usato per l'indicizzazione e la ricerca. Se l'analizzatore non è specificato, verrà usato l'analizzatore Lucene Standard predefinito.

Una regola generale consiste nell'usare lo stesso analizzatore sia per l'indicizzazione che per l'esecuzione di query, salvo diversamente indicato da requisiti specifici. Assicurarsi di eseguire test approfonditi. Quando l'elaborazione del testo è diversa in fase di indicizzazione e ricerca, si corre il rischio che i termini di query e i termini indicizzati non corrispondano quando le configurazioni degli analizzatori di ricerca e indicizzazione non sono allineate.

Test durante lo sviluppo attivo

L'override dell'analizzatore standard richiede una ricompilazione dell'indice. Se possibile, stabilire quali analizzatori usare durante la fase di sviluppo attivo, prima di passare un indice nell'ambiente di produzione.

Controllare i termini in formato token

Se la ricerca non restituisce i risultati previsti, è molto probabile che esistano discrepanze a livello di token tra i termini di input nella query e i termini in formato token nell'indice. Se il token non corrispondono, non vengono individuate corrispondenze. Per esaminare l'output del tokenizer, è consigliabile usare l'API di analisi come strumento di indagine. La risposta è costituita da token, generati da un analizzatore specifico.

Esempi REST

Gli esempi seguenti mostrano le definizioni degli analizzatori per alcuni scenari chiave.

• Esempio di analizzatore personalizzato
• Esempio dell'assegnazione degli analizzatori a un campo
• Combinazioni di analizzatori per indicizzazione e ricerca
• Esempio di analizzatore del linguaggio

Esempio di analizzatore personalizzato

Questo esempio illustra una definizione di analizzatore con opzioni personalizzate. Le opzioni personalizzate per filtri char, tokenizer e filtri token vengono specificate separatamente come costrutti denominati a cui si fa riferimento nella definizione dell'analizzatore. Gli elementi predefiniti vengono usati così come sono, facendovi riferimento in base al nome.

Passaggi di questo esempio:

• Gli analizzatori sono una proprietà della classe di campo per un campo ricercabile.

• Un analizzatore personalizzato fa parte della definizione di un indice. Esso può essere parzialmente personalizzato (ad esempio, tramite la personalizzazione di una singola opzione in un filtro) o personalizzato in più posizioni.

• In questo caso, l'analizzatore personalizzato è "my_analyzer", che a sua volta usa il tokenizer standard personalizzato "my_standard_tokenizer" e due filtri token: un filtro asciifolding minuscolo e uno personalizzato "my_asciifolding".

• Definisce inoltre due filtri di caratteri personalizzati: "map_dash" e "remove_whitespace". Il primo sostituisce tutti i trattini con caratteri di sottolineatura, mentre il secondo rimuove tutti gli spazi. Nelle regole di mapping gli spazi devono essere codificati con UTF-8. I filtri di caratteri vengono applicati prima della tokenizzazione e influiranno sui token risultanti (le interruzioni standard dei tokenizer sui trattini e gli spazi, ma non sui caratteri di sottolineatura).

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false
        },
        {
           "name":"text",
           "type":"Edm.String",
           "searchable":true,
           "analyzer":"my_analyzer"
        }
     ],
     "analyzers":[
        {
           "name":"my_analyzer",
           "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
           "charFilters":[
              "map_dash",
              "remove_whitespace"
           ],
           "tokenizer":"my_standard_tokenizer",
           "tokenFilters":[
              "my_asciifolding",
              "lowercase"
           ]
        }
     ],
     "charFilters":[
        {
           "name":"map_dash",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["-=>_"]
        },
        {
           "name":"remove_whitespace",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["\\u0020=>"]
        }
     ],
     "tokenizers":[
        {
           "name":"my_standard_tokenizer",
           "@odata.type":"#Microsoft.Azure.Search.StandardTokenizerV2",
           "maxTokenLength":20
        }
     ],
     "tokenFilters":[
        {
           "name":"my_asciifolding",
           "@odata.type":"#Microsoft.Azure.Search.AsciiFoldingTokenFilter",
           "preserveOriginal":true
        }
     ]
  }

Esempio di assegnazione dell'analizzatore in base al campo

L'analizzatore Standard è l'impostazione predefinita. Si supponga di volere sostituire l'elemento predefinito con un analizzatore predefinito diverso, ad esempio l'analizzatore Pattern. Se non si impostano opzioni personalizzate, occorre specificare tale scelta in base al nome nella definizione del campo.

L'elemento "analizzatore" sostituisce l'analizzatore Standard campo per campo. Non vi è alcun override globale. In questo esempio, text1 usa l'analizzatore Pattern, mentre text2, che non specifica un analizzatore, usa l'elemento predefinito.

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false
        },
        {
           "name":"text1",
           "type":"Edm.String",
           "searchable":true,
           "analyzer":"pattern"
        },
        {
           "name":"text2",
           "type":"Edm.String",
           "searchable":true
        }
     ]
  }

Combinazioni di analizzatori per le operazioni di indicizzazione e ricerca

Le API includono attributi di indice per specificare analizzatori diversi per l'indicizzazione e la ricerca. Gli attributi searchAnalyzer e indexAnalyzer devono essere specificati come coppia, sostituendo il singolo attributo analizzatore.

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false
        },
        {
           "name":"text",
           "type":"Edm.String",
           "searchable":true,
           "indexAnalyzer":"whitespace",
           "searchAnalyzer":"simple"
        },
     ],
  }

Esempio di analizzatore del linguaggio

I campi contenenti stringhe in diverse lingue possono utsare un analizzatore del linguaggio, mentre altri campi mantengono il valore predefinito (o usano altri analizzatori predefiniti o personalizzati). Se si usa un analizzatore del linguaggio, questo deve essere usato per le operazioni di indicizzazione e ricerca. I campi che usano un analizzatore del linguaggio non possono disporre di analizzatori diversi per indicizzazione e ricerca.

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false
        },
        {
           "name":"text",
           "type":"Edm.String",
           "searchable":true,
           "indexAnalyzer":"whitespace",
           "searchAnalyzer":"simple"
        },
        {
           "name":"text_fr",
           "type":"Edm.String",
           "searchable":true,
           "analyzer":"fr.lucene"
        }
     ],
  }

Esempi di C#

Se si sta facendo uso degli esempi di codice .NET SDK, è possibile aggiungere questi esempi per usare o configurare gli analizzatori.

• Assegnare un analizzatore predefinito
• Configurare un analizzatore

Assegnare un analizzatore del linguaggio

Qualsiasi analizzatore usato così come è, senza alcuna configurazione, viene specificato in una definizione di campo. Non è necessario creare una voce nella sezione [analizzatori] dell'indice.

Gli analizzatori di lingua vengono usati così come sono. Per usarli, chiamare LexicalAnalyzer specificando il tipo LexicalAnalyzerName, il che fornisce un analizzatore di testo supportato Azure AI Search.

Gli analizzatori personalizzati vengono specificati in modo analogo nella definizione del campo, ma perché questo metodo funzioni è necessario specificare l'analizzatore nella definizione dell'indice, come descritto nella sezione successiva.

    public partial class Hotel
    {
       . . . 
        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.EnLucene)]
        public string Description { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.FrLucene)]
        [JsonPropertyName("Description_fr")]
        public string DescriptionFr { get; set; }

        [SearchableField(AnalyzerName = "url-analyze")]
        public string Url { get; set; }
      . . .
    }

Definire un analizzatore personalizzato

Quando la personalizzazione o la configurazione sono necessarie, aggiungere un costrutto di analizzatore a un indice. Dopo averlo definito, è possibile aggiungerlo alla definizione del campo, come illustrato nell'esempio precedente.

Creare un oggetto CustomAnalyzer. Un analizzatore personalizzato è una combinazione definita dall'utente di un tokenizer noto, zero o più filtri token e zero o più nomi di filtro di caratteri:

• CustomAnalyzer.Tokenizer
• CustomAnalyzer.TokenFilters
• CustomAnalyzer.CharFilters

L'esempio seguente crea un analizzatore personalizzato denominato "url-analyze" che usa il tokenizer uax_url_email e il filtro token Minuscole.

private static void CreateIndex(string indexName, SearchIndexClient adminClient)
{
   FieldBuilder fieldBuilder = new FieldBuilder();
   var searchFields = fieldBuilder.Build(typeof(Hotel));

   var analyzer = new CustomAnalyzer("url-analyze", "uax_url_email")
   {
         TokenFilters = { TokenFilterName.Lowercase }
   };

   var definition = new SearchIndex(indexName, searchFields);

   definition.Analyzers.Add(analyzer);

   adminClient.CreateOrUpdateIndex(definition);
}

Passaggi successivi

Una descrizione dettagliata dell'esecuzione di query è disponibile in Ricerca a tutto testo in Azure AI Search. Questo articolo usa alcuni esempi per illustrare comportamenti che potrebbero sembrare poco plausibili in un primo momento.

Per altre informazioni sugli analizzatori, vedere gli articoli seguenti:

• Aggiungere un analizzatore della lingua
• Aggiungere un analizzatore personalizzato
• Creare un indice di ricerca
• Creare un indice multilingue