Adicionar analisadores personalizados a campos de cadeia de caracteres em um índice da IA do Azure Search

Um analisador personalizado é uma combinação definida pelo usuário de um indexador, um ou mais filtros de token e um ou mais filtros de caracteres. Um analisador personalizado é especificado em um índice de pesquisa e, em seguida, referenciado por nome nas definições de campo que exigem análise personalizada. Um analisador personalizado é invocado por campo. Os atributos no campo determinarão se ele é usado para indexação, consultas ou ambos.

Em um analisador personalizado, os filtros de caracteres preparam o texto de entrada antes de ser processado pelo gerador de token (por exemplo, removendo a marcação). Em seguida, o gerador de token divide o texto em tokens. Por fim, os filtros de token modificam os tokens emitidos pelo gerador de token. Para obter conceitos e exemplos, consulte Analisadores na IA do Azure Search.

Por que usar um analisador personalizado?

Um analisador personalizado oferece controle sobre o processo de conversão de texto em tokens indexáveis e pesquisáveis, permitindo que você escolha quais tipos de análise ou filtragem devem ser invocados e a ordem na qual ocorrem.

Crie e atribua um analisador personalizado se nenhum dos analisadores padrão (padrão Lucence), internos ou de linguagem forem suficientes para suas necessidades. Você também pode criar um analisador personalizado se quiser usar um analisador interno com opções personalizadas. Por exemplo, se desejasse alterar o maxTokenLength no padrão, você criaria um analisador personalizado, com um nome definido pelo usuário, para definir essa opção.

Os cenários em que os analisadores personalizados podem ser úteis incluem:

• Usar filtros de caracteres para remover a marcação HTML antes que as entradas de texto sejam tokenizadas ou substituir determinados caracteres ou símbolos.

• Pesquisa fonética. Adicione um filtro fonético para permitir a pesquisa com base no som de uma palavra, e não na ortografia.

• Desabilitar análise léxica. Use o analisador de palavra-chave para criar campos de pesquisa que não são analisados.

• Pesquisa rápida de prefixo/sufixo. Adicione o filtro de token Edge N-gram para indexar prefixos de palavras a fim de habilitar a correspondência rápida de prefixo. Combine-a com o filtro de token Inverso para realizar a correspondência de sufixo.

• Criação de tokens personalizada. Por exemplo, use o criador de token Whitespace para dividir as frases em tokens usando o espaço em branco como um delimitador

• Folding ASCII. Adicione o filtro Folding ASCII padrão para normalizar diacríticos como ö ou ê em termos de pesquisa.

Criar um analisador personalizado

Para criar um analisador personalizado, especifique-o na seção analyzers de um índice no tempo de design e, em seguida, referencie-o em campos Edm.String pesquisáveis usando a propriedade analyzer ou o par indexAnalyzer e searchAnalyzer.

Uma definição de analisador inclui um nome, um tipo, um ou mais filtros de caracteres, um máximo de um criador de token e um ou mais filtros de token para processamento de pós-criação de token. Os filtros de caracteres são aplicados antes da criação de token. Filtros de token e filtros de caracteres são aplicados da esquerda para a direita.

• Os nomes em um analisador personalizado devem ser exclusivos e não podem ser iguais a nenhum dos analisadores, criadores de token, filtros de token ou filtros de caracteres internos. Deve conter apenas letras, números, espaços, traços ou sublinhados, pode começar e terminar apenas com caracteres alfanuméricos e está limitado a 128 caracteres.

• O tipo deve ser #Microsoft.Azure.Search.CustomAnalyzer.

• charFilters pode ser um ou mais filtros de Filtros de caracteres, processados antes de geração de tokens, na ordem fornecida. Alguns filtros de caracteres têm opções, que podem ser definidas em uma seção charFilters. Os filtros de caracteres são opcionais.

• tokenizer é exatamente um Gerador de token. É necessário um valor. Se precisar de mais de um criador de token, você pode criar vários analisadores personalizados e atribuí-los campo por campo em seu esquema de índice.

• tokenFilters pode ser um ou mais filtros de Filtros de tokens, processados antes da geração de tokens, na ordem fornecida. Para filtros de tokens que têm opções, adicione uma seção tokenFilter para especificar a configuração. Os filtros de tokens são opcionais.

Os analisadores não devem produzir tokens com mais de 300 caracteres ou haverá falha na indexação. Para cortar ou excluir tokens longos, use TruncateTokenFilter e LengthTokenFilter, respectivamente. Veja Filtros de tokens para referência.

