OpenWhispr 本地 Whisper 转写完全指南：whisper.cpp 私有化部署、GPU 加速与模型调优-平芜编程栈

OpenWhispr 本地 Whisper 转写完全指南：whisper.cpp 私有化部署、GPU 加速与模型调优

【免费下载链接】openwhisprVoice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.项目地址: https://gitcode.com/GitHub_Trending/op/openwhispr

OpenWhispr 是一款主打隐私优先、跨平台的语音转文字（dictation）桌面应用，其本地转写能力完全基于 whisper.cpp 构建：音频数据全程留在设备内，不需要任何云服务。本文围绕 LOCAL_WHISPER_SETUP.md 展开，结合仓库源码（download-whisper-cpp.js、whisper.js、whisperServer.js）深入讲解如何开启本地 Whisper、选择合适的 GGML 模型、启用 CUDA/Vulkan/Metal GPU 加速、从源码构建运行，以及排查常见问题。读完本文，你将能独立完成 OpenWhispr 本地转写环境的搭建与调优，并理解其底层工作链路。

一、为什么选择本地 Whisper：隐私与成本的权衡

OpenWhispr 支持本地与云端两种转写模式。本地模式使用 whisper.cpp——OpenAI Whisper 模型的高性能 C++ 实现——将整个转写流程放在本机完成：

whisper.cpp 的whisper-server可执行文件随应用打包（打包版本无需额外安装依赖），源码运行时也可下载到resources/bin/；
GGML 格式的模型在首次使用时自动下载到模型缓存目录（详见下文"文件位置"）；
音频在本机通过 FFmpeg（随应用打包，依赖ffmpeg-static）完成格式转换与预处理。

云端模式则会将音频发送到 OpenAI 等第三方服务，按 API 用量计费。两种模式的对比详见文末"隐私对比"一节。从源码结构看，本地模式的核心管理者是 whisper.js 中的WhisperManager，它负责模型下载、服务启动、GPU 后端解析与转写调用，是理解整条链路的关键入口。

二、快速开始：三步启用本地转写

在 OpenWhispr 界面中启用本地 Whisper 非常简单：

打开控制面板（右键点击托盘图标，或点击悬浮层）；
进入设置（Settings）→语音转文字处理（Speech to Text Processing）；
开启使用本地 Whisper（Use Local Whisper）；
选择一个模型（推荐base）；
点击保存（Save）。

首次转写时，应用会自动下载所选模型。这一"按需下载"行为在 whisper.js 的downloadWhisperModel中有完整实现：下载前会先checkDiskSpace校验磁盘空间（要求预留模型体积的 1.2 倍），下载完成后用validateFileSize校验文件大小是否与注册表期望一致，下载过程支持进度回调与取消。

另外，whisper.js 的initializeAtStartup会在应用启动时预启动（pre-warm）whisper-server：只要本地模式已启用、模型已存在且二进制可用，服务就会提前加载模型，从而消除首次转写时 2~5 秒的冷启动延迟。这也是为什么"启用后第一次转写会自动下载模型"的体验如此顺滑。

三、模型选择：六档 GGML 模型详解

原文档给出了完整的模型对照表，仓库中的真实注册表位于 modelRegistryData.json，两者的关键参数一致，并补充了实际文件名与下载源：

模型	大小	速度	质量	RAM	最佳用途	实际文件名
tiny	75MB	最快	基础	~1GB	快速笔记	`ggml-tiny.bin`
base	142MB	快	良好	~1GB	推荐	`ggml-base.bin`
small	466MB	中等	更好	~2GB	专业使用	`ggml-small.bin`
medium	1.5GB	慢	高	~5GB	高精度	`ggml-medium.bin`
large	3GB	最慢	最佳	~10GB	极致质量	`ggml-large-v3.bin`
turbo	1.6GB	快	高	~6GB	又快又准	`ggml-large-v3-turbo.bin`

几点来自源码的补充说明：

base在注册表中被标记为"recommended": true（modelRegistryData.json），是界面上默认推荐的平衡之选；
模型文件均为 GGML 格式，托管在 HuggingFace 的ggerganov/whisper.cpp仓库下；
large实际对应ggml-large-v3.bin（v3 版本），turbo对应ggml-large-v3-turbo.bin；
whisper.js 中的validateModelName会对模型名做白名单校验，只允许注册表中已知的模型名，防止路径遍历攻击——这也意味着你不能随意指定任意路径的模型文件；
模型管理 API 相当完整：listWhisperModels可查询各模型下载状态、deleteWhisperModel/deleteAllWhisperModels可释放磁盘空间（whisper.js），这些能力同样暴露在设置界面的模型选择器中。

