5分钟上手faster-whisper：从安装到API调用的极速语音转写指南

你还在为语音转写速度慢、占用内存高而烦恼吗？想快速实现高效准确的语音识别功能？本文将带你5分钟内从零开始，掌握faster-whisper的安装配置、API调用及参数优化技巧，让你轻松应对各种语音转写场景。读完本文，你将能够：

• 正确安装和配置faster-whisper环境
• 使用Python API实现基本语音转写功能
• 根据需求调整参数优化转写效果
• 了解高级功能如VAD过滤和词级时间戳的使用方法

为什么选择faster-whisper？

faster-whisper是基于OpenAI Whisper模型的高效实现，使用CTranslate2作为推理引擎，相比原始Whisper模型，它在保持相同准确率的情况下速度提升高达4倍，同时内存占用更低。特别值得一提的是，它支持CPU和GPU上的8位量化，进一步提高了效率。

性能对比

以下是使用Large-v2模型在GPU上的性能对比数据：

Implementation	Precision	Beam size	Time	Max. GPU memory	Max. CPU memory
openai/whisper	fp16	5	4m30s	11325MB	9439MB
faster-whisper	fp16	5	54s	4755MB	3244MB
faster-whisper	int8	5	59s	3091MB	3117MB

数据来源：README.md

从表格中可以明显看出，faster-whisper在速度和内存占用方面都有显著优势，特别是使用INT8量化时，GPU内存占用仅为原始Whisper的27%左右，而速度提升了近5倍。

安装与环境配置

系统要求

• Python 3.8或更高版本
• 对于GPU执行，需要安装CUDA 12兼容的cuBLAS和cuDNN 8

快速安装

faster-whisper可以通过PyPI直接安装：

pip install faster-whisper

如果你需要安装最新的开发版本，可以从GitHub仓库安装：

pip install --force-reinstall "faster-whisper @ https://gitcode.com/gh_mirrors/fas/faster-whisper/archive/refs/heads/master.tar.gz"

GPU支持配置

GPU执行需要安装以下NVIDIA库：

• cuBLAS for CUDA 12
• cuDNN 8 for CUDA 12

在Linux系统上，可以通过pip安装这些库：

pip install nvidia-cublas-cu12 nvidia-cudnn-cu12
export LD_LIBRARY_PATH=`python3 -c 'import os; import nvidia.cublas.lib; import nvidia.cudnn.lib; print(os.path.dirname(nvidia.cublas.lib.__file__) + ":" + os.path.dirname(nvidia.cudnn.lib.__file__))'`

注意：最新版本的nvidia-cudnn-cu12可能依赖cuDNN 9，而faster-whisper目前不支持cuDNN 9。请确保安装的是cuDNN 8版本。

基本API调用

faster-whisper提供了简洁易用的Python API。以下是一个基本的语音转写示例：

from faster_whisper import WhisperModel

model_size = "large-v3"

# 在GPU上运行，使用FP16精度
model = WhisperModel(model_size, device="cuda", compute_type="float16")

# 或者在GPU上使用INT8精度
# model = WhisperModel(model_size, device="cuda", compute_type="int8_float16")
# 或者在CPU上使用INT8精度
# model = WhisperModel(model_size, device="cpu", compute_type="int8")

segments, info = model.transcribe("audio.mp3", beam_size=5)

print("检测到语言: %s，概率: %f" % (info.language, info.language_probability))

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

注意：segments是一个生成器(generator)，因此只有在迭代它时才会真正开始转写过程。如果需要立即完成转写，可以将结果转换为列表：segments = list(segments)

模型初始化参数

在初始化WhisperModel时，可以设置以下关键参数：

• model_size_or_path: 模型大小或路径，可以是预定义大小（如"large-v3"）、本地转换模型目录路径或Hugging Face Hub上的模型ID
• device: 计算设备，可选"cpu"、"cuda"或"auto"
• device_index: 设备ID，多GPU时可以传入ID列表
• compute_type: 计算类型，影响精度和性能，可选"float16"、"int8_float16"等
• cpu_threads: CPU线程数，非零值会覆盖OMP_NUM_THREADS环境变量

详细参数说明可参考WhisperModel类定义

参数调优技巧

主要性能参数

• beam_size: 解码使用的beam大小，默认值为5。增大beam_size可以提高转写质量，但会增加计算时间
• compute_type: 计算类型，在GPU上推荐使用"float16"或"int8_float16"，在CPU上推荐使用"int8"

转写质量优化

