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

$Id: README,v 1.10 2012/03/20 07:01:29 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/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 scws_st
{
  struct scws_st *p;
  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。

·scws_t scws_fork(scws_t p);
描述：在已有scws_st对象上产生一个分支，可以独立用于某个线程分词，但它和父对象共享词典、规则集资源。
同样需要调用 scws_free() 来释放对象。在该分支对象上加载词典、规则集将直接作用于父对象，如果父对象
提前释放，则再调用分支对象进行分词就会引起内存错误。
返回值：克隆出来的分支 scws_st * (scws_t) 句柄。
错误：在内存不足的情况下，返回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 字符集替代。

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

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

错误： 这和 scws_add_dict 的区别在于会清空已有词典。

·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 表示复合分词法的级别，取值由下面几个常量异或组合:
	SCWS_MULTI_SHORT | SCWS_MULTI_DUALITY | SCWS_MULTI_ZMAIN | SCWS_MULTI_ZALL
	依次表示 短词|二元|主要单字|全部单字。缺省不复合分词。
返回值：无
错误：无

·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);
描述：根据词表集的链表头释放词表集
返回值：无
错误：无

·int scws_has_word(scws_t s, char *xattr);
描述：判断text中是包括指定的词性的词汇。参数 xattr 用来描述要排除或参与的统计词汇词性，多个词性之间用逗号隔开。当以~开头时表示统计结果中不包含这些词性，否则表示必须包含，传入 NULL 表示统计全部词性。
返回值：如果有返回 1 没有则返回 0
错误：无

·scws_top_t scws_get_words(scws_t s, char *xattr);
描述：返回指定词性的关键词表，系统会根据词语出现的先后插入列表。参数 xattr 用来描述要排除或参与的统计词汇词性，多个词性之间用逗号隔开。当以~开头时表示统计结果中不包含这些词性，否则表示必须包含，传入 NULL 表示统计全部词性。
返回值：返回词表集链表的头指针，该词表集必须调用 scws_free_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)
                   support text dictionary, multi dictionary file split by ':' (ver 1.1.0+)
  -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 之后使用）
       *NOTICE*
       自 1.1.0 版起，开始支持多词典同时载入，词典格式也支持纯文本格式（必须是.txt结尾）。
       
       多词典路径之间用冒号(:)隔开，排在越后面的词典优先级越高。

       文本词典的数据格式参见 gen_scws_dict 所用的格式，但更宽松一些，允许用不定量的空格分开，
       只有<词>是必备项目，其它数据可有可无，当词性标注为“!”（叹号）时表示该词作废，即使在
       较低优先级的词库中存在该词也将作废。

-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

主页：http://www.ftphp.com/scws
论坛：http://www.hightman.cn/bbs/
邮件：hightman2@yahoo.com.cn