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 词典是最基本的词典，它不做任何转换，直接保留 zhparser 分出来的词汇。
sql
```
ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;
-- 您可以根据需要添加或修改映射的词性标签和词典。
```
1
2
注意：zhparser 支持的词性标签可能与标准 NLP 标签略有不同，这里列出的是 zhparser 常用的标签。

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) 将 content 文本转换为 tsvector 格式，并指定使用我们之前创建的 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 创建自定义词典文件

创建或编辑自定义词典文件： ServBay 建议将 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 会话中，执行以下命令设置 zhparser 的字典路径：
sql
```
SET zhparser.dict_path = '/Applications/ServBay/etc/scws/custom_dict.txt';
-- 请确保该路径正确且PostgreSQL用户有读取权限。
```
1
2
注意：使用 SET 命令设置的参数仅对当前数据库会话有效。如果您希望此设置对所有新连接都生效，需要修改 PostgreSQL 的配置文件 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 和 PostgreSQL 的安装是否完整，或者尝试重启 ServBay。
Q: 自定义词典没有生效？ A: 请检查以下几点：
1. zhparser.dict_path 参数是否已正确设置为您的自定义词典文件路径 (/Applications/ServBay/etc/scws/custom_dict.txt)。请注意路径是大小写敏感的。
2. 您是否在设置 zhparser.dict_path 后执行了 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. 总结 ​