Normalização de texto para filtragem, facetamento e classificação sem diferenciação de maiúsculas e minúsculas

Importante

Esse recurso está em versão prévia pública nos Termos de Uso Complementares. A versão prévia da API REST dá suporte a esse recurso.

No Azure AI Search, um normalizador é um componente que pré-processa o texto para corresponder as palavras-chave com os campos marcados como "filtrante", "facetável" ou "classificável". Ao contrário dos campos "pesquisáveis" de texto completo, que são pareados com os analisadores de texto, o conteúdo criado para operações filter-facet-sort não é submetido à análise ou tokenização. A omissão da análise de texto pode produzir resultados inesperados quando as diferenças de caixa e caracteres aparecem, e é por isso que você precisa de um normalizador para homogeneizar as variações em seu conteúdo.

Ao aplicar um normalizador, você pode obter ligeiras transformações de texto que melhoram os resultados:

• Uso de maiúsculas consistente (como todas as letras minúsculas ou maiúsculas)
• Normalizar acentos e diacríticos como ö ou ê, transformando-os em seu equivalente ASCII, "o" e "e"
• Mapear caracteres como - e espaço em branco e substituí-los por um caractere especificado pelo usuário

Benefícios dos normalizadores

Para pesquisar e recuperar documentos de um índice de pesquisa, é preciso que a entrada de consulta corresponda ao conteúdo do documento. A correspondência é sobre o conteúdo tokenizado, como é o caso quando você invoca a "pesquisa", ou sobre o conteúdo não tokenizado, se a solicitação for uma operação de filtro, faceta ou orderby.

Como o conteúdo não tokenizado também não é analisado, as pequenas diferenças no conteúdo são avaliadas como valores nitidamente diferentes. Considere os seguintes exemplos:

• $filter=City eq 'Las Vegas' só devolverá documentos que contenham o texto "Las Vegas" exato e exclua documentos com "LAS VEGAS" e "las vegas", o que é inadequado quando o caso de uso requer todos os documentos, independentemente do invólucro.

• search=*&facet=City,count:5 vai voltar "Las Vegas", "LAS VEGAS" e "las vegas" como valores distintos apesar de ser a mesma cidade.

• search=usa&$orderby=Cityretornará as cidades em ordem lexicográfica: , , , mesmo que a intenção seja ordenar as mesmas cidades juntas, "Las Vegas""Seattle""las vegas"independentemente do caso.

Um normalizador, que é invocado durante a indexação e a execução da consulta, adiciona ligeiras transformações que atenuam diferenças mínimas no texto para cenários de filtro, faceta e classificação. Nos exemplos anteriores, as variantes de seriam processadas de "Las Vegas" acordo com o normalizador selecionado (por exemplo, todo o texto é minúsculo) para obter resultados mais uniformes.

Como especificar um normalizador

Os normalizadores são especificados em uma definição de índice, por campo, em campos de texto (Edm.String e Collection(Edm.String)) que têm pelo menos uma das propriedades "filtrável", "classificável" ou "facetável" definidas como true. A configuração de um normalizador é opcional e é nula por padrão. É recomendável avaliar os normalizadores predefinidos antes de configurar um personalizado.

Os normalizadores só podem ser especificados quando você adiciona um novo campo ao índice. Portanto, se possível, tente avaliar as necessidades de normalização antecipadamente e atribuir os normalizadores nos estágios iniciais de desenvolvimento, quando é comum descartar e recriar índices.

1. Ao criar uma definição de campo no índice, defina a propriedade "normalizador" como um dos seguintes valores: um normalizador predefinido, como "minúsculas", ou um normalizador personalizado (definido no mesmo esquema de índice).

   "fields": [
    {
      "name": "Description",
      "type": "Edm.String",
      "retrievable": true,
      "searchable": true,
      "filterable": true,
      "analyzer": "en.microsoft",
      "normalizer": "lowercase"
      ...
    }
   ]
   

2. Primeiro, os normalizadores personalizados são definidos na seção "normalizadores" do índice. Em seguida, são atribuídos à definição de campo, conforme mostrado na etapa anterior. Para saber mais, confira Criar Índice e também Adicionar Normalizadores Personalizados.

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

