xurong123/ChineseErrorDetectorElectra

中文检错前筛模型：背景、训练、改造与结果摘要

本文档概括本仓库在「纠错前筛」方向上的字级检测目标、数据与上游来源、训练与改造过程，以及阶段性评测与性能结论。操作级命令仍以 UPLOAD_AND_TRAIN.txt、CHAR_PIPELINE.txt 为准。

---

1. 背景

工业里完整纠错往往依赖大模型，成本高、延迟大。常见做法是先用轻量模型判断「哪些字在对齐意义上可能有问题」，再决定是否送下游纠错。本仓库主线为 字级 TokenClassification：输入为带错误的 source 与参考 target 对，子词对齐到字后学习 0/1 标签；推理侧用 pipeline_char 等，按字级概率与阈值决定是否触发纠错链路。

任务与 TW-NLP 开源的 ChineseErrorCorrector 生态在数据谱系上一致：覆盖拼写、语法等多类现象；本仓库检测头为 判别式微调，不直接复现其生成式纠错大模型。

---

2. 参考的上游项目与预训练模型

2.1 GitHub（方法、数据谱系与评测语境）

说明	链接
ChineseErrorCorrector（中文拼写+语法纠错平台、论文与模型索引）	https://github.com/TW-NLP/ChineseErrorCorrector

README 中列出 CSC（拼写）、CGC（语法）、Lang8+HSK（混合） 等数据来源；本仓库分层验证集构造与上述谱系对齐（见下文）。

数据集	用途
twnlp/ChinseseErrorCorrectData	约 200 万条对话格式数据；经 prepare_chinsese_errorcorrectdata_jsonl.py 转为 source/target JSONL（本仓库常称 CEC），train 含 train_stage1+train_stage2，validation 对应 val.json。
twnlp/csc_data	拼写类语料（如 train.txt 等），用于分层验证中 spelling 桶抽样。
twnlp/cgc_data	语法类语料（CGED / FCGEC / MuCGEC 及 nacgec_all_type.json 等），用于 grammar 桶抽样。
twnlp/lang8_hsk	官方 README 中的混合语料；当前部分环境下 datasets 无法直接加载，脚本中已做 回退（见改造说明）。

2.3 预训练基座（Hugging Face）

本仓库对外说明与发布用的字级模型，均基于 Chinese ELECTRA 判别器 微调：

模型	Hugging Face ID
Chinese ELECTRA（判别器）	hfl/chinese-electra-180g-base-discriminator

需 Fast tokenizer（return_offsets_mapping=True）。预下载示例：

python download_base_model.py --model_id hfl/chinese-electra-180g-base-discriminator --local_dir pretrained/hfl_chinese-electra-180g-base-discriminator

---

3. 数据与标签

• 训练/验证主 JSONL：由 CEC 转换而来，每行 {"source","target"}；本地常见文件名 data/cec_train.jsonl、data/cec_validation.jsonl。
• 字级标签：char_align.py 对归一化后的 source/target 做 difflib.SequenceMatcher，replace/delete 在 source 上标 1，其余 0；纯 insert 在 target 侧时 source 可能全 0，属规则定义而非实现错误。
• 分层验证集 data/val_task_stratified.jsonl：由 prepare_task_validation_jsonl.py 从 csc / cgc 等抽样，字段含 task（spelling / grammar / mixed）与 corpus。mixed 在 Lang8 不可用时自动回退为 cec_validation.jsonl 抽样，并在 corpus 中标注 mixed_fallback:cec_validation.jsonl。

---

4. 训练过程（字级，ELECTRA）

• 脚本：train_char.py；基座 --model_name_or_path 指向 hfl/chinese-electra-180g-base-discriminator（本地目录或 Hub id 均可）。
• 任务：TokenClassification，Fast tokenizer + offset_mapping 对齐到字。
• 类别不平衡：类权重、可选 class_weight_cap；损失可选 加权 CE 或 Focal（CharTokenTrainer）；可选 neg_subsample_keep、err_weight_mult。
• 选优：trainer_metrics.py 与 Trainer 的 eval_* 对齐（如 metric_for_best recall）。
• 评测：evaluate_char.py；上线：pipeline_char.py（整句是否送纠错由 max(p_ERR) 与 sentence_threshold 决定，见 evaluate_char --sweep_sentence）。
• 命令备忘：见 TRAIN_CHAR_ELECTRA.txt。

4.1 验证集用法

• 随机划分：默认 train_char.py 内 train_test_split。
• 固定分层验证：--val_jsonl data/val_task_stratified.jsonl，训练仍用全量 cec_train.jsonl。
• 按 task 分层划分：训练 JSONL 含 task 列时 --stratify_val_by_task（与 --val_jsonl 互斥）。

---

5. 改造过程（相对「仅 CEC + 单验证集」的基线）

