EasyOCR训练时如何配置自定义字典与数据增强参数？

Question

在使用 EasyOCR 进行自定义模型训练时，常遇到“如何正确注入领域专属字典并启用针对性数据增强”的问题：EasyOCR 官方训练脚本（如 `train.py`）默认不直接支持 external character dictionary 或细粒度增强策略配置；用户尝试通过修改 `character_list_file` 参数加载自定义字典时，易因编码格式、换行符或含空格字符导致字符映射错乱；同时，其内置的 `Augmentation` 模块（基于 imgaug）虽暴露 `augment` 参数，但未提供文档化接口控制旋转角度范围、模糊强度、背景噪声类型等关键增强因子。此外，字典与增强策略若未协同设计（如字典含繁体字但增强未包含字体形变），会导致训练收敛慢、识别漏字。开发者亟需明确：1）字典文件格式规范与加载时机；2）如何安全扩展 `SynthTextGenerator` 或重载 `Dataset` 类以注入定制增强逻辑；3）验证字典生效及增强实际作用的调试方法。

Answer 1

```html

一、字典文件格式规范与加载时机：从编码陷阱到字符映射验证

EasyOCR 的 character_list_file 参数要求 UTF-8 编码、无 BOM、单字符每行（含换行符 \n，禁止 \r\n），且严禁空行、首尾空格、制表符或控制字符。常见错误包括：繁体字「為」被误写为全角空格+「為」、日文平假名「あ」后带不可见 Zero Width Space（U+200B）。加载时机发生在 train.py 初始化 Recognizer 时调用 utils.get_char_dict()，该函数将字符列表转为 char2idx 映射字典，并同步构建 idx2char —— 若字符重复或含非法 Unicode（如 surrogate pairs），会静默截断或引发索引越界。

二、增强策略协同设计：字典语义驱动的细粒度增强配置矩阵

字典特征类型	推荐增强类型	imgaug 参数示例	物理意义对齐
繁体/异体字（如「龍」「龙」）	字体形变 + 透视扭曲	iap.Affine(scale=(0.9,1.1), rotate=(-5,5))	模拟手写/印刷体差异
工业铭牌数字（0–9, A–F）	高斯噪声 + 运动模糊	iap.GaussianNoise(scale=(0,0.1)) + iap.MotionBlur(k=3)	匹配金属反光与产线抖动
医学符号（℃、α、β、→）	对比度扰动 + 局部遮挡	iap.LinearContrast((0.7,1.3)) + iap.CoarseDropout(0.02, size_percent=0.1)	覆盖扫描伪影与墨水晕染

三、安全扩展 SynthTextGenerator：重载 Dataset 类的工程化实践

不建议直接修改 EasyOCR 源码。推荐继承 easyocr.dataset.SynthDataset 并重写 __getitem__：

class DomainAwareDataset(SynthDataset):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 注入领域增强链（非 imgaug 原生 pipeline，避免全局污染）
        self.domain_aug = iaa.Sequential([
            iaa.Affine(rotate=(-3, 3), mode='edge'),
            iaa.OneOf([
                iaa.GaussianBlur(sigma=(0.1, 0.5)),
                iaa.MedianBlur(k=(3, 5))
            ]),
            iaa.AdditiveGaussianNoise(scale=(0, 0.05*255))
        ])

    def __getitem__(self, idx):
        img, text = super().__getitem__(idx)
        # 在文本渲染后、归一化前注入增强（保留语义完整性）
        img = self.domain_aug(image=img)
        return img, text

四、调试验证双路径：字典生效性与增强可视化诊断流程

graph TD
    A[启动训练] --> B{检查 char2idx.json}
    B -->|存在且长度==len(custom_dict)| C[打印前10字符映射]
    B -->|长度异常| D[用 codecs.open 验证BOM/换行符]
    A --> E[启用 debug_mode=True]
    E --> F[保存 batch_0_img.png 与 label.txt]
    F --> G[人工比对：是否含字典外字符？增强是否引入畸变？]
    G --> H[统计 epoch_0 中 CER@top1 字符覆盖率]

五、进阶避坑指南：跨版本兼容性与分布式训练陷阱

• EasyOCR v1.7+ 引入了 character_filter 参数，可过滤训练样本中不在字典内的字符——但默认为 False，需显式设为 True 否则仍会报错；
• 使用 torch.distributed 多卡训练时，character_list_file 必须在所有 rank 上路径一致且内容完全相同（建议用绝对路径 + md5 校验）；
• 若字典含 emoji 或组合字符（如 👨‍💻），需确保 PyTorch DataLoader 的 num_workers>0 时启用 spawn 启动方式，否则 UnicodeDecodeError 可能静默丢失字符；
• 自定义增强若调用 cv2.putText 渲染中文，必须预加载支持 Unicode 的字体（如 NotoSansCJK），否则 SynthTextGenerator 会回退为空白方块；

六、生产级验证清单（Checklist）

1. ✅ 字典文件经 file -i dict.txt 确认 charset=utf-8；
2. ✅ 执行 python -c "print([ord(c) for c in open('dict.txt').read()[:10]])" 排查隐藏控制符；
3. ✅ 在 train.py 中插入 print('Loaded chars:', len(char2idx)) 验证加载量；
4. ✅ 使用 tensorboard --logdir=logs --bind_all 查看 images/train_sample_0 增强效果；
5. ✅ 训练 100 步后导出 preds.npy，用 numpy.unique 统计预测字符分布是否收敛至字典子集；
6. ✅ 对比启用/禁用增强的 loss 曲线斜率差异（理想值：增强组初期 loss 下降快 15%+）；

```