ServBayでの中国語全文検索：zhparser利用ガイド

zhparserは、高性能な中国語テキスト処理のために設計された、PostgreSQL用の強力なサードパーティ拡張モジュールです。PostgreSQLデータベースに正確な中国語分かち書きと全文検索機能を提供し、中国語コンテンツの検索アプリケーション構築に最適な選択肢となります。ServBayはローカルWeb開発環境の決定版として、このzhparser拡張をプリインストール・サポートしており、さらに日本語テキスト処理でポピュラーなscws（Simple Chinese Word Segmentation）分かち書きエンジンも統合されています。zhparserはこのscwsを活用し、独自のカスタム辞書機能も実現します。

本記事では、ServBay環境でzhparserのインストール（有効化）と設定方法から、実際の中国語全文検索利用例、さらにServBay内蔵scwsによるカスタム辞書の作成・反映手順まで、詳しく解説します。

1. 概要

中国語テキストを大量に含むアプリケーション（CMS、フォーラム、ECサイトなど）で、効率的かつ高精度な全文検索は不可欠です。PostgreSQLには標準で全文検索機能がありますが、空白で単語区切りを前提とするため中国語への対応は不十分です。zhparser拡張は中国語分かち書き技術を組み込むことでこの課題を解消し、PostgreSQLが中国語テキストの適切な語彙区切りを理解し、有効な全文検索を実現できるようにします。

ServBayではzhparserがあらかじめ組み込まれているため、面倒なコンパイルやインストール作業なしで、すぐに中国語全文検索対応のローカル開発環境を構築できます。

2. 前提条件

zhparserを使用する前に、以下を確認してください：

ServBayが正しくインストールされていること
ServBayに含まれるPostgreSQLパッケージが有効化・起動済みであること（状態はServBayアプリUIで確認、管理可能）

3. zhparser拡張のインストール（有効化）

ServBayではzhparserモジュールファイルが既にPostgreSQLの適切なディレクトリに設置済みです。あとは、利用するデータベース上でSQLコマンドを実行して拡張を有効化するだけです。

PostgreSQLデータベースに接続 ターミナルを開き、psqlコマンドラインツールでServBayのPostgreSQLに接続します。servbay-demoには自分のユーザー名、your_database_nameには拡張有効化したいDB名を入力してください。
bash
```
psql -U servbay-demo -d your_database_name
```
1
デフォルトデータベース（通常はユーザー名と同じ）へ接続する場合は-dを省略できます。
zhparser拡張を作成psqlのプロンプトで次のSQLを実行します。
sql
```
CREATE EXTENSION zhparser;
```
1
正常終了時はエラー表示なし。既存の場合「すでに有効です」旨の表示が出ます。
zhparserのインストール確認 データベースにインストールされた拡張一覧は、次のコマンドで確認可能です：
sql
```
\dx
```
1
リスト中にzhparserとそのバージョン情報が含まれていればOKです。

4. zhparserの設定

zhparser有効化後は、PostgreSQLのテキスト検索機能が中国語分かち書きを理解できるように設定を行います。ここで重要な操作は「テキスト検索構成（Text Search Configuration）」を作ることです。

テキスト検索構成の作成 構成では、ドキュメントがtsvector（索引用）へどう変換されるか・クエリ文字列がtsquery（検索用）へどう変換されるかを定義します。ここではchineseという名称の構成を作成し、パーサーとしてzhparserを指定します。
sql
```
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
```
1
単語種別と辞書のマッピング追加 パーサー（zhparser）が切り出した各品詞（token）に対し、どの辞書（dictionary）で処理するか指定します。zhparserは単語を名詞（n）、動詞（v）、形容詞（a）などのラベルで分類します。ここでは、名詞・動詞・形容詞・独立語（i）・感情詞（e）・数量詞（l）などをsimple辞書にマップ。「simple」は最も基本的な辞書で、切り出した単語を変換せずそのまま使います。
sql
```
ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
-- 必要に応じてマッピングする品詞や辞書は追加・変更可能です。
```
1
2
注意：zhparserの品詞ラベルは、標準的なNLPのラベルと異なる場合があります。ここではよく使われるラベルを例示しています。

