Body Locator · mmBERT-4096

在一条「带脚手架的长回复」里找出正文区间。输入整条回复(可能包含 <dream_plot> 之类的设定块、<Status_block> 之类的状态块、结尾选项块等),输出正文那一段连续的字符区间 [start, end)。不是逐 token 分类,也不改写文本:text[start:end] 就是正文原文。

  • 基座:alphaedge-ai/mmBERT-small-zho-32768(ModernBERT,54.8 M 参数 / hidden 384 / 22 层 / vocab 32768)。本模型 57.5 M 参数(多了全局块、字符嵌入和起止头)。
  • 同一份权重三种精度:best.pt(fp32,230 MB)、best_fp16.pt(115 MB)、best_int8.pt(97 MB),外加分词器和推理代码。
  • 只传了最好的那一轮:不含 last.pt、优化器状态、训练日志和历史预测。原始训练产物 660 MB,其中约 430 MB 是 AdamW 的一、二阶矩,推理用不到,已剥离。
  • 清洗后子集上重训的版本见 GoForceX/body-locator-small-v1-curated。

输入 / 输出

输入 一条完整回复的 UTF-8 文本(原样,不要先 strip / 重排换行)
输出 一个非空连续区间 [start, end),坐标是原始 Unicode 码点偏移,右端不含
长度上限 8,192 个去重 token(约 1.1 万汉字);超限直接报错,不截断、不降级
解码 在所有非空区间上做精确 MAP(线性复杂度),必得一个非空区间

坐标可以直接用于切片,例如 body = text[start:end]。需要按消息范围先裁切时传 target_span,返回的坐标仍然落在原文坐标系里。

快速开始

# 1) 取回仓库(三种精度全拿约 440 MB;只要 fp16 可加 --include "best_fp16.pt" 等)
hf download GoForceX/body-locator-small-v1 --local-dir body-locator-small-v1
cd body-locator-small-v1

#    只要小体积权重时:
#    hf download GoForceX/body-locator-small-v1 --local-dir body-locator-small-v1 \
#      --include "best_fp16.pt" "infer.py" "checkpoint.py" "model.py" "encode.py" \
#                "structure.py" "transition.py" "span.py" "data.py" "tokenizer/*"

# 2) 装依赖(Python >= 3.10;有 GPU 会自动用 CUDA,否则 CPU 也能跑)
python -m pip install -r requirements.txt

# 3) 预测,输出正文到文件
python predict.py --checkpoint best.pt --input examples/example_input.txt --output body.txt
# => {"span": [151, 448], "char_count": 718, "output": "body.txt"}

infer.py 是同一套逻辑的另一种入口,不落盘、直接回显结果:

python infer.py --checkpoint best_fp16.pt --input examples/example_input.txt   # 换权重即可

权重怎么选

文件 存储精度 体积 推理 说明
best.pt fp32 230 MB CPU/GPU 参考权重,DEV Exact 307/328
best_fp16.pt fp16 115 MB CPU/GPU 权重减半;载入后默认按 fp32 计算,DEV 全部预测与 best.pt 逐条一致
best_int8.pt int8(Linear 动态量化) 97 MB 仅 CPU 更快更小,但边界分数有量化漂移,Exact 会掉(见下方「精度与体积」)

三个文件共用同一套代码,--checkpoint 换文件名即可。fp16 想真正以半精度跑(省显存、GPU 更快):

locator = BodyLocator("best_fp16.pt", device="cuda", dtype="float16")   # CPU 上会拒绝 half
python infer.py --checkpoint best.pt --input examples/example_input.txt
# => {"span": [151, 448], "char_count": 718, "token_count": 522, "chunk_count": 1, "time_ms": 319}

Python API

from infer import BodyLocator

locator = BodyLocator("best.pt")            # 只加载一次,之后复用
result = locator.locate(text)               # text 是整条回复的原始字符串

print(result["span"])   # [151, 448]
print(result["body"])   # 正文原文,等于 text[151:448]

locate() 返回:

字段 含义
span [start, end),原始 Unicode 码点坐标
body text[start:end],即正文
text 回传输入原文,方便直接切片
char_count / token_count / chunk_count 字符数、去重 token 数、内部窗口数
time_ms 本次编码 + 前向 + 解码耗时

其他参数:

result = locator.locate(text, target_span=(1200, 5000))   # 只在指定范围内找正文,坐标仍是全文坐标
result = locator.locate(text, max_total_tokens=0)         # 放开 token 上限(显存/内存够才关)
locator = BodyLocator("best.pt", device="cpu")            # 强制 CPU

读文件时务必用 newline="",否则 CRLF 会被规范化成 LF,偏移就对不上了:

with open("reply.txt", encoding="utf-8", newline="") as f:
    text = f.read()

文件清单

文件 作用
best.pt 权重 + 完整 config + train_settings(DEV Exact 最优)
tokenizer/ 快分词器,离线可用,无需再下载基座
infer.py 推荐入口:BodyLocator 类 / 模块级 locate() / 命令行
predict.py 原包 CLI,参数与上面一致,输出正文到文件
checkpoint.py 读取 checkpoint,按内置 encoder config 复原网络(不联网)
model.py transition.py span.py 网络结构、边界修正、区间 NLL 与 MAP 解码
encode.py structure.py data.py 字符覆盖编码、20 维结构特征、前向输入组装
config.json 架构、训练设置、DEV 指标汇总
examples/example_input.txt 合成的示例输入(含设定块 + 正文 + 结尾选项块)

模型结构

  1. 局部编码:mmBERT 以 4096 token 窗口、128 重叠切块,逐块得到 token 表示。
  2. 全局块摘要:每块的 [CLS] 与掩码均值池化拼成摘要,过 2 层双向 RoPE Transformer(无因果掩码),得到块级全局上下文,再广播回 token。
  3. 字符间隙表示:每个 Unicode 字符间隙取左右两侧的 token 表示(left_proj / right_proj 各 128 维)、左右字符哈希嵌入(24 维 ×2)、10 维字符类别标志,拼接后经 1×1 投影 + 两层 kernel=5 的残差卷积。
  4. 起止头 + 边界修正:128 维间隙表示上各接一个线性头得到 start_logits / end_logits;同时用前后 8 / 64 个间隙的均值表示与 20 维结构特征(空白、换行、标点、括号、标签、围栏、标题、水平线)经 TransitionScorer 输出修正量,加到起止分数上。
  5. 训练目标:在所有合法非空区间上用联合负对数似然归一化(log_partition 精确计算);解码用 cummax(start) + end 取 MAP。

训练与指标

逐字节沿用原划分:TRAIN 5,729 / DEV 329 / TEST 306 篇。4 个 epoch,lr=2e-4、encoder_lr=1e-5、端到端微调、梯度检查点 + 4 步累积。

DEV(329 篇中 328 篇可评估,1 篇超过 8,192 token 预算):

指标 数值
Exact(起止全对) 307 / 328 = 93.60%
带跳过计错的 Exact 93.31%
覆盖率 99.70%
正文字符 F1 0.9946
误删正文 2,824 字
误留非正文 4,525 字
误删 ≥ 100 字 / ≥ 1,000 字 5 篇 / 1 篇
误删最多 5 篇合计 2,760 字

同口径 V5 基线为 295/324 Exact、误删 5,432 字、误留 6,790 字。选模型时先看 Exact,同分比字符 F1;上线更应关注误删。

精度与体积:fp16 / int8

三个权重是同一份参数的三种存储精度,解码逻辑完全相同。本机(CPU,无 GPU)实测前 40 篇 DEV:

文件 精度 体积 与 fp32 预测一致 说明
best.pt fp32 230 MB — 参考权重,前 40 篇命中 39/40(唯一漏的 real-dev-000008 预测 [25, 2408),gold [9, 2408))
best_fp16.pt fp16 存储 115 MB 40/40 载入后仍按 fp32 计算,边界决策与 fp32 逐条相同;只省体积
best_int8.pt int8(Linear 动态量化) 97 MB 36/40(90%) 4 篇偏差:3 篇起止差 6–26 字,1 篇起点被拉到 0(把整段脚手架当正文)

结论:**要稳定边界就用 best.pt 或 best_fp16.pt**;best_int8.pt 适合"体积/CPU 速度优先、能接受偶发边界漂移"的场合。int8 量化只改 encoder 里的 nn.Linear,不改 8,192 token 上限,也不能在 CUDA 上跑(量化算子是 CPU 实现)。

已知限制

  • 中文 RP / 长回复场景训练出来的模型,其他文体(邮件头、论坛签名等)可以跑通但精度不保证。
  • 长度硬上限 8,192 token,超过直接抛 TokenLimitError,不做截断。
  • 只输出一个连续区间;正文被脚手架块切开的多段情形会被合并覆盖。
  • 空格、CRLF、emoji 等全部按码点计数,--target-turn / target_span 也用码点坐标。
  • 空字符串、非法区间会抛 ValueError。

许可与数据

未附许可声明(默认保留所有权利),如需商用请先联系作者。训练数据为标注后的真实回复文本,未随仓库发布。

Downloads last month
35
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Model tree for GoForceX/body-locator-small-v1

Finetuned
(2)
this model