fast-plate-ocr 是一个轻量、快速的车牌 OCR 开源项目，基于 Keras 3 + ONNX Runtime，主打低延迟的车牌文字识别。除了输出车牌号，它还内置了一个可选的区域（region）识别功能：同一次推理，模型会同时告诉你这张车牌来自哪个国家。对于跨国 ETC、国际物流、跨境车队管理等场景，这个"多问一句车牌是哪国的"能力非常实用。

本文带你从网络结构原理讲到训练自己的区域识别模型，全程尽量不用大段代码，只讲清楚每个环节"在做什么、为什么这样做"。

一、region 识别是什么：一次推理，两个答案

传统车牌 OCR 只回答一个问题：车牌上写了什么？fast-plate-ocr 的 v2 系列模型多回答一个问题：这块牌子属于哪个地区/国家？

最终预测结果是一个PlatePrediction对象（定义见 fast_plate_ocr/core/types.py#L62-L79），核心字段如下：

换句话说，region 功能是一个纯增量能力：不加不碍事，加了不牺牲车牌识别速度（共享同一个主干网络）。

二、原理：一个主干，两个"头"

fast-plate-ocr 的默认架构是CCT（Compact Convolutional Transformer），由 models/cct_s_v2.yaml 这类 YAML 完全定义。理解 region 头，只需要看懂下面这条数据流：

1. 卷积 Stem + Patch 化：车牌图先经过几层卷积提取特征，再切成 patch 变成"token 序列"，这一步对两个任务完全共享；
2. Transformer 编码器：若干 Transformer 块对序列做上下文建模，同样共享；
3. Token 压缩：把变长序列压缩到固定的max_plate_slots个 token（每个 token 对应一个字符位）；
4. 两个分叉：
   • plate 头：每个 token 独立投影到词表，逐字符分类 —— 这是经典的车牌 OCR 输出；
   • region 头：对压缩后的整段 token 序列先补几层 Transformer 块，再做SequencePooling把"整张图的信息"聚合成一个向量，最后接一个Dense(softmax)层，类别数正好等于plate_regions列表长度 —— 这就是"看整张牌猜国家"的实现。

关键实现都在 fast_plate_ocr/train/model/model_builders.py#L104-L127：region 头把模型输出从单个plate变成{"plate": ..., "region": ...}两个分支。

💡 设计巧思：region 头复用 plate 头之前已经算好的特征，只额外加了一两层小 Transformer 和一个池化，额外计算量几乎可以忽略，这正是 fast-plate-ocr 能"免费"获得国家识别的原因。

三、一键运行：v2 模型自带区域识别

官方 Model Zoo 里的cct-s-v2-global-model（推荐默认）和cct-xs-v2-global-model就是用 65 个国家车牌训练出来的 v2 全局模型，开箱即用。

pip install fast-plate-ocr[onnx]

from fast_plate_ocr import LicensePlateRecognizer m = LicensePlateRecognizer("cct-s-v2-global-model") pred = m.run("test_plate.png", return_confidence=True)[0] print(pred.plate, pred.region, pred.region_prob)

推理侧的启用逻辑很严格（见 fast_plate_ocr/inference/plate_recognizer.py#L204-L221）：必须同时满足模型导出了region输出、plate config 里定义了plate_regions列表，region 预测才会开启；缺任何一边都会打一条 warning 并自动禁用，而不是静默出错。

region 标签的解码在 fast_plate_ocr/core/process.py#L269-L277：对 region 输出取 argmax，再按plate_regions列表顺序映射回国家名。

📚 更多推理细节：docs/inference/running_inference.md

四、训练自己的区域识别模型

想识别哪些国家，完全由你自己定义。整个训练流程分四步。

4.1 准备数据：CSV 加一列 plate_region

数据集是 CSV 标注 + 图片文件夹。在普通车牌 OCR 的两列基础上，加一列plate_region即可（格式规范见 docs/training/dataset.md）：

image_path,plate_text,plate_region images/00001.jpg,KNN505,Argentina images/00002.jpg,AB123CD,Brazil images/00003.jpg,17AB,Chile

plate_region的值必须出现在下面配置文件里的plate_regions列表中，且不允许有空值 —— 这些校验在 fast_plate_ocr/train/data/dataset.py#L50-L75 里自动完成，标签不在列表内会直接报错，帮你提前抓出标注笔误。

4.2 编写 plate config：列出你的国家清单

在 plate config YAML 末尾追加plate_regions字段。列表的顺序就是模型的类别顺序，官方 v2 配置就列了 66 个条目（含Unknown兜底类）：

plate_regions: [ 'Argentina', 'Brazil', 'Chile', 'Unknown' ]

完整可参考 config/latin_plate_config_v2.yaml#L19-L27；字段说明见 docs/training/config/plate_config.md。

⚠️ 注意：plate_regions里不能有重复项，配置校验会拒绝（fast_plate_ocr/train/model/config.py#L105-L108）。

4.3 训练命令与 region 专属参数

模型配置直接使用 v2 系列（如 models/cct_s_v2.yaml，其中region_pre_seqpool_layers: 1就是 region 头的深度），然后跑训练 CLI：

KERAS_BACKEND=tensorflow fast-plate-ocr train \ --model-config-file models/cct_s_v2.yaml \ --plate-config-file config/my_plate.yaml \ --annotations data/train.csv \ --val-annotations data/val.csv \ --epochs 150 --batch-size 64 \ --output-dir trained_models/

只要"CSV 有列 + 配置有列表"两个条件同时满足，region 头会自动启用，无需额外开关。CLI 还提供了 4 个 region 专属参数（定义在 fast_plate_ocr/cli/train.py#L236-L275）：

4.4 看什么指标判断区域识别学得好

启用 region 头后，训练日志会额外记录 4 个指标（详见 docs/training/metrics.md）：

• region_acc：区域分类准确率
• region_top3_acc：真值落在 Top-3 预测内的比例
• region_macro_f1：所有国家类别宏平均 F1 —— 小国样本少时重点盯它，防止模型只"认识"大国
• region_loss：region 损失

早停监控指标也可以直接写val_region_acc等 region 指标（见 fast_plate_ocr/cli/train.py#L60-L63），比如你想优先保证"猜对国家"，就用val_region_acc做早停。

五、常见错误排查清单

六、小结

• 原理：CCT 主干共享，region 头 = 少量 Transformer 块 + 序列池化 + softmax 分类，代价极低；
• 推理：v2 全局模型（如cct-s-v2-global-model）开箱即用，return_confidence=True还能拿到region_prob；
• 训练：CSV 加一列plate_region+ plate config 加plate_regions列表，region 头自动启用，再用--region-loss等 4 个参数调优；
• 排错：绝大多数问题来自"CSV 与配置不一致"，报错信息已经把缺哪个环节写得明明白白。

想深入了解完整训练流程，建议阅读 docs/training/intro.md 和微调教程 examples/tutorial_fine_tune_plate_model.ipynb。