5. zhparserでの全文検索利用

設定が完了すれば、zhparserによる中国語全文検索が利用可能です。基本的な流れを例示します。

5.1 サンプルテーブルとデータの作成

まずは中国語テキストを格納するサンプルテーブルとテストデータを用意します。

テーブル作成

sql

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

サンプルデータ挿入

sql

INSERT INTO documents (content) VALUES
('我愛自然言語処理'),
('中国語分かち書きはテキスト処理の重要なステップです'),
('zhparserは非常に優れた中国語分解ツールです'),
('ServBayはローカル開発をより便利にします');

5.2 全文検索用インデックス作成

大規模データセットで検索性能を確保するため、検索対象カラムには全文検索用インデックスの作成がおすすめです。tsvector型にGIN（Generalized Inverted Index）索引を使うのが定番です。

GINインデックス作成contentカラム上に、to_tsvector('chinese', content)を使ったGINインデックスを作成します。これにより、先ほど作ったchineseテキスト検索構成（zhparserベース）の分かち書きで索引されます。
sql
```
CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));
```
1

5.3 全文検索クエリの実行

検索語句をto_tsqueryでクエリ化し、@@演算子でtsvectorカラムとマッチングします。

検索クエリの実行 たとえば「中国語」かつ「分かち書き」を含む文書を検索：
sql
```
SELECT
    id,
    content,
    to_tsvector('chinese', content) AS content_tsvector -- オプション：分かち書き結果の確認用
FROM documents
WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中国語 & 分かち書き');
```
1
2
3
4
5
6
このクエリではidが2・3の文書がヒットします。なぜなら、それらのcontentに「中国語」「分かち書き」両方が含まれるためです。
他のクエリ例：
- 「ServBay」を含む文書の検索
  sql
```
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay');
```
  1
  （id=4の文書がヒット）
- 「自然言語処理」を含む文書の検索
  sql
```
SELECT * FROM documents WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '自然言語処理');
```
  1
  （id=1がヒットします。なお、zhparserが「自然言語処理」を一語として分かち書きするか、細かく分かつかは辞書やモード設定に依存します。カスタム辞書で登録していれば確実です。）

6. ServBay内蔵scwsによるカスタム辞書の作成

ServBayはscwsライブラリを統合しており、zhparserはscws用の辞書ファイル（カスタム辞書含む）を利用できます。これにより分かち書き精度、特に専門用語や新語への対応能力を向上させることができます。

6.1 カスタム辞書ファイルの作成

カスタム辞書ファイルの作成・編集 推奨パスは/Applications/ServBay/etc/scws/ディレクトリ。custom_dict.txtというファイル（未作成なら新規作成）を用意します。
bash
```
# ターミナルでファイル作成・編集
nano /Applications/ServBay/etc/scws/custom_dict.txt
```
1
2
単語の記述custom_dict.txt内には、1行につき1単語（zhparserに独立語として認識させたい表現）を記述：
plaintext
```
自然言語処理
中国語分かち書き
ServBay
ローカル開発環境
```
1
2
3
4
保存してファイルを閉じます。

6.2 zhparserでカスタム辞書を指定

zhparserに上記辞書の場所を教えます。

zhparser.dict_pathパラメータの設定
PostgreSQLのセッション内でこのように実行：
sql
```
SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
-- 路径が正しいこと、PostgreSQLユーザーが読み取り可能であることを確認してください。
```
1
2
注意：SETでの指定は現セッションのみ有効。全接続に永続設定したい場合はpostgresql.confでzhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt'を記述し、PostgreSQLを再起動（ServBayアプリ画面から可）。開発/テスト用途ならSETで十分です。

6.3 辞書の再読み込み

辞書ファイル編集後は、zhparserに再読み込みさせて変更を反映する必要があります。

再読み込み用関数の呼び出し
sql
```
SELECT zhprs_reload_dict();
```
1
この実行後、以降の分かち書きには更新済み辞書が反映されます。

