Metadata-Version: 2.4
Name: wapic
Version: 0.1.0
Summary: C++17 linear-chain CRF Chinese word segmenter
Keywords: chinese-word-segmentation,crf,nlp
Author: Ismantic
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Text Processing :: Linguistic
Project-URL: Homepage, https://github.com/Ismantic/Wapic
Project-URL: Model, https://huggingface.co/Ismantic/Wapic-CWS
Requires-Python: >=3.9
Requires-Dist: wapic-cws-model==0.1.0
Description-Content-Type: text/markdown

# Wapic

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

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

- 模型：[Ismantic/Wapic-CWS](https://huggingface.co/Ismantic/Wapic-CWS)
- 数据：[Ismantic/Wapic-CWS-Data](https://huggingface.co/datasets/Ismantic/Wapic-CWS-Data)

## 构建

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

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

## 下载模型

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

```bash
uv pip install huggingface_hub
python3 scripts/download.py model
```

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

## 推理

交互式分词：

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

批量 BMES 标注：

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

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

## Python

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

```bash
pip install wapic
```

用法：

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

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

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

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

```bash
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("中华人民共和国"))'
```

## 评估

```bash
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](https://huggingface.co/datasets/Ismantic/Wapic-CWS-Data)。

## 训练

除了使用发布模型，也可以按 [TUTORIAL.md](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](data/README.md)。

## 文档

CRF、前向后向算法、梯度计算以及 L-BFGS/OWL-QN 的原理讲解见《底层实现：文本处理》的
[中文分词：高级篇](https://ismantic.github.io/text/wapic.html)。

## License

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