MASC-CSC

MASC-CSC (Mechanism-Aware Selective Collaboration for Chinese Spelling Correction) 是一个用于中文拼写纠错（CSC）的高级双层协同框架。

本项目致力于解决大语言模型（LLM）在拼写纠错任务中容易**“过度纠正”和“随意改写”**的问题。通过引入多模态小模型作为前端“报错传感器”，结合动态路由机制与受限的 LLM 解码策略，实现了纠错准确率与推理成本的最佳平衡。

🌟 核心特性与架构

本系统由四个高度协同的模块组成：

1. 多模态前端 (Multimodal Frontend)
   • 基于 chinese-macbert-base。
   • 在 Embedding 层深度融合了拼音特征 (Pinyin) 与字形视觉特征 (Glyph)。
   • 暴露丰富的中间态元数据：Logits, 检测分数 (Detection Score), 不确定度 (Uncertainty) 和 Top-K 候选。
2. 机制推断与候选生成 (Mechanism Inference & Candidate Gen)
   • 错误机制推断：支持精确与模糊的音近（声母/韵母混淆组）和形近（图像余弦相似度）特征判定。
   • 约束候选生成：依据错误机制动态过滤 Top-K 备选字，生成高度可靠的有限候选句，有效约束 LLM 的解空间。
3. 选择性风险路由 (Selective Escalation Router)
   • 提取 8 维句子级特征（包含计算语义、音、形分布的 JS 散度得出的多模态冲突得分）。
   • 通过 SelectiveRouterMLP 动态评估句子风险。低风险句子直接输出前端结果，仅高风险句子触发 LLM 验证，大幅降低 API/算力开销。
4. 三阶段 LLM 约束验证 (Three-Stage LLM Verifier)
   • 内置定制的 LogitsProcessor，从底层严格限制 LLM 的输出格式（仅限字母选项或单个汉字），彻底消除 LLM 的废话与幻觉。
   • Stage 1 (闭集选择)：LLM 在约束候选中做单选题，支持弃权 (N)。
   • Stage 2 (开放修复)：若 LLM 弃权，允许其提出单个新汉字作为补充。
   • Stage 3 (复核确认)：对补充候选进行最终的闭集校验。

📁 目录结构

MASC-CSC/
├── models/
│   ├── multimodal_frontend.py     # 多模态小模型前端实现
│   └── common.py                  # 基础网络组件
├── masc_csc/
│   ├── pipeline.py                # 核心协同管线串联
│   ├── mechanism.py               # 音形错误机制推断
│   ├── candidate_generator.py     # 机制感知候选生成
│   ├── selective_escalation.py    # 基于 MLP/规则的风险路由
│   └── llm_verifier.py            # 三阶段本地大模型验证器
├── scripts/
│   ├── data_process.py            # 数据预处理
│   ├── run_pipeline.py            # 管线测试运行脚本
│   └── run_masc_csc.py            # 单句测试脚本
├── utils/                         # 训练工具、评价指标等
├── train.py                       # 前端模型训练脚本
└── train_router.py                # Router MLP 门控网络训练脚本

🚀 快速上手

1. 环境依赖

建议环境：Python >= 3.8, PyTorch >= 2.0

pip install -r requirements.txt
# 确保安装了 pypinyin, transformers, lightning, peft 等依赖

2. 运行端到端管线 (Pipeline Inference)

你可以直接使用预置的脚本测试 MASC-CSC 管线：

# 使用本地 LLM (如 Baichuan-7B) 进行协同纠错
python scripts/run_pipeline.py \
    --sentence "我喜换吃平果，逆呢？" \
    --use_llm \
    --llm_path "baichuan-inc/Baichuan-7B" \
    --router_ckpt "./ckpt/router.ckpt"

3. 训练流程

本项目支持拆分训练前端模型与 Router 门控网络：

训练多模态前端：

python train.py --model multimodal_frontend --datas train.csv --batch-size 32

训练 Selective Router (MLP)：

python scripts/train_router.py --train_data ./data/train_features.pt

微调本地 LLM (LoRA)： 项目中提供了针对大语言模型的 LoRA 微调脚本：

sh scripts/train_llm_lora.sh

📝 数据格式

前端模型与验证集需要以下 CSV 格式数据：

src,tgt
我喜换吃平果,我喜欢吃苹果
今田天气很好,今天天气很好

(要求：src 与 tgt 必须等长，且不可包含半角逗号)

💡 开发与扩展

• LLM 支持：当前 llm_verifier.py 默认适配本地加载的因果语言模型（如 Baichuan, Qwen 等），通过 HuggingFace API 配合自定义的 LogitsProcessor 工作。
• 降级模式：如果不加载 LLM，Pipeline 会自动降级使用 NoOpVerifier，回退为高性能、纯小模型的纠错模式。