ServBay 中文全文搜尋：zhparser 使用指南

zhparser 是一款強大的第三方 PostgreSQL 擴充套件，專為高效處理中文文本而設計。它為 PostgreSQL 資料庫提供精確的中文分詞與全文搜尋能力，是建構含有中文內容搜尋應用的理想選擇。ServBay 作為一套完整的本機 Web 開發環境，已預設整合並支援 zhparser 擴充功能，同時內建了 scws（Simple Chinese Word Segmentation）中文分詞庫，zhparser 可結合 scws 實現自訂詞庫功能。

本文將詳細說明如何在 ServBay 環境下安裝（啟用）、設定 zhparser，並展示如何用於中文全文搜尋及如何利用 ServBay 內建的 scws 建立及套用自訂字典。

1. 概述

針對含有大量中文資料的應用系統，例如內容管理系統、論壇、電商平台等，實現高效且精準的全文搜尋至關重要。PostgreSQL 雖原生支援全文搜尋，卻對中文支持有限，因為其預設針對由空白分隔的語言設計。zhparser 擴充解決此問題，為 PostgreSQL 帶來中文分詞技術，使資料庫能理解中文詞彙邊界，完善實現中文全文檢索。

ServBay 為開發者預先整合了 zhparser，免除手動編譯與安裝煩瑣過程，讓您可在本地快速搭建支援中文全文搜尋的開發環境。

2. 前置條件

在使用 zhparser 之前，請確認：

您已成功安裝 ServBay。
ServBay 的 PostgreSQL 套件已啟用且正在運行。可於 ServBay 應用程式介面檢查和管理軟體狀態。

3. 安裝（啟用）zhparser 擴充套件

ServBay 已將 zhparser 模組置於 PostgreSQL 可識別的資料夾。您僅需於目標資料庫執行 SQL 指令啟用即可。

連線至您的 PostgreSQL 資料庫：開啟終端機，並透過 psql 指令連接 ServBay 運行中的 PostgreSQL。請將 servbay-demo 替換成實際的資料庫用戶名，your_database_name 替換成您需啟用 zhparser 的資料庫名稱。
bash
```
psql -U servbay-demo -d your_database_name
```
1
若連接預設資料庫（通常和用戶名相同），可省略 -d 參數。
創建 zhparser 擴充套件：在 psql 互動界面執行下述 SQL 指令：
sql
```
CREATE EXTENSION zhparser;
```
1
如果執行成功，將無錯誤提示。若顯示已存在表示已啟用過。
確認 zhparser 是否安裝成功：可用下列指令檢視已安裝擴充套件列表：
sql
```
\dx
```
1
在清單中應可看到 zhparser 及其版本資訊。

4. 設定 zhparser

啟用 zhparser 後，需要設定 PostgreSQL 的全文搜尋功能，使其能正確利用 zhparser 進行中文分詞。這主要涉及創建全文搜尋組態（Text Search Configuration）。

建立全文搜尋組態：全文搜尋組態定義如何將文件轉換為 tsvector（索引用）及查詢字串轉換為 tsquery（查詢用）。我們建立一個名為 chinese 的組態，並指定使用 zhparser 做為解析器（PARSER）。
sql
```
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
```
1
設定詞類對應字典：全文搜尋組態需要定義在解析器（zhparser）產生的不同詞類（token）時，應使用哪種字典（dictionary）處理。zhparser 會根據詞性如名詞 n、動詞 v、形容詞 a 等標記詞彙。在此，我們將名詞（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 欄位創建 GIN 索引。索引時，利用 to_tsvector('chinese', content) 轉換文本並指定使用組態 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 的文件。注意若詞典中有“自然語言處理”，分詞效果會更佳；否則會依分詞與模式不同而定。）

6. 使用 ServBay 內建 scws 建立自訂字典

ServBay 已整合 scws 分詞庫，zhparser 可設定使用 scws 字典檔案（含自訂字典）來提升分詞精度，對於領域專屬詞彙或新詞特別有效。

6.1 建立自訂字典檔案

創建或編輯自訂字典檔：建議將 scws 自訂詞典放於 /Applications/ServBay/etc/scws/ 目錄。若尚未存在，請建立 custom_dict.txt 檔案。
bash
```
# 在終端機建立或編輯檔案
nano /Applications/ServBay/etc/scws/custom_dict.txt
```
1
2
在檔案中新增詞彙：於 custom_dict.txt 每行輸入一個您希望 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 套件已正確安裝並運作。ServBay 應已將 zhparser 套件安裝於 PostgreSQL 的擴充資料夾。如有問題，請檢查安裝完整性或嘗試重啟 ServBay。
Q: 自訂字典未生效？ A: 請檢查以下事項：
1. zhparser.dict_path 參數是否正確指向您的自訂字典（/Applications/ServBay/etc/scws/custom_dict.txt），且注意路徑區分大小寫。
2. 設定字典路徑後，是否有執行 SELECT zhprs_reload_dict(); 重新載入詞典？
3. 自訂字典格式是否正確（一行一詞）？
4. 使用新資料庫連線測試時，是否重新設定過 SET zhparser.dict_path = ...;，或已於 postgresql.conf 設定並重啟 PostgreSQL？
5. PostgreSQL 用戶確實具備字典檔案讀取權限。
Q: 全文搜尋結果不如預期？ A: 請檢查全文搜尋組態（chinese）的詞性映射設定是否正確。調整 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. 總結 ​