wapic 0.1.0

C++17 linear-chain CRF Chinese word segmenter

Wapic

Wapic 是一个 C++17 线性链 CRF 序列标注工具，本项目用CRF来做中文分词。它支持 SGD-L1 与 L-BFGS/OWL-QN 训练、BMES 解码、批量推理和可选的 Python 绑定。

发布模型与大规模训练数据不存放在Git仓库中：

• 模型：Ismantic/Wapic-CWS
• 数据：Ismantic/Wapic-CWS-Data

构建

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

训练对编译优化较敏感，建议始终使用 Release 构建。

下载模型

安装 huggingface_hub，然后下载主模型：

uv pip install huggingface_hub
python3 scripts/download.py model

模型默认保存到 data/model/wapic-cws.wac。

推理

交互式分词：

./build/wapic -m data/model/wapic-cws.wac

批量 BMES 标注：

./build/wapic test -m data/model/wapic-cws.wac \
  input_chars.txt output_tags.txt

输入文件每行一个字符，空行分句。

Python

从 PyPI 安装。默认模型会作为依赖一起安装，无需另外下载：

pip install wapic

用法：

import wapic
seg = wapic.Segmenter()
print(seg.segment("中华人民共和国是一个伟大的国家"))
# ['中华人民共和国', '是', '一个', '伟大', '的', '国家']

# 也可以显式加载自己训练的模型
custom = wapic.Segmenter("/path/to/custom.wac")

# 批量：多核并行（释放 GIL），大语料吞吐 ~Nx
results = seg.segment_batch(["第一句", "第二句", ...])

开发时也可从仓库源码安装或用 PYTHONPATH 直接引用：

pip install .
uv pip install pybind11
cmake -B build_py -DWAPIC_PYTHON=ON -DCMAKE_BUILD_TYPE=Release \
  -Dpybind11_DIR="$(python3 -m pybind11 --cmakedir)"
cmake --build build_py
PYTHONPATH=build_py/python python3 -c 'import wapic; print(wapic.Segmenter("data/model/wapic-cws.wac").segment("中华人民共和国"))'

评估

python3 scripts/download.py data          # 加 --full 下载完整训练集
python3 scripts/test.py data/model/wapic-cws.wac

发布模型在 PD/News 测试集上的 F1 为98.01/97.95。完整训练数据与两阶段 warm-start 配方见数据集仓库 Ismantic/Wapic-CWS-Data。

训练

除了使用发布模型，也可以按 TUTORIAL.md 用公开的人民日报 1998 语料从零训练一个分词模型（1–5 月训练 / 6 月测试，单机约 3 分钟得到 F1≈97.4）。 涉及脚本：scripts/convert.py（PFR→jsonl）、scripts/prepare.py（jsonl→BMES）。 仓库内的PFR语料不适用MIT许可证，详情见 data/README.md。

文档

CRF、前向后向算法、梯度计算以及 L-BFGS/OWL-QN 的原理讲解见《底层实现：文本处理》的 中文分词：高级篇。

License

源码采用MIT许可证。data/PeopleDaily1998.zip 的版权和使用条件独立于源码许可证。