如何快速上手 wav2vec2-large-xlsr-cantonese:新手10分钟从零跑通粤语语音转文字教程
如何快速上手 wav2vec2-large-xlsr-cantonese:新手10分钟从零跑通粤语语音转文字教程
正在找粤语语音转文字方案?wav2vec2-large-xlsr-cantonese 是一个专为粤语优化的自动语音识别(ASR)模型,基于 Meta 的 wav2vec2-large-xlsr-53 架构,用 Common Voice 粤语数据集(zh-HK 6.1.0)微调而成,在粤语测试集上的字符错误率(CER)仅 15.11%,能让机器"听懂"粤语并输出文字。
本文是面向新手的完整指南:不需要 GPU,不需要复杂背景,跟着 10 分钟即可从零跑通你的第一段粤语语音转文字。
一、模型是什么?为什么选它?
| 项目 | 说明 |
|---|---|
| 模型架构 | wav2vec2(CTC 解码,非自回归,推理快) |
| 预训练基座 | wav2vec2-large-xlsr-53(Meta 发布的跨语言语音模型) |
| 微调数据 | Mozilla Common Voice 粤语(zh-HK 6.1.0) |
| 识别效果 | CER 15.11%(测试集实测) |
| 词表规模 | 3555 个粤语用字 |
| 音频要求 | 16kHz 单声道 |
| 许可证 | CC-BY-SA-4.0 |
它特别适合这类场景:
- 🎙️ 粤语语音备忘录、录音自动转写
- 📻 粤语播客、访谈字幕生成
- 🤖 粤语语音助手 / 智能客服的前置识别
- 🏫 粤语学习工具的听写对照
二、10分钟上手前的准备清单
开始之前,请确认三件事,能省掉 90% 的踩坑时间:
- Python 环境:建议 Python 3.8 及以上
- 依赖库:
transformers、torch、soundfile - 一段粤语音频:
.wav格式、16kHz 采样率、单声道
💡 提示:wav2vec2 对采样率敏感。如果你的音频不是 16kHz,先用 ffmpeg 转换:
ffmpeg -i input.mp3 -ar 16000 -ac 1 audio.wav
核心配置文件速览
理解下面的两个文件,有助于你排查问题和定制流程:
- 模型结构:config.json —— 可见
hidden_size: 1024、num_hidden_layers: 24、vocab_size: 3555等关键参数 - 音频预处理:preprocessor_config.json —— 固定了
sampling_rate: 16000,这就是"必须 16kHz"的出处 - 词表:vocab.json —— 粤语字与 token id 的映射
- 分词器配置:tokenizer_config.json
- 项目说明:README.md —— 含完整的用法示例代码
三、最快配置方法:一键安装依赖
在新终端中执行以下命令,安装所需依赖:
pip install transformers torch soundfile
安装完成后,验证版本:
python -c "import transformers; import torch; import soundfile; print('OK')"
看到 OK 即说明环境就绪。
四、从零跑通:3步完成粤语语音转文字
整个推理流程只有 3 步:加载模型 → 处理音频 → 解码输出。
第 1 步:加载模型和处理器
from transformers import Wav2Vec2ForCTC, Wav2Vec2Processor
processor = Wav2Vec2Processor.from_pretrained("scottykwok/wav2vec2-large-xlsr-cantonese")
model = Wav2Vec2ForCTC.from_pretrained("scottykwok/wav2vec2-large-xlsr-cantonese")
⏳ 首次运行会自动下载模型权重(约 1GB),请耐心等待;之后走缓存,秒级加载。
第 2 步:读取并预处理音频
import soundfile as sf
import torch
# 音频必须是 16kHz 单声道
audio_input, sample_rate = sf.read('audio.wav')
input_values = processor(audio_input, sampling_rate=sample_rate,
return_tensors="pt").input_values
processor 会自动完成归一化和填充(规则见 preprocessor_config.json),把原始波形变成模型可吃张量。
第 3 步:推理并输出文字
# 取 logits 并做 argmax(CTC 贪心解码)
logits = model(input_values).logits
predicted_ids = torch.argmax(logits, dim=-1)
# 解码为文字
transcription = processor.decode(predicted_ids[0])
print("-" * 20)
print("Transcription:\n", transcription.lower())
print("-" * 20)
运行完成后,终端会打印出识别出的粤语文字,恭喜 🎉 你已经跑通了第一个粤语语音转文字 Demo!
五、模型文件结构一览
| 文件 | 作用 |
|---|---|
| pytorch_model.bin | 模型权重(推理核心) |
| config.json | 模型结构超参数 |
| preprocessor_config.json | 音频特征提取器配置(16kHz 采样) |
| vocab.json | 粤语字符词表(3555 个 token) |
| tokenizer_config.json | CTC 分词器配置 |
| special_tokens_map.json | 特殊 token 映射 |
| trainer_state.json | 训练过程记录(80 个 epoch) |
| README.md | 官方使用说明 |
六、新手常见问题 FAQ
Q1:识别结果是繁体字,正常吗? 正常。词表(vocab.json)以粤语书面用字为准,多为繁体,可自行转换简体。
Q2:我的音频是 mp3 / m4a,能直接用吗? 不能直接读。先用 ffmpeg 转成 16kHz 单声道 wav 再送入模型。
Q3:识别不准怎么办?
- 检查音频信噪比,粤语环境噪声大时建议先做降噪
- 语速过快或含大量俚语、夹杂英文时,CTC 模型错误率会上升
- 15.11% 的 CER 意味着平均每 100 个字约有 15 个错,日常短句识别体验良好
Q4:能换成别的粤语模型吗?
本仓库是完整可加载的 HuggingFace 模型格式,from_pretrained 里的模型名替换为本地路径(如 "./wav2vec2-large-xlsr-cantonese")即可离线使用。
七、总结
- ✅ 10 分钟完成:装依赖 → 准备音频 → 三步推理
- ✅ 模型轻量好用:CTC 架构推理快,CPU 也能跑短音频
- ✅ 粤语专精:Common Voice zh-HK 微调,CER 15.11%
现在就准备一段粤语录音,开始你的语音转文字之旅吧!