scws

SCWS-1.x.x 自述文件 (Written by hightman)
HomePage: http://www.ftphp.com/scws

$Id: README,v 1.4 2008/12/21 04:41:37 hightman Exp $

> ----------------------------------------------------------- <
1. 简介

2. 安装说明

3. API 使用说明

4. 配套工具

5. PHP 扩展安装说明

6. 代码结构

7. rules.ini 规则集编写说明

8. 关于词典

9. 性能指标

> ----------------------------------------------------------- <

[SCWS 简介]

SCWS 是 Simple Chinese Words Segmentation 的缩写（简易中文分词系统）。
它是一套基于词频词典的机械中文分词引擎，它能将一整段的汉字基本正确的
切分成词，因为词是汉语的基本语素单位，而书写的时候不像英语会在词之间
用空格分开，所以如何准确快速的分词一直是中文分词的攻关难点。

本分词法并无太多创新成分，采用的是自己采集的词频词典，并辅以一定的专
有名称，人名，地名，数字年代等规则识别来达到基本分词，经小范围测试大
概准确率在 90% ~ 95% 之间，已能基本满足一些小型搜索引擎、关键字提取
等场合运用。首次雏形版本发布于 2005 年底。

本系统支持的汉字编码包括 GBK、UTF-8

在线分词演示：
G B K: http://www.ftphp.com/scws/demo/v4.php
UTF-8: http://www.ftphp.com/scws/demo/v48.php
繁体: http://www.ftphp.com/scws/demo/v48.cht.php

详情可见项目主页：http://www.ftphp.com/scws

[安装说明]

以 Linux(FreeBSD) 操作系统为例

1. 取得 scws-1.0.1 的代码
wget http://www.ftphp.com/scws/down/scws-1.0.1.tar.gz

2. 解开压缩包
[hightman@d1 ~]$ tar xvzf scws-1.0.1.tar.gz

3. 进入目录执行配置脚本和编译
[hightman@d1 ~]$ cd scws-1.0.1
[hightman@d1 ~]$ ./configure --prefix=/usr/local/scws ; make ; make install

注：这里和通用的 GNU 软件安装方式一样，具体选项参数执行 ./configure --help 查看。
常用的三个选项为：
--prefix=<scws的安装目录>
--disable-mmap <这表示禁用 MMAP 来读取 xdb，在 debian, ubuntu 的部分 Linux 中建议关闭 mmap>
--enable-developer <这表示以开发者模式编译，主要是用于调试编译时加入了 -g 选项及部分标准输出的信息>

4. 顺利的话已经编译并安装成功到 /usr/local/scws 中了，执行下面命令看看文件是否存在
[hightman@d1 ~]$ ls -al /usr/local/scws/lib/libscws.la

5. 试试执行 scws-cli 文件
[hightman@d1 ~]$ /usr/local/scws/bin/scws -h
scws (scws-cli/1.0.1)
Simple Chinese Word Segmentation - Command line usage.
Copyright (C)2007 by hightman.
...

6. 生成词典
在源代码目录树的 etc/ 目录下附上了词典的文本文件，编码为 GBK，使用前必须先转换成 xdb 格式。
假设您在源码目录中，请执行
/usr/local/scws/bin/gen_scws_dict -h 查看词典生成帮助，调用指令(-c用于指定编码, gbk或utf8)：

/usr/local/scws/bin/gen_scws_dict -c gbk -i etc/dict_chs_gbk.txt -o /usr/local/scws/etc/dict_chs_gbk.xdb

执行需要一段时间，最终生成可用的 xdb 文件于 /usr/local/scws/etc/ 中

如果您需要使用 utf8 编码，请事先将 dict_chs_gbk.txt 转换成 utf8 编码再调用 gen_scws_dict 来转换。

注：scws 自 1.0.1 起发布版中不再包含词典 text 文件，而直接在主页发布 xdb 格式的词典文件，请参看主页进行下载。

