Faster-Whisper 本地实时语音识别部署实战

要实现类似微信或豆包的语音输入功能，通常有两种主流方案：云端 API（轻量、准确度高）和本地模型（免费、隐私保护、无需联网）。对于需要集成语音识别且对数据隐私有要求的系统，本地部署是更好的选择。这里记录一下使用 Faster-Whisper 实现实时语音转文本的完整流程。

一、环境安装

首先需要在虚拟环境中安装核心依赖。推荐使用 Python 3.8+ 环境。

pip install faster-whisper pyaudio

注意：原教程中提到的 pyaudiowpatch 并非标准库，建议直接使用标准的 pyaudio 包，兼容性更好。

如果电脑有独立显卡，建议提前配置好 CUDA 和 cuDNN 环境以加速推理。具体安装步骤可参考 NVIDIA 官方文档或社区通用教程。

二、模型下载与配置

1. 模型选择

Faster-Whisper 支持多种大小的模型，根据硬件性能选择即可：

Tiny / Base: 速度最快，适合低配设备。
Small / Medium: 平衡速度与精度。
Large-v2 / Large-v3: 效果最好，但需要较强算力。
Distil-Large-v3: 蒸馏版，速度快且效果接近原版。

可以通过 Hugging Face 手动下载模型文件（如 config.json, model.bin, tokenizer.json 等），放入指定文件夹离线使用。当然，首次运行脚本时也可以让代码自动从 Hugging Face 下载。

2. 实时录音转文本脚本

下面是一个完整的 Python 脚本示例，实现了持续录音、切片处理及实时转录。代码中使用了多线程来避免录音阻塞，并集成了 VAD（语音活动检测）过滤静音片段。

# -*- coding: utf-8 -*-
import os
import sys
import time
import wave
import tempfile
import threading
import torch
import pyaudio
from faster_whisper import WhisperModel

# 录音切片时长（秒）
AUDIO_BUFFER = 5

def record_audio(p, device):
    """创建临时文件进行录音"""
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
        filename = f.name
        wave_file = wave.open(filename, "wb")
        wave_file.setnchannels(int(device["maxInputChannels"]))
        wave_file.setsampwidth(p.get_sample_size(pyaudio.paInt16))
        wave_file.setframerate(int(device["defaultSampleRate"]))

        def callback(in_data, frame_count, time_info, status):
            wave_file.writeframes(in_data)
            return (in_data, pyaudio.paContinue)

        try:
            stream = p.open(
                format=pyaudio.paInt16,
                channels=int(device["maxInputChannels"]),
                rate=int(device["defaultSampleRate"]),
                frames_per_buffer=1024,
                input=True,
                input_device_index=device["index"],
                stream_callback=callback,
            )
            stream.start_stream()
            time.sleep(AUDIO_BUFFER)
        except Exception as e:
            print(f"录音出错：{e}")
        finally:
            if 'stream' in locals():
                stream.stop_stream()
                stream.close()
            wave_file.close()
    return filename

def whisper_audio(filename, model):
    """调用模型进行转录"""
    try:
        # vad_filter=True 可以去掉没说话的静音片段
        segments, info = model.transcribe(
            filename,
            beam_size=5,
            language="zh",
            vad_filter=True,
            vad_parameters=dict(min_silence_duration_ms=500)
        )
        for segment in segments:
            print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))
    except Exception as e:
        print(f"转录出错：{e}")
    finally:
        # 转录完成后删除临时文件
        if os.path.exists(filename):
            os.remove(filename)

def main():
    print("正在加载 Whisper 模型...")
    # 检查 GPU
    if torch.cuda.is_available():
        device = "cuda"
        compute_type = "float16"  # 或者 "int8_float16"
        print("使用 GPU (CUDA) 进行推理")
    else:
        device = "cpu"
        compute_type = "int8"  # CPU 上推荐用 int8
        print("使用 CPU 进行推理")

    # 模型路径，如果是自动下载可设为 "large-v3"
    model_path = "large-v3"
    try:
        model = WhisperModel(model_path, device=device, compute_type=compute_type, local_files_only=True)
        print("模型加载成功！")
    except Exception as e:
        print(f"模型加载失败：{e}")
        return

    with pyaudio.PyAudio() as p:
        try:
            default_mic = p.get_default_input_device_info()
            print(f"\n当前使用的麦克风：{default_mic['name']} (Index: {default_mic['index']})")
            print(f"采样率：{default_mic['defaultSampleRate']}, 通道数：{default_mic['maxInputChannels']}")
            print("-" * 50)
            print("开始持续录音 (按 Ctrl+C 停止)...")
            while True:
                filename = record_audio(p, default_mic)
                thread = threading.Thread(target=whisper_audio, args=(filename, model))
                thread.start()
        except OSError:
            print("未找到默认麦克风，请检查系统声音设置。")
        except KeyboardInterrupt:
            print("\n停止录音，程序退出。")
        except Exception as e:
            print(f"\n发生未知错误：{e}")

if __name__ == '__main__':
    main()

三、常见报错与解决

在部署过程中，可能会遇到一些依赖冲突问题，以下是几个高频坑点及解决方案。

1. cuDNN 版本不匹配

报错信息： Could not locate cudnn_ops64_9.dll. Please make sure it is in your library path!

原因： Faster-Whisper 底层依赖的 CTranslate2 引擎是基于 cuDNN 9.x 版本编译的，而你的系统可能只安装了旧版 cuDNN。

解决： 尝试降级 CTranslate2 到兼容版本：

pip install --force-reinstall ctranslate2==4.4.0

2. cublas DLL 缺失或版本冲突

报错信息： Applying the VAD filter requires the onnxruntime package 或 cuBLAS failed with status CUBLAS_STATUS_NOT_SUPPORTED

原因： PyTorch 版本与 CUDA 版本不匹配，或者虚拟环境中缺少对应的 cublas64_x.dll 文件。

解决：

确保 onnxruntime 版本稳定，建议安装：
```
pip install onnxruntime==1.19.2
```
如果提示找不到 cublas64_12.dll，可以尝试将现有的 cublas64_11.dll 复制一份并重命名为 cublas64_12.dll（仅限 Windows 环境下的临时变通方案）。
- 查找位置通常在 torch\lib 目录下。
- 例如：D:\Python\Lib\site-packages\torch\lib\cublas64_11.dll

3. 其他注意事项

确保麦克风权限已开启。
如果使用 CPU 推理，务必设置 compute_type="int8" 以提升速度。
模型加载时间较长，请耐心等待控制台输出日志。

总结

通过上述步骤，你可以快速搭建起一个本地的实时语音识别系统。相比云端 API，本地方案在隐私保护和长期成本上更有优势。如果在部署过程中遇到其他特定环境问题，建议查阅 Faster-Whisper 的 GitHub Issues 获取最新反馈。