在 ServBay 中使用 pg_jieba 實現 PostgreSQL 中文全文檢索

概述

對於英文等語言，PostgreSQL 內建的全文檢索功能可藉由空白與標點符號進行有效的詞法分析。不過，中文文本並沒有天然的空格分隔，因此需要專門的**分詞（Segmentation）**工具，將持續的漢字序列切割成具獨立語意的詞語。

pg_jieba 是一個為 PostgreSQL 資料庫設計的第三方擴充套件，集成了熱門的 結巴（Jieba）分詞庫。有了 pg_jieba，你可以在 PostgreSQL 中針對中文文本進行高效且精準的分詞處理，進而打造強大的中文全文檢索體驗。

作為整合式本地 Web 開發環境，ServBay 已預載了 pg_jieba 擴充，省去自行編譯安裝的繁雜步驟，讓你能快速在本地開發與測試中文全文檢索功能。

本文將詳細說明如何在 ServBay 環境下啟用、設定與使用 pg_jieba 擴充功能。

前置條件

在使用 pg_jieba 前，請確保你已完成以下準備：

已於 macOS 系統安裝 ServBay，且 PostgreSQL 資料庫已成功啟動。
具備基本的 PostgreSQL 操作知識，包括如何連線資料庫及執行 SQL 語句。

安裝與啟用 pg_jieba

ServBay 已隨 PostgreSQL 打包提供 pg_jieba 擴充模組。你無需手動下載或編譯，只需在目標資料庫中執行簡單 SQL 指令即可啟用。

步驟如下：

連線至你的 PostgreSQL 資料庫：開啟終端機，利用 psql 指令連線至你的 PostgreSQL。請將 your_username 替換為您的資料庫帳號，your_database 替換為資料庫名稱。ServBay 預設的 PostgreSQL 用戶及資料庫名稱通常為 servbay 或 postgres。
bash
```
psql -U your_username -d your_database
```
1
範例，使用預設帳號及資料庫：
bash
```
psql -U servbay -d servbay
```
1
建立並啟用 pg_jieba 擴充：在 psql 介面下執行下列 SQL 指令：
sql
```
CREATE EXTENSION pg_jieba;
```
1
若擴充已存在，重複執行該指令會出錯，屬正常現象。
確認 pg_jieba 是否啟用成功：執行下列指令列出目前資料庫已安裝擴充：
sql
```
\dx
```
1
若清單中含有 pg_jieba，代表已成功啟用。

設定 pg_jieba 進行中文全文檢索

啟用 pg_jieba 後，需要設定 PostgreSQL 的全文本搜尋（Text Search）功能，指定以 pg_jieba 做為斷詞器。

建立文本搜尋組態（Text Search Configuration）

文本搜尋組態會定義 PostgreSQL 如何處理文件內容，包括指定哪個剖析器（parser）進行分詞，及各類詞元（token）的處理方式。

建立新的文本搜尋組態：建一個名為 chinese 的組態，並指定使用 pg_jieba 作為解析器。
sql
```
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);
```
1
此組態將引導 PostgreSQL 處理文本時調用 pg_jieba 斷詞。
為分詞結果指定對應映射（Mapping）： pg_jieba 依詞性標註不同詞元。為使這些詞元得以索引及搜尋，需將它們對應至特定字典。這裡將常見詞性（如名詞 n、動詞 v、形容詞 a 等）對應到 PostgreSQL 內建的 simple 字典。simple 字典不做進一步處理，直接採用 pg_jieba 輸出的詞元。
sql
```
ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
```
1
其中的 n,v,a,i,e,l 是 pg_jieba 常見識別的詞性標籤，你可視需求擴增或調整。常見標籤包括：
- n: 名詞
- v: 動詞
- a: 形容詞
- i: 成語
- e: 嘆詞
- l: 慣用語
- nr: 人名
- ns: 地名
- nt: 機構／團體
- nz: 其他專有名詞
- m: 數詞
- q: 量詞
- t: 時間詞
- s: 處所詞
- f: 方位詞
- p: 介詞
- c: 連詞
- u: 助詞
- xc: 其他虛詞
- w: 標點符號
- eng: 英文
- x: 非語素字
實務上，通常僅索引具實質意義的詞（如名詞、動詞、形容詞等）。

使用 pg_jieba 進行全文檢索範例

完成組態後，即可運用 pg_jieba 執行中文全文檢索。以下為簡單範例：

建立範例表格與資料

首先，建立用於儲存文件的資料表，並插入幾筆含中文內容的示例數據。

建立資料表：

sql

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

插入示例資料：

sql

INSERT INTO documents (content) VALUES
('我愛自然語言處理技術'),
('中文分詞是文本處理的重要步驟'),
('pg_jieba是一個很好的中文分詞工具，它基於結巴分詞庫'),
('ServBay 讓本地開發變得簡單高效');

建立全文搜尋索引

為了加快搜尋速度，特別是對大量資料，可在待檢索欄位建立索引。PostgreSQL 的 GIN（通用反向索引）類型非常適合全文檢索。

建立 GIN 索引：使用 to_tsvector 搭配剛剛的 chinese 組態，對 content 欄位建立 GIN 索引。to_tsvector('chinese', content) 會將內容以 pg_jieba 分詞為 tsvector，供全文檢索使用。
sql
```
CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));
```
1

執行全文搜尋查詢

