anning-2026/w2v-xls-r-uk
模型介绍
文件和版本
Pull Requests
讨论
分析

Yehor/w2v-xls-r-uk 昇腾 NPU 部署文档

1. 模型简介

模型名称: Yehor/w2v-xls-r-uk 模型链接: https://huggingface.co/Yehor/w2v-xls-r-uk 模型描述: 基于 Wav2Vec2-XLS-R-300M 在 Common Voice 10.0 乌克语数据上微调的语音转文本(STT)模型(CTC 字符级解码),输入 16kHz 单声道音频,输出乌克语文本。 模型架构: Wav2Vec2ForCTC(XLS-R encoder,24 层 Transformer,hidden 1024,7 层卷积特征提取,字符表 40) 参数规模: ~315.5M(fp32,单分片 model.safetensors 1,261,971,432 bytes,sha256 校验与 LFS oid 一致) 适配引擎: torch_npu(昇腾 NPU 推理引擎)

标签集合: automatic-speech-recognition / wav2vec2 / xls-r / audio / speech-to-text / ctc / NPU / Ascend / torch_npu / model-agent-tagged

2. 环境依赖

依赖项版本说明
torch2.9.0
torch_npu2.9.0.post1昇腾 NPU 推理引擎
transformers4.46.3标准格式加载(Wav2Vec2ForCTC + Wav2Vec2Processor),无需 custom code
soundfile / librosa-音频读取与重采样
av(PyAV)>= 12ogg/opus 解码(内置示例音频为 Ogg Opus)
fastapi / uvicorn / python-multipart-服务化推理(server.py)

注:本模型为 transformers 标准格式(model.safetensors + config.json + preprocessor_config.json + vocab.json),权重与配置放 /tmp/w2v-xls-r-uk/。仓内 language_model/(4-gram kenlm)为可选增强,默认 greedy 解码即可。

3. 推理步骤

# 内置示例音频(30s 乌克语,默认 npu:0)
python inference.py --device npu:0

# 指定音频文件(wav/flac 直读;ogg/opus 自动用 PyAV 解码并重采样到 16kHz)
python inference.py --audio your_audio.ogg --device npu:0

# 纯 CPU 推理(对比验证)
python inference.py --device cpu

推理流程:Wav2Vec2Processor(audio, sampling_rate=16000) 提取特征 → Wav2Vec2ForCTC(input_values, attention_mask) 前向得到 CTC logits → argmax + batch_decode() 得到乌克语文本。

4. 测试样例及输出结果

以下输出为在昇腾 Ascend 910B4(CANN 8.5.1 + torch_npu 2.9.0.post1 + transformers 4.46.3)上实测获得。

样例 1:乌语语音转写(30s)

命令:

python inference.py --device npu:0

输出:

[加载] 完成: Wav2Vec2ForCTC (315.5M params),耗时 3.90s
[输入] examples/sample_uk_30s.wav(30.00s @16kHz)
[结果] 转写文本: падре неканор заперечував проти відправлення релігійного обряду і поховання самовбивці в освячений землі гурсула почала з ним суперечко по своєму чогні ...
[耗时] 7.38s

正确性验证:

  • 首次推理含算子编译预热(约 7s),进程内稳态耗时 0.10s/条(30s 音频)
  • 同一输入在 CPU 与 NPU 上推理,greedy 转写文本完全一致(CTC logits 幅值大,逐点比较无意义,以解码结果为准)
  • 转写结果为连贯、语义通顺的乌克语文本,验证了 w2v-xls-r-uk 在昇腾 NPU 上的语音识别链路通畅

5. Agent 适配截图

Agent 适配流程 NPU 设备调用 模型适配结果

6. 服务化推理

python server.py --port 8000 --device npu:0

接口:

  • GET /health → {"status":"ok","model":"Yehor/w2v-xls-r-uk","device":"npu:0","loaded":true}
  • POST /asr(multipart:file 音频文件)→ 乌克语转写文本

实测(服务化):

  • /health → {"status":"ok","model":"Yehor/w2v-xls-r-uk","device":"npu:0","loaded":true}
  • /asr(sample_uk_30s.wav,稳态)→ {"text":"падре неканор заперечував проти відправлення ...","audio_seconds":30.0,"elapsed_s":0.103}

7. 注意事项

  • 模型权重位于 /tmp/w2v-xls-r-uk/(1,261,971,432 bytes,sha256 校验通过),不占用仓库空间,不纳入本仓库
  • 音频要求——16kHz 单声道;单次前向建议 ≤30s(超长截断),return_attention_mask=true 必须随输入传入
  • 首帧预热——NPU 首次推理含算子编译,约 7s;服务化场景建议启动后先跑一次预热请求
  • ogg/opus 音频——libsndfile 不支持 Opus,脚本自动回退 PyAV 解码(需 pip install av)
  • LM 增强——仓内 language_model/lm.binary 可配合 pyctcdecode 做 4-gram LM 解码提升准确率,默认未启用
  • 大文件务必校验 sha256 与 LFS oid 一致,避免下载损坏导致输出异常