eardoi/vn-address-normalizer-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

vn-address-normalizer 昇腾 NPU 适配

vn-address-normalizer 是越南地址归一化 Seq2Seq Transformer 模型(26M 参数):4 层编码器 + 3 层解码器,字符级分词(源词表 287 / 目标词表 269),将非规范越南语地址归一化为 2025 年后行政区划的标准形式。

模型规格

项目值
模型qox/vn-address-normalizer
架构Seq2Seq Transformer(4 层编码器 + 3 层解码器,D=256,4 头)
参数量26M
源词表287(字符级)
目标词表269(字符级)
许可证MIT
精度float32

环境要求

  • 硬件:Ascend 910B 系列(≥1 卡)
  • CANN ≥ 8.0(source /usr/local/Ascend/ascend-toolkit/set_env.sh)
  • Python 3.10 – 3.11
  • torch 2.9.0 / torch_npu 2.9.0.post1

环境准备

export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/
pip install torch torch_npu safetensors numpy

模型权重

权重从 Hugging Face 获取:

export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download qox/vn-address-normalizer --local-dir model_src

说明:上游 HF 仓库缺失 model_v3_final/src_vocab.json 与 tgt_vocab.json 两个词表文件, 因此无法还原字符↔id 的精确映射做完整文本归一化。本适配采用社区通行做法 (参见 GitCode qox-vn-address-normalizer-NPU),通过编码器/解码器前向传播 + CPU-vs-NPU 精度对比验证模型在 NPU 上真实运行。

推理

NPU 前向推理(编码器 + 自回归解码器 step):

python3 inference.py --model_path . --device npu:0

CPU-NPU 精度对比:

python3 inference.py --model_path . --device cpu --out /tmp/vn_addr
python3 inference.py --model_path . --device npu:0 --out /tmp/vn_addr
python3 inference.py --model_path . --compare --out /tmp/vn_addr

验证输出:

=== vn-address-normalizer CPU-vs-NPU precision verification ===
last_step_logits: cosine=0.999999919 l2=0.035791 max_abs_diff=4.845858e-03
encoder_out:      cosine=0.999999875 l2=0.039477 max_abs_diff=2.156258e-03
RESULT: PASS (overall cosine=1.000000, threshold >0.999)

验证结果

  • 设备:Ascend 910B(npu:0)
  • 推理:✅ 通过(权重真实加载,load_state_dict 无缺失/多余)
  • CPU-NPU 一致性:✅ cosine = 1.000000(阈值 >0.999)
  • 验证日期:2026-08-22

适配说明

上游 nn.TransformerEncoderLayer/nn.TransformerDecoderLayer 使用的融合算子 aten::_transformer_encoder_layer_fwd 在 torch_npu 上无 NPU 内核、会回退 CPU。 本适配将其手动分解为 NPU 支持的算子(linear / GELU / LayerNorm / scaled_dot_product_attention),子模块与参数命名与原实现完全一致, safetensors 权重原样加载,全部计算在 npu:0 上执行。

目录结构

├── inference.py            # NPU 推理脚本(含 CPU-NPU 对比)
├── manual_transformer.py   # NPU 友好手动 Transformer 实现
├── upstream_inference.py   # 上游原始推理代码(含 S2S 类)
├── config.json             # 模型配置
├── model.safetensors       # 权重(不推送)
├── model_v3_final/         # 地址数据库(不推送)
├── README.md               # 本模型卡片
└── assets/                 # 截图素材

引用

qox/vn-address-normalizer — Vietnamese address normalization
https://huggingface.co/qox/vn-address-normalizer