ChineseErrorCorrector3-4B CSC Eval

这个项目用于直接调用 Hugging Face 上的 twnlp/ChineseErrorCorrector3-4B 模型，对中文拼写纠错（CSC）.txt 数据集做稳定、可复现的推理评测，不包含微调逻辑。

功能

• 直接加载 twnlp/ChineseErrorCorrector3-4B 做推理评测
• 支持单个 .txt 文件、目录下多个 .txt 文件、以及任意同格式自定义数据集
• 数据格式兼容：
  • <空格分隔的源句字符>\t<空格分隔的目标句字符>
  • 读取时先按 \t 拆分，再去掉字符空格，还原成正常句子
• 指标实现直接参考工作区内的 Metrics.py
• 支持 --max_seq，超过长度的样本会跳过并写日志
• 实现了稳健的输出抽取：
  • 清理多余换行
  • 清理常见前后缀和 prompt echo
  • 若输出长度仍异常，则记录异常并回退为源句，保证最终预测长度与源句一致
• 评测结束后：
  • 详细日志写入 outputs/<run_id>/run.log
  • 异常样本写入 outputs/<run_id>/anomalies.jsonl
  • 机器可读汇总写入 outputs/<run_id>/summary.json
  • 最终摘要追加写入根目录 eval_results.txt

目录结构

.
├─ run_eval.py
├─ requirements.txt
├─ Metrics.py
├─ src/csc_eval/
│  ├─ data.py
│  ├─ evaluate.py
│  ├─ extract.py
│  └─ inference.py
├─ lemon_v2/
├─ sighan_ecspell/
└─ OD-CSC.txt

安装

建议先准备 Python 3.10+ 环境，然后安装依赖：

pip install -r requirements.txt

如果需要 GPU 推理，请安装与你本机 CUDA 匹配的 PyTorch 版本。

用法

1. 评测单个文件

python run_eval.py ^
  --dataset OD-CSC.txt ^
  --max_seq 128 ^
  --batch_size 1 ^
  --device auto ^
  --torch_dtype bfloat16

2. 评测一个目录

python run_eval.py ^
  --dataset lemon_v2 ^
  --max_seq 128 ^
  --batch_size 1 ^
  --device auto ^
  --torch_dtype bfloat16

3. 评测多个目录中的全部 .txt

python run_eval.py ^
  --dataset . ^
  --max_seq 128 ^
  --batch_size 1 ^
  --device auto ^
  --torch_dtype bfloat16

4. 只做流程冒烟测试

python run_eval.py ^
  --dataset lemon_v2\new.txt ^
  --max_seq 64 ^
  --limit 20 ^
  --dry_run

--dry_run 不加载真实模型，只把源句复制为预测，用于验证数据读取、跳过逻辑、指标汇总和结果落盘。

主要参数

• --dataset: 单个 .txt 文件或目录路径
• --max_seq: 句子长度上限。len(source) > max_seq 时直接跳过该样本
• --batch_size: 推理 batch size，默认 1
• --device: auto、cuda:0、cpu 等
• --torch_dtype: auto / bfloat16 / float16 / float32
• --max_new_tokens: 每条样本生成的最大 token 上限
• --generation_buffer: 动态生成长度时，额外预留 token 数
• --prompt_prefix: 可自定义提示词前缀
• --limit: 每个数据文件只评测前 N 条解析成功的样本
• --dry_run: 不加载真实模型，用于流程验证

输出说明

eval_results.txt

每次运行会追加一段摘要，包括：

• 本次运行时间
• 模型名和关键参数
• 扫描到的数据文件
• 每个文件的样本数、跳过数、异常计数
• 句子级检测 / 句子级纠正 / 字符级检测 / 字符级纠正指标

outputs/<run_id>/anomalies.jsonl

会记录以下异常，而不是静默吞掉：

• 数据集行格式错误
• 金标准长度不一致
• max_seq 超长跳过
• 模型输出为空
• 输出长度异常
• prompt echo
• 推理报错

关于提示词

项目默认 prompt 是：

你是一个文本纠错专家，纠正输入句子中的错误，并只输出纠正后的句子，不要解释，不要添加任何前缀，输入句子为：

这与 TW-NLP/ChineseErrorCorrector 仓库和 Hugging Face 模型页上的示例用法保持同一路线，并额外强调“只输出纠正后的句子，不要解释”。

参考：

• GitHub: https://github.com/TW-NLP/ChineseErrorCorrector
• Hugging Face: https://huggingface.co/twnlp/ChineseErrorCorrector3-4B

评测指标

项目直接复用了当前工作区的 Metrics.py，输出：

• sentence_detect
• sentence_correct
• char_detect
• char_correct

说明

• 这是面向 CSC 的长度对齐评测脚本，所以如果金标准 src / trg 长度不一致，会记录日志并跳过该样本。
• 为了保证可复现，脚本会固定随机种子，并使用 do_sample=False 做确定性生成。
• 当模型输出异常且无法可靠抽取出与源句等长的最终句子时，脚本会记录异常并回退为源句，而不是隐式截断或补字。