选择建议：日常听写用base即可获得良好准确率与速度；追求更高准确率或处理专业内容可升级small；large/turbo更适合对准确性要求极高、且硬件充裕（大内存 + GPU）的场景。注意 RAM 需求会随模型显著增长，medium及以上在低配机器上可能影响其他应用的流畅度。

四、GPU 加速：CUDA、Vulkan 与 Metal

本地 Whisper 可以借助 GPU 大幅提升转写速度。OpenWhispr 的 GPU 支持分为三路：

macOS：Metal 加速内置于 Apple Silicon 的二进制中，无需任何额外设置；
NVIDIA（Windows/Linux）：在转写模型选择器的 GPU 卡片中一键下载 CUDA 运行时；
AMD / Intel（Windows/Linux）：在同一张 GPU 卡片中一键下载 Vulkan 运行时，覆盖 Radeon、Arc 及核显。

GPU 运行时会按需下载，并且带有SHA-256 校验。这在 whisperCudaManager.js 与 whisperVulkanManager.js 的EXPECTED_DIGESTS中有明确体现：每个发布版本（如当前固定的0.0.10）都为 Windows/Linux 的 CUDA、Vulkan 压缩包写死了期望摘要，下载后经 gpuBinaryManager.js 的sha256File计算比对，防止篡改或损坏。CUDA 归档还要求携带 MSVC 运行时 DLL（msvcp140.dll、vcruntime140.dll等，见 whisperCppRelease.js），避免目标机器缺少 VC++ 运行库而无法加载。

4.1 GPU 后端的选择逻辑与失败回退

GPU 后端的选择并非写死，而是每次启动服务时动态解析。关键逻辑在 whisper.js 的resolveGpuStartOptions：

只要 CUDA 包已下载且WHISPER_CUDA_ENABLED环境变量未被显式设为"false"，就优先启用 CUDA；
否则若 Vulkan 包已下载且WHISPER_VULKAN_ENABLED未被设为"false"，则启用 Vulkan；
如果某个后端曾在当前机器上崩溃，其名称会被记录到WHISPER_GPU_FAILED环境变量中（逗号分隔），此后不再自动重试，直到用户手动重试或重新下载，避免每次启动都重复失败的 GPU 冷启动。

GPU 服务启动失败会自动回退到 CPU：无论是 CUDA 内核缺失、显存（VRAM）不足还是 Vulkan shader 编译问题，只要 GPU 服务器在启动阶段失败，whisperServer.js 都会捕获错误、停止进程，并以useCuda: false, useVulkan: false重新以 CPU 模式启动，同时向界面发送cuda-fallback/gpu-fallback事件提示用户。转写功能因此不会中断。值得注意的是，Vulkan 冷启动由于需要编译 shader 并加载完整模型，超时时间被放宽到 120 秒（VULKAN_STARTUP_TIMEOUT_MS），而普通启动为 30 秒（whisperServer.js）。

4.2 更细致的 GPU 行为（从源码可见）

CUDA 设备选择：启动时设置CUDA_DEVICE_ORDER=PCI_BUS_ID，若存在TRANSCRIPTION_GPU_UUID环境变量则进一步用CUDA_VISIBLE_DEVICES锁定具体 GPU，保证多卡环境下设备选择无歧义（whisperServer.js）；
Vulkan 设备选择：通过--device参数指定逻辑设备索引（而非物理枚举索引）。启动后解析 stderr 中ggml_vulkan: N = ...形式的设备列表，若默认设备 0 是核显（uma: 1）而存在独显，会自动重启并固定到独显；若之前固定的设备已不存在（硬件变更），则清除固定（whisperServer.js）；
唤醒后重新预热：笔记本从睡眠唤醒会清空显存中的模型，WhisperManager.onWakeFromSleep会检测到 GPU 模式下的运行中服务并自动重新加载模型（whisper.js）。

五、工作原理：从麦克风到文本的完整链路

OpenWhispr 使用 whisper.cpp 的HTTP server 模式（whisper-server）完成转写，而非命令行一次性调用。整条链路如下：

