Faster-Whisper 本地部署：实现实时语音转文本实战指南

前言

要实现类似豆包、微信的语音输入功能，通常有两种主流方案：云端 API（轻量、准确度高）和本地模型（免费、隐私好、无需联网）。如果开发场景需要添加语音识别且对数据隐私有要求，本地部署 Faster-Whisper 是个不错的选择。

Faster-Whisper 是 Whisper 的高效实现版本，支持多种量化级别和硬件加速。下面记录一下如何在本地环境部署并实现实时语音转文本。

一、安装环境

首先确保你的虚拟环境中安装了必要的依赖。核心库是 faster-whisper，录音部分使用 pyaudio。

pip install faster-whisper pyaudio

如果有 NVIDIA 显卡，建议提前配置好 CUDA 和 cuDNN 环境，否则推理速度会受限。具体安装步骤可参考官方文档或相关技术社区教程。

二、使用步骤

1. 下载模型

如果你希望离线使用，或者想把模型文件放在指定目录，可以手动从 Hugging Face 下载。根据需求选择合适的模型大小：

• Tiny (最小/最快): Systran/faster-whisper-tiny
• Base: Systran/faster-whisper-base
• Small: Systran/faster-whisper-small
• Medium: Systran/faster-whisper-medium
• Large-v2: Systran/faster-whisper-large-v2
• Large-v3 (效果最好): Systran/faster-whisper-large-v3
• Distil-Large-v3 (蒸馏版/速度快): Systran/faster-distil-whisper-large-v3

在 Hugging Face 的 "Files and versions" 页面中，下载以下几个关键文件并存入同一个文件夹：

• config.json
• model.bin
• tokenizer.json
• vocabulary.json
• preprocessor_config.json

2. 实时录音转文本脚本

下面是完整的 Python 脚本示例。代码中使用了多线程来分离录音和转录过程，避免阻塞主循环。

# -*- 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 进行推理")

    # 模型路径，设置为 local_files_only=True 强制使用本地文件
    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()

3. 报错解决方法

在实际运行中，可能会遇到一些依赖冲突问题，以下是常见解决方案：

问题 1：cuDNN 版本不匹配 报错信息类似：Could not locate cudnn_ops64_9.dll 或 Invalid handle. Cannot load symbol cudnnCreateTensorDescriptor。

这是因为 Faster-Whisper 底层依赖的 CTranslate2 引擎是基于 cuDNN 9.x 版本编译的，而你的系统可能没有安装对应版本。可以尝试降级 ctranslate2 到兼容旧版本的稳定版：

pip install --force-reinstall ctranslate2==4.4.0

问题 2：cublas DLL 缺失 如果仍然报错找不到 cublas64_12.dll，可能是 CUDA 版本与 PyTorch 不匹配。例如虚拟环境使用的是 CUDA 11.8，但缺少对应的动态库。

你可以尝试将现有的 cublas64_11.dll 复制一份并重命名为 cublas64_12.dll，放置在 PyTorch 的 lib 目录下（如 Lib\site-packages\torch\lib）。这属于一种变通方法，用于解决版本标识不一致的问题。

问题 3：VAD 滤镜依赖 报错提示：Applying the VAD filter requires the onnxruntime package。

降低 onnxruntime 版本通常能解决兼容性问题：

pip install onnxruntime==1.19.2

总结

通过上述步骤，你可以在本地快速搭建起基于 Faster-Whisper 的实时语音识别服务。虽然过程中可能会遇到一些依赖版本冲突，但只要理清 CUDA、cuDNN 和 PyTorch 的版本关系，大部分问题都能迎刃而解。这种方式特别适合对隐私敏感或网络环境受限的场景。