wtpsplit🪓

对任意文本进行分段——稳健、高效、可适应⚡

本仓库允许您将文本分割成句子或其他语义单元。它实现了以下模型：

• SaT — Segment Any Text: 一种稳健、高效且可适应的通用句子分割方法，作者为Markus Frohmann、Igor Sterner、Benjamin Minixhofer、Ivan Vulić 和 Markus Schedl（当前最先进，推荐使用）。
• WtP — 句号在哪里？自监督多语言无标点符号依赖的句子分割，作者为Benjamin Minixhofer、Jonas Pfeiffer 和 Ivan Vulić（旧版本，为保证结果可复现而保留）。

出于一致性考虑，沿用了“WtP”这一名称。我们的新模型 SaT 在 85 种语言上提供了更稳健、高效且可适应的句子分割功能，同时性能更高、计算成本更低。请参阅我们在 Segment any Text 论文 中展示的在 8 个不同语料库和 85 种语言上的最先进结果。

安装

pip install wtpsplit

或者，如果您需要 ONNX 支持，可以安装以下任一选项：

pip install wtpsplit[onnx-gpu]
pip install wtpsplit[onnx-cpu]

使用方法

from wtpsplit import SaT

sat = SaT("sat-3l")
# 可选：在 GPU 上运行以获得更好的性能
# 也支持 TPU，例如通过 sat.to("xla:0")；此时需将 pad_last_batch 参数设为 True
sat.half().to("cuda")

sat.split("这是一个测试 这是另一个测试。")
# 返回 ["这是一个测试 ", "这是另一个测试。"]

# 为了提升性能，建议不要逐个调用 sat.split 对每段文本进行处理，而是直接传入文本列表：
sat.split(["这是一个测试 这是另一个测试。", "还有一些其他的文本..."])
# 返回一个迭代器，依次生成每段文本对应的句子列表

# 对于一般的句子分割任务，可以使用 '-sm' 模型：
sat_sm = SaT("sat-3l-sm")
sat_sm.half().to("cuda") # 可选，参考上述说明
sat_sm.split("这是一个测试 这是另一个测试")
# 返回 ["这是一个测试 ", "这是另一个测试"]

# 如果需要针对特定语言或领域/风格进行强适应性调整，可以使用经过微调的 LoRA 模块：
sat_adapted = SaT("sat-3l", style_or_domain="ud", language="en")
sat_adapted.half().to("cuda") # 可选，参考上述说明
sat_adapted.split("这是一个测试 这是另一个测试。")
# 返回 ['这是一个测试 ', '这是另一个测试']

ONNX 支持

🚀 现在您可以为 sat 和 sat-sm 模型启用更快的 ONNX 推理！🚀

sat = SaT("sat-3l-sm", ort_providers=["CUDAExecutionProvider", "CPUExecutionProvider"])

>>> from wtpsplit import SaT
>>> texts = ["这是一句话。这又是另一句话。"] * 1000

# PyTorch GPU
>>> model_pytorch = SaT("sat-3l-sm")
>>> model_pytorch.half().to("cuda");
>>> %timeit list(model_pytorch.split(texts))
# 144 ms ± 252 μs 每循环（7 次运行，每次 10 次循环的平均值 ± 标准差）
# 已经相当快了，但...