二进制：whisper-server-{platform}-{arch}（Windows 为.exe）随应用打包在resources/bin/或应用资源目录（process.resourcesPath/bin/），whisperServer.js 会依次探测多个候选路径；GPU 二进制则位于用户数据目录下的bin/whisper-cuda/或bin/whisper-vulkan/子目录；
服务启动：本地服务监听127.0.0.1回环地址，端口从 8178 起按可用性递增（范围 8178–8199），启动参数包括--model、--port、--language auto（显式传auto开启语言自动检测，否则 whisper.cpp 默认按英文处理）、--max-len 4096（避免长文本被 60 字符强制换行截断）以及可选的--threads、--device、--vad等（whisperServer.js）；
音频预处理：FFmpeg（优先ffmpeg-static，其次系统路径，whisperServer.js）将任意格式音频转换为16kHz 单声道 WAV——这是 whisper.cpp 要求的精确输入格式；若找不到 FFmpeg，服务器将只接受 16kHz 单声道 WAV；
转写请求：WhisperManager以 multipart/form-data 向/inference端点 POST 音频，同时携带language、可选prompt（自定义词典词汇）、response_format=json等字段（whisperServer.js）；
结果解析：返回的 JSON 经 whisper.js 的parseWhisperResult处理：规范化空白字符（whisper.cpp 会在段落间输出换行）、拼接分段文本，并识别[BLANK_AUDIO]标记判定"未检测到音频"。

5.1 语音活动检测（VAD）与静音处理

OpenWhispr 集成了 Silero VAD 模型（ggml-silero-v5.1.2.bin，由download-whisper-vad-model脚本下载）。启用 VAD 时，服务启动参数会附加--vad --vad-model ...以及一组阈值参数。默认配置与取值范围定义在 whisperVad.json：

参数	默认值	取值范围
threshold（VAD 阈值）	0.5	0.1 ~ 0.95
minSpeechDurationMs（最小语音时长）	250ms	50 ~ 2000ms
minSilenceDurationMs（最小静音时长）	200ms	50 ~ 2000ms
maxSpeechDurationS（最大语音段长）	30s	5 ~ 120s
speechPadMs（语音前后填充）	100ms	0 ~ 1000ms
samplesOverlap（采样重叠）	0.5	0 ~ 0.95

需要注意的是，VAD 在不同场景下的启用策略不同（whisperVadConfig.js）：听写场景默认关闭（dictationSileroEnabled需显式开启），因为频繁停顿的听写可能会被 VAD 误删语音片段；而笔记、会议等长时录音场景默认开启，用于跳过长时间静音。

5.2 转写质量细节：防幻觉阈值与自定义词典

防幻觉：源码中针对连续听写场景设置了更严格的解码器阈值entropy_thold: 2.8、logprob_thold: -1.25（whisperServer.js），用于抑制 whisper.cpp 在近静音窗口输出的训练数据式结尾废话（如 "Thank you for watching"）。会议等长音频块通过skipDecoderThresholds保留服务器默认值，因为其本身已有 RMS 门控、VAD 等多重防幻觉保护；
自定义词典：转写请求可携带prompt字段，将用户词典中的自定义词汇注入解码器，提升专业术语、专有名词的识别率。

5.3 线程数控制

本地推理的线程数可通过WHISPER_THREADS环境变量配置：设为具体数值则固定线程数（上限 64），设为auto或不设置则自动按 CPU 并行度（可用并行度的 75%）计算，默认下限 4、自动上限 12（whisperServer.js）。若自动计算的线程数导致启动失败，服务会自动回退到默认线程数重启。

六、系统要求

磁盘空间：75MB ~ 3GB，取决于所选模型（base142MB 是推荐起点）；
内存（RAM）：约 1GB ~ 10GB，模型越大占用越高；
无需额外依赖：打包版本中 whisper.cpp 二进制已内置；FFmpeg 通过ffmpeg-static随应用打包（若缺失，会自动回退查找系统 FFmpeg，如 macOS 的/opt/homebrew/bin/ffmpeg、Linux 的/usr/bin/ffmpeg等）。

七、从源码运行：下载 whisper-server 二进制

如果你是从 git 检出（git checkout）本地运行 OpenWhispr（而非使用打包安装包），需要手动下载当前平台的 whisper.cpp 二进制：

npm run download:whisper-cpp

该脚本（对应 package.json 中的node scripts/download-whisper-cpp.js --current）会从固定的发布版本拉取二进制，放入resources/bin/目录。底层逻辑见 download-whisper-cpp.js：