• temperature: 采样温度，控制输出的随机性。可以是一个温度值或温度列表，默认值为[0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
• condition_on_previous_text: 是否使用前一个输出作为下一个窗口的提示，默认值为True。禁用可能导致文本不一致，但可以避免陷入循环
• initial_prompt: 初始提示文本，可以帮助模型更好地理解特定领域的术语

实用参数组合

快速转写（优先速度）

model = WhisperModel("base", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio.mp3", beam_size=1, temperature=0)

高质量转写（优先准确率）

model = WhisperModel("large-v3", device="cuda", compute_type="float16")
segments, info = model.transcribe("audio.mp3", beam_size=10, temperature=[0.0, 0.2, 0.4])

高级功能使用

语音活动检测(VAD)

faster-whisper集成了Silero VAD模型，可以过滤掉音频中没有语音的部分，提高转写效率和准确性：

segments, _ = model.transcribe("audio.mp3", vad_filter=True)

可以通过vad_parameters自定义VAD行为：

segments, _ = model.transcribe(
    "audio.mp3",
    vad_filter=True,
    vad_parameters=dict(min_silence_duration_ms=500),
)

VAD相关代码实现可参考vad.py

词级时间戳

启用词级时间戳可以获取每个单词的开始和结束时间：

segments, _ = model.transcribe("audio.mp3", word_timestamps=True)

for segment in segments:
    for word in segment.words:
        print("[%.2fs -> %.2fs] %s" % (word.start, word.end, word.word))

多语言支持

faster-whisper支持多种语言的转写，可以通过language参数指定语言：

segments, info = model.transcribe("audio.mp3", language="zh")

如果不指定语言，模型会自动检测音频中的语言：

segments, info = model.transcribe("audio.mp3")
print("检测到语言: %s，概率: %f" % (info.language, info.language_probability))

实际应用示例

批量处理音频文件

以下是一个批量处理多个音频文件的示例代码：

import os
from faster_whisper import WhisperModel

model = WhisperModel("medium", device="cuda", compute_type="int8_float16")

audio_dir = "path/to/audio/files"
output_dir = "path/to/output/transcripts"

os.makedirs(output_dir, exist_ok=True)

for filename in os.listdir(audio_dir):
    if filename.endswith((".mp3", ".wav", ".m4a")):
        audio_path = os.path.join(audio_dir, filename)
        output_path = os.path.join(output_dir, os.path.splitext(filename)[0] + ".txt")
        
        segments, info = model.transcribe(audio_path, beam_size=5)
        
        with open(output_path, "w", encoding="utf-8") as f:
            f.write(f"检测到语言: {info.language}，概率: {info.language_probability:.2f}\n\n")
            for segment in segments:
                f.write(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}\n")

实时转写应用

结合音频流处理库，可以实现实时语音转写功能：

import audioop
import pyaudio
from faster_whisper import WhisperModel

model = WhisperModel("small", device="cpu", compute_type="int8")

FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 16000
CHUNK = 4096

audio = pyaudio.PyAudio()

stream = audio.open(format=FORMAT, channels=CHANNELS,
                    rate=RATE, input=True,
                    frames_per_buffer=CHUNK)

print("开始录音...")

audio_frames = []
for _ in range(0, int(RATE / CHUNK * 5)):  # 录制5秒
    data = stream.read(CHUNK)
    audio_frames.append(data)

print("录音结束，开始转写...")

# 停止录音
stream.stop_stream()
stream.close()
audio.terminate()

# 处理音频数据
audio_data = b''.join(audio_frames)
audio_np = np.frombuffer(audio_data, dtype=np.int16).astype(np.float32) / 32768.0

# 转写
segments, info = model.transcribe(audio_np, language="zh")

for segment in segments:
    print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")

常见问题解决

模型下载问题

如果模型下载速度慢或失败，可以手动下载模型文件并指定本地路径：

model = WhisperModel("/path/to/local/model/directory")

GPU内存不足

• 尝试使用更小的模型，如从"large-v3"降级到"medium"
• 使用INT8量化：compute_type="int8_float16"
• 减少beam_size：beam_size=3

转写结果不理想

• 尝试使用更大的模型，如从"base"升级到"large-v3"
• 调整temperature参数：temperature=0.5
• 提供相关领域的初始提示：initial_prompt="这是一段关于人工智能的讲座内容。"

性能基准测试

faster-whisper项目提供了多个基准测试脚本，可以帮助你评估不同配置下的性能：

• speed_benchmark.py: 速度基准测试
• memory_benchmark.py: 内存使用基准测试
• wer_benchmark.py: 词错误率基准测试

运行基准测试的方法：

# 安装测试依赖
pip install -r benchmark/requirements.benchmark.txt

# 运行速度基准测试
python benchmark/speed_benchmark.py --model large-v3 --device cuda

总结与展望

faster-whisper作为OpenAI Whisper的高效实现，通过CTranslate2推理引擎实现了显著的性能提升，同时保持了相近的转写质量。它简单易用的API和丰富的参数选项，使其能够满足各种语音转写需求。

通过本文介绍的安装配置、API调用和参数优化方法，你应该能够在5分钟内快速上手faster-whisper，并根据实际需求调整参数以获得最佳性能。无论是开发实时语音转写应用，还是处理批量音频文件，faster-whisper都能提供高效可靠的语音转写能力。

未来，随着模型优化和硬件发展，faster-whisper的性能还有进一步提升的空间。建议关注项目的GitHub仓库以获取最新更新和功能。

希望本文对你有所帮助，如果有任何问题或建议，欢迎在项目仓库提交issue或PR。

相关资源

• 项目源代码
• API文档
• 基准测试工具
• Docker部署