shibing624/macbert4csc-base-chinese on Ascend NPU

1. 简介

本文档记录 shibing624/macbert4csc-base-chinese 中文拼写纠错（CSC, Chinese Spelling Correction）模型在昇腾 NPU（Ascend 910B3）上的迁移适配、精度评测与性能验证结果。

MacBERT（MLM as Correction BERT）是哈工大 SCIR 实验室提出的创新性中文纠错方案。核心思想是将 CSC 任务转化为 Masked Language Model（MLM）任务：对输入句子中检测到的疑似错字位置进行掩码，通过 BERT 的 token 级词汇预测找回正确字符。该模型为 BertForMaskedLM（BERT-base，12 层 768 维），输出每个位置在 21128 个中文 token 上的概率分布。

适配中的关键坑：该模型是 MLM 模型（非 sequence classification），使用分类模板会得到 6.42% 误差（FAIL），需要使用 MLM logits 展平比较方式。

相关获取地址：

• 权重下载地址（HuggingFace）：https://huggingface.co/shibing624/macbert4csc-base-chinese

2. 验证环境

• NPU：8 × Ascend 910B3

3. 部署使用流程

3.1 环境准备

conda create -n shibing624_macbert4csc-base-chinese python=3.11 -y
conda activate shibing624_macbert4csc-base-chinese

pip install torch==2.8.0 torch_npu==2.8.0.post4 \
    -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install transformers numpy \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

3.2 推理脚本使用

python inference.py --text "今天天气很好。" --device npu

编程接口：

from inference import main
# MacBERT 展示每个位置的 Top-5 预测字符

4. Smoke 验证

python inference.py --text "今天天气很好。" --device npu

预期输出：每个 token 位置的 Top-5 预测字符，无运行时错误。

5. 性能参考

测试条件：4 条中文句子，比 encoder 前向传播时间。

6. 精度评测

6.1 评测方法

比较 MLM logits（model(**inputs).logits，shape (batch, seq_len, 21128)）展平后的余弦相似度。MLM 在每个 token 位置输出完整 21128 词表的概率分布，展平后向量维度约为 seq_len × 21128（10-30 万维）。

6.2 评测结果

结论：精度误差率 0.0003%，PASS。

7. 迁移适配说明

7.1 模型结构

• Backbone：BertForMaskedLM（BERT-base，12 层，768 维）
• MLM Head：768 → 21128（中文词表大小）
• Tokenizer：BERT WordPiece（vocab.txt），中文按字符分词
• 参数量：约 110M

7.2 适配要点

1. 使用 AutoModelForMaskedLM.from_pretrained()（非 SequenceClassification）
2. 关键差异：分类模板会导致 6.42% 误差 FAIL，必须使用 MLM 专用评测脚本
3. 输出 logits shape 为 (batch, seq_len, 21128)，展平后比较余弦相似度
4. model.to("npu:0") 迁移

7.3 关键代码

import torch, torch_npu
from transformers import AutoModelForMaskedLM, AutoTokenizer

model = AutoModelForMaskedLM.from_pretrained(
    "macbert4csc-base-chinese"
).to("npu:0")
tokenizer = AutoTokenizer.from_pretrained("macbert4csc-base-chinese")

text = "今天天气很好。"
inputs = tokenizer(text, return_tensors="pt")
inputs = {k: v.to("npu:0") for k, v in inputs.items()}

with torch.no_grad():
    logits = model(**inputs).logits  # (1, seq_len, 21128)
    top5 = torch.topk(logits[0], 5, dim=-1).indices
    predictions = [tokenizer.decode(ids) for ids in top5]

8. 注意事项

1. MLM 非分类模型：MacBERT 是 BertForMaskedLM，不是 BertForSequenceClassification。这是适配过程中最重要的教训——错误使用分类模板导致 FAIL（6.42% 误差）。
2. CSC 使用流程：完整纠错需两步：(a) 检测：通过混淆集或语言模型找出疑似错字位置；(b) 纠正：对疑似位置掩码后送入 MacBERT 预测正确字符。本适配仅验证模型推理精度。
3. 中文按字分词：tokenizer 将中文按字符切分（"天气" → ["天", "气"]），每个汉字一个 token。MLM 在字符粒度上进行预测。
4. 输出维度大：MLM 输出为 (seq_len, 21128)，评测时展平向量约 10-30 万维。MAE 会略高于分类模型（0.0002 vs 0.000001），但余弦相似度和 token 匹配率高。
5. 首次 NPU 推理：BERT-base 12 层预热约 3-5 秒。