qox/vn-address-normalizer（昇腾 NPU 适配）

源仓库：qox/vn-address-normalizer（HuggingFace） 任务：越南语地址规范化（address-normalization）—— 非规范地址 → 2025 后行政规范地址，seq2seq + 字典约束 beam search

模型简介

将越南语地址字符串（可带重音或 ASCII slug，如 p tan dinh q1 tphcm）规范化为 规范行政地址（如 Phường Tân Định, Thành phố Hồ Chí Minh）。模型在 187,817 条 规范地址数据库上做 Trie 约束解码，输出保证在库内。

架构

自定义 S2S Transformer（与官方权重布局完全一致，NPU 算子化分解实现）：

• 参数量：6,589,197（F32）
• 编码器：4 层 nn.TransformerEncoderLayer（d_model=256，4 头，d_ff=1024，GELU）
• 解码器：3 层 nn.TransformerDecoderLayer（同维度）
• 词表：字符级，src=287 / tgt=269，MAX_SRC=128 / MAX_TGT=96
• 解码：province 约束 beam search（默认 beam=5）

NPU 适配说明（如实标注）

• 官方 nn.TransformerEncoderLayer/DecoderLayer 的 forward 会路由到融合算子 aten::_transformer_encoder_layer_fwd，该算子 NPU 后端不支持，torch_npu 会整层 回退 CPU（性能损失）。本仓库将 Enc/Dec 层分解为 MultiheadAttention(SDPA) + LayerNorm + Linear + GELU 等纯 PyTorch 算子，权重布局与官方 state_dict 完全一致 （已在 CPU 验证与官方输出逐位一致，decoder logits max_abs_diff = 0.0）， Transformer 前向全量运行于 NPU，无 CPU fallback；
• Trie 构建 / 正则抽取 / beam search 候选枚举为纯 Python（宿主 CPU）， 仅 Transformer 前向落在 NPU —— 与官方实现一致，不属于算子回退。

环境要求

pip install -r requirements.txt

快速开始

# 默认用例（5 个官方示例地址，自动选择 NPU）
python3 inference.py --device npu --device_id 0

# 自定义地址
python3 inference.py --device npu --device_id 0 --input "Phuong Ba Dinh Ha Noi"

验证结果（昇腾 NPU 实测）

• 设备：npu:0（Ascend910_9362，CANN 8.5.1，PyTorch 2.9.0 / torch_npu 2.9.0.post1）
• 用例：5 个官方示例地址，valid=5/5，finite_all=True，NPU_INFERENCE_PASS=True
• 示例：p tan dinh q1 tphcm → Phường Tân Định, Thành phố Hồ Chí Minh（conf=-5.94，958.0ms）
• 权重 SHA256：4fcaae4f7a2e725aad234533e579884daa227c761b82c1c6a82c7ff73bbc2e3a

详细证据见 results/（npu_result.json、inference_evidence.txt、npu_smi.txt）。

仓库结构

inference.py        推理脚本（必选交付）
readme.md           部署说明文档（必选交付）
requirements.txt    环境依赖清单
model_v3_final/     模型权重与词表/规范地址库（model.safetensors 26MB Git LFS）
results/            真实 NPU 验证证据

许可证

mit