whisper-large-v3-turbo-quantized-uk快速上手:5步用vLLM跑通乌克兰语语音转文字完整流程

原创2026-11-09 19:38:482,266 阅读
文章标签:语音模型量化本地部署人工智能深度学习

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

登录后查看全文
whisper-large-v3-turbo-quantized-uk