Buzz 离线语音转录与翻译常见问题全解析模型存储、性能优化、GPU 加速与故障排查【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz导读本文基于 Buzz 官方 FAQ 文档系统梳理这款基于 OpenAI Whisper 的本地离线转录/翻译工具在实战中最常遇到的 11 类问题涵盖模型文件存储位置、转录速度优化、系统音频录制、模型选型策略、GPU 加速、离线部署、崩溃排查、开发版获取与 Flatpak 主题修复等场景。文中结合本仓库源码如 model_loader.py、download-models.py、models_preferences_widget.py给出可验证的实现细节与操作路径读完即可自主完成模型管理、性能调优与故障定位。1. 模型存储在哪里Buzz 使用 platformdirs 的user_cache_dir(Buzz)计算缓存根目录再拼接models子目录作为模型根目录。相关实现见 model_loader.pymodel_root_dir user_cache_dir(Buzz) model_root_dir os.path.join(model_root_dir, models) model_root_dir os.getenv(BUZZ_MODEL_ROOT, model_root_dir) os.makedirs(model_root_dir, exist_okTrue)因此在三大桌面平台上的默认模型位置为平台默认模型目录Linux~/.cache/Buzz/modelsmacOS~/Library/Caches/Buzz/modelsWindows%USERPROFILE%\AppData\Local\Buzz\Buzz\Cache\models即%LOCALAPPDATA%\Buzz\Buzz\Cache\models几点补充环境变量覆盖设置BUZZ_MODEL_ROOT可整体改变模型根目录recording_transcriber.py与whisper_file_transcriber.py中同样读取该变量这在离线部署、多机共享模型缓存时非常有用。GUI 快速定位在菜单Help - Preferences - Models帮助 - 偏好设置 - 模型中下载任意模型后点击Show file location按钮即可在文件管理器中打开模型所在目录。该按钮由 models_preferences_widget.py 实现点击后调用TranscriptionModel.open_file_location()见 model_loader.py底层使用os.startfileWindows、openmacOS或xdg-openLinux打开目录。缓存目录的其它内容同一个缓存根目录下还存放转录任务缓存tasks.json与transcriptions/*.json见 cache.py以及插件目录plugins/、plugins_deps/见 loader.py。2. 转录太慢可以尝试什么语音识别是计算密集型任务官方 FAQ 给出的提速路线按成本从低到高依次为改用更小的 Whisper 模型tiny、base等小模型显著降低计算量代价是准确率下降。模型尺寸与近似体积见 model_loader.py 中的WHISPER_MODEL_SIZEStiny约 73 MB、base约 139 MB、small约 462 MB、medium约 1.5 GB、large/large-v2/large-v3约 2.9 GB、large-v3-turbo约 1.6 GB。改用 Whisper.cpp 后端这是优化过的 C 实现运行高效即使在仅集成显卡的现代笔记本上也能实时转录且完全支持纯 CPU 运行。使用 Faster Whisper 后端若拥有至少 6 GB 显存的 NVIDIA GPU可选用 Faster Whisper速度比原生 Whisper 快数个数量级且内存占用更低。使用 OpenAI API 远程转录在偏好设置中填入 OpenAI API Key将转录计算卸载到远程服务器。API Key 输入框与测试按钮位于 general_preferences_widget.py密钥通过系统钥匙串安全存储见 keyring_store.py。该后端为OPEN_AI_WHISPER_API模型类型见 model_loader.py无需下载任何本地模型。详细偏好设置请参阅 偏好设置文档。3. 如何录制系统音频Buzz 的录音转录功能见 2_live_recording.md默认捕获麦克风输入。要转录系统内部播放的声音例如网页会议、在线视频需要先创建虚拟音频设备把目标应用的音频输出路由到该虚拟扬声器然后在 Buzz 的录音音源下拉框中选中它对应的下拉控件为 audio_devices_combo_box.py。各平台常用工具平台推荐工具macOSBlackHole免费开源虚拟音频驱动WindowsVB-CABLE虚拟音频线缆LinuxPulseAudio Volume Controlpavucontrol配置完成后在 Buzz 的实时录音界面选择该虚拟设备即可开始转录系统音频。4. 我应该使用哪个模型模型选择是「硬件算力」与「识别精度」之间的权衡小模型快但不准大模型准但吃硬件。FAQ 对大模型家族给出了如下经验large最早发布的旧版大模型。large-v2后续改进版准确率更高在部分语言上被认为最稳健、最稳定。large-v3最新版本多数情况下准确率最佳但偶尔会出现幻觉编造音频中并不存在的词。large-v3-turboTurbo在速度与准确率之间取得较好平衡。这些枚举值可在 model_loader.py 的WhisperModelSize中看到此外还包含tiny/tiny.en/base/base.en/small/small.en/medium/medium.en以及custom、lumii拉脱维亚语专用等特殊项。名称带.en的模型仅支持英语对其他语言无效。除模型大小外还需选择Whisper 实现类型ModelType枚举见 model_loader.pyWhisperOpenAI 官方初版实现准确但速度慢、内存占用高。Faster Whisper优化实现比原生 Whisper 快数个数量级且内存占用更低。推荐在至少 6 GB 显存的 NVIDIA GPU 上使用从源码看该选项在 macOS x86_64 平台会被隐藏is_available()返回False。Whisper.cpp优化的 C 实现速度快、效率高支持任意品牌 GPU含 Apple Silicon也能纯 CPU 运行是 Mac 用户和没有 NVIDIA GPU 用户的最佳选择。注意large在 Whisper.cpp 下被映射为large-v1见 model_loader.py。Hugging FaceTransformers 实现最大优势是支持海量社区微调模型可针对特定语言优化自版本1.4.0起支持 Meta AI 的MMS多语言语音识别模型家族覆盖 1000 多种语言以及 Whisper 模型的PEFT参数高效微调版本自版本1.5.0起额外支持Parakeet、Qwen3-ASR与VibeVoice ASR等 Hugging Face 热门 ASR 模型相关下载文件过滤规则见 model_loader.py 的HUGGING_FACE_MODEL_ALLOW_PATTERNS。最可靠的办法是在你自己的语言上逐个实测选出精度与速度的平衡点。5. 如何启用 GPU 加速LinuxNVIDIA GPU 开箱即用。若遇到问题请安装 CUDA 12、cuBLAS 与 cuDNN 运行时库。WindowsGPU 支持已包含在官方安装包.exe中但要求 CUDA 12使用旧版 CUDA 的机器会回退到 CPU 计算。详细的启用步骤可参阅 CONTRIBUTING.md 中的 GPU Support 一节。Faster Whisper 前提该后端依赖 CUDA 12 环境显存建议不低于 6 GB。Buzz 的模型下载与加载逻辑中内置了「下载完整性标记」DOWNLOAD_COMPLETE_MARKER .buzz_complete见 model_loader.py并在 cuda_setup.py 中处理 CUDA 相关的运行环境探测GPU 不可用时会自动降级到 CPU 推理。6. 如何修复Unanticipated host error[PaErrorCode-9999]该错误是 PortAudio 的主机错误通常意味着 Buzz 无法访问麦克风Windows进入设置 - 隐私 - 麦克风确认允许 Buzz 使用麦克风杀毒/安全软件检查是否有安全软件拦截了 Buzz 的录音权限可尝试临时禁用杀毒软件验证无需卸载或在其设置中为 Buzz 放行系统级权限检查是否存在系统策略阻止应用访问麦克风。修复后重启 Buzz 重新开始录音即可。7. 可以在没有互联网的计算机上使用 Buzz 吗可以。Buzz 的转录完全在本地运行模型下载完成后即不再需要网络。离线部署的推荐做法在一台联网机器上打开Help - Preferences - Models下载所需模型点击Show file location打开模型目录将整个模型目录复制到离线计算机的相同位置例如 Linux 下为~/.cache/Buzz/models。仓库还提供了官方离线模型缓存准备脚本 download-models.py可在任意联网机器上批量预下载模型其用法示例# 下载全部后端whisper / whispercpp / fasterwhisper的标准尺寸模型 uv run python scripts/download-models.py # 只下载 Faster Whisper 的 small 模型 uv run python scripts/download-models.py --model-type fasterwhisper --model-size small # 下载 Whisper.cpp 的 tiny、base、small 三个尺寸 uv run python scripts/download-models.py --model-type whispercpp --model-size tiny base small脚本支持的--model-type取值为whisper、whispercpp、fasterwhisper--model-size取值与 GUI 中的模型尺寸一一对应。它还支持用BUZZ_MODEL_ROOT指定模型存放目录如挂载到 NFS 共享BUZZ_MODEL_ROOT/mnt/nfs/buzz-models uv run python scripts/download-models.py脚本会跳过已下载的模型并在全部完成后汇总失败项。若想在纯命令行环境下使用 Buzz可参考 cli.py 提供的参数如-t/--tasktranscribe/translate、-m/--model-type、-s/--model-size、-l/--language与-hfidHugging Face 模型 ID等详细用法见 CLI 文档。8. Buzz 崩溃了怎么办崩溃排查按以下顺序进行检查模型文件是否损坏模型下载不完整或被截断是崩溃的最常见诱因。进入Help - Preferences - Models删除对应模型后重新下载。GUI 中的Delete按钮models_preferences_widget.py会根据模型类型删除单个文件或整个快照目录逻辑见 model_loader.py。Buzz 也会通过「完整性标记 文件大小校验」自动识别不完整下载Whisper 原生模型要求实际文件大小不低于预期的 95%model_loader.pyHugging Face / Faster Whisper 模型则要求快照目录中存在.buzz_complete标记。查看日志并上报进入Help - About Buzz点击Show logs按钮即可打开日志目录。各平台日志位置macOS~/Library/Logs/BuzzWindows%USERPROFILE%\AppData\Local\Buzz\Buzz\LogsLinux直接在终端运行 Buzz观察标准错误输出如果仍无法解决请携带日志文件到项目 Issues 区报告方便维护者定位修复。硬件前提Buzz 需要 CPU 支持AVX2指令集非常老旧AVX2 之前的CPU 不受支持。9. 如何获取最新的开发版本开发版本包含最新的 bug 修复与新功能官方鼓励有探索精神的用户提前试用因为它们需要更多真实环境测试。Linux 用户直接通过 Snap 渠道安装 edge 版本sudo snap install buzz --edge其他平台打开项目 CI 构建页面筛选main分支的最新构建点击列表中最近一次成功的构建条目滚动到构建页底部的 Artifacts构建产物区域下载对应平台的安装文件需要登录 GitHub 账号才能看到下载链接。10. 为什么 Flatpak 安装的 Buzz 没有应用系统主题Flatpak 沙箱默认无法读取宿主机主题目录导致 Buzz 界面与系统主题不一致。修复方法GNOME 深色主题安装gnome-themes-extra后执行gsettings set org.gnome.desktop.interface gtk-theme Adwaita-dark gsettings set org.gnome.desktop.interface color-scheme prefer-dark主题目录权限将系统主题复制到~/.themes并授权 Flatpak 访问cp -r /usr/share/themes/ ~/.themes/ flatpak override --user --filesystem~/.themesFedora 用户安装以下包即可补齐所需组件sudo dnf install gnome-themes-extra qadwaitadecorations-qt{5,6} qt{5,6}-qtwayland11. Buzz 内部使用了哪些库Buzz 的转录能力建立在以下优秀的开源项目之上对应源码可在本仓库的buzz/transcriber/、buzz/transformers_whisper.py、whisper.cpp/与whisper_diarization/子目录中进一步探索whisper.cppC 版 Whisper 推理引擎驱动WHISPER_CPP后端faster-whisperCTranslate2 加速实现驱动FASTER_WHISPER后端**transformers 中集成 MMS 等模型stable-ts用于稳定时间戳与词级对齐的转录后处理srt_equalizer字幕时间轴均衡器用于 SRT 等字幕格式的导出优化whisper-diarization说话人分离Speaker Diarization流水线支撑 5_speaker_identification.md 中介绍的话者识别功能。这些库协同工作构成了 Buzz「本地离线、多后端、多语言」的完整转录与翻译能力。【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAIs Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考