wav2vec2-large-xlsr-cantonese推理完全教程:5个步骤把粤语音频变成文字

原创2026-11-10 17:43:321,702 阅读
文章标签:语音音频深度学习微调人工智能NLP

wav2vec2-large-xlsr-cantonese推理完全教程:5个步骤把粤语音频变成文字

wav2vec2-large-xlsr-cantonese 是一个面向粤语(zh-HK)的语音识别(ASR)模型,基于 wav2vec2-large-xlsr-53 在 Common Voice zh-HK 数据集上微调而来,测试集 CER 低至 15.11%。本教程带你用 5 个步骤完成部署与推理:把一段粤语音频变成文字,全程只需几十行配置 + 十几行 Python 代码。🎧

一、为什么选择 wav2vec2-large-xlsr-cantonese?

很多通用语音模型对粤语支持不佳,而粤语作为独立语系,声调和用字都有特殊性。wav2vec2-large-xlsr-cantonese 正是为此而生的专项模型:

项目 说明
基座模型 wav2vec2-large-xlsr-53
微调数据 Common Voice zh-HK 6.1.0
训练时长 80 个 epoch(单卡 RTX 3090,apex fp16)
测试集 CER 15.11%(越低越好)
推理架构 Wav2Vec2ForCTC(CTC 解码,无需语言模型)
许可证 cc-by-sa-4.0
输出文字 粤语专用汉字(如"攞""啜""叻"),见 vocab.json

💡 一句话总结:粤语语音转文字、离线可用、开箱即用的开源 ASR 模型。

二、步骤 1:安装依赖环境

本教程需要 Python 3.8+。核心依赖只有 3 个库:torch、transformers、soundfile:

pip install torch transformers soundfile

如果后续想用 datasets 加载示例音频做批量测试,可再装:

pip install datasets

提示:CTC 架构的 wav2vec2 模型推理速度快,8GB 显存的消费级显卡即可流畅运行;纯 CPU 也能用,只是速度会慢不少。

三、步骤 2:获取模型文件

模型仓库中包含了推理所需的全部文件。推荐用 Git 获取:

git clone https://gitcode.com/hf_mirrors/scottykwok/wav2vec2-large-xlsr-cantonese

⚠️ 新手最容易踩的坑:仓库中 pytorch_model.bin、optimizer.pt 等大文件使用 Git-LFS 管理。如果你没有安装 git-lfs,克隆下来的 pytorch_model.bin 只有约 135 字节(内容是一行 LFS 指针文本),加载时会直接报错。解决方法:

git lfs install
git clone https://gitcode.com/hf_mirrors/scottykwok/wav2vec2-large-xlsr-cantonese

完整的文件说明见下文模型目录速查表。

四、步骤 3:准备 16kHz 单声道音频

处理器配置 preprocessor_config.json 中写明了硬性要求:sampling_rate 为 16000(即 16kHz),且音频需为单声道(mono)。如果你的音频是 44.1kHz 立体声,直接用 ffmpeg 或 sox 转换一下即可:

ffmpeg -i input.mp3 -ar 16000 -ac 1 audio.wav
  • -ar 16000:重采样到 16kHz
  • -ac 1:转为单声道

这一步做对,后面就不会出现识别结果错乱的问题。✅

五、步骤 4:加载模型并执行推理

推理脚本参考 README.md 官方 Usage,核心流程分 4 小步:

  1. 加载处理器和模型:Wav2Vec2Processor 负责音频特征提取,Wav2Vec2ForCTC 负责声学建模(词表与特殊 token 定义在 tokenizer_config.json 和 special_tokens_map.json)。
  2. 读取音频:用 soundfile 读入 16kHz 单声道波形。
  3. 前向推理:模型输出 logits,取 argmax 得到字符 ID 序列。
  4. 解码文字:processor.decode() 把 ID 序列还原为粤语文字,| 作为词语分隔符。

完整参考代码(已精简):

import soundfile as sf
import torch
from transformers import Wav2Vec2ForCTC, Wav2Vec2Processor

processor = Wav2Vec2Processor.from_pretrained("scottykwok/wav2vec2-large-xlsr-cantonese")
model = Wav2Vec2ForCTC.from_pretrained("scottykwok/wav2vec2-large-xlsr-cantonese")

audio_input, sample_rate = sf.read("audio.wav")  # 必须 16kHz 单声道

input_values = processor(audio_input, sampling_rate=sample_rate,
                         return_tensors="pt").input_values

logits = model(input_values).logits
predicted_ids = torch.argmax(logits, dim=-1)

print("Transcription:\n", processor.decode(predicted_ids[0]).lower())

🚀 模型结构参数(24 层 Transformer、隐藏维度 1024、词表 3555)都记录在 config.json 中,一般无需关心。

六、步骤 5:验证结果与常见问题排查

拿到转录文字后,可以对照原音频核对。遇到以下情况按表处理:

现象 原因 解决办法
加载报 OSError: ... not a PyTorch file pytorch_model.bin 是 LFS 指针文件 安装 git-lfs 后重新 clone
识别结果完全错乱/空白 采样率不是 16kHz 或为立体声 按步骤 3 重转音频
首次推理慢 权重首次读入 + 模型初始化 属正常现象,后续推理明显变快
长音频 OOM 一次性送入过长波形 分段切块后逐段推理

想了解模型的训练轨迹(loss 与 CER 随 epoch 的下降过程),可以查看 trainer_state.json——里面记录了 80 个 epoch、共 100 次评估的完整日志。

七、模型目录速查表(新手避坑指南)

wav2vec2-large-xlsr-cantonese/
├── README.md                 # 模型介绍 + 推理示例
├── config.json               # 模型结构配置
├── preprocessor_config.json  # 音频处理器配置(16kHz)
├── tokenizer_config.json     # CTC 分词器配置
├── special_tokens_map.json   # 特殊 token 定义
├── vocab.json                # 粤语字符词表
└── pytorch_model.bin         # 模型权重(约 1.2GB,LFS)
  • 推理只需关注加粗的 6 个 JSON/配置文件 + pytorch_model.bin 权重。
  • optimizer.pt、rng_state.pth、scheduler.pt、training_args.bin 都是训练过程的中间产物,推理时用不到,可放心忽略。

八、常见问题 FAQ

Q1:识别出来的是繁体字还是简体字? 词表基于粤语常用汉字,输出多为粤语固有写法(繁简混用),可再自行做繁简转换。

Q2:支持普通话吗? 不建议。本模型专为粤语(zh-HK)微调,普通话请选用其他 zh 系列模型。

Q3:CER 15.11% 是什么概念? 字符错误率 15.11%,意味着约 100 个字里平均错 15 个,在粤语识别领域属于实用水平,日常对话、新闻语速下准确率会更高。

Q4:可以商用吗? 模型许可证为 cc-by-sa-4.0(署名-相同方式共享),商用前请自行确认合规要求。


按以上 5 个步骤——装环境 → 拿模型 → 转音频 → 跑推理 → 验结果——你已完成 wav2vec2-large-xlsr-cantonese 的完整部署。接下来不妨录一段粤语日常对话试试效果,把模型接入你自己的字幕或语音助手项目里吧!

登录后查看全文
wav2vec2-large-xlsr-cantonese