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/openwhisprOpenWhispr 是一款主打隐私优先、跨平台的语音转文字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开启使用本地 WhisperUse Local Whisper选择一个模型推荐base点击保存Save。首次转写时应用会自动下载所选模型。这一按需下载行为在 whisper.js 的downloadWhisperModel中有完整实现下载前会先checkDiskSpace校验磁盘空间要求预留模型体积的 1.2 倍下载完成后用validateFileSize校验文件大小是否与注册表期望一致下载过程支持进度回调与取消。另外whisper.js 的initializeAtStartup会在应用启动时预启动pre-warmwhisper-server只要本地模式已启用、模型已存在且二进制可用服务就会提前加载模型从而消除首次转写时 2~5 秒的冷启动延迟。这也是为什么启用后第一次转写会自动下载模型的体验如此顺滑。三、模型选择六档 GGML 模型详解原文档给出了完整的模型对照表仓库中的真实注册表位于 modelRegistryData.json两者的关键参数一致并补充了实际文件名与下载源模型大小速度质量RAM最佳用途实际文件名tiny75MB最快基础~1GB快速笔记ggml-tiny.binbase142MB快良好~1GB推荐ggml-base.binsmall466MB中等更好~2GB专业使用ggml-small.binmedium1.5GB慢高~5GB高精度ggml-medium.binlarge3GB最慢最佳~10GB极致质量ggml-large-v3.binturbo1.6GB快高~6GB又快又准ggml-large-v3-turbo.bin几点来自源码的补充说明base在注册表中被标记为recommended: truemodelRegistryData.json是界面上默认推荐的平衡之选模型文件均为 GGML 格式托管在 HuggingFace 的ggerganov/whisper.cpp仓库下large实际对应ggml-large-v3.binv3 版本turbo对应ggml-large-v3-turbo.binwhisper.js 中的validateModelName会对模型名做白名单校验只允许注册表中已知的模型名防止路径遍历攻击——这也意味着你不能随意指定任意路径的模型文件模型管理 API 相当完整listWhisperModels可查询各模型下载状态、deleteWhisperModel/deleteAllWhisperModels可释放磁盘空间whisper.js这些能力同样暴露在设置界面的模型选择器中。选择建议日常听写用base即可获得良好准确率与速度追求更高准确率或处理专业内容可升级smalllarge/turbo更适合对准确性要求极高、且硬件充裕大内存 GPU的场景。注意 RAM 需求会随模型显著增长medium及以上在低配机器上可能影响其他应用的流畅度。四、GPU 加速CUDA、Vulkan 与 Metal本地 Whisper 可以借助 GPU 大幅提升转写速度。OpenWhispr 的 GPU 支持分为三路macOSMetal 加速内置于 Apple Silicon 的二进制中无需任何额外设置NVIDIAWindows/Linux在转写模型选择器的 GPU 卡片中一键下载 CUDA 运行时AMD / IntelWindows/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 运行时 DLLmsvcp140.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_ORDERPCI_BUS_ID若存在TRANSCRIPTION_GPU_UUID环境变量则进一步用CUDA_VISIBLE_DEVICES锁定具体 GPU保证多卡环境下设备选择无歧义whisperServer.jsVulkan 设备选择通过--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_formatjson等字段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参数默认值取值范围thresholdVAD 阈值0.50.1 ~ 0.95minSpeechDurationMs最小语音时长250ms50 ~ 2000msminSilenceDurationMs最小静音时长200ms50 ~ 2000msmaxSpeechDurationS最大语音段长30s5 ~ 120sspeechPadMs语音前后填充100ms0 ~ 1000mssamplesOverlap采样重叠0.50 ~ 0.95需要注意的是VAD 在不同场景下的启用策略不同whisperVadConfig.js听写场景默认关闭dictationSileroEnabled需显式开启因为频繁停顿的听写可能会被 VAD 误删语音片段而笔记、会议等长时录音场景默认开启用于跳过长时间静音。5.2 转写质量细节防幻觉阈值与自定义词典防幻觉源码中针对连续听写场景设置了更严格的解码器阈值entropy_thold: 2.8、logprob_thold: -1.25whisperServer.js用于抑制 whisper.cpp 在近静音窗口输出的训练数据式结尾废话如 Thank you for watching。会议等长音频块通过skipDecoderThresholds保留服务器默认值因为其本身已有 RMS 门控、VAD 等多重防幻觉保护自定义词典转写请求可携带prompt字段将用户词典中的自定义词汇注入解码器提升专业术语、专有名词的识别率。5.3 线程数控制本地推理的线程数可通过WHISPER_THREADS环境变量配置设为具体数值则固定线程数上限 64设为auto或不设置则自动按 CPU 并行度可用并行度的 75%计算默认下限 4、自动上限 12whisperServer.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.10whisperCppRelease.js源码注释说明这是经过测试的构建跟随上游最新版可能导致应用发布之间转写输出漂移、难以审查变更平台覆盖支持darwin-arm64、darwin-x64、win32-x64CPU 版带 MSVC 运行时 DLL、linux-x64download-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.jsgetModelsDirForService(whisper)返回${cacheRoot}/whisper-models。以下几点值得注意可通过环境变量OPENWHISPR_CACHE_ROOT整体重定向缓存根目录Linux 下若设置了XDG_CACHE_HOME则优先使用${XDG_CACHE_HOME}/openwhisprWindows 下若用户目录包含非 ASCII 字符如中文、西里尔字母路径原生 whisper/parakeet 二进制会崩溃因此会自动回退到C:\ProgramData\OpenWhispr\cache等纯 ASCII 安全路径旧版本遗留的模型目录会自动迁移含跨卷复制与失败回滚保护。九、故障排查状态显示 Not Found找不到二进制在控制面板中点击Recheck Installation重新检查安装重启应用若内置二进制确实失效可通过系统包管理器安装macOSbrew install whisper-cppLinux从 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 后端与线程数三个维度入手即可。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考