# onnxruntime GPU
>>> model_ort = SaT("sat-3l-sm", ort_providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
>>> %timeit list(model_ort.split(texts))
# 94.9 ms ± 165 μs 每循环（7 次运行，每次 10 次循环的平均值 ± 标准差）
# ...这应该会快约 50%！（在 RTX 3090 上测试过）

如果您希望将 LoRA 与 ONNX 模型结合使用：

• 运行 scripts/export_to_onnx_sat.py，并将 use_lora 设置为 True，同时指定合适的 output_dir: <OUTPUT_DIR>。
  • 如果您已有本地的 LoRA 模块，请使用 lora_path。
  • 如果您希望从 Hugging Face Hub 加载 LoRA 模块，则使用 style_or_domain 和 language。
• 加载已合并 LoRA 权重的 ONNX 模型： sat = SaT(<OUTPUT_DIR>, onnx_providers=["CUDAExecutionProvider", "CPUExecutionProvider"])

可用模型

如果您需要一个通用的句子分割模型，建议使用 -sm 模型（如 sat-3l-sm）。对于对速度敏感的应用场景，我们推荐 3 层模型（sat-3l 和 sat-3l-sm），它们在速度和性能之间取得了很好的平衡。而性能最佳的则是我们的 12 层模型：sat-12l 和 sat-12l-sm。

模型	英语得分	多语言得分
sat-1l	88.5	84.3
sat-1l-sm	88.2	87.9
sat-3l	93.7	89.2
sat-3l-lora	96.7	94.8
sat-3l-sm	96.5	93.5
sat-6l	94.1	89.7
sat-6l-sm	96.9	95.1
sat-9l	94.3	90.3
sat-12l	94.0	90.4
sat-12l-lora	97.3	95.9
sat-12l-sm	97.4	96.0

以上分数分别为“英语”和“多语言”类别下的宏平均 F1 分数，分别基于所有可用数据集计算得出。“adapted”表示通过 LoRA 进行适配；详细信息请参阅 论文。

作为对比，以下是其他一些工具的英语得分：

模型	英语得分
PySBD	69.6
SpaCy（单语句分割器）	92.9
SpaCy（多语句分割器）	91.5
Ersatz	91.4
Punkt (nltk.sent_tokenize)	92.2
WtP (3l)	93.9

请注意，本库同样支持之前的 WtP 模型。您可以以与 SaT 模型基本相同的方式使用它们：

from wtpsplit import WtP

wtp = WtP("wtp-bert-mini")

# 与 SaT 模型类似的功能
wtp.split(“这是一个测试 这是另一个测试。”)

有关 WtP 的更多详细信息以及复现细节，请参阅 WtP 文档。

段落分割

由于 SaT 模型经过训练可以预测换行概率，因此除了句子之外，它们还可以将文本分割成段落。

# 返回一个段落列表，每个段落包含一个句子列表
# 可通过 `paragraph_threshold` 参数调整段落阈值。
sat.split(text, do_paragraph_segmentation=True)

（新增！v2.2+）长度约束分割

使用 min_length 和 max_length 参数控制片段长度。这在需要将文本分割为特定大小限制的片段时非常有用（例如，用于嵌入模型、存储或下游处理）。

基本用法

from wtpsplit import SaT

sat = SaT("sat-3l-sm")

text = (
    "起初，上帝创造了天地。 地是空虚混沌，渊面黑暗；上帝的灵运行在水面上。 上帝说：‘要有光！’于是就有了光。 上帝看着光，觉得甚好；于是将光与暗分开。 上帝称光为昼，称暗为夜。 这样，就有了晚上和早晨，这是第一天。"
)

# 将文本按最大片段长度 120 字符进行分割
segments = sat.split(text, max_length=120)
for i, s in enumerate(segments):
    print(f"[{len(s):3d} 字] {s}")
# [ 55 字] 起初，上帝创造了天地。
# [ 86 字] 地是空虚混沌，渊面黑暗。
# [112 字] 上帝的灵运行在水面上。上帝说：‘要有光！’于是就有了光。
# [ 86 字] 上帝看着光，觉得甚好；于是将光与暗分开。
# [115 字] 上帝称光为昼，称暗为夜。这样，就有了晚上和早晨，这是第一天。

assert "".join(segments) == text  # 文本被完整保留

# 同时强制最小和最大长度
sat.split(text, min_length=80, max_length=200)

# 使用贪心算法以获得更快但次优的结果
sat.split(text, max_length=120, algorithm="greedy")

长度偏好先验

使用先验来影响片段长度分布。可用的先验包括：

先验	最佳用途
"uniform"（默认）	只强制最大长度，让模型自行决定
"gaussian"	偏好接近目标长度的片段（直观）
"lognormal"	右偏偏好（对较长片段更宽容）
"clipped_polynomial"	必须非常接近目标长度

# 高斯先验（推荐）：偏好接近目标长度的片段
sat.split(text, max_length=100，prior_type="gaussian", 
          prior_kwargs={"target_length": 50, "spread": 10})

# 对数正态先验：右偏（对较长片段更宽容）
sat.split(text, max_length=100，prior_type="lognormal", 
          prior_kwargs={"target_length": 70, "spread": 25})

# 截断多项式：在目标长度上下一定范围内硬性截断
sat.split(text, max_length=100，prior_type="clipped_polynomial", 
          prior_kwargs={"target_length": 60, "spread": 25})

语言感知的默认设置

传递 lang_code 参数，即可根据语言特定的语料库统计信息使用语言相关的 target_length 和 spread 默认值：

# 德语的平均句长较长 → 自动使用 target_length=90，spread=35
sat.split(text, max_length=150，prior_type="gaussian", 
          prior_kwargs={"lang_code": "de"})

# 中文的平均句长较短 → 自动使用 target_length=45，spread=15
sat.split(text，max_length=100，prior_type="gaussian", 
          prior_kwargs={"lang_code": "zh"})

当使用 LoRA 并指定语言时，这些设置会自动应用：

sat = SaT("sat-3l", style_or_domain="ud", language="de")
sat.split(text，max_length=150，prior_type="gaussian")  # 自动使用德语默认值

工作原理

维特比算法会找到全局最优的分割点，从而在以下两者之间取得平衡：

• 模型对句子边界的预测（自然分隔的位置）
• 您的长度偏好（通过先验；如果提供）

文本重建：

# 如果有长度约束（max_length 或 min_length）：
original_text = "".join(segments)  # 片段可能包含换行符

# 如果没有长度约束（SaT 默认且 split_on_input_newlines=True）：
original_text = "\n".join(segments)

注意：使用长度约束时，片段可能会包含换行符。如果您希望去除这些换行符，可以在后处理阶段进行清理。

注意：当设置了 max_length 时，threshold 参数将被忽略。维特比/贪心算法会直接使用原始模型概率，而不是基于阈值的过滤。

有关更多信息，请参阅 长度约束文档。

适应性

SaT 模型可以通过 LoRA 技术针对特定领域和风格进行适配。我们为 sat-3l 和 sat-12l 提供了适用于 81 种语言的通用依存关系、OPUS100、Ersatz 和 TED（即 ASR 风格转录演讲）句子风格的训练好的 LoRA 模块。此外，我们还提供了适用于 6 种语言的法律文件（法律和判决）、4 对语言组合中的代码转换以及 3 种语言的推文的 LoRA 模块。有关详细信息，请参阅我们的论文 arXiv:2406.16678。

我们还为 sat-12-no-limited-lookahead 提供了 16 种体裁的诗句分割模块。

加载 LoRA 模块的方式如下：

# 需要同时指定 lang_code 和 style_or_domain
# 可用的模块请查看 <model_repository>/loras 文件夹
sat_lora = SaT("sat-3l", style_or_domain="ud", language="en")
sat_lora.split("你好，这是一个测试。但现在情况不同了。现在下一个开始了，looool")
# 接下来是一个非常不同的领域
sat_lora_distinct = SaT("sat-12l", style_or_domain="code-switching", language="es-en")
sat_lora_distinct.split("早上在那里，每当我讲些什么，他就会回应我。")

您也可以自由调整分割阈值，较高的阈值会导致更保守的分割：

sat.split("这是一个测试 这是另一个测试。", threshold=0.4)
# LoRA 模块同样适用；但其阈值更高
sat_lora.split("你好，这是一个测试。但现在情况不同了。现在下一个开始了，looool", threshold=0.7)

高级用法

获取文本中换行符或句子边界的概率：

# 返回换行符概率（支持批量处理！）
sat.predict_proba(text)

在 HuggingFace transformers 中加载 SaT 模型：

# 导入库以注册自定义模型
import wtpsplit.models
from transformers import AutoModelForTokenClassification

model = AutoModelForTokenClassification.from_pretrained("segment-any-text/sat-3l-sm") # 或者其他模型名称；请参阅 https://huggingface.co/segment-any-text

通过LoRA适配您自己的语料库

我们的模型可以通过LoRA高效且强大地进行适配。仅需10至100个经过分段标注的训练句子，性能即可显著提升。具体操作如下：

克隆仓库并安装依赖项：

git clone https://github.com/segment-any-text/wtpsplit
cd wtpsplit
pip install -r requirements.txt
pip install adapters==0.2.1 --no-dependencies
cd ..

1. 按照以下格式创建数据：

import torch

torch.save(
    {
        "language_code": {
            "sentence": {
                "dummy-dataset": {
                    "meta": {
                        "train_data": ["训练句1", "训练句2"],
                    },
                    "data": [
                        "测试句1",
                        "测试句2",
                    ]
                }
            }
        }
    },
    "dummy-dataset.pth"
)

请注意，单个句子内不应包含换行符！否则会引发错误。列表中的每个条目都应为一个完整的句子，且不得含有\n字符。因此，您的语料库应已预先进行良好的分割。

2. 创建或调整配置文件；通过model_name_or_path指定基础模型，并通过text_path提供训练数据的.pth文件：

configs/lora/lora_dummy_config.json

我们建议从该配置开始，必要时调整model_name_or_path、output_dir和text_path。您也可以根据需要进一步调整adapter_config及批量大小等参数，但这属于实验性内容。

3. 训练LoRA：

python3 wtpsplit/train/train_lora.py configs/lora/lora_dummy_config.json

4. 训练完成后，将保存的模块路径提供给SaT：

sat_lora_adapted = SaT("model-used", lora_path="dummy_lora_path")
sat_lora_adapted.split("一些领域特定或风格化的文本")

重要提示： 推理时使用的模型变体必须与训练时一致（例如，sat-12l-sm和sat-12l的配置不同，基于前者训练的适配器无法加载到后者上）。

请根据您的需求调整上述代码中的数据集名称、语言和模型。

复现论文结果

configs/ 目录下包含了论文中关于基础模型、sm模型以及LoRA模块的运行配置文件。您可以按如下方式分别启动训练：

python3 wtpsplit/train/train.py configs/<config_name>.json
python3 wtpsplit/train/train_sm.py configs/<config_name>.json
python3 wtpsplit/train/train_lora.py configs/<config_name>.json

此外：

• wtpsplit/data_acquisition 包含从mC4语料库获取评估数据和原始文本的代码。
• wtpsplit/evaluation 包含以下代码：
  • 通过 intrinsic.py 进行句子分割结果的内在评估。
  • 通过 intrinsic_pairwise.py 进行短序列评估（即句子对/k-mer的分割结果）。
  • LLM基线评估（llm_sentence.py）、法律基线评估（legal_baselines.py）。
  • 基于PySBD、nltk等工具的基线评估结果见 intrinsic_baselines.py 和 intrinsic_baselines_multi.py。
  • 原始评估结果以JSON格式存储在 evaluation_results/ 中。
  • 统计显著性检验的代码及结果位于 stat_tests/。
  • 标点符号标注实验见 punct_annotation.py 和 punct_annotation_wtp.py（仅适用于WtP）。
  • 机器翻译方面的外在评估见 extrinsic.py（仅适用于WtP）。

请确保提前安装 requirements.txt 中列出的软件包。

支持的语言

支持语言表

iso	名称
af	南非语
am	阿姆哈拉语
ar	阿拉伯语
az	阿塞拜疆语
be	白俄罗斯语
bg	保加利亚语
bn	孟加拉语
ca	加泰罗尼亚语
ceb	宿务语
cs	捷克语
cy	威尔士语
da	丹麦语
de	德语
el	希腊语
en	英语
eo	世界语
es	西班牙语
et	爱沙尼亚语
eu	巴斯克语
fa	波斯语
fi	芬兰语
fr	法语
fy	西弗里斯兰语
ga	爱尔兰语
gd	苏格兰盖尔语
gl	加利西亚语
gu	古吉拉特语
ha	豪萨语
he	希伯来语
hi	印地语
hu	匈牙利语
hy	亚美尼亚语
id	印度尼西亚语
ig	伊博语
is	冰岛语
it	意大利语
ja	日本语
jv	爪哇语
ka	格鲁吉亚语
kk	哈萨克语
km	高棉语
kn	卡纳达语
ko	韩语
ku	库尔德语
ky	吉尔吉斯语
la	拉丁语
lt	立陶宛语
lv	拉脱维亚语
mg	马达加斯加语
mk	马其顿语
ml	马拉雅拉姆语
mn	蒙古语
mr	马拉地语
ms	马来语
mt	马耳他语
my	缅甸语
ne	尼泊尔语
nl	荷兰语
no	挪威语
pa	旁遮普语
pl	波兰语
ps	普什图语
pt	葡萄牙语
ro	罗马尼亚语
ru	俄语
si	僧伽罗语
sk	斯洛伐克语
sl	斯洛文尼亚语
sq	阿尔巴尼亚语
sr	塞尔维亚语
sv	瑞典语
ta	泰米尔语
te	泰卢固语
tg	塔吉克语
th	泰语
tr	土耳其语
uk	乌克兰语
ur	乌尔都语
uz	乌兹别克语
vi	越南语
xh	豪萨语
yi	意第绪语
yo	约鲁巴语
zh	中文
zu	祖鲁语

有关详细信息，请参阅我们的 Segment any Text 论文。

社区移植版本

• Rust: wtsplit-rs 由 @19h 开发

注：社区移植版本由独立维护，可能具有不同的功能集或更新计划。

引用

对于 SaT 模型，请引用我们的论文：

@inproceedings{frohmann-etal-2024-segment,
    title = "分割任意文本：一种鲁棒、高效且可适应的通用句子分割方法",
    author = "Frohmann, Markus 与  Sterner, Igor 与  Vuli{\'c}, Ivan 与  Minixhofer, Benjamin 与  Schedl, Markus",
    editor = "Al-Onaizan, Yaser 与  Bansal, Mohit 与  Chen, Yun-Nung",
    booktitle = "2024年自然语言处理经验方法会议论文集",
    month = nov,
    year = "2024",
    address = "美国佛罗里达州迈阿密",
    publisher = "计算语言学协会",
    url = "https://aclanthology.org/2024.emnlp-main.665",
    pages = "11908--11941"
}

对于该库和 WtP 模型，请引用：

@inproceedings{minixhofer-etal-2023-wheres,
    title = "句号在哪里？自监督多语言无标点符号依赖的句子分割",
    author = "Minixhofer, Benjamin 与  Pfeiffer, Jonas 与  Vuli{\'c}, Ivan",
    booktitle = "第61届计算语言学协会年会论文集（第一卷：长文）",
    month = jul,
    year = "2023",
    address = "加拿大多伦多",
    publisher = "计算语言学协会",
    url = "https://aclanthology.org/2023.acl-long.398",
    pages = "7215--7235"
}

致谢

本研究全部或部分由奥地利科学基金会（FWF）资助，项目编号为 P36413、P33526 和 DFH-23；同时，也得到了上奥地利州以及联邦教育、科学与研究部通过 LIT-2021-YOU-215 资助的支持。此外，Ivan Vulić 和 Benjamin Minixhofer 还获得了英国皇家学会大学研究 fellowship“面向真正多语世界的包容性与可持续语言技术”（编号 221137）的资助。本研究还得到了谷歌 TPU 研究云（TRC）提供的 Cloud TPU 支持。此外，本工作还获得了 Cohere For AI Research Grant 的算力资助，该资助旨在支持学术合作伙伴开展以发布有益的科研成果和数据为目标的研究。我们还要感谢 Simone Teufel 提供的富有成效的讨论。

---

如有任何问题，请提交 issue 或发送邮件至 markus.frohmann@gmail.com，我将尽快回复您。

wtpsplit 快速上手指南

wtpsplit 是一个强大且高效的文本分割工具，支持将任意文本稳健地分割为句子或段落。它基于最新的 SaT (Segment Any Text) 模型，在 85 种语言上实现了业界领先的性能，并支持通过 LoRA 进行领域和风格适配。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上。
• 硬件加速（可选）：
  • GPU：如需加速推理，请确保已安装 NVIDIA CUDA 驱动及对应的 PyTorch GPU 版本。
  • ONNX Runtime：若需极致推理速度，可安装 ONNX Runtime 版本。
• 依赖管理：建议使用 pip 或 conda 管理环境。

提示：国内开发者如遇下载慢的问题，建议在安装命令中指定清华或阿里镜像源。

安装步骤

1. 基础安装

安装标准版本（基于 PyTorch）：

pip install wtpsplit -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 启用 ONNX 加速（推荐用于生产环境）

如果需要更快的推理速度（支持 CPU 或 GPU），请选择以下其一安装：

GPU 加速版：

pip install "wtpsplit[onnx-gpu]" -i https://pypi.tuna.tsinghua.edu.cn/simple

CPU 加速版：

pip install "wtpsplit[onnx-cpu]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 最简单的句子分割

加载预训练模型并进行分割。默认推荐使用 -sm 后缀的模型以获得速度与精度的最佳平衡。

from wtpsplit import SaT

# 初始化模型 (推荐使用 sat-3l-sm)
sat = SaT("sat-3l-sm")

# 可选：启用 GPU 加速 (如果可用)
# sat.half().to("cuda")

text = "This is a test. This is another test."
sentences = sat.split(text)

print(sentences)
# 输出: ['This is a test. ', 'This is another test.']

2. 批量处理（高性能模式）

为了获得最佳性能，请一次性传入文本列表，而不是循环调用。

texts = [
    "First sentence. Second sentence.",
    "Another text block here."
]

# 返回一个迭代器，每个元素是对应输入文本的句子列表
results = sat.split(texts)

for res in results:
    print(res)

3. 进阶功能速览

段落分割 利用模型预测换行符概率的能力，直接将文本分割为段落。

# 返回段落列表，每个段落包含句子列表
paragraphs = sat.split(text, do_paragraph_segmentation=True)

长度约束分割 (v2.2+) 控制分割后的片段长度（例如限制最大字符数），适用于嵌入模型输入或存储限制场景。

# 限制每个片段最大长度为 120 字符
segments = sat.split(text, max_length=120)

领域/语言适配 (LoRA) 加载针对特定语言或风格微调的 LoRA 模块，以获得更高精度。

# 加载针对英语通用依赖树库 (UD) 适配的模型
sat_adapted = SaT("sat-3l", style_or_domain="ud", language="en")
sat_adapted.split("Complex sentence structure...")

模型选择建议

• 通用场景/速度敏感：使用 sat-3l-sm 或 sat-1l-sm。
• 高精度需求：使用 sat-12l-sm 或带 LoRA 适配的模型（如 sat-3l-lora）。
• 多语言支持：所有 sat 系列模型均原生支持 85 种语言。