不用纯规则#

论文里确实有很多强格式信号：关键词： 开头的多半是关键词段、图 1.1 开头的是图注、[1] 开头的是参考文献条目。这些都用规则处理，而且比模型可靠得多。

但”这是一级标题还是二级标题”没有可靠规则。有的论文写 1 绪论，有的写 第一章 绪论，有的干脆不编号。规则会迅速退化成一张越来越长的正则表，而且互相打架。

不用大模型#

调用 API 的问题很明显：论文通常是未发表的，走外部服务有隐私顾虑；很多高校场景在内网离线环境；再加上逐段调用几十上百次，成本和延迟都不合适。

用小 BERT#

最终选择是 uer/chinese_roberta_L-4_H-256 —— 只有 4 层、隐藏维度 256 的极小 RoBERTa，量化到 int8 后 8.6MB，CPU 上就能跑。

理由是这个任务本身不难：分类依据主要是段落的形式特征（开头词、有没有编号、句子结构），不需要模型理解深层语义。用大模型是浪费。

这里有个关键判断：这是个分类问题，不是生成问题。 一旦认清这一点，就不需要 LLM。

问题#

逐段独立分类会丢掉一个强信号：论文结构是序列相关的。摘要标题后面大概率是摘要内容，参考文献标题后面大概率是参考文献条目。只看当前段落，这些上下文全浪费了。

方案：把上一段的标签塞进输入#

没有上序列模型（CRF / BiLSTM），而是用了一个很取巧的办法：把上一段的标签作为文本前缀拼进输入。

训练时，每条样本的格式是：

1
[PREV=heading_level_1] 1.1 研究背景

推理时用完全相同的格式拼接：

1
def _prompt(prev_label: Optional[str], text: str) -> str:
2
    """拼接 PREV 上下文前缀，与训练侧 PREV_PREFIX 格式严格一致。"""
3
    return f"[PREV={prev_label}] {text}"

首段的 prev_label 是 None，拼出来就是 [PREV=None] 论文题目。

这样模型看到的输入里就带上了结构上下文，而代价只是文本长了十来个 token。

两个必须注意的细节#

第一，推理时用的是”预测标签”而不是真值。

真值只有训练时才有。推理时必须拿上一段的预测结果去拼下一段的输入 —— 这就构成了一条状态链，也意味着误差会沿链传播：前面一段判错，可能把后面几段一起带偏。

这是典型的 exposure bias（训练时见真值、推理时见预测）。在这个任务里可以接受，因为绝大多数段落分类是高置信的，链断掉的概率不高；而且它确实带来了显著的收益。

第二，批量推理和状态链是冲突的。

批量推理要求整个 batch 一次算完，但 batch 内每个样本的 PREV 理论上都不同（取决于前一段的预测结果）。实际做法是：整个 batch 共享同一个 PREV 上下文（即 batch 首段之前的标签），每个 batch 结束后返回末段的预测标签，作为下一个 batch 的初始 PREV。

1
def onnx_batch_infer(texts, prev_label=None):
2
    """批量推理。整个 batch 共享同一 PREV 上下文（跨批链由调用方推进），
3
    返回 (结果列表, 本批末段的预测标签)。"""

外层再包一个 onnx_batch_infer_safe，负责自动分片并跨分片维护状态链。

这是在”批量吞吐”和”上下文精度”之间取的折中：batch 内退化成无上下文，batch 间保持链式。把 BATCH_SIZE 从 32 调大能提速，但会削弱上下文效果 —— 这个参数需要按实际场景权衡。

现象#

为了让长尾类别（样本不足的类别）补齐形态，我们用规则模板 + 词表组合合成了 880 条训练数据，重训后留出集准确率从 96.27% 涨到 98.11%，长尾类别 abstract_chinese_content 从 20% 直接到 100%。

看起来皆大欢喜。但端到端跑真实文档时出问题了：某篇论文的 4 段绪论正文被吸进了”中文摘要内容”类别。

被误判的段落长这样：

紧跟人工智能和大数据技术的发展步伐，围绕智能电网……

根因#

摘要的开场句和绪论首段在词面上本质同构。两者都常用”随着……的发展""本文针对……”这类句式。模型只看文本，没有任何依据区分它们 —— 无论是合成数据还是真实数据都救不了，因为问题不在数据量，在于信息不足。

继续加合成数据已经没有边际收益了。

解法：位置门控#

真正的约束是位置：摘要内容只可能出现在摘要标题之后。

于是在后处理链里加了一条规则：

1
_gate_abstract_content(result)
2
# 规则：abstract_chinese_content / abstract_english_content
3
#       的相邻上一段必须是摘要标题或摘要内容，否则回退 body_text

一条几行的规则，把 4 段绪论全部归位，摘要内容从误判的 6 段修正回真实的 2 段。

教训#

模型负责语义，规则负责结构位置，这条边界要划清楚。

