Recherche plein texte en chinois avec pg_jieba dans ServBay

Vue d’ensemble

Pour les langues comme l’anglais, la fonctionnalité de recherche plein texte intégrée à PostgreSQL fonctionne efficacement grâce à une analyse lexicale basée sur les espaces et la ponctuation. Le chinois, en revanche, ne dispose pas d’espaces naturels pour séparer les mots : il faut donc utiliser un outil de segmentation spécialisé capable de découper les suites de caractères chinois en mots porteurs de sens.

pg_jieba est une extension tierce pour PostgreSQL qui intègre la populaire bibliothèque de segmentation Jieba. Avec pg_jieba, il est possible d’effectuer une segmentation efficace et précise des textes chinois dans PostgreSQL et ainsi d’implémenter une fonction de recherche plein texte puissante.

ServBay, un environnement intégré de développement web local, inclut déjà l’extension pg_jieba prête à l’emploi. Il n’est donc plus nécessaire de se préoccuper de la compilation ou de l’installation, ce qui vous permet de commencer rapidement à développer et tester la recherche plein texte chinoise en local.

Ce guide vous explique comment activer, configurer et utiliser l’extension pg_jieba dans ServBay.

Prérequis

Avant d’utiliser pg_jieba, assurez-vous d’avoir :

1. Installé ServBay sous macOS avec une instance PostgreSQL démarrée et opérationnelle.
2. Une connaissance de base de PostgreSQL, notamment la connexion à une base de données et l’exécution de requêtes SQL.

Installer et activer pg_jieba

ServBay intègre l’extension pg_jieba avec PostgreSQL. Vous n’avez rien à télécharger ou compiler : il vous suffit de lancer quelques commandes SQL pour l’activer dans la base ciblée.

Voici comment l’activer :

1. Connectez-vous à votre base de données PostgreSQL :
   Ouvrez le Terminal et connectez-vous grâce à l’outil en ligne de commande psql. Remplacez your_username et your_database par vos propres identifiants. Par défaut, ServBay utilise généralement l’utilisateur et la base servbay ou postgres.

   psql -U your_username -d your_database

   Exemple avec les paramètres par défaut :

   psql -U servbay -d servbay

2. Créer et activer l’extension pg_jieba :
   Depuis l’interface psql, exécutez :

   CREATE EXTENSION pg_jieba;

   Si l’extension existe déjà, cette commande retournera une erreur bénigne.

3. Vérifier que l’extension est bien active :
   Listez les extensions installées avec :

   \dx

   Si pg_jieba apparaît, l’activation est réussie.

Configurer pg_jieba pour la recherche plein texte en chinois

Après avoir activé pg_jieba, configurez la recherche textuelle de PostgreSQL pour utiliser ce module de segmentation.

Créer une configuration de recherche dédiée

La configuration de recherche définit comment les documents sont traités pour la recherche plein texte : quel parseur utiliser et comment gérer les différents types de tokens.

1. Créer une configuration nommée chinese utilisant pg_jieba comme parseur :

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);

   Ainsi, PostgreSQL utilisera pg_jieba lors du traitement du texte.

2. Ajouter un mapping pour les résultats de la segmentation :
   Le parseur pg_jieba génère des tokens selon leur nature grammaticale. Pour que ces tokens soient indexés et recherchés, affectez-les à un dictionnaire. Ici, nous associons les catégories principales (n pour nom, v pour verbe, a pour adjectif, etc.) au dictionnaire intégré simple, qui ne fait aucune transformation, mais conserve directement l’output de pg_jieba.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;

   Ces codes (n,v,a,i,e,l) sont les tags que pg_jieba peut assigner :

   • n : nom
   • v : verbe
   • a : adjectif
   • i : idiome
   • e : interjection
   • l : expression figée
   • nr : nom de personne
   • ns : nom de lieu
   • nt : organisation
   • nz : nom propre
   • m : numéral
   • q : classificateur
   • t : mot de temps
   • s : localisateur
   • f : orientation
   • p : préposition
   • c : conjonction
   • u : particule
   • xc : autre particule
   • w : ponctuation
   • eng : anglais
   • x : mot inclassable

   En général, seuls les mots porteurs de signification (noms, verbes, adjectifs…) sont indexés et recherchés.

Exemples de recherche plein texte avec pg_jieba

Une fois la configuration en place, vous pouvez utiliser pg_jieba pour effectuer des recherches sur du contenu chinois.

Création d’une table d’exemple

Commençons par créer une table simple et y insérer quelques entrées avec du texte chinois.

1. Créer la table :

   CREATE TABLE documents (
       id SERIAL PRIMARY KEY,
       content TEXT
   );

2. Insérer des données d’exemple :

   INSERT INTO documents (content) VALUES
   ('我爱自然语言处理技术'),
   ('中文分词是文本处理的重要步骤'),
   ('pg_jieba是一个很好的中文分词工具，它基于结巴分词库'),
   ('ServBay 让本地开发变得简单高效');

Créer un index pour la recherche plein texte

Pour des performances optimales, surtout avec de gros volumes, créez un index sur la colonne concernée grâce au type d’index GIN (Generalized Inverted Index), particulièrement adapté à la recherche plein texte sous PostgreSQL.

1. Créer l’index GIN sur la colonne content :
   Utilisez la fonction to_tsvector avec la configuration chinese précédemment définie. La conversion produit un champ tsvector employé en interne par PostgreSQL pour la recherche.

   CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));

Effectuer des recherches plein texte

Avec la fonction to_tsquery et l’opérateur @@, vous pouvez lancer des requêtes plein texte :
to_tsquery('chinese', 'votre requête') convertit votre recherche selon la configuration chinoise, et @@ teste la correspondance.

