whisper-large-v3-turbo-quantized-uk快速上手:5步用vLLM跑通乌克兰语语音转文字完整流程
whisper-large-v3-turbo-quantized-uk快速上手:5步用vLLM跑通乌克兰语语音转文字完整流程
whisper-large-v3-turbo-quantized-uk 是基于 OpenAI Whisper Large V3 Turbo 的 4 位量化版乌克兰语语音识别模型,专门针对乌克兰语做了校准量化。本文带你 5 步用 vLLM 跑通乌克兰语语音转文字(STT)完整流程:安装依赖、加载量化模型、构建音频输入、执行推理、拿到转写结果。全程只需一条 pip 命令和几十行 Python 代码,新手也能快速上手。
一、先认识这个模型:它和普通 Whisper 有什么区别?
简单来说,你拿到的是一包"开箱即用"的量化模型文件,仓库里包含完整运行所需的全部资源:
| 文件 | 作用 |
|---|---|
| model.safetensors | 量化后的模型权重(4-bit 打包格式) |
| config.json | 模型结构配置,含量化方案 quantization_config |
| generation_config.json | 生成参数与语言 ID 映射(乌克兰语 `< |
| preprocessor_config.json | 音频特征提取配置:16kHz 采样率、30 秒分块 |
| tokenizer_config.json、vocab.json、merges.txt、added_tokens.json、special_tokens_map.json | 分词器完整配置 |
| normalizer.json | 文本规范化规则 |
| recipe.yaml | 量化配方:W4A16 方案,作用于 Linear 层 |
三个核心特点 ⚡
- 4 位权重量化(W4A16):recipe.yaml 显示采用
GPTQModifier的W4A16方案,权重压缩到 int4(group_size: 128),显存占用大幅下降; - 乌克兰语专项校准:模型基于乌克兰语数据集
Yehor/cv10-uk-testset-clean-punctuated完成校准量化,转写质量比"直接量化"更稳; - vLLM 原生支持:
compressed-tensors量化格式可被 vLLM 直接加载,享受 PagedAttention 等高性能推理优化。
📖 模型来源与量化方法详见仓库说明:README.md
二、5 步上手:从安装到输出转写结果
第 1 步:安装依赖
只需安装两个包:vllm(推理引擎)和 polars(读取测试数据集):
pip install vllm polars
第 2 步:准备音频数据
Whisper 系列模型要求音频为 单声道、16 位、16kHz 采样率。参考实现用标准 wave 模块把 WAV 字节转成 float32 波形:
def bytes_to_numpy(_bytes):
with wave.open(io.BytesIO(_bytes), "rb") as wr:
# 要求:单声道、采样宽度 2 字节
audio_data = wr.readframes(wr.getnframes())
return np.frombuffer(audio_data, dtype=np.int16).astype(np.float32) / 32768.0
批量测试可以直接用 polars 读取示例数据集(README.md 中的写法):
df = pl.read_parquet("hf://datasets/Yehor/cv10-uk-testset-clean/data/train-*.parquet")
第 3 步:用 vLLM 加载量化模型
LLM 会自动从模型仓库下载并加载 model.safetensors 等文件,关键参数建议照抄官方推荐值:
from vllm import LLM, SamplingParams
llm = LLM(
model="Yehor/whisper-large-v3-turbo-quantized-uk",
max_model_len=448, # 与 config.json 中 max_target_positions 一致
max_num_seqs=400, # 并发序列数,适合批量转写
gpu_memory_utilization=0.8,
limit_mm_per_prompt={"audio": 1}, # 每条输入 1 段音频
)
💡 max_model_len=448 不是随便写的——它对应 config.json 中的 max_target_positions: 448,即单次转写输出长度上限。
第 4 步:构建乌克兰语识别输入
Whisper 的提示词格式固定为「起始符 + 语言 + 任务 + 时间戳开关」,指定 <|uk|> 就锁定为乌克兰语:
inputs = {
"encoder_prompt": {
"prompt": "",
"multi_modal_data": {
"audio": (bytes_to_numpy(row["audio"]["bytes"]), 16_000),
},
},
"decoder_prompt": "<|startoftranscript|><|uk|><|transcribe|><|notimestamps|>",
}
四个特殊标记的含义:
| 标记 | 作用 |
|---|---|
| `< | startoftranscript |
| `< | uk |
| `< | transcribe |
| `< | notimestamps |
第 5 步:执行推理,拿到转写文本
Whisper 官方推荐贪心解码(temperature=1.0 + top_p=1.0),再调用 generate 即可:
sampling_params = SamplingParams(temperature=1.0, top_p=1.0, max_tokens=200)
outputs = llm.generate(inputs, sampling_params)
print("PREDICTION:", outputs[0].outputs[0].text)
恭喜!到这里你已经完整跑通 whisper-large-v3-turbo-quantized-uk + vLLM 的乌克兰语语音转文字流程 🎉
三、关键参数速查表
| 参数 | 推荐值 | 说明 |
|---|---|---|
max_model_len |
448 | 输出序列长度上限,与模型配置对齐 |
max_num_seqs |
400 | 高并发批量转写 |
gpu_memory_utilization |
0.8 | 显存占用比例,按显卡余量调整 |
temperature / top_p |
1.0 / 1.0 | 贪心解码,转写任务最稳定 |
max_tokens |
200 | 单条音频的输出 token 上限 |
| 音频采样率 | 16000 Hz | 见 preprocessor_config.json 的 sampling_rate |
完整示例代码可直接参考仓库文档:README.md
四、常见问题 FAQ
Q1:没有 GPU 能跑吗?
该量化模型面向 GPU 推理优化,gpu_memory_utilization 参数依赖显存管理,建议至少准备一块 8GB 显存的显卡。
Q2:能识别其他语言吗?
generation_config.json 中保留了多语言映射(如 <|en|>、<|zh|> 等),技术上可替换语言标记,但本模型的量化校准针对乌克兰语,建议主要用于 乌克兰语 STT 场景。
Q3:W4A16 量化会损失精度吗? 4 位量化后模型体积和显存占用显著降低,且通过乌克兰语真实数据校准,在目标语言上的精度损失通常很小,详见 README.md 的量化说明。
总结
- whisper-large-v3-turbo-quantized-uk = Whisper Large V3 Turbo + W4A16 四位量化 + 乌克兰语校准;
- 用 vLLM 加载只需 4 个关键参数,音频转写只需 1 行
llm.generate调用; - 按本文 5 步流程走一遍,即可在几十分钟内搭建起一条 乌克兰语语音转文字 的生产级推理管线。
现在就可以动手试试,把仓库克隆到本地开始实验:git clone https://gitcode.com/hf_mirrors/Yehor/whisper-large-v3-turbo-quantized-uk