facebook/w2v-bert-2.0 · 昇腾 NPU 推理适配

模型卡 · 中文版（Model Card, zh-CN）

1. 模型简介

W2v-BERT 2.0 是 Meta 开源的 Conformer 架构多语言自监督语音编码器，约 600M 参数， 基于 450 万小时、覆盖 143+ 种语言的未标注语音预训练（见论文 Seamless: Multilingual Expressive and Streaming Speech Translation）。 本仓库将其适配到 昇腾（Ascend）NPU 上，通过 torch_npu 在 npu:0 执行前向推理， 输出顶层语音 embedding。

该模型为 裸编码器（bare encoder）：不含 ASR 识别头、不含 tokenizer，需在预训练基础上 微调才能用于 ASR / 音频分类等下游任务。因此本仓库直接使用 AutoFeatureExtractor （解析为 SeamlessM4TFeatureExtractor）将 16 kHz 波形转为 log-mel 频谱后送入编码器。

2. 支持的任务

• 主用（本仓库）：语音表示提取 —— 前向得到 (1, T, 1024) 顶层 last_hidden_state 序列 embedding。
• 下游（需微调，未包含）：自动语音识别（ASR）、音频分类、说话人/语义特征下游任务等。
• 当前版本不支持：端到端语音翻译（Seamless 完整流程）、文本侧 tokenizer 解码。

3. 环境与依赖

前置平台栈（本仓库不负责安装）：

• 操作系统：Linux aarch64（本次验证环境）
• 昇腾 CANN 工具链（本次为 CANN 8.5.1）
• Python 3.11
• torch + torch-npu（本次为 torch 2.9.0 + torch-npu 2.9.0.post1）

应用层依赖（requirements.txt，仅列出推理脚本真正需要的库，不含平台栈）：

pip install -r requirements.txt

4. 获取模型（固定版本 / 校验哈希）

模型：facebook/w2v-bert-2.0，固定 revision da985ba0987f70aaeb84a80f2851cfac8c697a7b。

权重 model.safetensors 固定哈希（脚本内置校验，不匹配即拒绝运行、绝不静默替换）：

获取方式（无需手动执行；inference.py 在本地 models/ 缺失时会自动下载）：

• 首选：Hugging Face 固定 revision

  python -c "from huggingface_hub import snapshot_download; \
  snapshot_download('facebook/w2v-bert-2.0', revision='da985ba0987f70aaeb84a80f2851cfac8c697a7b', \
  local_dir='models', allow_patterns=['model.safetensors','config.json','preprocessor_config.json','README.md'])"

• 镜像兜底（仅当最终字节/SHA 匹配才采用）：ModelScope facebook/w2v-bert-2.0

  python -c "from modelscope import snapshot_download; \
  snapshot_download('facebook/w2v-bert-2.0', revision='master', local_dir='models', \
  allow_patterns=['model.safetensors','config.json','preprocessor_config.json','README.md'])"

• 策略：脚本只在字节数 + SHA256 双校验通过后使用或持久化 checkpoint； 对已存在的已验证本地 models/ 不做任何改动。

5. 使用方法

# 1) 安装应用依赖（平台栈 torch/torch-npu/CANN 需已就绪）
pip install -r requirements.txt

# 2) 运行 NPU 推理（必须存在可用昇腾 NPU，无 CPU 回退）
python inference.py --model-dir models --wav sample.wav --device npu:0

参数：

• --model-dir：可选。指定后必须与固定哈希一致；缺省时优先使用已验证的本地 models/， 否则自动按固定 revision 从 Hugging Face 下载（镜像兜底须哈希一致）。
• --wav：真实 16 kHz 单声道 WAV 路径，默认 sample.wav。
• --device：默认 npu:0。

输出：result.json（见第 8 节）与完整日志 npu_result.txt。

6. 真实样本

sample.wav 为官方真实语音样本，取自 Hugging Face hf-internal-testing/librispeech_asr_demo （clean/validation，id 1272-128104-0000），固定 revision 48b47ace52db0fb183e30b87988149a5b4f9a5b2。非合成、非重编码，逐字节传输。

7. 真实昇腾 NPU 验证

在 npu:0（Ascend910_9362，共 2 卡）上使用上述真实样本完成前向冒烟验证：

[npu] device=npu:0 count=2 name=Ascend910_9362
[in]  real input sample.wav: 93680 samples @ 16000 Hz (5.86s)
[out] last_hidden_state (1, 292, 1024) dtype=torch.float32 device=npu:0
[out] stats mean=-0.00003 std=0.15411 min=-2.81605 max=4.11433
[out] forward time on npu:0: 0.214s

• 全链路（模型参数、input_features、attention_mask、输出）均在 NPU 上，无 CPU 回退； 若 torch.npu.is_available() 为假则直接报错退出。
• 输出形状 (1, 292, 1024) 与 hidden_size=1024 一致；5.86 s 音频对应 292 帧， 与编码器 80-mel / stride 2 下采样相符。
• 输出 dtype 由 result.json / npu_result.txt 记录（配置声明 torch_dtype: float32）。
• 完整日志：npu_result.txt；结构化结果：result.json。

仓库中的三张真实昇腾 NPU 证据截图（位于 assets/）：

8. 输出解读与限制

result.json 关键字段：

限制：

• 裸编码器输出 不是 语音识别文本，也不含概率/置信度；如需 ASR 请微调后接识别头。
• 本次最终复验以 torch.float32 前向；数值为编码器隐层表示， 需按下游任务语义使用。
• 平台栈（torch / torch-npu / CANN）与硬件由部署方保证，本仓库不负责安装。

9. 许可证

模型与模型卡：MIT（依据 models/README.md 元数据 license: mit）。 本仓库的适配脚本与文档可按 MIT 使用。本地仓库中未附带独立的 LICENSE.md 文件， 交付物中因此不含（“如可用才包含”）。