方向	内容
验证与任务	prepare_task_validation_jsonl.py：按 spelling/grammar/mixed 分层抽样；evaluate_char.py --by_task 分任务报表。
门控阈值扫描	evaluate_char.py --sweep_sentence：对每句 max(p_ERR) 扫阈值，推荐 pipeline_char --sentence_threshold；曾修复 sent_max_p 未定义的 NameError。
损失与目标	Focal、err_weight_mult、neg_subsample_keep 等，便于拉高错字 recall，需与阈值/业务容忍度一起调。
推理吞吐	char_inference.forward_char_preds_batch：padding batch 前向；benchmark_char_inference.py、pipeline_char.py、evaluate_char.py 均支持 batch_size。
Lang8 回退	lang8_hsk 加载失败时自动用 cec_validation.jsonl 补 mixed 桶，保证分层验证可跑通。

---

6. 结果摘要（阶段性，非最终产品指标）

以下数值来自实际跑通的分任务验证与测速，仅作阶段记录；换数据、随机种子、checkpoint 会变，另外项目仅开放上传了ELECTRA训练出来的结果。

6.1 字级整体（全 task 混合，TokenClassification argmax）

指标	ELECTRA	MacBERT	更优
n_tokens	360006	360006	-
accuracy	0.908	0.913	MacBERT
precision	0.256	0.264	MacBERT
recall	0.822	0.797	ELECTRA
F1	0.391	0.396	MacBERT（差距很小）

6.2 字级按 task（更清晰对照）

6.2.1 spelling（99500 tokens）

指标	ELECTRA	MacBERT	更优
accuracy	0.981	0.977	ELECTRA
precision	0.611	0.568	ELECTRA
recall	0.986	0.984	ELECTRA
F1	0.754	0.720	ELECTRA

6.2.2 grammar（128877 tokens）

指标	ELECTRA	MacBERT	更优
accuracy	0.889	0.894	MacBERT
precision	0.214	0.225	MacBERT
recall	0.823	0.838	MacBERT
F1	0.339	0.355	MacBERT

6.2.3 mixed（131629 tokens）

指标	ELECTRA	MacBERT	更优
accuracy	0.872	0.883	MacBERT
precision	0.206	0.210	MacBERT
recall	0.732	0.662	ELECTRA
F1	0.322	0.319	ELECTRA（差距很小）

解读： spelling 子集（ELECTRA 在 F1/precision 上更高）；grammar MacBERT 略高；mixed 上 ELECTRA 召回更高。全混合 F1 不宜单独代表拼写能力。

6.3 句级 max(p_ERR) 分布（按金标是否含错字）

金标	n	mean(E)	mean(M)	p50(E)	p50(M)	p90(E)	p90(M)
无错句	2200	0.710	0.686	0.805	0.782	0.980	0.973
有错句	5300	0.939	0.923	0.986	0.983	0.9997	0.9999

6.4 门控阈值扫（need_correct := max_p_err >= thr，target_recall_used=0.9）

规则	threshold(E)	precision(E)	recall(E)	F1(E)	threshold(M)	precision(M)	recall(M)	F1(M)
best F1	0.70	0.787	0.946	0.859	0.70	0.794	0.923	0.854
recall≥0.9 下 precision 尽量高	0.80	0.811	0.908	0.857	0.75	0.803	0.904	0.850

6.5 推理速度（示例：ELECTRA 字级、A100、batch 推理）

• 在 batch_size=1024、max_length=256、约 1.4 万句 的基准下，曾测得约 108 句/秒、约 9.3 ms/句（纯 GPU 推理循环，不含线上 I/O）。
• 小样本、非 batch 测得的吞吐 不能代表稳态；应以 大批量 + 合理 warmup 为准（见 benchmark_char_inference.py）。

---

---

7. 仓库内文档与入口

文件	作用
UPLOAD_AND_TRAIN.txt	打包、环境、命令总览
CHAR_PIPELINE.txt	字级流水线、测速、batch 说明
TRAIN_CHAR_ELECTRA.txt	ELECTRA 字级训练示例
PIPELINE_AND_RESULTS.md	阈值、指标解读、文件速查
PROJECT_OVERVIEW.md	本文：背景、参考、字级训练/改造/结果总览
HUGGINGFACE_PUBLISH.md	将微调权重与模型卡片发布到 Hugging Face Hub 的步骤与 README 模板

若要把服务器上的 **char_detector_electra.tar.gz**（或解压后的 save_pretrained 目录）做成 新的 HF Model 项目，按 HUGGINGFACE_PUBLISH.md 操作即可；模型页 README.md 可与本文指标、基座说明保持一致。

---

8. 引用与致谢

方法与数据谱系主要参考 TW-NLP 的 ChineseErrorCorrector 项目及其公开的 Hugging Face 数据集与模型卡片；预训练骨干为 哈工大 HFL 发布的 Chinese ELECTRA（discriminator）。具体论文与引用格式见上游与 ELECTRA 模型页 相关说明。