f
fbybl/vn-address-normalizer
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

vn-address-normalizer 昇腾 NPU 适配记录

一、做了什么

把 qox/vn-address-normalizer 从"只能在本机 python inference.py 逐条跑"改造为常驻 NPU 的 HTTP 服务。模型本身是个小体积的字符级 Transformer(编码 4 层、解码 3 层、d_model=256、共约 658 万参数),解决越南语地址标准化:输入 p tan dinh q1 tphcm,输出 Phường Tân Định, Thành phố Hồ Chí Minh。

它和主流大模型服务化最大的区别在解码环节。模型推理不是自回归生成任意文本,而是在 18.7 万条标准地址构建的前缀树(Trie)里做受限 beam 搜索(beam 宽度 5),保证输出必然落在标准地址集合中。适配时把这套 Trie 约束解码完整搬进了服务端,所以对外表现的"标准地址可校验"这一核心特性没有丢。

二、环境与依赖

部署目标为单卡昇腾 910B,配套 CANN 8.5.1、vLLM 0.18.0 与 vllm-ascend。模型权重为 fp32,加载后约占 26 MB 显存。服务进程峰值 AICore 使用率约 20%、HBM 约 25.6 GB,对整卡 64 GB 而言余量充足,适合与轻量任务共存。

需要准备的材料:

  • 权重与词表(model.safetensors、src_vocab.json、tgt_vocab.json)
  • 地址语料(clean_canonicals.json 18.7 万条、legacy_ward_idx.json 1.3 万条旧坊名)
  • config.json(声明 max_src=128、max_tgt=96、d_model=256 等)

三、部署操作

先把模型文件聚到一个目录,再把自定义模型插件加入 Python 路径,最后执行 run_vllm_serve.py 注册架构并拉起 vllm serve:

export ASCEND_RT_VISIBLE_DEVICES=1
export PYTHONPATH=/opt/vn-addr/plugin:$PYTHONPATH
export VLLM_ENABLE_V1_MULTIPROCESSING=0
export HF_HUB_OFFLINE=1
export HF_HOME=/tmp/hf-cache

python3 /opt/vn-addr/plugin/run_vllm_serve.py \
  /opt/vn-addr/serve \
  --port 8091 \
  --served-model-name vn-address-normalizer \
  --dtype float32 \
  --max-model-len 256 \
  --max-num-seqs 1 \
  --gpu-memory-utilization 0.3 \
  --enforce-eager \
  --trust-remote-code \
  --no-enable-prefix-caching

等待日志出现 Application startup complete. 即成功。其中两个参数需要说明:--max-num-seqs 1 是因为受限解码按请求串行计算整条答案,无法混批;--enforce-eager 是因为该模型没有 KV cache,走 eager 最省心。

四、调用方式

就绪后按 OpenAI 兼容协议访问:

curl http://127.0.0.1:8091/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"vn-address-normalizer","prompt":"Xa Cu Chi TP HCM","max_tokens":96,"temperature":0}'

响应核心字段(text)即标准化结果,例如 Xã Củ Chi, Thành phố Hồ Chí Minh。仓库根的 inference.py 封装了这套调用,--local 参数可切到上游单机逻辑做对照。

五、实测样例与延迟

在目标 NPU 上取几组有代表性的输入实测:

输入输出延迟
p tan dinh q1 tphcmPhường Tân Định, Thành phố Hồ Chí Minh~0.95 s
Phuong Ba Dinh Ha NoiPhường Ba Đình, Thành phố Hà Nội~1.02 s
P. Bến Nghé Q.1 HCMPhường Sài Gòn, Thành phố Hồ Chí Minh~0.23 s
phuong 14 quan 10 tphcm(空)~0.02 s
42 hung vuong thanh pho can thoHùng Vương, Phường Tân An, Thành phố Cần Thơ~0.84 s

可以看到"拒绝数字坊"这类输入响应极快,因为解析阶段即提前终止,无需进入解码。

六、与上游基线的一致性

适配是否忠实,关键看昇腾服务端输出与上游 CPU 脚本是否逐条一致。我们选取了无音调缩写、带音调全称、旧坊名映射、数字坊拒绝等 8 类输入做对比,结论是全部一致。此处不再逐一罗列输入输出表,可运行仓库 inference.py --local 与 inference.py 自行复核(示例已内置于 assets/README.md 所列脚本中)。

七、注意事项

  • 本仓库不含权重与语料,请从上游 qox/vn-address-normalizer 拉取后按第三节组织目录。
  • 两个词表文件与两个地址库文件是运行刚需,缺失会导致服务启动失败或解码退化。
  • 服务串行处理请求,不适用于高并发场景;确有需要可在插件层改批量解码。
  • 模型仅认识 2025 年后区划;历史坊名依赖 legacy 映射,纯数字坊名会被拒绝返回空串。
  • 若与他人共用机器,请先 npu-smi info 看空闲设备与端口,--port 和 ASCEND_RT_VISIBLE_DEVICES 可调,不要误杀他人进程。