版本固定：默认下载WHISPER_CPP_TAG = "0.0.10"（whisperCppRelease.js），源码注释说明这是经过测试的构建，跟随上游最新版可能导致应用发布之间转写输出漂移、难以审查变更；
平台覆盖：支持darwin-arm64、darwin-x64、win32-x64（CPU 版带 MSVC 运行时 DLL）、linux-x64（download-whisper-cpp.js）；
安装标记：每个平台目录下会写入.whisper-cpp-{platform}.json标记文件，记录版本号与已安装的配套库，用于判断安装是否完整、避免重复下载；--force参数可强制重新下载；
打包分发：prebuild/prebuild:mac等构建流程中已包含download:whisper-cpp，因此打包产物自带二进制。

如果需要在单台机器上为多平台打包（交叉打包），使用：

npm run download:whisper-cpp:all

对应node scripts/download-whisper-cpp.js --all，会依次下载全部四个平台的二进制（package.json）。

八、文件位置：模型缓存目录与路径覆盖

模型文件默认存放在系统缓存目录：

平台	模型路径
macOS	`~/.cache/openwhispr/whisper-models/`
Windows	`%USERPROFILE%\.cache\openwhispr\whisper-models\`
Linux	`~/.cache/openwhispr/whisper-models/`

路径解析逻辑集中在 modelDirUtils.js：getModelsDirForService("whisper")返回${cacheRoot}/whisper-models。以下几点值得注意：

可通过环境变量OPENWHISPR_CACHE_ROOT整体重定向缓存根目录；
Linux 下若设置了XDG_CACHE_HOME，则优先使用${XDG_CACHE_HOME}/openwhispr；
Windows 下若用户目录包含非 ASCII 字符（如中文、西里尔字母路径），原生 whisper/parakeet 二进制会崩溃，因此会自动回退到C:\ProgramData\OpenWhispr\cache等纯 ASCII 安全路径；
旧版本遗留的模型目录会自动迁移（含跨卷复制与失败回滚保护）。

九、故障排查

状态显示 "Not Found"（找不到二进制）

在控制面板中点击Recheck Installation（重新检查安装）；
重启应用；
若内置二进制确实失效，可通过系统包管理器安装：
- macOS：brew install whisper-cpp
- Linux：从 whisper.cpp 上游源码自行构建（构建产物替换resources/bin/下对应二进制即可）。

应用内还提供了依赖诊断能力：whisper.js 的getDiagnostics会汇总平台信息、FFmpeg 可用性、whisper-server 路径与已下载模型列表，方便快速定位缺失组件。

转写失败

检查麦克风权限是否正确授予；
换用更小的模型（tiny或base）——大模型在小内存机器上可能加载失败；
检查模型下载目录的磁盘剩余空间（下载前会校验是否足够模型体积的 1.2 倍）。

性能缓慢

使用更小的模型（tiny/base），或在WHISPER_THREADS中调整推理线程数；
关闭占用资源的其他应用，为推理留出 CPU/内存/显存；
大型文件的转写可考虑改用云端模式（前提是接受音频上传的隐私与费用权衡）。

十、隐私对比：本地模式 vs 云端模式

模式	音频是否离开设备	是否需要联网	费用
本地	否	仅首次下载模型时需要	免费
云端	是（发送至 OpenAI 等第三方）	是	按 API 用量计费

本地模式的最大优势是音频永不离开设备——麦克风采集、FFmpeg 转码、whisper-server 推理全部在本机完成，联网仅在首次下载模型时发生一次（GGML 模型按需下载至缓存目录）。对于处理敏感会议、医疗内容或受合规约束的工作场景，这是极具吸引力的方案；代价是需要为模型预留磁盘与内存，且推理速度取决于本机硬件。

结语

OpenWhispr 的本地 Whisper 能力是一套完整的端到端私有化转写方案：从 download-whisper-cpp.js 的二进制分发、modelRegistryData.json 的模型注册表，到 whisperServer.js 的服务生命周期管理与 GPU 自动回退，再到 VAD 静音过滤与防幻觉阈值等质量工程细节，构成了一个开箱即用、容错性强的本地转写引擎。按照本文的步骤完成设置后，你就可以在不向任何第三方发送音频的前提下，获得流畅的语音转文字体验；后续如需调优，优先从模型档位、GPU 后端与线程数三个维度入手即可。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考