Elasticsearch:Configurer et utiliser des synonymes

Dans les scénarios de recherche, les utilisateurs emploient souvent des termes différents pour exprimer un même concept, par exemple « téléphone portable » et « smartphone ». Cela peut entraîner des résultats de recherche incomplets. La fonctionnalité de synonymes remédie à ce problème en traitant ces termes comme équivalents, élargissant ainsi le périmètre de recherche, améliorant le taux de rappel et optimisant l'expérience utilisateur.

Avant de commencer

Avant de modifier un fichier de synonymes, vérifiez les points suivants :

• Assurez-vous que les index critiques disposent d'au moins un shard réplica afin de maintenir la disponibilité du service lors du redémarrage d'un nœud unique. (La suppression d'un dictionnaire déclenche un redémarrage du cluster.)

• Surveillez le cluster pour vous assurer que sa charge reste à un niveau sain (recommandé : utilisation du CPU < 60 %, utilisation de la mémoire heap < 50 %).

  Connectez-vous à votre cluster et exécutez GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem.heap_* pour vérifier l'utilisation du CPU et de la mémoire heap pour tous les nœuds.

Fonctionnement et prise de décision

Ce guide compare les deux méthodes de configuration des synonymes et leurs compromis afin de vous aider à choisir l'approche la plus adaptée à vos besoins.

Règles de syntaxe des synonymes

Un fichier de synonymes doit être un fichier .txt encodé en UTF-8. Chaque ligne du fichier définit une règle de synonyme selon l'un des deux formats suivants :

• Synonymes équivalents (format Solr) : les termes séparés par des virgules sont considérés comme entièrement équivalents. Une recherche sur l'un des termes renvoie les documents contenant n'importe quel terme du groupe.

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

• Mappage directionnel (format WordNet) : utilisez => pour mapper un ensemble de termes vers un terme canonique unique. Cette approche est souvent utilisée pour la normalisation, où les termes non standards sont mappés vers un terme préféré.

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

Comparaison des méthodes de configuration

Vous pouvez configurer les synonymes en téléchargeant un fichier ou en les définissant directement dans la configuration de l'index. Le tableau suivant compare ces deux méthodes.

Procédure

Méthode 1 : Télécharger un fichier de synonymes (réutilisable)

Cette méthode convient mieux aux dictionnaires qui changent rarement.

Étape 1 : Télécharger le fichier de synonymes

Cet exemple montre comment configurer des synonymes en utilisant un filtre avec un fichier test nommé aliyun_synonyms.txt, qui contient l'entrée : begin, start.

1. Connectez-vous à la console Alibaba Cloud Elasticsearch. Sélectionnez la région et le groupe de ressources où se trouve votre instance, puis cliquez sur l'ID de l'instance cible.

2. Dans le volet de navigation de gauche, choisissez Configuration and Management > Cluster Configuration. Dans la section Basic Configuration, repérez Synonym Configuration et cliquez sur Upload.

3. Dans le panneau qui s'affiche, cliquez sur Configure et sélectionnez une méthode de téléchargement :

   Le fichier doit avoir l'extension .txt. Le nom du fichier peut contenir des lettres majuscules, des lettres minuscules, des chiffres et des underscores (_), et ne doit pas dépasser 30 caractères.

   • Upload File : sélectionnez le fichier .txt de synonymes depuis votre machine locale.

   • Add OSS File : saisissez le nom du bucket et le nom du fichier de synonymes, puis cliquez sur Add.

     Limitation : le bucket OSS doit se trouver dans la même région que l'instance Alibaba Cloud Elasticsearch.

4. Cliquez sur Save et confirmez l'opération.

Étape 2 : Créer un index et référencer le fichier

Attendez que l'instance repasse à l'état Active. Ensuite, connectez-vous au cluster et créez un index qui utilise le fichier de synonymes téléchargé.

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": ["| => |"]
            }
          }
      }
    }
  }
}

La syntaxe de création d'un index varie selon la version du cluster. Pour plus d'informations, consultez Exemples d'opérations d'index pour les versions courantes d'Elasticsearch .

Étape 3 : Configurer le champ title

• Pour les versions d'Elasticsearch antérieures à 7,0

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

• Pour Elasticsearch 7,0 et versions ultérieures

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

Étape 4 : Vérifier la configuration

Utilisez l'API _analyze pour vérifier que l'analyseur a correctement chargé les synonymes. Cet exemple suppose que le fichier de synonymes contient begin,start.

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

Une réponse réussie inclut à la fois les jetons begin et 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
    }
  ]
}

Étape 5 : Tester les résultats de recherche

1. Indexez deux documents, chacun contenant l'un des termes synonymes.

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

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

