Elasticsearch:Configure and use synonyms

Em cenários de busca, usuários frequentemente utilizam palavras diferentes para expressar o mesmo conceito, como "celular" e "smartphone". Isso pode resultar em resultados incompletos. O recurso de sinônimos resolve esse problema ao tratar esses termos como equivalentes, ampliando o escopo da pesquisa, melhorando a taxa de recall e aprimorando a experiência do usuário.

Antes de começar

Antes de alterar um arquivo de sinônimos, verifique os seguintes pontos:

• Garanta que os índices críticos tenham pelo menos um shard réplica para manter a disponibilidade do serviço durante a reinicialização de um único nó. (A exclusão de um dicionário aciona a reinicialização do cluster.)

• Monitore o cluster para assegurar que sua carga esteja em um nível saudável (recomendado: uso de CPU < 60%, uso de memória heap < 50%).

  Conecte-se ao cluster e execute GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem.heap_* para verificar o uso de CPU e memória heap de todos os nós.

Funcionamento e critérios de escolha

Este guia compara os dois métodos de configuração de sinônimos e suas contrapartidas para ajudar você a selecionar a melhor abordagem para suas necessidades.

Regras de sintaxe de sinônimos

O arquivo de sinônimos deve ser um arquivo .txt codificado em UTF-8. Cada linha define uma regra de sinônimo em um dos dois formatos a seguir:

• Sinônimos equivalentes (formato Solr)Termos separados por vírgulas são tratados como totalmente equivalentes. Uma busca por um termo corresponde a documentos que contenham qualquer termo do grupo.

  # Example: Searches for "phone", "smartphone", and "mobile phone" yield the same results.
  phone,smartphone,mobile phone
  ipod,i-pod,i pod

• Mapeamento direcional (formato WordNet)Use => para mapear um conjunto de termos para um único termo canônico. Esse formato é frequente em normalizações, nas quais termos não padronizados são mapeados para um termo preferencial.

  # Example: Map "usa" and "us" to "United States".
  usa,us => United States

Comparação dos métodos de configuração

É possível configurar sinônimos fazendo upload de um arquivo ou definindo-os inline na configuração do índice. A tabela a seguir compara esses dois métodos.

Procedimento

Método 1: Fazer upload de um arquivo de sinônimos (reutilizável)

Esta abordagem é mais adequada para dicionários com alterações pouco frequentes.

Etapa 1: Fazer upload do arquivo de sinônimos

Este exemplo demonstra como configurar sinônimos usando um filtro com um arquivo de teste chamado aliyun_synonyms.txt, que contém a entrada: begin, start.

1. Faça logon no console do Alibaba Cloud Elasticsearch. Selecione a região e o grupo de recursos onde sua instância está localizada e clique em ID da instância de destino.

2. No painel de navegação à esquerda, escolha Configuration and Management > Cluster Configuration. Na seção Basic Configuration, localize Synonym Configuration e clique em Upload.

3. No painel exibido, clique em Configure e selecione um método de upload:

   O arquivo deve ter a extensão .txt. O nome do arquivo pode conter letras maiúsculas, minúsculas, dígitos e sublinhados (_), e não deve exceder 30 caracteres.

   • Upload File: Selecione o arquivo .txt de sinônimos em sua máquina local.

   • Add OSS File: Insira o nome do bucket e o nome do arquivo de sinônimos e clique em Add.

     Limitação: O bucket do OSS deve estar na mesma região da instância do Alibaba Cloud Elasticsearch.

4. Clique em Save e confirme a operação.

Etapa 2: Criar um índice e referenciar o arquivo

Aguarde até que a instância retorne ao status Active. Em seguida, conecte-se ao cluster e crie um índice que utilize o arquivo de sinônimos enviado.

PUT /aliyun-index-test
{
  "settings": {
    "index":{
      "analysis": {
          "analyzer": {
            "by_smart": {
              "type": "custom",
              "tokenizer": "ik_smart",
              "filter": ["by_tfr","by_sfr"],
              "char_filter": ["by_cfr"]
            },
            "by_max_word": {
              "type": "custom",
              "tokenizer": "ik_max_word",
              "filter": ["by_tfr","by_sfr"],
              "char_filter": ["by_cfr"]
            }
         },
         "filter": {
            "by_tfr": {
              "type": "stop",
              "stopwords": [" "]
              },
           "by_sfr": {
              "type": "synonym",
              "synonyms_path": "analysis/aliyun_synonyms.txt"
              }
          },
          "char_filter": {
            "by_cfr": {
              "type": "mapping",
              "mappings": ["| => |"]
            }
          }
      }
    }
  }
}

A sintaxe para criação de índices varia conforme a versão do cluster. Para mais informações, consulte Exemplos de operações de índice para versões comuns do Elasticsearch .

Etapa 3: Configurar o campo title

• Para versões do Elasticsearch anteriores à 7,0

  PUT /aliyun-index-test/_mapping/doc
  {
  "properties": {
   "title": {
     "type": "text",
     "analyzer": "by_max_word",
     "search_analyzer": "by_smart"
   }
  }
  }