現可透過 to_tsquery 結合 @@ 運算子進行查詢。to_tsquery('chinese', 'your query') 會將搜尋短語用 pg_jieba 斷詞並產生 tsquery 型別，@@ 用於比對結果。

執行搜尋：查找同時含有「中文」和「分詞」的文檔。

sql

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

& 為 AND 運算。你也可用 | 做 OR，! 為 NOT。

例如，搜尋「ServBay」或「開發」：

sql

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

自訂詞典

pg_jieba 預設採用 Jieba 分詞庫的標準字典。某些情境下，可能需要加入自訂詞彙（如專業術語、產品名稱），以提升分詞正確性。

你可以建立自訂詞典檔，並設定 pg_jieba 載入使用。

新增自訂詞彙

建立自訂詞典檔案：於 ServBay 設定目錄中創建文字檔，例如：
plaintext
```
/Applications/ServBay/etc/pg_jieba/custom_dict.txt
```
1
這是建議放置路徑，實際目錄位置可依 ServBay 安裝結構及偏好調整。
在詞典檔加入詞彙：使用文字編輯器開啟 custom_dict.txt，每行新增一筆詞彙。也可選擇在詞後指定詞頻（frequency）及詞性（tag），以空格分隔。格式：詞彙 [詞頻 [詞性]]。詞頻越高，分詞時越易切出該詞。
plaintext
```
自然語言處理 3 n
ServBay 5 eng
結巴分詞庫 3 n
```
1
2
3
其中 3 n 意指「自然語言處理」詞頻3，詞性名詞（n）；5 eng 代表「ServBay」詞頻5，詞性為英文（eng）。
設定 pg_jieba 使用自訂詞典：在你的 PostgreSQL 連線中，以 pg_jieba.dict_path 指向詞典所在資料夾。**注意：**此參數通常指向「目錄」，而非單一檔案。若你的自訂詞典與主詞典放在同一資料夾或已被 pg_jieba 設定掃描，則可省略。ServBay 如有特殊打包請依其說明調整。
若 ServBay 的 pg_jieba 設定允許直接指定自訂詞典，或你已將詞典放至系統預設目錄下，則下述 SET 指令只供參考，實際以安裝環境為準：
sql
```
SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- 假設主詞典與 custom_dict.txt 均於此
```
1
或，如允許直接指定詞典檔案（非標準作法，僅為說明）：
sql
```
SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- 請依實際驗證，慎用
```
1
重要：SET 指令僅於當前會話生效。要永久生效需修改 PostgreSQL 的 postgresql.conf，指定正確的 pg_jieba.dict_path 路徑。

重新載入詞典

修改詞典檔或 pg_jieba.dict_path 後，需通知 pg_jieba 重新載入才能生效。

重新載入詞典：執行下列函數：
sql
```
SELECT jieba_reload_dict();
```
1
成功後，後續分詞會採用新詞典設定。

常見問題解答（FAQ）

問：執行 CREATE EXTENSION pg_jieba; 出現「extension "pg_jieba" is not available」錯誤？ 答：這通常代表 pg_jieba 擴充未正確安裝或 PostgreSQL 無法定位。在 ServBay 環境此套件應預載。請確定連線的是 ServBay 提供的 PostgreSQL，且 ServBay 安裝無損壞。若仍有問題，請重啟 ServBay 或查閱其日誌。
問：自訂詞典未生效怎麼辦？ 答：請檢查：
1. 詞典檔案路徑是否正確且資料庫用戶具讀取權限。
2. 詞典檔案格式是否正確，每行一詞，詞頻詞性空白隔開。
3. 是否正確設置 pg_jieba.dict_path，SET 僅當前會話有效，跨會話須調整 postgresql.conf。
4. 是否執行 SELECT jieba_reload_dict(); 進行詞典重載。
5. 修改 postgresql.conf 後，是否重啟 PostgreSQL 服務。
問：全文檢索結果不精確怎麼辦？ 答：精準度取決於分詞結果及查詢建構方式。
1. 可用 ts_debug('chinese', '你的文本') 檢查斷詞與標註是否如預期。
2. 調整 ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple; 中映射的詞性，排除無搜索意義的種類（如助詞標點）。
3. 查驗 to_tsquery 語法與邏輯運算（&, |, !）是否反映你的搜尋邏輯。

結論

pg_jieba 是在 PostgreSQL 平台上建構中文全文檢索的強力工具。透過 ServBay 提供的預設整合，開發者能無痛於本地配置與啟用中文分詞。依照本文步驟，你應已掌握於 ServBay 中安裝、設定及運用 pg_jieba 斷詞與全文檢索，亦能透過自訂詞典提升分詞與檢索精度。將上述技術應用至專案，可大幅提升中文內容的可搜索性。

在 ServBay 中使用 pg_jieba 實現 PostgreSQL 中文全文檢索 ​

概述 ​

前置條件 ​

安裝與啟用 pg_jieba ​

設定 pg_jieba 進行中文全文檢索 ​

建立文本搜尋組態（Text Search Configuration） ​

使用 pg_jieba 進行全文檢索範例 ​

建立範例表格與資料 ​

建立全文搜尋索引 ​

執行全文搜尋查詢 ​

自訂詞典 ​

新增自訂詞彙 ​

重新載入詞典 ​

常見問題解答（FAQ） ​

結論 ​