m0_74196153/wav2vec2-large-xls-r-300m-Urdu

wav2vec2-large-xls-r-300m-Urdu on Ascend NPU

1. 简介

本文档记录 kingabzpro/wav2vec2-large-xls-r-300m-Urdu 在华为昇腾 Ascend910B4 NPU 环境下的适配部署与验证结果。

该模型是基于 facebook/wav2vec2-xls-r-300m 在 Urdu 语料（Mozilla Common Voice 8.0）上微调得到的自动语音识别（ASR）模型，参数量约 315M。

适配方式

仅通过 torch_npu.contrib.transfer_to_npu 自动将 CUDA API 映射至 NPU，无需对模型架构代码做任何修改。

模型获取地址

平台	地址
HuggingFace	https://huggingface.co/kingabzpro/wav2vec2-large-xls-r-300m-Urdu
本仓库	本仓库

参考文档

2. 验证环境

组件	版本
CANN	8.5.1
PyTorch	2.9.0
torch_npu	2.9.0.post1+gitee7ba04
transformers	4.57.6
pyctcdecode	0.5.0
kenlm	0.2.0

NPU: 1 卡 Ascend910B4（29.5 GB HBM）
操作系统: openEuler (aarch64)

3. 环境准备

3.1 基础环境

# Source CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 指定 NPU 卡
export ASCEND_RT_VISIBLE_DEVICES=0

# 指定 CANN 算子缓存路径
export ASCEND_AICPU_PATH=/usr/local/Ascend/ascend-toolkit/latest

3.2 Python 依赖

pip install torch torch_npu transformers soundfile pyctcdecode
pip install https://github.com/kpu/kenlm/archive/master.zip  # 可选，用于 LM 解码

3.3 torch_npu 基础校验

python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a)"

确保输出 tensor 的 device 为 npu:0。

4. 推理使用方法

4.1 基本推理

# 推理单个音频文件
python3 inference.py --audio /path/to/speech.wav

# 推理目录下所有音频
python3 inference.py --audio /path/to/audio_dir/

# 使用合成音频测试
python3 inference.py --test

4.2 精度验证

一键运行 CPU 基线推理 + NPU 精度对比：

python3 accuracy_run.py

该脚本会依次执行：

CPU 基线推理，保存 logits
NPU 推理，对比 logits
输出精度验证报告

4.3 性能测试

# 运行性能基准测试（3s/5s/10s/30s 音频）
python3 accuracy_run_perf.py

5. 精度评测

使用合成测试音频（3 秒，16kHz，混合正弦波 + 噪声）进行 NPU 与 CPU 的逐元素精度对比。

指标	数值
Token 预测一致率	100.00%
Top-1 in Top-5 重合率	100.00%
最大绝对误差	0.0151
平均绝对误差	0.0022
平均相对误差 (	CPU

精度验证结论：PASSED。模型在 NPU 和 CPU 上的 argmax 解码结果完全一致，CTC 转录文本完全一致。

转录结果对比

设备	转录文本
CPU	'ی'
NPU	'ی'
对比	✅ 一致

评测日志

详细日志见 eval_report/logs/accuracy_verification.log。

6. 性能参考

测试条件：单卡 Ascend910B4，fp32 精度，合成音频，10 次运行取平均。

音频长度	平均延迟	标准差	RTF
3 s	32.32 ms	1.22 ms	0.0108
5 s	31.62 ms	1.73 ms	0.0063
10 s	33.48 ms	2.18 ms	0.0033
30 s	56.44 ms	4.35 ms	0.0019

详细日志见 eval_report/logs/perf_benchmark.log。

7. 交付文件

文件	说明
`inference.py`	NPU 推理脚本（主入口）
`accuracy_run.py`	精度验证脚本（CPU 基线 + NPU 对比）
`accuracy_run_perf.py`	性能基准测试脚本
`run.py`	通用推理入口
`run_cpu_baseline.py`	CPU 基线推理脚本
`run_npu.py`	NPU 对比验证脚本
`check_accuracy_run_perf.py`	验证结果检查脚本
`README.md`	本文档
`eval_report/`	评测报告目录（含运行日志）
`accuracy_check/`	精度/性能数据目录

8. 注意事项

音频采样率: 模型训练于 16kHz 音频，输入音频需重采样至 16kHz 以获得最佳效果
LM 解码: Wav2Vec2ProcessorWithLM 需要安装 kenlm 和 pyctcdecode，否则自动降级为 Wav2Vec2FeatureExtractor
fp32 精度: Ascend910B4 不支持 fp64（double），torch_npu 自动降级为 fp32，不影响推理精度
KenLM 安装: pip install https://github.com/kpu/kenlm/archive/master.zip，编译需要 gcc
环境变量: transfer_to_npu 会自动将 torch.cuda.* 映射为 torch.npu.*，建议在脚本最顶部 import