7. 分かち書きモードの調整

zhparserは分かち書き粒度などの調整パラメータも対応。なかでも主要なのがzhparser.seg_with_dualityです。

7.1 分かち書きモード設定

zhparser.seg_with_dualityパラメータの設定
- true指定：「二元分かち書き」モードを有効化。より細かな単語単位の分割となり、検索の網羅性（リコール）が向上します（例：「自然言語処理」が「自然」「言語」「処理」「自然言語」「言語処理」など複数に分割）。
  sql
```
SET zhparser.seg_with_duality = true;
```
  1
- false指定：より粗い分割となり、通常は辞書の最長一致で分割（例：「自然言語処理」がそのまま一語として分割される：辞書に登録済みの場合）。
  sql
```
SET zhparser.seg_with_duality = false;
```
  1
どちらを選ぶかは用途に応じて設定可能。このパラメータもpostgresql.confで全体設定できます。

8. よくある質問（FAQ）

Q: CREATE EXTENSION zhparser; で拡張が見つからない場合？ A: ServBayのPostgreSQLパッケージが正しくインストール・起動しているか確認してください。正常ならzhparserのライブラリが拡張ディレクトリに入っているはずです。症状が改善しない場合はServBay本体・PostgreSQLの再インストールやServBayの再起動もお試しください。
Q: カスタム辞書が反映されない場合？ A: 下記を確認してください。
1. zhparser.dict_pathが対象のカスタム辞書パス（例：/Applications/ServBay/etc/scws/custom_dict.txt）に正しく設定されているか（パスは大文字小文字も区別）
2. zhparser.dict_path設定後にSELECT zhprs_reload_dict();で再読み込みしているか
3. 辞書フォーマットが1行1単語となっているか
4. 新しいDBセッションの場合は再度SET zhparser.dict_path = ...;の実行、もしくはpostgresql.confで永続化＋DBの再起動を実施しているか
5. PostgreSQLユーザーが辞書ファイル読取権限を持つこと
Q: 全文検索の検索結果が期待と異なる場合？ A: テキスト検索構成（chinese）の品詞-to-辞書マッピングが正しいか確認。zhparser.seg_with_dualityのオン/オフも調整してみてください。SELECT to_tsvector('chinese', '（確認したい中国語テキスト）');で分かち書き解析結果を直接目視するのもおすすめです。クエリでto_tsqueryの構文や論理演算子（&, |, !）が正しいかもご確認ください。
Q: 全文検索パフォーマンスが良くない場合？ A: to_tsvector(...)で索引したカラムにGINインデックスを作成できているか要確認。さらに巨大データの場合はPostgreSQLの設定見直しや追加の高度なインデックスチューニングも検討しましょう。

9. まとめ

ServBayを使えば、PostgreSQLのzhparser拡張による中国語全文検索環境をシンプルな手順ですぐ構築できます。拡張の有効化・テキスト検索構成の設定・ServBay内蔵scwsによるカスタム辞書活用まで一貫してサポート。zhparserの基本的な使い方とチューニング方法を理解することで、ローカル開発環境での中国語テキストデータ処理能力を格段に高め、多機能な中国語アプリケーション構築の基礎を固めることができるでしょう。

ServBayでの中国語全文検索：zhparser利用ガイド ​

1. 概要 ​

2. 前提条件 ​

3. zhparser拡張のインストール（有効化） ​

4. zhparserの設定 ​

5. zhparserでの全文検索利用 ​

5.1 サンプルテーブルとデータの作成 ​

5.2 全文検索用インデックス作成 ​

5.3 全文検索クエリの実行 ​

6. ServBay内蔵scwsによるカスタム辞書の作成 ​

6.1 カスタム辞書ファイルの作成 ​

6.2 zhparserでカスタム辞書を指定 ​

6.3 辞書の再読み込み ​

7. 分かち書きモードの調整 ​

7.1 分かち書きモード設定 ​

8. よくある質問（FAQ） ​

9. まとめ ​