企业官网建设流程全解析

Buzz Whisper 模型下载不动？改用国内镜像跑通离线转写配置

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

Buzz 是在本地离线完成音频转写与翻译的工具，引擎为 Whisper。装好后第一道坎是模型下载：文件从 70 MB 到 2.9 GB 不等，源站是 Hugging Face，国内直连经常超时、进度框长时间转圈。本文给出 Buzz 模型下载加速的完整做法：把下载入口重定向到国内镜像，验证模型完整落盘，并覆盖离线机器的替代方案。

为什么 Buzz 的模型下载会卡住：请求全部直连 Hugging Face

Buzz 的 Whisper.cpp、OpenAI Whisper、Faster Whisper 引擎统一通过huggingface_hub的snapshot_download从 Hugging Face 拉取模型，缓存目录在 Linux 为~/.cache/Buzz/models，模型规格与体积的对照写在 model_loader.py：

因为请求直连 Hugging Face 服务器，国内网络下容易超时中断。Buzz 虽有自动重试——失败后按 5 秒、10 秒退避、共 3 次，已下载的字节也保留在缓存——但重试解决不了网络不通。根子在于「从哪拉」，需要换成一个可达的镜像端点。

启动 Buzz 前设置 HF_ENDPOINT，把模型请求重定向到镜像

huggingface_hub原生读取HF_ENDPOINT环境变量决定访问哪个端点，所以只要在启动 Buzz 的同一个终端里设置它，全部模型请求就会改走镜像，不用改任何源码：

export HF_ENDPOINT=https://hf-mirror.com python -m buzz

Windows PowerShell 中把第一行换成$env:HF_ENDPOINT="https://hf-mirror.com"。官方文档 docs/docs/preferences.md 也把该变量列为国内加速的推荐配置。

变量必须对 Buzz 进程可见

环境变量只对同会话启动的进程生效：双击桌面快捷方式弹出的 Buzz 读不到终端里设置的变量。要么在设好变量的终端中启动 Buzz，要么把HF_ENDPOINT设为系统级环境变量后重新打开应用。

在 Models 偏好页发起真实下载，无百分比的进度框是设计如此

打开 Preferences（快捷键 Ctrl/Cmd + ,）进入 Models 页：Group 选 Whisper.cpp，模型列表选 Tiny，点 Download。Whisper.cpp、Faster Whisper 与 Hugging Face 三类引擎的进度框只显示「Downloading model」转圈，没有百分比——这是 model_download_progress_dialog.py 中NO_PROGRESS_MODEL_TYPES的设计而非卡死。下载完成后，模型从「Available for Download」移入「Downloaded」，Download 按钮消失。

用 .buzz_complete 标记与文件大小判断模型是否完整落盘

download_from_huggingface下完全部文件后，会在模型快照目录写入标记文件.buzz_complete。Buzz 用它判断模型是否就绪：标记存在，界面才把该模型显示为已下载。下载结束后执行：

find ~/.cache/Buzz/models -name ".buzz_complete"

有输出说明标记已写入。

再核对模型文件本身的大小

进入快照目录找到ggml-tiny.bin，与 Hugging Face 仓库中的原始文件对比大小。明显偏小说明没下完：删掉不完整文件与.buzz_complete标记后重新 Download，重试只补缺失部分，不必清空整个缓存。

内网机器用官方脚本预下载，BUZZ_MODEL_ROOT 决定模型落盘位置

Buzz 自带离线预下载脚本 scripts/download-models.py，在联网机上先把模型拉好：

BUZZ_MODEL_ROOT=/data/buzz-models python scripts/download-models.py --model-type whispercpp --model-size tiny

BUZZ_MODEL_ROOT同时决定模型存放位置：Buzz 启动时若该变量存在，模型目录与HF_HOME都据此推导（见 buzz.py），脚本和 GUI 因此写入同一处。

把模型目录迁移到离线机器

把/data/buzz-models整个拷到内网机器并设置相同变量，Buzz 直接复用已下载的模型，无需再联网。

三类下载异常的排查入口

改了 HF_ENDPOINT 速度没变化，或进度框长时间转圈

先在启动 Buzz 的同一终端执行echo $HF_ENDPOINT：有输出而速度仍慢，是镜像侧带宽问题；无输出则是快捷方式启动、进程没继承变量。分不清慢还是卡死时，连跑两次du -sh ~/.cache/Buzz/models对比，目录大小还在增长就是带宽慢。另注意 Windows 上为避免huggingface_hub的文件锁竞争，Buzz 自动改用单线程下载，速度天然低于 Linux。

重新下载报文件对不上或大小异常

不需要删除整个缓存目录：huggingface_hub保留已下载的字节，重试只补缺失部分。若确认文件不完整，删掉对应模型文件与.buzz_complete标记，再回 Models 页点 Download。

归根结底是三件事：用HF_ENDPOINT把下载入口指向镜像，在 Models 页发起真实下载，再用.buzz_complete标记验证落盘。想进一步调整线程数、量化版本等参数，可查 docs/docs/preferences.md 的环境变量列表。

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