qox/vn-address-normalizer — 昇腾 NPU 适配模型

赛事: 昇腾 Model Agent 模型适配大赛（第二季）引擎: torch_npu（昇腾 NPU 推理引擎）硬件: Ascend 310P / 910B 标签: npu ascend pytorch seq2seq vietnamese

📖 模型简介

属性	值
原始模型	qox/vn-address-normalizer
参数量	~6.6M（字符级 Seq2Seq Transformer）
任务类型	越南语地址规范化（序列到序列）
输入格式	越南语地址字符串（含变音符号或 ASCII slug，最长 300 字符）
输出格式	规范化标准地址 + valid 标记 + province/ward 信息 + 置信度

模型将非规范/简写越南语地址（如 p tan dinh q1 tphcm）规范化到 2025 年行政区划后的标准行政地址格式（如 Phường Tân Định, Thành phố Hồ Chí Minh）。采用 4 层编码器 + 3 层解码器 Transformer（D_MODEL=256，4 头，GELU，Pre-LN），结合省约束 Trie + Beam Search 解码。

🔧 环境依赖

pip install -r requirements.txt -i https://repo.huaweicloud.com/repository/pypi/simple/

🚀 推理步骤

⚠️ 本仓库不包含模型权重（交付件仅 inference.py / readme.md / requirements.txt / assets/），推理前必须先从原始模型仓单独下载权重。

# 1. 下载模型权重（仓库不含权重，必须单独下载）
huggingface-cli download qox/vn-address-normalizer --local-dir ./ --local-dir-use-symlinks False
# 注：官方 HF 仓库缺少 src_vocab.json / tgt_vocab.json，
#     需从作者 GitHub 仓库 qosu/vn-address-normalizer 的 model_v3_final/ 补齐后放回该目录

# 2. 运行 NPU 推理
python3 inference.py --model_path . --input "p tan dinh q1 tphcm" --device npu:0

🧪 测试用例

用例 1: 缩写地址规范化

python3 inference.py --model_path . --input "p tan dinh q1 tphcm" --device npu:0

预期输出:

Input:       p tan dinh q1 tphcm
Canonical:   Phường Tân Định, Thành phố Hồ Chí Minh
Valid:       True
Province:    Thành phố Hồ Chí Minh
Ward hint:   tan dinh
Space:       170 candidates

📁 目录结构

.
├── inference.py          # NPU 推理脚本（torch_npu 引擎）
├── readme.md             # 本文件
├── requirements.txt      # 依赖清单
└── assets/               # 截图素材

📝 适配说明

本模型由昇腾 Model Agent 自动完成 NPU 适配：

torch_npu 不支持 nn.TransformerEncoderLayer/DecoderLayer 内部的 scaled_dot_product_attention（ERR01007），已用手写多头注意力 + FFN（F.linear / torch.matmul / F.softmax / F.layer_norm / F.gelu）替换，权重键名与官方完全一致；
beam search 采用固定 shape（B×MAX_TGT）批量前向，避免 NPU 逐 token 重编译开销；
CPU 与 NPU 输出完全一致（Canonical / Valid / Province 相同）。