本地离线部署 Whisper 模型实现语音转写指南

在本地搭建 Whisper 语音转写环境其实并不复杂，只要按部就班配置好依赖即可。整个过程适用于 Windows、macOS 和 Linux 系统，其中 Windows 亲测可用。

一、基础环境准备

1. 安装 Python 确保安装 Python 3.8+ 版本：

• 下载地址：python.org/downloads
• 安装时务必勾选 "Add Python to PATH"（关键步骤）

2. 验证 Python 安装 打开命令行（CMD/PowerShell/终端），输入 python --version 或 python3 --version（macOS/Linux），显示版本号即表示安装成功。

二、安装 Whisper

国内用户建议配置镜像加速以提升下载速度：

pip install openai-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple

1. 安装核心库 命令行输入以下命令（基础安装默认包含轻量模型支持）：

pip install openai-whisper

2. 安装音频处理依赖 Whisper 需要额外工具处理音频格式转换：Windows 需下载并安装 FFmpeg，将 ffmpeg.exe 所在目录添加到系统环境变量 PATH。

三、下载 Whisper 模型

Whisper 会自动下载所需模型，但推荐提前手动指定大型模型 large-v3 以获得最佳效果：

pip install "openai-whisper[large-v3]"

模型会保存在以下路径（可手动替换或管理）：

• Windows：C:\Users\你的用户名\.cache\whisper\
• macOS/Linux：~/.cache/whisper/

四、基本使用方法

1. 命令行直接转写

# 转写音频文件（支持 WAV/MP3/MP4 等格式）
whisper 你的音频文件路径.wav --model large-v3 --language Chinese

# 示例（替换为你的文件路径）
whisper D:\Net_Program\test\whisper-test.wav --model large-v3 --language Chinese

2. 关键参数说明

• --model：指定模型（tiny/base/small/medium/large-v3，越大精度越高，需求资源越多）
• --language Chinese：指定语言为中文（避免自动检测错误）
• --output_dir 输出目录：指定结果保存路径
• --format txt：输出格式（支持 txt/srt/vtt 等）

五、Python 脚本调用

为了更灵活地集成到业务中，我们可以封装一个 Python 脚本。这里我特意加了繁简转换逻辑，防止识别结果出现繁体字混入的情况。

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)

注意代码中的 check_ffmpeg 函数非常关键，很多报错其实是环境变量没配好导致的。另外 initial_prompt 能引导模型更好地遵循指令，比如强制要求简体中文。

六、常见问题解决

1. 内存不足

   • 若提示 OutOfMemoryError，换用更小的模型（如 medium 或 small）
   • 关闭其他占用内存的程序（large-v3 建议至少 16GB 内存）

2. 音频格式错误

   • 用 FFmpeg 转换格式：ffmpeg -i 输入文件.mp3 -ar 16000 -ac 1 输出文件.wav（转为 16kHz 单声道 WAV）

3. 模型下载慢

   • 手动下载模型文件（可在 Hugging Face 找到），放入 .cache/whisper/ 目录

通过以上步骤，你可以在本地搭建一个稳定的 Whisper 转写环境，无需依赖 Ollama，直接调用模型进行语音转写。如果追求更高精度，优先使用 large-v3 模型；若注重速度或资源有限，可选择 small 或 base 模型。