• Para Elasticsearch 7,0 e posteriores

  PUT /aliyun-index-test/_mapping/
  {
  "properties": {
   "title": {
     "type": "text",
     "analyzer": "by_max_word",
     "search_analyzer": "by_smart"
   }
  }
  }

Etapa 4: Verificar a configuração

Use a API _analyze para confirmar se o analisador carregou corretamente os sinônimos. Este exemplo pressupõe que o arquivo de sinônimos contenha begin,start.

GET /aliyun-index-test/_analyze
{
"analyzer": "by_smart",
"text":"begin"
}

Uma resposta bem-sucedida inclui tanto os tokens begin quanto start.

{
  "tokens" : [
    {
      "token" : "begin",
      "start_offset" : 0,
      "end_offset" : 5,
      "type" : "ENGLISH",
      "position" : 0
    },
    {
      "token" : "start",
      "start_offset" : 0,
      "end_offset" : 5,
      "type" : "SYNONYM",
      "position" : 0
    }
  ]
}

Etapa 5: Testar os resultados da busca

1. Indexe dois documentos, cada um contendo um dos termos sinônimos.

   PUT /aliyun-index-test/doc/1
   {
   "title": "Shall I begin?"
   }

   PUT /aliyun-index-test/doc/2
   {
   "title": "I start work at nine."
   }

2. Pesquise por um dos termos, como begin. A busca retornará documentos que contenham tanto begin quanto start.

   GET /aliyun-index-test/_search
   {
    "query" : { "match" : { "title" : "begin" }},
    "highlight" : {
        "pre_tags" : ["<red>", "<blue>"],
        "post_tags" : ["</red>", "</blue>"],
        "fields" : {
            "title" : {}
        }
    }
   }

   Resposta:

   {
     "took" : 70,
     "timed_out" : false,
     "_shards" : {
       "total" : 1,
       "successful" : 1,
       "skipped" : 0,
       "failed" : 0
     },
     "hits" : {
       "total" : {
         "value" : 2,
         "relation" : "eq"
       },
       "max_score" : 0.28247005,
       "hits" : [
         {
           "_index" : "aliyun-index-test",
           "_type" : "_doc",
           "_id" : "1",
           "_score" : 0.28247005,
           "_source" : {
             "title" : "Shall I begin?"
           },
           "highlight" : {
             "title" : [
               "Shall I <red>begin</red>?"
             ]
           }
         },
         {
           "_index" : "aliyun-index-test",
           "_type" : "_doc",
           "_id" : "2",
           "_score" : 0.25069216,
           "_source" : {
             "title" : "I start work at nine."
           },
           "highlight" : {
             "title" : [
               "I <red>start</red> work at nine."
             ]
           }
         }
       ]
     }
   }
   

Método 2: Configurar inline (não reutilizável)

Este método consiste em escrever as regras de sinônimo diretamente na configuração do índice. É ideal para dicionários pequenos que exigem atualizações frequentes.

Etapa 1: Criar um índice e definir sinônimos

Conecte-se ao cluster e defina as regras de sinônimo diretamente no array synonyms ao criar o índice.

PUT /my_index
{
 "settings": {
     "analysis": {
         "analyzer": {
             "my_synonyms": {
                 "filter": [
                     "lowercase",
                     "my_synonym_filter"
                 ],
                 "tokenizer": "ik_smart"
             }
         },
         "filter": {
             "my_synonym_filter": {
                 "synonyms": [
                     "begin,start"
                 ],
                 "type": "synonym"
             }
         }
     }
 }
}

Este comando cria um índice chamado my_index e configura uma análise de texto personalizada. Funcionamento: Quando um campo de texto usa o analisador my_synonyms, o tokenizador ik_smart divide o texto de entrada em tokens. O filtro lowercase converte todos os tokens para minúsculas. Por fim, o my_synonym_filter aplica as regras de sinônimo, tratando tokens como begin e start como equivalentes.

Etapa 2: Configurar o campo title

• Para versões do Elasticsearch anteriores à 7,0

  PUT /my_index/_mapping/doc
  {
  "properties": {
   "title": {
     "type": "text",
     "analyzer": "my_synonyms"
   }
  }
  }

• Para Elasticsearch 7,0 e posteriores

  PUT /my_index/_mapping/
  {
  "properties": {
   "title": {
     "type": "text",
     "analyzer": "my_synonyms"
   }
  }
  }

Etapa 3: Verificar a configuração

GET /my_index/_analyze
{
 "analyzer":"my_synonyms",
 "text":"Shall I begin?"
}

Resposta:

{
  "tokens" : [
    {
      "token" : "shall",
      "start_offset" : 0,
      "end_offset" : 5,
      "type" : "ENGLISH",
      "position" : 0
    },
    {
      "token" : "i",
      "start_offset" : 6,
      "end_offset" : 7,
      "type" : "ENGLISH",
      "position" : 1
    },
    {
      "token" : "begin",
      "start_offset" : 8,
      "end_offset" : 13,
      "type" : "ENGLISH",
      "position" : 2
    },
    {
      "token" : "start",
      "start_offset" : 8,
      "end_offset" : 13,
      "type" : "SYNONYM",
      "position" : 2
    }
  ]
}

