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

Um analisador personalizado é uma combinação definida pelo usuário de um tokenizador, um ou mais filtros de token e um ou mais filtros de caracteres. Um analisador personalizado é especificado dentro de um índice de pesquisa e, em seguida, referenciado pelo nome em 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 que ele seja processado pelo tokenizador (por exemplo, removendo marcação). Em seguida, o tokenizador divide o texto em tokens. Finalmente, os filtros de token modificam os tokens emitidos pelo tokenizador. Para obter conceitos e exemplos, consulte Analisadores no Azure AI 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 invocar e a ordem em que eles ocorrem.

Crie e atribua um analisador personalizado se nenhum dos analisadores padrão (Standard Lucence), incorporados ou de idioma for suficiente para suas necessidades. Você também pode criar um analisador personalizado se quiser usar um analisador interno com opções personalizadas. Por exemplo, se você quisesse alterar o maxTokenLength no Standard, 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:

• Usando 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 em como uma palavra soa, não como ela está escrita.

• Desative a análise lexical. Use o Analisador de palavras-chave para criar campos pesquisáveis que não são analisados.

• Pesquisa rápida de prefixos/sufixos. Adicione o filtro de token Edge N-gram aos prefixos de índice de palavras para permitir a correspondência rápida de prefixos. Combine-o com o filtro de token reverso para fazer a correspondência de sufixos.

• Tokenização personalizada. Por exemplo, use o tokenizador de espaço em branco para dividir frases em tokens usando espaço em branco como delimitador

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

Criar um analisador personalizado

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

Uma definição de analisador inclui um nome, tipo, um ou mais filtros de caracteres, um máximo de um tokenizador e um ou mais filtros de token para processamento pós-tokenização. Os filtros de caracteres são aplicados antes da tokenização. 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 qualquer um dos analisadores, tokenizadores, filtros de token ou filtros de caracteres internos. Deve conter apenas letras, dígitos, espaços, traços ou sublinhados, só pode começar e terminar com caracteres alfanuméricos e está limitado a 128 caracteres.

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

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

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

• tokenFilters pode ser um ou mais filtros de Filtros de Token, processados após a tokenização, na ordem fornecida. Para filtros de token com opções, adicione uma tokenFilter seção para especificar a configuração. Os filtros de token são opcionais.

Os analisadores não devem produzir tokens com mais de 300 caracteres, ou a indexação falhará. Para cortar token longo ou excluí-los, use o TruncateTokenFilter e o LengthTokenFilter , respectivamente. Consulte Filtros de token 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 vai 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 char, tokenizadores e filtros de token são adicionadas ao índice somente se você estiver definindo opções personalizadas. Para usar um filtro ou tokenizador existente no estado em que se encontra, especifique-o pelo nome na definição do analisador. Para obter mais informações, consulte Criar índice (REST). Para obter mais exemplos, consulte Adicionar analisadores no Azure AI Search.

Testar analisadores personalizados

Você pode usar o Test Analyzer (REST) para ver como um analisador divide determinado texto em tokens.

Pedir

  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 tokenizador, um filtro de token ou um filtro de caracteres é definido, ele não pode ser modificado. Novos podem ser adicionados a um índice existente somente se o allowIndexDowntime sinalizador 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 coloca o índice offline por pelo menos alguns segundos, fazendo com que as solicitações de indexação e consulta falhem. O desempenho e a disponibilidade de gravação do índice podem ser prejudicados por vários minutos após a atualização do índice, ou por mais tempo para índices muito grandes, mas esses efeitos são temporários e, eventualmente, resolvem por conta própria.

Analisadores integrados

Se você quiser usar um analisador interno com opções personalizadas, criar um analisador personalizado é o mecanismo pelo qual você especifica essas opções. Por outro lado, para usar um analisador interno no estado em que se encontra, basta fazer referência a ele pelo nome na definição de campo.

1 Os tipos de analisador são sempre prefixados em código com #Microsoft.Azure.Search tal que PatternAnalyzer seria realmente especificado como #Microsoft.Azure.Search.PatternAnalyzer. Removemos o prefixo por brevidade, mas o prefixo é necessário no seu código.

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

Filtros de caracteres

Os filtros de caracteres adicionam processamento antes que uma cadeia de caracteres chegue ao tokenizador.

O Azure AI Search dá suporte a filtros de caracteres na lista a seguir. Mais informações sobre cada um deles podem ser encontradas na referência da API Lucene.

1 Os tipos de filtro Char são sempre prefixados em código com #Microsoft.Azure.Search tal que MappingCharFilter seria realmente especificado como #Microsoft.Azure.Search.MappingCharFilter. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo no seu código. Observe que char_filter_type é fornecido apenas para filtros que podem ser personalizados. Se não houver opções, como é o caso do html_strip, não haverá nenhum tipo #Microsoft.Azure.Search associado.

Tokenizadores

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

O Azure AI Search dá suporte a tokenizadores na lista a seguir. Mais informações sobre cada um deles podem ser encontradas na referência da API Lucene.

1 Os tipos de tokenizador são sempre prefixados em código com #Microsoft.Azure.Search tal que ClassicTokenizer seria realmente especificado como #Microsoft.Azure.Search.ClassicTokenizer. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo no seu código. Observe que tokenizer_type é fornecido apenas para tokenizadores que podem ser personalizados. Se não houver opções, como é o caso do tokenizador de letras, não haverá nenhum tipo #Microsoft.Azure.Search associado.

Filtros de token

Um filtro de token é usado para filtrar ou modificar os tokens gerados por um tokenizador. Por exemplo, você pode especificar um filtro minúsculo que converta todos os caracteres em 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 são listados.

Na tabela abaixo, os filtros de token implementados usando o Apache Lucene estão vinculados à documentação da API do Lucene.

1 Os tipos de filtro de token são sempre prefixados em código com #Microsoft.Azure.Search tal que ArabicNormalizationTokenFilter seria realmente especificado como #Microsoft.Azure.Search.ArabicNormalizationTokenFilter. Removemos o prefixo para reduzir a largura da tabela, mas lembre-se de incluí-lo no seu código.

Consulte também

• Azure AI Search REST APIs
• Analisadores no Azure AI Search (exemplos)
• Criar índice (REST)