2. Recherchez l'un des termes, par exemple begin. La recherche renvoie les documents contenant à la fois begin et start.

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

   Réponse :

   {
     "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éthode 2 : Configurer inline (non réutilisable)

Cette méthode consiste à écrire les règles de synonymes directement dans la configuration de l'index et convient mieux aux petits dictionnaires nécessitant des mises à jour fréquentes.

Étape 1 : Créer un index et définir les synonymes

Connectez-vous au cluster et définissez les règles de synonymes directement dans le tableau synonyms lors de la création de l'index.

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

Cette commande crée un index nommé my_index et configure une analyse de texte personnalisée. Voici comment cela fonctionne : lorsqu'un champ de texte utilise l'analyseur my_synonyms, le tokenizer ik_smart découpe le texte d'entrée en jetons. Le filtre lowercase convertit ensuite tous les jetons en minuscules. Enfin, le filtre my_synonym_filter applique les règles de synonymes, traitant les jetons comme begin et start comme équivalents.

Étape 2 : Configurer le champ title

• Pour les versions d'Elasticsearch antérieures à 7,0

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

• Pour Elasticsearch 7,0 et versions ultérieures

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

Étape 3 : Vérifier la configuration

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

Réponse :

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

Impact des opérations sur les synonymes

Les différentes opérations liées aux synonymes ont des impacts variés sur un cluster. Comprendre ces différences vous aide à choisir la méthode de mise à jour adaptée à vos exigences métier.

Mise à jour incrémentielle (mise à jour à chaud)

Lorsque vous téléchargez un fichier de synonymes portant le même nom qu'un fichier existant, le système effectue une mise à jour incrémentielle (mise à jour à chaud), qui ne déclenche pas de redémarrage du cluster. Le nouveau fichier écrase l'original et tous les nouveaux index que vous créez utilisent automatiquement le dictionnaire mis à jour.

Mises à jour depuis la console déclenchant un redémarrage du cluster

Les opérations suivantes déclenchent un redémarrage progressif du cluster :

• Téléchargement d'un fichier de synonymes avec un nouveau nom et enregistrement de la modification.

• Suppression d'un fichier de synonymes existant et enregistrement de la modification.

Si votre activité nécessite d'éviter un redémarrage du cluster, nous vous recommandons d'utiliser le plugin elasticsearch-analysis-dynamic-synonym pour implémenter des mises à jour dynamiques.

Un redémarrage progressif peut avoir les effets suivants :

• Instabilité du service : lors d'un redémarrage progressif où les nœuds redémarrent séquentiellement, vous pouvez constater une augmentation temporaire de la latence des requêtes, même si vous disposez de shards réplicas.

• Risque d'interruption de service : dans des conditions extrêmes, telles qu'une charge élevée du cluster ou des index sans shards réplicas, un redémarrage peut entraîner l'échec de certaines requêtes ou provoquer une brève interruption de service.

• Durée du redémarrage : le temps total requis pour le redémarrage et la distribution du dictionnaire dépend de la taille du cluster, du volume de données et de la charge. Le processus peut prendre plusieurs minutes, voire plus.

Disponibilité en lecture et écriture pendant les modifications

Après avoir soumis une configuration de synonymes, le statut de l'instance passe à taking effect. Durant cette période :

• Les opérations de lecture et d'écriture sur l'instance ne sont pas affectées et restent disponibles.

• La fonctionnalité d'expansion par synonymes est temporairement indisponible et les requêtes de recherche s'appuyant sur les nouvelles règles de synonymes peuvent renvoyer des résultats incomplets.

• Une fois les modifications appliquées, le statut de l'instance revient à Active et les index nouvellement créés utilisent automatiquement le dictionnaire de synonymes mis à jour.

FAQ

Dépannage du statut Yellow ou des modifications bloquées

Si le statut du cluster passe à Yellow ou si les modifications suivantes sont bloquées après la configuration ou la mise à jour des synonymes, vérifiez les causes courantes suivantes :

• Fichier de synonymes mal formaté : le fichier contient des lettres majuscules, ce qui entraîne l'échec de l'analyseur lors de l'analyse.

• Erreur OpenStorePlugin : un contenu anormal dans le fichier de synonymes déclenche une erreur OpenStorePlugin. Cela empêche l'allocation correcte des shards, rend le statut du cluster anormal et bloque les modifications ultérieures.

Pour diagnostiquer et résoudre ce problème, suivez les étapes ci-dessous :

1. Vérifiez et corrigez le fichier de synonymes : assurez-vous que tous les mots du fichier sont en minuscules. Après correction, téléchargez à nouveau le fichier.

2. Ajoutez un filtre lowercase : dans la configuration des filtres de l'analyseur au sein des paramètres de l'index, ajoutez un filtre lowercase pour garantir que les jetons sont automatiquement convertis en minuscules lors de l'analyse. Exemple de configuration :

   "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. Récupérez un index non opérationnel : si la modification du filtre de l'analyseur nécessite la fermeture ou la reconstruction d'un index dans un environnement de production, ou si la modification de l'analyseur n'est pas réalisable en production, essayez de restaurer le statut du cluster en forçant la réallocation des shards :

   POST /_cluster/reroute?retry_failed=true

Risques liés au plugin analysis-dynamic-synonym

Le plugin open source analysis-dynamic-synonym permet de charger dynamiquement des synonymes depuis un fichier distant ou local, appliquant ainsi de nouvelles règles de synonymes sans redémarrer le cluster. Cependant, ce plugin présente les risques connus suivants :

• Défaut de concurrence : dans les scénarios de lecture et d'écriture à forte concurrence, ce plugin peut provoquer un interblocage (deadlock) dans le processus Elasticsearch, entraînant une utilisation du CPU à 100 % et l'indisponibilité du service.

• Limitations des cas d'utilisation : utilisez ce plugin avec prudence sur une instance Serverless ou dans des environnements de production exigeant une stabilité stricte. Avant de l'activer, nous vous recommandons d'évaluer pleinement sa stabilité sous vos charges réelles de requêtes et d'écriture dans un environnement de test. Si les synonymes ne sont pas mis à jour fréquemment, nous vous conseillons d'utiliser la méthode de mise à jour incrémentielle (téléchargement d'un fichier portant le même nom) afin d'éviter les risques potentiels liés aux plugins tiers.