Impacto das operações de sinônimos

Diferentes operações com sinônimos causam impactos distintos no cluster. Compreender essas diferenças ajuda a escolher o método de atualização adequado aos seus requisitos de negócio.

Atualização incremental (hot update)

Ao fazer upload de um arquivo de sinônimos com o mesmo nome de um já existente, o sistema executa uma atualização incremental (hot update), que não aciona a reinicialização do cluster. O novo arquivo substitui o original, e quaisquer novos índices criados usarão automaticamente o dicionário atualizado.

Atualizações via console que acionam reinicialização do cluster

As operações a seguir acionam uma reinicialização gradual do cluster:

• Fazer upload de um arquivo de sinônimos com um novo nome e salvar a alteração.

• Excluir um arquivo de sinônimos existente e salvar a alteração.

Se o seu negócio exige evitar a reinicialização do cluster, recomendamos o uso do plugin elasticsearch-analysis-dynamic-synonym para implementar atualizações dinâmicas.

Uma reinicialização gradual pode causar os seguintes efeitos:

• Instabilidade do serviço: Durante uma reinicialização gradual, em que os nós são reiniciados sequencialmente, pode ocorrer um aumento temporário na latência de consulta, mesmo que existam shards réplicas.

• Risco de interrupção do serviço: Em condições extremas, como alta carga do cluster ou índices sem shards réplicas, a reinicialização pode causar falhas em algumas solicitações ou levar a uma breve interrupção do serviço.

• Duração da reinicialização: O tempo total necessário para a reinicialização e distribuição do dicionário depende do tamanho do cluster, volume de dados e carga. O processo pode levar vários minutos ou mais.

Disponibilidade de leitura e gravação durante alterações

Após enviar uma configuração de sinônimos, o status da instância muda para taking effect. Durante esse período:

• As operações de leitura e gravação da instância não são afetadas e permanecem disponíveis.

• O recurso de expansão de sinônimos fica temporariamente indisponível, e consultas de busca que dependam das novas regras de sinônimo podem retornar resultados incompletos.

• Depois que as alterações entram em vigor, o status da instância retorna a Active, e os índices recém-criados usam automaticamente o dicionário de sinônimos atualizado.

Perguntas frequentes

Solução de problemas de status Yellow ou alterações travadas

Se o status do cluster mudar para Yellow ou se alterações subsequentes forem bloqueadas após configurar ou atualizar sinônimos, verifique as causas comuns abaixo:

• Arquivo de sinônimos formatado incorretamente: O arquivo contém letras maiúsculas, o que causa falha no analisador durante o parsing.

• Erro no OpenStorePlugin: Conteúdo anômalo no arquivo de sinônimos dispara um erro no OpenStorePlugin. Isso impede a alocação correta dos shards, torna o status do cluster anormal e bloqueia alterações subsequentes.

Para solucionar e resolver esse problema, execute as etapas a seguir:

1. Verifique e corrija o arquivo de sinônimos: Assegure-se de que todas as palavras no arquivo estejam em minúsculas. Após as correções, faça o upload do arquivo novamente.

2. Adicione um filtro lowercase: Na configuração de filtros do analisador nas definições do índice, adicione um filtro lowercase para garantir que os tokens sejam convertidos automaticamente para minúsculas durante a análise. Exemplo de configuração:

   "filter": {
     "my_synonym_filter": {
       "type": "synonym",
       "synonyms_path": "analysis/your-dict-name.txt"
     }
   },
   "analyzer": {
     "my_synonyms": {
       "filter": ["lowercase", "my_synonym_filter"],
       "tokenizer": "ik_smart"
     }
   }

3. Recupere um índice inoperante: Se modificar o filtro do analisador exigir fechar ou reconstruir um índice em ambiente de produção, ou se essa modificação não for viável nesse ambiente, tente restaurar o status do cluster forçando a realocação de shards:

   POST /_cluster/reroute?retry_failed=true

Riscos do plugin analysis-dynamic-synonym

O plugin open-source analysis-dynamic-synonym permite carregar sinônimos dinamicamente a partir de um arquivo remoto ou local, aplicando novas regras sem reiniciar o cluster. No entanto, este plugin apresenta os seguintes riscos conhecidos:

• Defeito de concorrência: Em cenários de leitura e gravação com alta concorrência, este plugin pode causar deadlock no processo do Elasticsearch, levando a 100% de uso de CPU e indisponibilidade do serviço.

• Limitações de caso de uso: Utilize este plugin com cautela em instâncias Serverless ou em ambientes de produção com requisitos rigorosos de estabilidade. Antes de ativá-lo, recomendamos avaliar completamente sua estabilidade sob suas cargas reais de consulta e gravação em um ambiente de teste. Se os sinônimos não forem atualizados frequentemente, prefira o método de atualização incremental (upload de arquivo com o mesmo nome) para evitar riscos potenciais de plugins de terceiros.