本地离线部署 Whisper 语音转写

• --model：指定模型，常见有 tiny、base、small、medium、large-v3
• --language Chinese：明确指定中文，避免自动识别时出偏差
• --output_dir：指定输出目录
• --format：输出格式，例如 txt、srt、vtt

通过 Python 脚本调用

如果只是偶尔转写，用命令行就够了；要做成自己的小工具，Python 脚本会顺手很多。下面这段代码包含了几个实用检查：先确认 FFmpeg 是否可用，再检查音频文件是否存在，最后加载模型进行转写，并把结果保存成文本文件。

这里我额外加了繁简转换，目的是尽量把输出统一成简体中文。实际使用时，如果你不需要这层处理，可以把 zhconv 相关部分去掉。

import whisper
import os
import pathlib
import subprocess
from zhconv import convert  # 用于繁转简


def check_ffmpeg():
    """检查FFmpeg是否安装并配置正确"""
    try:
        subprocess.run(
            ["ffmpeg", "-version"],
            check=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
        return True
    except FileNotFoundError:
        print("错误：未找到FFmpeg工具，请先安装并配置环境变量")
        return False
    except Exception as e:
        print(f"FFmpeg检查失败：{str(e)}")
        return False


def transcribe_audio(audio_path, model_name="large-v3", language="Chinese"):
    # 检查FFmpeg
    if not check_ffmpeg():
        return None

    # 验证音频文件路径
    audio_path = str(pathlib.Path(audio_path).resolve())

    if not os.path.exists(audio_path):
        print(f"错误：音频文件不存在 '{audio_path}'")
        return None

    if not os.path.isfile(audio_path):
        print(f"错误：'{audio_path}' 不是有效的文件")
        return None

    # 加载模型并转写
    try:
        print(f"开始加载模型 {model_name}...")
        model = whisper.load_model(model_name, device="cpu")

        print(f"开始转写文件：{audio_path}")
        # 这里明确指定中文，并关闭自动语言检测带来的不确定性
        result = model.transcribe(
            audio=audio_path,
            language="Chinese",
            verbose=True,
            fp16=False,
            initial_prompt="请用简体中文转写，不要使用繁体中文。"
        )

        # 将结果统一转换为简体中文
        simplified_text = convert(result["text"], 'zh-cn')

        # 保存结果
        output_dir = "whisper_results"
        os.makedirs(output_dir, exist_ok=True)
        audio_name = os.path.splitext(os.path.basename(audio_path))[0]
        output_path = os.path.join(output_dir, f"{audio_name}_transcript.txt")

        with open(output_path, "w", encoding="utf-8") as f:
            f.write(simplified_text)

        print(f"\n✅ 转写完成（已转换为简体中文），结果保存至：{output_path}")
        return simplified_text

    except Exception as e:
        print(f"转写过程出错：{str(e)}")
        return None


if __name__ == "__main__":
    # 安装繁转简依赖（首次运行需要）
    try:
        import zhconv
    except ImportError:
        print("正在安装繁转简依赖...")
        subprocess.run(["pip", "install", "zhconv"], check=True)
        import zhconv

    # 替换为你的音频文件路径
    audio_file = r"D:\Net_Program\test\whisper-test.wav"
    transcribe_audio(audio_file)

这段脚本里有几个地方值得留意：

• device="cpu" 适合本地通用环境，如果机器有合适的 GPU，也可以按实际情况调整
• fp16=False 是为了避免 CPU 环境下出现类型不兼容问题
• initial_prompt 这类提示词在中文场景里挺有用，能减少模型输出繁体或夹杂其他语言的概率
• 保存结果时单独建了 whisper_results 目录，避免转写文件散落在各处

常见问题处理

内存不足

如果转写时提示 OutOfMemoryError，通常是模型太大导致的。解决办法很直接：

• 换成更小的模型，比如 medium、small 或 base
• 关闭其他占内存的程序
• 如果坚持用 large-v3，机器内存最好充足一些

音频格式不兼容

遇到格式问题时，可以先用 FFmpeg 统一一下音频参数。下面这条命令很实用，通常能把输入转成 16kHz 单声道 WAV：

ffmpeg -i 输入文件.mp3 -ar 16000 -ac 1 输出文件.wav

模型下载速度慢

如果自动下载太慢，可以考虑手动准备模型文件，再放到 Whisper 的缓存目录里。只要路径和文件完整，后续调用时就能直接复用，不必每次重新拉取。

小结

本地部署 Whisper 的关键，不在于代码有多复杂，而在于环境链路要顺：Python、Whisper、FFmpeg、模型文件这几块都通了，转写就会很稳定。对资源要求不高的机器，先从 base 或 small 跑起来最省心；如果更看重识别质量，再切到 large-v3。