atlasleong/w2v-xls-r-uk-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Yehor/w2v-xls-r-uk · 乌克兰语 Wav2Vec2 CTC 语音识别 · 昇腾 NPU 推理交付

本目录为 Yehor/w2v-xls-r-uk(Wav2Vec2ForCTC,乌克兰语 ASR)在昇腾 Ascend 910B4(torch_npu)上针对 npu:2 的离线推理适配与交付文档。 所有推理均为真实运行结果:日志与 JSON 见 logs/,截图见 assets/。模型权重与测试音频全程使用本地文件,推理时不联网、不重新下载。


1. 模型简介

Yehor/w2v-xls-r-uk 是一个在**乌克兰语(Ukrainian / українська, ISO 639-1: uk)**上微调的自动语音识别(ASR)模型,基座为 Facebook 的 facebook/wav2vec2-xls-r-300m(Wav2Vec2 XLS-R,300M 参数)。

  • 结构:Wav2Vec2ForCTC(CTC 输出层,vocab_size=40,字符级词表)
  • 参数量:约 3.15 亿(315,479,720 个参数;model.safetensors 约 1.26 GB)
  • 微调数据:Mozilla Common Voice 10.0(uk 配置)
  • 官方评测:Common Voice uk test 集 WER 20.24%、CER 3.64%(float16,evaluate 库)
  • 输入要求:16 kHz 单声道语音
  • 模型卡自身提示已更新模型:https://huggingface.co/Yehor/w2v-bert-uk-v2.1(本交付仍按任务要求适配本模型)

用途:在无 GPU 的昇腾 NPU 环境中,将 16 kHz 语音转写为乌克兰语文本(CTC 贪心解码)。本仓库提供开箱即用的 inference.py、固定版本依赖、确定性测试音频、真实运行日志与校验信息。


2. 模型源与固定版本(可复现性)

项值
源仓库(HuggingFace)https://huggingface.co/Yehor/w2v-xls-r-uk
固定 revision(commit)e3ced4def0d70be3aab0f2db598a59961fe9ab3b
基座模型facebook/wav2vec2-xls-r-300m
本地模型目录/work/pipeline/models/audio7/w2v-xls-r-uk
本地权重文件model.safetensors
权重大小1,261,971,432 bytes(≈ 1.26 GB / 1.18 GiB)
权重 SHA256e8d3ea3825853c6016539d474878fc281cf0bbb2fa9209f34f403b91e2eb0fe9

固定 revision 与本地模型 git rev-parse HEAD 完全一致(e3ced4d,lastModified 2025-05-12)。 模型文件由平台提供的下载脚本从 AtomGit 镜像仓库 https://atomgit.com/hf_mirrors/Yehor/w2v-xls-r-uk.git 拉取到本地并检出到该固定 revision;jobs/audio7/download-logs/w2v-xls-r-uk.log 记录 DOWNLOAD_STATUS=PASS 与上述 SHA256。因此本交付使用真实预训练权重,未使用随机初始化/仅配置权重,也不在推理时下载未固定版本的替换物。

2.1 许可证说明(manifest 与模型卡差异)

平台自动生成的 manifest 中 license 字段记录为 not-declared-in-model-card;但经核实,模型卡(含固定 revision 的本地 README.md)与 HuggingFace API 的 cardData 均声明 license: apache-2.0(HF API tag 亦含 license:apache-2.0)。本交付以模型卡实际声明为准,将上游许可证记录为 Apache-2.0。测试音频为本仓库自创 CC0 波形,与模型权重许可证相互独立。

2.2 本地模型文件清单

config.json                1,590 bytes
model.safetensors      1,261,971,432 bytes
preprocessor_config.json     262 bytes
special_tokens_map.json     406 bytes
tokenizer_config.json       337 bytes
vocab.json                   452 bytes
alphabet.json                403 bytes
added_tokens.json             30 bytes
language_model/            (可选 KenLM,贪心 CTC 不需要)

说明:模型目录中的 language_model/ 为 KenLM 语言模型(lm.binary 为占位文件);贪心 CTC 解码不需要 KenLM,本交付未加载语言模型。


3. 环境依赖与运行环境(实测)