"analyzers":(optional)[
   {
      "name":"name of analyzer",
      "@odata.type":"#Microsoft.Azure.Search.CustomAnalyzer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenizer":"tokenizer_name",
      "tokenFilters":[
         "token_filter_name_1",
         "token_filter_name_2"
      ]
   },
   {
      "name":"name of analyzer",
      "@odata.type":"#analyzer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name",
      "@odata.type":"#char_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenizers":(optional)[
   {
      "name":"tokenizer_name",
      "@odata.type":"#tokenizer_type",
      "option1":value1,
      "option2":value2,
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name",
      "@odata.type":"#token_filter_type",
      "option1":value1,
      "option2":value2,
      ...
   }
]

Dentro de uma definição de índice, você pode colocar essa seção em qualquer lugar no corpo de uma solicitação de criação de índice, mas geralmente ela ocorre no final:

{
  "name": "name_of_index",
  "fields": [ ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) { },
  "analyzers":(optional)[ ],
  "charFilters":(optional)[ ],
  "tokenizers":(optional)[ ],
  "tokenFilters":(optional)[ ]
}

A definição do analisador é uma parte do índice maior. As definições para filtros de caracteres, criadores de token e filtros de token serão adicionadas ao índice somente se você estiver definindo opções personalizadas. Para usar um filtro ou criador de token existente no estado em que ele se encontra, especifique-o por nome na definição do analisador. Para obter mais informações, veja Criar índice (REST). Para obter mais exemplos, consulte Adicionar analisadores na IA do Azure Search.

Testar analisadores personalizados

Você pode usar o Analisador de teste (REST) para ver como um analisador divide o texto em tokens.

Solicitação

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

  {
     "analyzer":"my_analyzer",
     "text": "Vis-à-vis means Opposite"
  }

Response

  {
    "tokens": [
      {
        "token": "vis_a_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "vis_à_vis",
        "startOffset": 0,
        "endOffset": 9,
        "position": 0
      },
      {
        "token": "means",
        "startOffset": 10,
        "endOffset": 15,
        "position": 1
      },
      {
        "token": "opposite",
        "startOffset": 16,
        "endOffset": 24,
        "position": 2
      }
    ]
  }

Atualizar analisadores personalizados

Depois que um analisador, um criador de token, um filtro de token ou um filtro de caractere é definido, ele não pode ser modificado. Outros novos poderão ser adicionados a um índice existente apenas se o sinalizador allowIndexDowntime estiver definido como true na solicitação de atualização de índice:

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Essa operação deixa seu índice offline por pelo menos alguns segundos, fazendo com que suas solicitações de indexação e de consulta falhem. O desempenho e a disponibilidade de gravação do índice podem ser prejudicados por vários minutos após o índice ser atualizado, ou por mais tempo em caso de índices muito grandes, mas esses efeitos são temporários e acabam se resolvendo sozinhos.

Analisadores internos

Se você quiser usar um analisador interno com opções personalizadas, a criação de um analisador personalizado é o mecanismo pelo qual você especifica essas opções. Por outro lado, para usar um analisador interno como está, basta fazer referência a ele pelo nome na definição de campo.

¹ Tipos do Analisador sempre são prefixados no código com #Microsoft.Azure.Search de modo que PatternAnalyzer de fato seja especificado como #Microsoft.Azure.Search.PatternAnalyzer. Removemos o prefixo para encurtar, mas ele é necessário em seu código.

O analyzer_type é fornecido apenas para analisadores que podem ser personalizados. Se não há opções, como é o caso do analisador de palavras-chave, não há nenhum tipo associado do #Microsoft.Azure.Search.

Filtros de caractere

Filtros de caracteres adicionam processamento antes que uma cadeia de caracteres atinja o criador de token.

A IA do Azure Search dá suporte a filtros de caracteres na lista a seguir. Mais informações sobre cada uma podem ser encontradas na referência da API Lucene.

¹ Tipos do filtro de char sempre são prefixados no código com #Microsoft.Azure.Search de modo que MappingCharFilter de fato seja especificado como #Microsoft.Azure.Search.MappingCharFilter. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo em seu código. Observe que char_filter_type é fornecido apenas para filtros que podem ser personalizados. Se não ha opções, como é o caso de html_strip, não há nenhum tipo associado do #Microsoft.Azure.Search.

Criadores de token

Um criador de token divide o texto contínuo em uma sequência de tokens, assim como quebrar uma frase em palavras ou uma palavra em formas raiz.

A IA do Azure Search dá suporte aos geradores de token na lista a seguir. Mais informações sobre cada uma podem ser encontradas na referência da API Lucene.

¹ Tipos do gerador de token sempre são prefixados no código com #Microsoft.Azure.Search de modo que ClassicTokenizer de fato seja especificado como #Microsoft.Azure.Search.ClassicTokenizer. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo em seu código. Observe que tokenizer_type é fornecido apenas para criadores de token que podem ser personalizados. Se não há opções, como é o caso do criador de token de letra, não há nenhum tipo associado do # Microsoft.Azure.Search.

Filtros de token

Um filtro de token é usado para filtrar ou modificar os tokens gerados por um criador de token. Por exemplo, você pode especificar um filtro de minúsculas que converte todos os caracteres em letras minúsculas. Você pode ter vários filtros de token em um analisador personalizado. Os filtros de token são executados na ordem em que estão listados.

Na tabela abaixo, os filtros de token que são implementados usando o Apache Lucene têm links para a documentação da API Lucene.

¹ Tipos de filtro de token sempre são prefixados no código com #Microsoft.Azure.Search de modo que ArabicNormalizationTokenFilter de fato seja especificado como #Microsoft.Azure.Search.ArabicNormalizationTokenFilter. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo em seu código.

Confira também

• APIs REST da IA do Azure Search
• Analisadores na IA do Azure Search (Exemplos)
• Criar Índice (REST)