7. 写个小程序测试一下
[hightman@d1 ~]$ cat > test.c
#include <scws.h>
main()
{
scws_t s;
s = scws_new();
scws_free(s);
printf("test ok!\n");
}

8. 编译测试程序
gcc -o test -I/usr/local/scws/include -L/usr/local/scws/lib test.c -lscws
./test

9. 这样就好了，就可以用这套 API 了

> ----------------------------------------------------------- <

[LibSCWS API 使用说明]

本说明由 hightman 编写于 2007.06.08
网页地址：http://www.ftphp.com/scws

0. 概述
Libscws 代码是当前 SCWS(简易中文分词) 算法使用C语言编写的链接库，
目前仅基于 Unix 族的操作系统，可能必须适当修改才能运行在 Windows
平台中（经测试在 Cygwin 环境中无需任何修改可以顺利编译和使用）。

这套 scws 库没有外部扩展依赖，代码力争简洁高效，针对分词词典组织
上做了一些优化。除分词外，由于分词词库采用的是自行设计的 xdb 和
xtree 结构，故本库函数也可以用以 XDB 和 XTree 数据存取。
（另行介绍，暂时没有说明）。

1. 数据类型（仅列出API中需要关注的部分）
·scws 操作句柄，几乎所有的 API 函数都使用到它，不应尝试拷贝 scws_st 结构，不保证这类拷贝结果会有用。
typedef struct
{
xdict_t d;
rule_t r;
unsigned char *mblen;
unsigned int mode;
unsigned char *txt;
int len;
int off;
int wend;
scws_res_t res0;
scws_res_t res1;
word_t **wmap;
struct scws_zchar *zmap;
} scws_st, *scws_t;

struct scws_zchar
{
int start;
int end;
};
注：xdict_t 和 rule_t 分别是词典和规则集的指针，可判断其是否为 NULL 来判断加载的成功与失败。

·scws 系列结果集，每次 scws 返回的分词结果的数量都是不定的，直到返回结果为 NULL 才表示这次分词过程结束，这是一个单链表结构。
typedef struct scws_result *scws_res_t;
struct scws_result
{
int off;
float idf;
unsigned char len;
char attr[3];
scws_res_t next;
};

·scws 高频关键词统计集，简称＂词表集＂，这是 scws 中统计调用时返回用的结构，也是一个单链表结构。
typedef struct scws_topword *scws_top_t;
struct scws_topword
{
char *word;
float weight;
short times;
char attr[2];
scws_top_t next;
};

2. 函数说明

·scws_t scws_new();
描述：分配或初始化与scws系列操作的 scws_st 对象。该函数将自动分配、初始化、并返回新对象的指针。通过调用 scws_free() 来释放该对象。
返回值：初始化的 scws_st * （即 scws_t）句柄。如果无足够内存以分配新的对象，返回NULL。
错误：在内存不足的情况下，返回NULL。

·void scws_free(scws_t s);
描述：释放由 scws_new() 返回的 scws 操作句柄及对象内容，同时也会释放已经加载的词典和规则。
返回值：无
错误：无

·void scws_set_charset(scws_t s, const char *cs);
描述：设定当前 scws 所使用的字符集，目前仅支持 gbk 和 utf-8 两种字符集。参数 cs 描述的是新指定的字符集。若无此调用则系统缺省使用gbk字符集，指定字符集时 cs 参数的大小写不敏感。
返回值：无
错误：若指定的字符集不存在，则会自动使用 gbk 字符集替代。

·void scws_set_dict(scws_t s, const char *fpath, int mode);
描述：设定当前 scws 操作所有的词典文件。参数 fpath 描述的是词典的文件路径，词典格式是 XDB 格式。
参数 mode 有2种值，分别为宏定义的：SCWS_XDICT_XDB （这表示直接读取 xdb 文件）、SCWS_XDICT_MEM （这表示将 xdb 文件全部加载到内存中，以 XTree 结构存放）。具体用哪种方式需要根据自己的实际应用来决定。当使用本库做为 daemon server 时应当使用 mem 方式，当只是 embed 调用时应该使用 xdb 方式，将 xdb 文件加载进内存不仅占用了比较多的内存，而且也需要一定的时间（35万条数据约需要0.3~0.5秒左右）。
若此前 scws 句柄已经加载过词典，则此调用会先释放已经加载的词典。
返回值：无