项值
主机 / 系统Linux 5.10.0-309(openEuler 22.03 SP4)· aarch64
Python3.11.14(/usr/local/python3.11.14/bin/python3)
昇腾 AI 处理器Ascend 910B4(npu-smi 显示 8 × 910B4-1)
分配设备npu:2(torch.npu.current_device()=2)
CANN8.5.1(ASCEND_HOME_PATH=/usr/local/Ascend/cann-8.5.1)
Driver / npu-smi25.5.1(npu-smi 25.5.1)
PyTorch2.9.0+cpu(昇腾基础镜像预装)
torch_npu2.9.0(昇腾基础镜像预装,显式 import torch_npu 注册 NPU backend)
transformers5.15.0
soundfile0.14.0
numpy1.26.4
safetensors0.8.0
huggingface_hub1.28.0
Pillow12.3.0(仅用于渲染 assets/*.png)
NPU 可用性torch.npu.is_available()=True、torch.npu.device_count()=8、torch.npu.current_device()=2
NPU 冒烟randn 张量 NPU 运算正常(torch_npu 导入与设备访问成功)

4. 安装依赖

4.1 昇腾基础镜像预装(不要用普通 PyPI 覆盖)

torch 与 torch_npu 由昇腾基础镜像预装为匹配对,不在 requirements.txt 中,避免普通 PyPI 覆盖 NPU 配套包:

预装包版本
torch2.9.0+cpu
torch_npu2.9.0

4.2 requirements.txt(固定版本)

仓库提供精确固定版本的 requirements.txt(顶层非 torch 依赖):

transformers==5.15.0
safetensors==0.8.0
huggingface_hub==1.28.0
soundfile==0.14.0
numpy==1.26.4
Pillow==12.3.0   # 仅渲染 assets/*.png 用

4.3 阿里云 PyPI 安装命令

pip install -i https://mirrors.aliyun.com/pypi/simple/ \
    --trusted-host mirrors.aliyun.com \
    -r requirements.txt

本机已配置阿里云源(环境变量 PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/)。不得安装 CUDA wheels、Triton、flash-attn、xformers、bitsandbytes 或其它 torch 构建。


5. 分步推理操作流程

步骤 0:加载昇腾环境(CANN)

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=2        # 仅暴露 npu:2(可选,按需)

步骤 1:确认本地模型与测试音频

ls -l /work/pipeline/models/audio7/w2v-xls-r-uk/model.safetensors
sha256sum /work/pipeline/models/audio7/w2v-xls-r-uk/model.safetensors
# 期望 e8d3ea3825853c6016539d474878fc281cf0bbb2fa9209f34f403b91e2eb0fe9

ls -l assets/uk_test_speech.wav
sha256sum assets/uk_test_speech.wav
# 期望 010205be4c70d43feba3f95f9dd361535ef467c7183dc92db2971b40aab96cb7

步骤 2:(可选)重新生成确定性测试音频

python3 make_test_audio.py        # 生成 assets/uk_test_speech.wav + .json

步骤 3:执行 NPU 推理(设备 npu:2)

python3 inference.py \
    --model  /work/pipeline/models/audio7/w2v-xls-r-uk \
    --audio  assets/uk_test_speech.wav \
    --device npu:2 \
    --output-json logs/npu_result.json

步骤 4:查看结果

cat logs/npu_result.json

参数表:inference.py

参数必填默认说明
--model否/work/pipeline/models/audio7/w2v-xls-r-uk本地模型目录
--audio否assets/uk_test_speech.wav输入音频(16 kHz 单声道 WAV 最佳)
--device否npu:2目标设备,仅接受 npu:<idx>,否则报错退出
--output-json否logs/npu_result.json结构化结果 JSON 输出路径
--revision否e3ced4def0d70be3aab0f2db598a59961fe9ab3b固定源 revision

6. 完整测试用例(真实输出)

6.1 测试输入

assets/uk_test_speech.wav —— 本仓库自创、确定性、CC0 豁免的合成类语音波形(非真人录音):

属性值
采样率16,000 Hz
声道1(单声道)
采样点数28,800
时长1.8 s
RMS0.272873
字节数57,644
SHA256010205be4c70d43feba3f95f9dd361535ef467c7183dc92db2971b40aab96cb7
来源自作者生成(formant 滤波谐波元音序列 + 确定性摩擦噪声),无版权
许可证CC0-1.0

6.2 实际执行命令(本次交付执行)

cd /work/pipeline/jobs/audio7/w2v-xls-r-uk/w2v-xls-r-uk-npu
source /usr/local/Ascend/ascend-toolkit/set_env.sh
python3 inference.py \
    --model  /work/pipeline/models/audio7/w2v-xls-r-uk \
    --audio  assets/uk_test_speech.wav \
    --device npu:2 \
    --output-json logs/npu_result.json

6.3 实际输出(stdout,保存于 logs/npu_inference.log)

[INFO] loading model: /work/pipeline/models/audio7/w2v-xls-r-uk
======================================================================
Yehor/w2v-xls-r-uk — Wav2Vec2ForCTC (Ukrainian ASR) — NPU inference result
======================================================================
engine           : torch_npu
torch            : 2.9.0+cpu
torch_npu        : 2.9.0
CANN             : 8.5.1
NPU available    : True
NPU device count : 8
NPU current dev  : 2
NPU device name  : Ascend910B4-1
device requested : npu:2
pinned revision  : e3ced4def0d70be3aab0f2db598a59961fe9ab3b
local revision   : e3ced4def0d70be3aab0f2db598a59961fe9ab3b
weights          : /work/pipeline/models/audio7/w2v-xls-r-uk/model.safetensors
  bytes          : 1261971432
  sha256         : e8d3ea3825853c6016539d474878fc281cf0bbb2fa9209f34f403b91e2eb0fe9
audio            : /work/pipeline/jobs/audio7/w2v-xls-r-uk/w2v-xls-r-uk-npu/assets/uk_test_speech.wav
  sample_rate    : 16000 Hz
  samples        : 28800
  duration       : 1.8 s
input device     : npu:2
model device     : npu:2
logits device    : npu:2
output device    : npu:2
logits shape     : [1, 89, 40]
logits absmax    : 16.545188903808594
last-frame top-5 : [{'token_id': 2, 'logit': 7.793326377868652}, {'token_id': 4, 'logit': 4.779824733734131}, {'token_id': 1, 'logit': 2.018268346786499}, {'token_id': 32, 'logit': 1.60408616065979}, {'token_id': 31, 'logit': 1.4694147109985352}]
pred token ids   : [[2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 20, 2, 2, 2, 2, 2, 2, 2, 19, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 10, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 24, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]]
non-blank ids    : [20, 19, 10, 24]
transcription    : поеу
output           : {"text": "поеу", "language": "uk", "decoding": "greedy CTC (torch.argmax + Wav2Vec2Processor.batch_decode)", "logits": {...}, "tokens": {"non_blank_ids": [20, 19, 10, 24], ...}}
elapsed          : 11.0644 s
======================================================================
[INFO] JSON result written: logs/npu_result.json

6.4 结构化结果(logs/npu_result.json)

{
  "engine": "torch_npu",
  "model_id": "Yehor/w2v-xls-r-uk",
  "source_url": "https://huggingface.co/Yehor/w2v-xls-r-uk",
  "pinned_revision": "e3ced4def0d70be3aab0f2db598a59961fe9ab3b",
  "local_model_revision": "e3ced4def0d70be3aab0f2db598a59961fe9ab3b",
  "local_revision_matches_pinned": true,
  "exit_code": 0,
  "torch_version": "2.9.0+cpu",
  "torch_npu_version": "2.9.0",
  "cann_version": "8.5.1",
  "npu_available": true,
  "npu_device_count": 8,
  "npu_current_device": 2,
  "npu_device_name": "Ascend910B4-1",
  "device_requested": "npu:2",
  "model_path": "/work/pipeline/models/audio7/w2v-xls-r-uk",
  "weight_file": "model.safetensors",
  "weight_bytes": 1261971432,
  "weight_sha256": "e8d3ea3825853c6016539d474878fc281cf0bbb2fa9209f34f403b91e2eb0fe9",
  "audio": {
    "path": "/work/pipeline/jobs/audio7/w2v-xls-r-uk/w2v-xls-r-uk-npu/assets/uk_test_speech.wav",
    "sample_rate": 16000,
    "channels": 1,
    "samples": 28800,
    "duration_sec": 1.8
  },
  "input_device": "npu:2",
  "model_device": "npu:2",
  "logits_device": "npu:2",
  "output_device": "npu:2",
  "logits_shape": [1, 89, 40],
  "logits_absmax": 16.545188903808594,
  "logits_last_frame_topk": [
    {"token_id": 2, "logit": 7.793326377868652},
    {"token_id": 4, "logit": 4.779824733734131},
    {"token_id": 1, "logit": 2.018268346786499},
    {"token_id": 32, "logit": 1.60408616065979},
    {"token_id": 31, "logit": 1.4694147109985352}
  ],
  "pred_token_ids": [
    [2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 20, 2, 2, 2, 2, 2, 2, 2, 19, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 10, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 24, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
  ],
  "transcription": "поеу",
  "output": {
    "text": "поеу",
    "language": "uk",
    "decoding": "greedy CTC (torch.argmax + Wav2Vec2Processor.batch_decode)",
    "logits": {
      "shape": [1, 89, 40],
      "absmax": 16.545188903808594,
      "device": "npu:2",
      "last_frame_topk": [
        {"token_id": 2, "logit": 7.793326377868652},
        {"token_id": 4, "logit": 4.779824733734131},
        {"token_id": 1, "logit": 2.018268346786499},
        {"token_id": 32, "logit": 1.60408616065979},
        {"token_id": 31, "logit": 1.4694147109985352}
      ]
    },
    "tokens": {
      "argmax_ids": [
        [2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 20, 2, 2, 2, 2, 2, 2, 2, 19, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 10, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 24, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
      ],
      "non_blank_ids": [20, 19, 10, 24],
      "non_blank_text": "поеу"
    }
  },
  "elapsed_sec": 11.064409
}

6.5 并发 npu-smi info 监控(logs/npu_smi_monitor.log)

推理期间后台并发轮询 npu-smi info,捕获到 NPU 2 上的活跃推理进程与显存上升:

| 2       0                 | 2845124       | python                   | 1526                    |
| 0                         | 0000:81:00.0  | 0           0    / 0          3398 / 65536         |   (空闲)
| 0                         | 0000:81:00.0  | 0           0    / 0          4871 / 65536         |   (推理中)

即 NPU 2 的 HBM 从空闲 ~3398 MB 上升至推理中 ~4871 MB,并出现 python 推理进程(PID 2845124,进程内存 1526 MB)——证明神经推理确实运行在 npu:2 上。


7. 输出结果

指标值
enginetorch_npu
退出码0
NPU 可用性 / 名称 / 数量True / Ascend910B4-1 / 8
分配设备npu:2
输入 / 模型 / 输出 devicenpu:2 / npu:2 / npu:2
输出 logits shape[1, 89, 40]
logits absmax16.5452
末帧 top-5 token id / logit2:7.793 4:4.780 1:2.018 32:1.604 31:1.469
预测 token 序列(89 帧 argmax)[2,2,…,2,20,…,2,19,…,2,10,…,2,24,…,2](CTC 去重后解码为 поеу)
解码转写(乌克兰语)поеу
顶层 output.textпоеу
顶层 output.decodinggreedy CTC (torch.argmax + Wav2Vec2Processor.batch_decode)
顶层 output.tokens.non_blank_ids[20, 19, 10, 24](CTC 去 blank 后序列)
耗时11.0644 s(含首次图编译)

证据文件:

  • logs/npu_inference.log(真实推理 stdout,已去除 CANN 无害 stderr 噪声;原始含噪声版本见 evidence/npu_inference_raw.log)
  • logs/npu_result.json(结构化结果)
  • logs/npu_smi_monitor.log(并发 NPU 监控)
  • assets/agent_workflow.png(1440×1800,工作流截图)
  • assets/npu_device_call.png(1440×900,NPU 设备调用证据)
  • assets/model_result.png(1440×900,模型结果证据)

8. NPU 无 CPU fallback 说明

本交付严禁静默回退 CPU,并在代码与运行结果双重落实:

  1. inference.py 显式 import torch_npu(注册 NPU backend),缺省不可用。
  2. 硬校验(任一不满足即报错退出,绝不回退):
    • torch.npu.is_available() == False → 报错退出(exit 1);
    • torch.npu.device_count() == 0 → 报错退出(exit 1);
    • 请求设备索引 ≥ 设备数 → 报错退出(exit 2);
    • --device 非 npu:<idx> 形式 → 报错退出(exit 2)。
  3. 推理后断言 input_device == model_device == logits_device == output_device == npu:2,任何不一致即报错退出。
  4. CPU 仅用于文档化的音频 I/O(读 WAV)、特征预处理、CTC 解码与后处理;神经 forward 全程在 NPU。
  5. 实测结果四者均为 npu:2(见第 6/7 节)。

9. 交付文件清单

文件说明
inference.pyNPU 推理脚本(无 CPU fallback,--device npu:2)
make_test_audio.py确定性 CC0 合成测试音频生成脚本
render_assets.py从真实日志渲染三张截图 PNG 的脚本
requirements.txt固定版本非 torch 依赖
readme.md / README.md本文档(两份字节完全一致)
.gitignore排除 __pycache__/、*.py[cod]、运行时缓存与编译产物
SHA256SUMS交付文件哈希清单(不含模型权重)
assets/uk_test_speech.wav确定性 CC0 测试音频(16 kHz / 1.8 s)
assets/uk_test_speech.json测试音频统计与 SHA256
assets/agent_workflow.png工作流截图(1440×1800)
assets/npu_device_call.pngNPU 设备调用证据截图(1440×900)
assets/model_result.png模型结果证据截图(1440×900)
assets/*.txt对应截图的纯文本数据源
logs/npu_inference.log真实推理 stdout(已清理 CANN stderr 噪声)
logs/npu_result.json真实推理结构化结果
logs/npu_smi_monitor.log并发 npu-smi info 监控日志
evidence/npu_inference_raw.log推理 stdout 原始副本(含 path string is NULL 无害噪声)

10. 校验

# 语法检查
python3 -m py_compile inference.py make_test_audio.py render_assets.py

# 交付文件哈希校验
sha256sum -c SHA256SUMS

# 模型权重单独校验
sha256sum /work/pipeline/models/audio7/w2v-xls-r-uk/model.safetensors
# e8d3ea3825853c6016539d474878fc281cf0bbb2fa9209f34f403b91e2eb0fe9

# readme/README 字节一致性
cmp readme.md README.md && echo OK

# 依赖镜像校验
pip config list   # 应显示 mirrors.aliyun.com

11. 故障排查

问题原因解决
torch.npu.is_available() == FalseCANN/驱动环境未加载或 torch_npu 未导入source /usr/local/Ascend/ascend-toolkit/set_env.sh;确认 python3 -c "import torch_npu" 成功
RuntimeError: ... not supported on NPU个别算子未适配 NPU使用标准 PyTorch/torch_npu 算子替代,或缩小输入
device placement check failed输入/模型/logits/输出不在请求设备检查 --device 与 torch.npu.set_device 一致
加载权重报 OOM1.26 GB 权重 + 图编译需 HBM确保设备空闲、HBM 充足;换空闲 NPU
安装依赖拉到 torchpip 解析到 torch 依赖只用 -i https://mirrors.aliyun.com/pypi/simple/ 安装 requirements.txt;绝不重装 torch/torch_npu

12. 模型局限

  • 评测域:模型仅在 Common Voice uk test 集报告 WER 20.24% / CER 3.64%;口音、噪声、电话语音等场景 WER 会上升。
  • 无外部语言模型:当前为 CTC 贪心解码,未集成 KenLM/语言模型;长句与专有名词转写质量有限。模型自带的 language_model/(KenLM)在本交付中未加载。
  • 采样率:要求 16 kHz 输入;非 16 kHz 会自动重采样,但以 16 kHz 为最优。
  • 词表较小:vocab_size=40(字符级),数字、标点、未登录词支持有限。
  • 合成测试音频:assets/uk_test_speech.wav 为自创类语音波形(CC0),用于硬件通路冒烟测试;其转写 поеу 是模型的真实输出,但不能代表真实乌克兰语口语识别质量。真实语音应使用清晰 16 kHz 人声。
  • 模型卡提示:作者推荐使用更新模型 Yehor/w2v-bert-uk-v2.1;本交付仅按任务要求适配固定 revision 的本模型。

13. 许可证与使用限制

  • 模型权重:上游模型卡声明 Apache-2.0(license: apache-2.0)。使用时请遵循 Apache-2.0 条款(保留版权声明、不得使用贡献者名称作背书等)。
  • 测试音频:assets/uk_test_speech.wav 为本仓库自创合成类语音波形,以 CC0-1.0(公有领域)发布,无版权、可自由使用与再分发。
  • 代码与文档:本交付仓库内 inference.py、make_test_audio.py、render_assets.py、readme.md、requirements.txt 等为本任务适配产物。
  • 运行环境:必须在预装匹配 torch==2.9.0+cpu / torch_npu==2.9.0 的昇腾容器中运行;用普通 PyPI 覆盖 torch 会使 NPU 不可用。
  • 本交付不含任何凭据、密钥路径、临时文件或模型权重;权重保留在交付目录之外的本地模型路径。

附录 A:参考资料

  • 模型卡:https://huggingface.co/Yehor/w2v-xls-r-uk
  • 基座模型:https://huggingface.co/facebook/wav2vec2-xls-r-300m
  • 数据集:https://huggingface.co/datasets/mozilla-foundation/common_voice_10_0(uk)
  • 固定 revision:e3ced4def0d70be3aab0f2db598a59961fe9ab3b
  • torch_npu:https://gitee.com/ascend/pytorch

ModelAgent 现场会话界面

下图是本次适配与第二轮上游规范复核的 ModelAgent 流式会话只读回放,来源为公开交付中的脱敏会话日志;命令、问题定位、修复和验收结论均来自真实会话。

ModelAgent 现场会话界面

昇腾 NPU 适配证据截图

Agent 完整适配工作流

Agent 完整适配工作流

NPU 硬件设备调用日志

NPU 硬件设备调用日志

模型最终适配验收结果

模型最终适配验收结果