Observação

Para alterar o normalizador de um campo existente, recrie o índice inteiramente (não é possível recriar campos individuais).

Uma boa solução para índices de produção, em que a recriação deles é dispendiosa, é criar um campo novo idêntico ao antigo com o novo normalizador e usá-lo em seu lugar. Use Atualizar índice para incorporar o novo campo e mergeOrUpload para populá-lo. Posteriormente, como parte da manutenção planejada do índice, será possível limpar o índice para remover campos obsoletos.

Normalizadores predefinidos e personalizados

O Azure AI Search tem normalizadores integrados para os casos de uso mais comuns, além de permitir a personalização quando necessário.

Categoria	Descrição
Normalizadores predefinidos	Fornecidos de forma integrada e podem ser usados sem nenhuma configuração.
Normalizadores personalizados1	Cenários avançados. Requer que o usuário defina uma combinação de elementos existentes, formada por filtros de caracteres e tokens.

⁽¹⁾ Normalizadores personalizados não especificam criadores de token, pois sempre produzem apenas um.

Referência de normalizadores

Normalizadores predefinidos

Nome	Descrição e opções
padrão	Deixa em letras minúsculas o texto seguido por asciifolding.
letras minúsculas	Transforma caracteres em letras minúsculas.
letras maiúsculas	Transforma caracteres em letras maiúsculas.
asciifolding	Transforma os caracteres que não estão no bloco Unicode latino básico em seu equivalente ASCII, se houver. Por exemplo, alterando à para a.
elision	Remove a elisão do início dos tokens.

Filtros de caracteres suportados

Os normalizadores são compatíveis com dois filtros de caracteres idênticos aos seus equivalentes em filtros de caracteres de analisador personalizado:

• mapeamento
• pattern_replace

Filtros de token suportados

A lista a seguir mostra os filtros de token compatíveis com normalizadores e é um subconjunto dos filtros de token gerais usados nos analisadores personalizados.

• arabic_normalization
• asciifolding
• cjk_width
• elision
• german_normalization
• hindi_normalization
• indic_normalization
• persian_normalization
• scandinavian_normalization
• scandinavian_folding
• sorani_normalization
• lowercase
• uppercase

Adicionar normalizadores personalizados

Os normalizadores personalizados são definidos dentro do esquema de índice. A definição inclui nome, tipo, um ou mais filtros de caractere e filtros de token. Os filtros de caracteres e de token são os elementos básicos de um normalizador personalizado. Eles são responsáveis pelo processamento do texto e aplicados da esquerda para a direita.

token_filter_name_1 é o nome do filtro de token; char_filter_name_1 e char_filter_name_2 são nomes de filtros de caracteres (confira as tabelas de filtros de token compatíveis e filtros de caracteres compatíveisabaixo para ver os valores válidos).

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

Os normalizadores personalizados podem ser adicionados durante a criação do índice ou depois atualizando um existente. Para adicionar um normalizador personalizado a um índice existente, é preciso especificar o sinalizador "allowIndexDowntime" em Atualizar índice, o que deixa o índice indisponível por alguns segundos.

Exemplo de normalizador personalizado

O exemplo a seguir ilustra uma definição de normalizador personalizado com filtros de caractere e de token correspondentes. Opções personalizadas para filtros de caracteres e de token são especificadas separadamente como constructos nomeados e, depois, referenciadas na definição do normalizador, como ilustrado abaixo.

• Um normalizador personalizado, "my_custom_normalizer", é definido na seção "normalizadores" da definição do índice.

• O normalizador é composto de dois filtros de caracteres e três filtros de token: elisão, letras minúsculas e filtro asciifolding personalizado "my_asciifolding".

• O primeiro filtro de caracteres, "map_dash", substitui todos os hifens pelo caractere de sublinhado, enquanto o segundo, "remove_whitespace", remove todos os espaços.

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

Confira também

• Conceitos dos conjunto de habilidades no Azure AI Search

• Analisadores para processamento linguístico e de texto

• API REST para pesquisar documentos