1. Exemple de recherche :
   Chercher les documents contenant simultanément les mots “中文” et “分词” :

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   Ici, le symbole & désigne l’opérateur logique ET dans la syntaxe tsquery.
   Utilisez | pour OU logique, et ! pour la négation.

   Par exemple, chercher “ServBay” ou “开发” :

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay | 开发');

Utilisation d’un dictionnaire personnalisé

Par défaut, pg_jieba s’appuie sur le dictionnaire standard de Jieba. Dans certains cas (terminologie métier, noms de produits…), un dictionnaire personnalisé permet d’améliorer la précision de la segmentation.

Vous pouvez créer un fichier dictionnaire et configurer pg_jieba pour qu’il le prenne en compte.

Ajouter des mots personnalisés

1. Créer un fichier dictionnaire :
   Placez un fichier texte (ex. : custom_dict.txt) dans le répertoire de configuration de ServBay :

   /Applications/ServBay/etc/pg_jieba/custom_dict.txt

   Cette localisation n’est qu’un exemple : adaptez-la à l’organisation réelle de vos fichiers ServBay.

2. Ajouter des entrées dans le dictionnaire :
   Avec un éditeur de texte, ajoutez chaque mot sur une nouvelle ligne. Vous pouvez indiquer optionnellement une fréquence (frequency) et une catégorie grammaticale (tag), séparés par des espaces. Format : mot [fréquence [catégorie]].

   自然语言处理 3 n
   ServBay 5 eng
   结巴分词库 3 n

   Ici, “自然语言处理” a une fréquence de 3 et la catégorie “nom” (n) ; “ServBay” a une fréquence de 5 et la catégorie anglaise “eng”.

3. Configurer pg_jieba pour utiliser ce dictionnaire :
   Lors d’une session PostgreSQL, définissez le paramètre pg_jieba.dict_path sur le dossier contenant votre fichier dictionnaire.
   Remarque : pg_jieba.dict_path référence le dossier et non le fichier lui-même. Si votre fichier personnalisé se trouve dans le même répertoire que le principal ou dans celui renseigné dans la configuration de pg_jieba, il n’est pas forcément nécessaire de le modifier, ou ServBay peut être livré avec une configuration spécifique. Consultez la documentation ServBay ou faites des tests pour déterminer la valeur correcte.

   Si votre configuration le permet, vous pouvez aussi pointer directement sur un fichier (comportement non standard, à vérifier selon la version de ServBay) :

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- Supposant que le dictionnaire principal et custom_dict.txt sont dans ce dossier

   ou, si l’extension accepte un fichier unique :

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- À utiliser avec précaution et vérifier la configuration ServBay

   Important : La commande SET ne s’applique qu’à la session en cours. Pour la rendre permanente, modifiez le fichier de configuration PostgreSQL (postgresql.conf) et précisez-y le chemin souhaité pour pg_jieba.dict_path.

Recharger le dictionnaire

Après modification du dictionnaire ou du paramètre dict_path, rechargez le dictionnaire pour prendre en compte les changements.

1. Recharger la configuration :

   SELECT jieba_reload_dict();

   Après exécution, les nouvelles entrées seront utilisables lors des prochaines segmentations.

Foire aux questions (FAQ)

• Pourquoi l’erreur "extension 'pg_jieba' is not available" s’affiche-t-elle lors de CREATE EXTENSION pg_jieba; ?
  Cette erreur signifie généralement que l’extension n’est pas installée ou que PostgreSQL ne la localise pas correctement. Dans ServBay, l’extension est en principe préinstallée. Vérifiez que vous êtes bien connecté à l’instance PostgreSQL de ServBay et que l’installation est intacte. En cas de problème persistant, essayez de redémarrer ServBay ou consultez les logs pour plus d’informations.

• Pourquoi mon dictionnaire personnalisé n’est-il pas pris en compte ?
  Veuillez vérifier les points suivants :

  1. Chemin du fichier : est-il correct ? L’utilisateur de PostgreSQL a-t-il les droits de lecture ?
  2. Format du dictionnaire respecté : un mot par ligne, fréquence et tag optionnels séparés par des espaces.
  3. Le paramètre pg_jieba.dict_path a-t-il été correctement défini ? Rappel : la commande SET n’est valable que pour la session ; pour une persistance, modifiez postgresql.conf.
  4. Avez-vous exécuté SELECT jieba_reload_dict(); pour recharger le dictionnaire ?
  5. Si vous avez changé postgresql.conf, PostgreSQL a-t-il été redémarré ?

• Les résultats de la recherche ne sont pas corrects, que faire ?
  L’exactitude dépend de la segmentation et de la requête.

  1. Vérifiez la segmentation avec : ts_debug('chinese', 'votre texte') pour visualiser comment pg_jieba segmente et si le dictionnaire personnalisé est pris en compte.
  2. Optimisez la configuration de segmentation avec la commande ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple; en n’incluant que les types linguistiques utiles.
  3. Adaptez votre requête — vérifiez les mots-clés et les opérateurs logiques (&, |, !).

Conclusion

pg_jieba offre une solution puissante pour implémenter la recherche plein texte en chinois avec PostgreSQL. Grâce à sa préinstallation dans ServBay, les développeurs peuvent facilement activer et configurer le découpage linguistique pour des applications locales. Cette documentation vous a présenté les étapes d’installation de pg_jieba, la création et la configuration d’une recherche textuelle, l’utilisation des requêtes de base ainsi que les moyens d’étendre la segmentation avec des dictionnaires personnalisés. Intégrez ces techniques à vos projets pour optimiser la recherche dans vos contenus en chinois.