当模型面对的信息不足以区分两个类别时，不要继续喂数据 —— 先想清楚这个区分到底需要什么信息。如果那个信息不在文本里（而在文档结构中），那么它就不该由模型来学。

这条链的代价#

规则确实有效 —— 它们把留出集 98% 的模型准确率，在端到端场景里推到了可用的程度。

但代价是：这 12 步规则和”学术论文”这个领域强绑定。 _apply_section_state 靠”参考文献""致谢”这些标题词驱动，_gate_abstract_content 靠”摘要”这个概念存在。换个文体（比如公文），它们不是”不生效”，而是会产生错误的负收益。

这也是项目当前面临的主要架构问题：这些领域知识散落在核心解析代码里，没有一个可替换的边界。改进方向是把「类别体系 + 阈值 + 后处理规则 + 模型权重」打成一个可替换的整体单元，而不是继续往这条链上加规则。

7.1 节点-段落错位：zip 的静默失败#

这是最典型的一个。

阶段二需要把”结构树里的节点”和”文档里的段落”对应起来。做法是按位置顺序 zip：

1
for node, para in zip(nodes, paragraphs):
2
    node.paragraph = para

问题在于：只要两者数量不等，zip 不会报错，它会静默截断。而一旦数量不等，错位不是少一个，是后面全部前移一位 —— 每个节点都套用了邻居的段落。

症状非常诡异：

• 正文被加上了 图1.1 的前缀（图注的编号规则套到了正文上）
• 中文关键词的批注出现在论文题目上
• 标题层级规则作用到了参考文献上

排查了很久才定位到根因之一：前端在数据层过滤掉了 figure_image 占位节点，导致前端看得到的节点数比后端实际生成的少。前端为了”列表干净”做了一次过滤，代价是整个对齐关系崩了。

修复分两头：

1
if len(nodes) != len(paragraphs):
2
    raise ValueError(
3
        f"当前文档({len(paragraphs)} 段)与节点 JSON({len(nodes)} 节点)不一致，"
4
        "两者必须一一对应。可能是生成节点后又换过文档，"
5
        "或页面版本过旧（旧版会过滤占位节点）。"
6
        "请刷新页面后重新上传文档并点击「生成节点JSON」，再执行格式化。"
7
    )

• 后端：数量不等直接报错，并给出可操作的指引，绝不容忍静默错位；
• 前端：过滤从数据层挪到显示层，占位节点照常存在，只是不显示。

教训：在”按位置对齐”这个前提下，任何一方悄悄改变元素数量都是灾难。 而且这类 bug 的症状离根因非常远，会浪费大量排查时间 —— 所以宁可显式崩溃，也不要静默降级。

7.2 一个阈值管不了 22 个类#

早期的前端用一个全局阈值判断”这个分类结果可不可信”：SCORE_THRESHOLD = 0.8。

结果是 UI 上满屏”阈值过低”的告警。原因是不同类别的置信度分布差异极大：body_text 这种主力类别经常 0.99，而 heading_fulu（附录标题）这种长尾类别普遍偏低。

用一个从模型分数分布里实测出来的分级阈值表替代：

1
# 以留出集上"每类正确段"的 p10 分为准分档（0.35 ~ 0.6）
2
CONF_THRESHOLDS = {
3
    body_text: 0.6,
4
    heading_level_1: 0.6,
5
    ...
6
    abstract_english_content: 0.35,
7
    heading_fulu: 0.35,
8
    default: 0.5,
9
}

效果很直接：

教训：置信度分布是类别相关的，全局阈值必然错。 而且阈值不该拍脑袋定，要从留出集的真实分数分布里取分位数。

7.3 体积：69MB → 6MB#

1.6.1 之前，发布包体积异常膨胀到 69MB。

根因在打包配置：package-data 用了通配表达式 data/**/*，把整个目录无差别收进包里。开发过程中旧模型（99MB 的旧 BERT、中间 checkpoint、fp32 原件）在磁盘上留有残留，于是全被打进了发布包。

修复用了三层防御：

1
[tool.setuptools.package-data]
2
# 只收集明确清单，绝不使用 `data/**/*` 通配收集整个目录：
3
# 磁盘上残留的旧模型（bert_paragraph_classifier.onnx 等）会被无差别打进包。
4
wordformat = [
5
    "data/model/*_int8.onnx",
6
    "data/model/id2label.json",
7
    ...
8
]

1. package-data 从通配收窄为显式白名单；
2. CI 移除模型缓存与下载步骤，避免旧模型经构建缓存混入；
3. 新增 MANIFEST.in 防御 sdist 混入开发资产。

结果：69MB → 6MB。

顺带把 download_model.py 从”下载脚本”退役成”模型存在性检查”，并在里面留了守卫逻辑 —— 任何人误运行它，只会得到一句提示，不会真的去拉那个 99MB 的旧模型。

教训：打包配置必须显式。通配符会收集你没打算发布的东西，而且这个问题在开发机上永远不会暴露。