错误：如果加载失败，scws_t 结构中的 d 元素为 NULL，即通过 s->d == NULL 与否来判断加载失败或成功。

·void scws_set_rule(scws_t s, const char *fpath);
描述：设定规则集文件。参数 fpath 是规则集文件的路径。若此前 scws 句柄已经加载过规则集，则此调用会先释放已经加载的规则集。规则集定义了一些新词自动识别规则，包括常见的人名、地区、数字年代等。规则编写方法另行参考其它部分。
返回值：无
错误：加载失败，scws_t 结构中的 r 元素为 NULL，即通过 s->r == NULL 与否来判断加载的失败与成功。

·void scws_set_ignore(scws_t s, int yes);
描述：设定分词执行过程中是否忽略所有的标点等特殊符号（不会忽略\r和\n）。参数 yes 为 1 表示忽略，为0表示不忽略，缺省情况为不忽略。
返回值：无
错误：无

·void scws_set_multi(scws_t s, int mode);
描述：设定分词执行时是否执行针对长词复合切分。（例如：中国人->中国+人+中国人）。参数 mode 表示复合分词法的级别，取值为 1 ~ 15。mode 设定值，1~15。按位与的 1|2|4|8 依次表示短词|二元|主要单字|全部单字。缺省不复合分词。
返回值：无
错误：无

·void scws_set_duality(scws_t s, int yes);
描述：设定是否将闲散文字自动以二字分词法聚合，参数 yes 的值如果为 1 表示执行二分聚合，0 表示不处理，缺省为 0。
返回值：无
错误：无

