企业官网建设流程全解析

Buzz 离线转录模型下载慢？3 种免费加速方案的完整教程

【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAI's Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz

Buzz 是一款基于 OpenAI Whisper 的免费离线语音转录工具，但首次使用要下载几十 MB 到几 GB 的语音模型，网络不佳时下载缓慢甚至失败。本文从源码讲清 Buzz 模型下载慢的根因，并给出 3 种立即可用的加速方案。

症状清单

先看你的情况属于哪一种，后文按这个顺序解决：

为什么会这样

根因写在 model_loader.py 里：Whisper.cpp 模型统一从 Hugging Face Hub 上的ggerganov/whisper.cpp仓库拉取（第 600 行），真正发起下载的是下面这段代码（第 701~707 行）：

result = huggingface_hub.snapshot_download( repo_id, allow_patterns=allow_patterns, cache_dir=cache_dir, max_workers=max_workers, )

这几行说明：Buzz 并不直连某个模型服务器，而是全部经由 huggingface_hub 库走它默认的海外入口——线路慢就慢，连接抖动就中断。另一条路线（官方 Whisper 的 .pt 模型）的下载地址由whisper._MODELS表给出，同样在海外（第 926 行）。所以瓶颈不在 Buzz 本身，而在"默认去海外取货"这一事实。

它是怎么工作的

整个流程分三步：在"偏好设置 → 模型"里选定类型和尺寸 → 后台子进程调 huggingface_hub 取元数据、分片下载文件 → 成功后写入.buzz_complete标记文件（第 127 行）；官方 Whisper 路线还会额外做 SHA256 校验（第 1171~1186 行），不匹配就删文件。

所有模型文件放在系统缓存目录下的Buzz/models子目录：默认路径由user_cache_dir("Buzz")决定（第 120~121 行），可用环境变量BUZZ_MODEL_ROOT覆盖（第 122 行）；启动时 buzz.py 还会把 HuggingFace 的缓存位置 HF_HOME 也指到同一处（第 19~23 行），保证模型只存一份。

健壮性方面：下载失败自动重试 3 次、间隔 5 秒后翻倍（第 686~725 行）；官方 Whisper 路线支持按字节断点续传（第 1007~1086 行）；但 Windows 上被设为单线程、其余平台 8 线程（第 739 行），这就是 Windows 体感最慢的原因。

怎么解决 🔄

方案一：指向国内镜像（最推荐）

适用场景：能访问国内镜像站点，想让 Buzz 改动最小。

1. 启动 Buzz 前设置镜像环境变量：

# Linux / macOS export HF_ENDPOINT=https://hf-mirror.com # Windows PowerShell $env:HF_ENDPOINT="https://hf-mirror.com"

2. 再启动程序（python main.py或你已安装的 Buzz），重新触发模型下载。

HF_ENDPOINT是 huggingface_hub 库自带的镜像切换开关，Buzz 的下载逻辑完全建立在该库之上，所以改一个环境变量即可生效，无需动代码。

验证方法：下载完成后到模型目录确认出现了新模型目录和.buzz_complete标记文件；界面上模型立即可选。注意模型搜索框直连 huggingface.co（第 87 行），镜像后该功能可能暂时不可用，不影响下载本体。

方案二：手动预置模型（离线导入）

适用场景：企业内网、或目标机器完全无法访问外部网络。

1. 在一台网络正常的机器上，按需要的尺寸取到对应的ggml-xxx.bin文件。尺寸参考（代码第 159~172 行常量）：tiny 约 73MB、base 约 139MB、small 约 462MB、medium 约 1.5GB、large 约 2.9GB、large-v3-turbo 约 1.6GB。
2. 在目标机器上查出 Buzz 的模型目录（Linux/macOS/Windows 通用）：

python -c "from platformdirs import user_cache_dir; import os; print(os.path.join(user_cache_dir('Buzz'), 'models'))"

3. 把文件复制进该目录并改名为ggml-model-whisper-custom.bin——这是 Buzz 唯一直接按固定路径读取的"自定义模型"文件名（第 655 行）。
4. 在"偏好设置 → 模型"中选 Whisper.cpp，尺寸选 Custom。

验证方法：选到 Custom 后不再弹出下载对话框，直接开始转录即说明生效。

方案三：走代理下载

适用场景：你已经有可用的代理工具，不想引入镜像。

1. 启动 Buzz 前设置代理（端口按你的代理实际修改）：Linux/macOS 用export HTTPS_PROXY=http://127.0.0.1:7890，PowerShell 用$env:HTTPS_PROXY="http://127.0.0.1:7890"。
2. 重新触发下载。Buzz 底层用的 requests 和 huggingface_hub 都会读取这两个环境变量，代码无需任何修改。

验证方法：先执行curl -I https://huggingface.co，若快速返回状态码说明代理链路正常，再回 Buzz 下载观察速度。

效果对比

表中速度为一般网络环境下的约数，仓库未提供实测数据；模型尺寸数字来自 model_loader.py 第 159~172 行的常量，可直接核对。

还不行时

1. 进度一直是 0%——Whisper.cpp 本就没有进度条（model_download_progress_dialog.py 的NO_PROGRESS_MODEL_TYPES），不代表卡死。跑watch -n 2 'du -sh <你的模型目录>'（Linux/macOS）看文件是否在变大；Windows 可在 PowerShell 定期执行Get-ChildItem <目录> -Recurse | Measure-Object Length -Sum。
2. 提示 SHA256 不匹配——文件已损坏。删除模型目录里那个不完整文件后重新下载；官方 Whisper 路线支持断点续传（第 1007~1086 行），不必从零开始。
3. 下载到一半中断——直接再点一次下载即可。huggingface_hub 缓存会保留已下成功的分片，只补缺失部分，且内置 3 次自动重试（第 686~725 行）。
4. Windows 速度奇慢——单线程是代码设定（第 739 行），大文件建议改用方案一或方案二。

选哪条路

• 家庭/个人用户：走方案一，一行环境变量的成本，收益最大。
• 企业内网/批量部署：走方案二，外网机下好一次，拷入内网分发。
• 已有代理的用户：直接用方案三，少改一项配置。

更进一步 📦

• buzz/model_loader.py：下载、重试与 SHA256 校验的核心逻辑，重点看第 600、686~786、1171~1186 行
• buzz/buzz.py：模型目录与 HF_HOME 的初始化（第 19~23 行）
• buzz/widgets/preferences_dialog/models_preferences_widget.py：模型设置面板，含自定义模型链接输入框（第 107~121 行）
• 想通读源码：git clone https://gitcode.com/GitHub_Trending/buz/buzz

Buzz 模型下载慢的根因很集中：默认去海外节点取货。改的是网络路径，不是代码。建议你先用「症状清单」确认自己卡在哪一步，再从方案一开始动手；模型就位后，把音频文件拖进 Buzz 就能开始离线转录了。

【免费下载链接】buzzBuzz transcribes and translates audio offline on your personal computer. Powered by OpenAI's Whisper.项目地址: https://gitcode.com/GitHub_Trending/buz/buzz