·void scws_set_debug(scws_t s, int yes);
描述：设定分词时对于疑难多路径综合分词时，是否打印出各条路径的情况。注意，打印使用的是 fprintf(stderr, ... 故，这项功能不要随便使用，仅在命令行嵌入式调用时可以使用，参见例子中的 cmd.c 。当库函数编译选项中加入 -DLIBSCWS_QUIET 时此项不生效。（参见 php 扩展，PHP扩展里就是加入此项）
返回值：无
错误：无

·void scws_send_text(scws_t s, const char *text, int len);
描述：设定要切分的文本数据，text 指定该串文本的起始位置，而 len 表示这段文本的长度。该函数可安全用于二进制数据，不会因为字符串中包括 \0 而停止切分。这个函数应该在 scws_get_result 和 scws_get_tops 之前调用。
返回值：无
错误：无。
注：scws结构内部维护着该字符串的指针和相应的偏移及长度，故连续调用的话后者会覆盖前者的设定；不应在多次 scws_get_result 循环中调用 scws_send_text()。

·scws_res_t scws_get_result(scws_t s);
描述：取回一系列分词结果集，该分词结果必须调用 scws_free_result() 释放，传入链表头指针。
返回值：返回的是结果集链表的头部指针。该函数必须循环调用，当返回值为 NULL 时表示分词结束。
错误：无

·void scws_free_result(scws_res_t result);
描述：根据结果集的链表头释放结果集
返回值：无
错误：无

·scws_top_t scws_get_tops(scws_t s, int limit, char *xattr);
描述：返回指定的关键词表统计集，系统会自动根据词语出现的次数及其 idf 值计算排名。参数 limit 指定取回数据的最大条数，若传入值为0或负数，则自动重设为10。参数 xattr 用来描述要排除或参与的统计词汇词性，多个词性之间用逗号隔开。当以~开头时表示统计结果中不包含这些词性，否则表示必须包含，传入 NULL 表示统计全部词性。
返回值：返回词表集链表的头指针，该词表集必须调用 scws_free_tops 释放
错误：无

·void scws_free_tops(scws_top_t tops);
描述：根据词表集的链表头释放词表集
返回值：无
错误：无

3. 使用实例
一个简单的分词实例：
#include <scws.h>
#include <stdlib.h>
main()
{
scws_t s;
scws_res_t res, cur;
char *text = "Hello, 我名字叫李那曲是一个中国人, 我有时买Q币来玩, 我还听说过C#语言";

if (!(s = scws_new())) {
printf("error, can't init the scws_t!\n");
exit(-1);
}
scws_set_charset(s, "gbk");
scws_set_dict(s, "/usr/local/scws/etc/dict_chs_gbk.xdb", SCWS_XDICT_XDB);
scws_set_rule(s, "/usr/local/scws/etc/rules.ini");

scws_send_text(s, text, strlen(text));
while (res = cur = scws_get_result(s))
{
while (cur != NULL)
{
printf("Word: %.*s/%s (IDF = %4.2f)\n", cur->len, text+cur->off, cur->attr, cur->idf);
cur = cur->next;
}
scws_free_result(res);
}
scws_free(s);
}

编译：gcc -o test -I/usr/local/scws/include -L/usr/local/scws/lib test.c -lscws

> ----------------------------------------------------------- <

[配套工具]

1. /usr/local/scws/bin/scws 或 $prefix/bin/scws

这是分词的命令行演示版本
执行 scws -h 可以看到详细帮助：

Usage: scws [options] [input] [output]
-i <file|string> input string or filepath
(default: try to read from <stdin> everyline)
-o <file> output filepath (default to <stdout>)
-c <charset> set the charset (default: gbk)
charset must been same with dictionary & ruleset
-r <file> set the ruleset file (default: none)
-d <file> set the dictionary file (default: none)
-M <1~15> use multi child words mode(中国人->中国+人+中国人)
1|2|4|8: short|duality|zmain|zall
-I ignore the all mark symbol such as ,:
-A show the word attribute
-E import the xdb dict into xtree(memory)
-N don't show time usage and warnings
-D debug segment, see the segment detail
-U use duality algorithm for single chinese
-t <NUM> fetch the top words instead of segment
-a [~]<attr1,attr2,...> prefix by ~ means exclude them.
For topwords, exclude or include some word attrs
-v Show the version.
-h Show this page for help.

-i <>: 要切分的字符串或者文件路径，如不指定则程序自动读取标准输入，每输入一次换行执行一次分词
-o <>: 切分结果输出保存的文件路径，若不指定直接输出到屏幕
-c <>: 指定分词的字符集，默认是 gbk
-r <>: 指定规则集文件（规则集用于数词、数字、专有名字、人名的识别）
-d <>: 指定词典文件路径（XDB格式，请在 -c 之后使用）
-M <>: 复合分词的级别：1~15，按位与的 1|2|4|8 依次表示短词|二元|主要单字|全部单字。缺省不复合分词。
-I: 输出结果忽略跳过所有的标点符号
-A: 显示分词属性
-E: 将 xdb 词典读入内存 xtree 结构 (如果切分的文件很大才需要)
-N: 不显示切分时间和提示
-D: debug 模式 (不必用, 需要编译时打开 --enable-developer)
-U: 将闲散单字自动调用二分法结合
-t <>: 取得高频词，参数为个数
-a [~]<attr1,..> 只显示某些词性的词，加~表示过滤该词性的词
-v: 查看版本
-h: 查看帮助

2. /usr/local/scws/bin/gen_scws_dict 或 $prefix/bin/gen_scws_dict

这将文本的词典转换成 xdb 文件
词典格式请参见源码 etc/ 中的 dict_chs_gbk.txt 和 dict_cht_gbk.txt
每行一个词，各行由4个字段组成，字段之间用 \t 分隔，含义分别为：

<词> <词频(TF)> <词重(IDF)> <词性(北大标注)>

---
Usage: gen_scws_dict [options] [input file] [output file]
-i Specified the plain text dictionary(default: dict.txt).
-o Specified the output file path(default: dict.xdb)
-c Specified the input charset(default: gbk)
-p Specified the PRIME num for xdb
-v Show the version.
-h Show this page.

-c 指定字符集
-i 文本文件(txt)
-o 输出 xdb 文件的路径
-p (指定XDB结果的质数，一般不需要）

> ----------------------------------------------------------- <

[PHP 扩展安装说明]

本软件包，在源码目录树中包含了 php 扩展的移植代码，可用于 php4
或 php5 ，这里介绍它的安装方式，假设您已经将 scws-1.0.1 安装到
/usr/local/scws 中或 $prefix 中。

安装此扩展要求您的 php 和系统环境安装了相应的 autoconf automake
工具及 phpize 。

(对于 Windows 系统请直接跳到第 8 开始阅读。)

1. 进入源码目录的 phpext/ 目录
2. 执行 phpize （在PHP安装目录的bin/目录下）
3. 执行 ./configure --with-scws=/usr/local/scws
若 php 安装在特殊目录 $php_prefix, 则请在 configure 后加上
--with-php-config=$php_prefix/bin/php-config

4. 执行 make 然后用 root 身份执行 make install

5. 在 php.ini 中加入以下几行

[scws]
;
; 注意请检查 php.ini 中的 extension_dir 的设定值是否正确, 否则请将 extension_dir 设为空，
; 再把 extension = scws.so 或 php_scws.dll 指定绝对路径。
;
extension = scws.so
scws.default.charset = gbk
scws.default.fpath = $prefix/etc

6. 命令行下执行 php -m 就能看到 scws 了或者在 phpinfo() 中看看关于 scws 的部分

7. 这样就算安装完成了，余下的工作只是PHP代码编写问题了。
关于 PHP 扩展的使用说明请参看代码中 phpext/php_scws_manual.txt 文件

=== Windows 下的安装方式 ===

8. windows 下的 php 扩展是采用 .dll 文件的，系统已预编译 2 个版本的扩展文件。
位于 phpext/scws-1.0.0_win32_php-4.4.x.zip 和 phpext/scws-1.0.0_win32_php-5.2.x.zip

请根据您的 PHP 版本选用一个文件，将其解压缩，可得到 php_scws.dll 文件。

将得到的 php_scws.dll 文件放入 PHP 安装目录的 extensions/ 目录中去，然后再看上面的
第 5 点修改相应的 php.ini 即可。

win32 的版一建议将词典和规则集文件统一放在 C:/Program files/scws/etc 目录中，
将 php.ini 中的 scws.default.fpath 的值设为 c:/program files/scws/etc 即可。

> ----------------------------------------------------------- <

[代码结构]

scws-1.0.x/
COPYING -- 版权说明
README -- 相关全部文档，包括安装及使用，必读
cli/ -- 配套工具 scws-cli 及词典制作工具
scws_cmd.c
gen_dict.c

libscws/ -- 核心C代码
*.h *.c

phpext/ -- php扩展的代码
win32/ -- win32 下的 php 扩展的二进制文件及工程文件 (by ben)
etc/ -- 文本词典及规则集文件
rules.ini
rules.utf8.ini -- utf8编码版的rules

dict_chs_gbk.txt -- gbk 编码的简体为主的文本词表
dict_cht_utf8.txt -- utf8 编码的繁体为主的文本词表

> ----------------------------------------------------------- <

[rules.ini 规则集]

（暂缺）

> ----------------------------------------------------------- <

[关于词典]

我们的词典使用的是 XDB 格式，这是自行开发的专用格式。

免费提供的默认词典是通用的互联网信息词汇集，约 28 万个词。
如果您需要定制词典以作特殊用途，请与我们联系，可能会视情况进行收费。

> ----------------------------------------------------------- <

[性能指标]

在 FreeBSD 6.2 系统，单核单 CPU 至强 3.0G 的服务器上，
测试长度为 80, 535 的文本, 用附带的命令行工具耗时将约 0.17 秒,
若改用 php 扩展方式调用, 则耗时约为 0.65 秒.

分词精度 95.60%, 召回率 90.51% (F-1: 0.93)

> ----------------------------------------------------------- <

hightman. 20080304