企业官网建设流程全解析

3条路径跑通Buzz离线语音转录：从模型下载超时到出转录结果

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

进度条卡在0%，弹窗弹出 ConnectionError，下了一半的 Whisper 模型文件又得从头再来——这是 Buzz 离线语音转录卡在"模型下载"时最常见的现场。这篇文章把从克隆仓库到出转录结果的路径拆开讲，三种网络环境下各有一条可直接执行的路线。

快速诊断：Buzz 模型下载卡在哪个环节

对号入座，先判断你属于哪种情况：

• 如果看到ConnectionError或ConnectTimeout：大概率是直连 Hugging Face 的链路不通，属于网络层问题，优先走下面的"代理"或"镜像"路线。
• 如果看到ReadTimeout、进度条长时间不动：连接建立了但跨国链路限速，文件会越下越慢甚至中途断掉，属于带宽问题，换个出口比重试有用。
• 如果文件下完了但启动时仍提示要下载，或模型尺寸明显偏小：多半是上次中断留下的残缺缓存。项目里用.buzz_complete标记文件表示下载完成，没这个标记的文件等于没下完，删掉缓存重下即可。
• 如果报LocalEntryNotFoundError：Buzz 在本地模型目录里没找到对应模型文件，通常是手动放置的路径不对，对照下面第二条路线检查。

按场景选方案

三条路线各有一个明确的使用前提，先判断自己属于哪类，再看对应小节。

如果你只是想快点跑起来

直接克隆国内镜像仓库，模型下载走的是仓库内的网络，不再依赖直连国外站点：

# 克隆镜像仓库 git clone https://gitcode.com/GitHub_Trending/buz/buzz cd buzz # 安装依赖（要求 Python 3.12，项目锁定 >=3.12,<3.13） pip install -e . # 启动 python main.py

注意 Python 版本这条别跳过，3.10、3.13 装依赖都会出问题。

如果你的网络环境比较特殊

手动把模型文件弄到本地缓存目录，再让 Buzz 指过去。缓存目录由platformdirs按平台生成，固定是Buzz/models子目录：

• Windows：%LOCALAPPDATA%\Buzz\models
• macOS：~/Library/Caches/Buzz/models
• Linux：~/.cache/Buzz/models

在 Buzz 的偏好设置 → 模型页里，Whisper、Whisper.cpp、Faster Whisper 这几类模型都支持手动下载（源码里对应is_manually_downloadable）。另外还有一个隐藏开关：BUZZ_MODEL_ROOT环境变量可以整体覆盖模型根目录（见 buzz/model_loader.py），适合把模型放到大容量磁盘上。

如果你已经有代理

让 Buzz 走代理下载，在启动前设置环境变量即可。Linux/macOS：

export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890 python main.py

Windows PowerShell：

$env:HTTP_PROXY="http://127.0.0.1:7890" $env:HTTPS_PROXY="http://127.0.0.1:7890" python main.py

项目文档里还记录了一个针对国内环境的选项HF_ENDPOINT（指向 hf-mirror 镜像端点），和代理二选一，详见 docs/docs/preferences.md。

从克隆到出结果的完整走一遍

按顺序执行，每步只看一个成功标志。

① 装环境：执行上面第一条路线的命令块。看到Successfully installed字样就算通过，此时不用急着启动。

② 首次启动选模型：运行python main.py。首次运行会弹出模型选择，第一次建议选 Tiny 或 Base——Tiny 约 73MB、Base 约 139MB，先让全链路通起来，大模型随时可以后补。

③ 建转录任务：把音频拖进主界面，任务表格里选好模型、语言，勾选后任务开始排队。任务列表和状态都在这里管理：

④ 查看结果：任务跑完后双击打开查看器，带时间戳的文本就是最终产物，支持导出 TXT、SRT、VTT 等格式：

看到带时间戳的文本出来的那一刻，就说明从模型加载到解码的全链路是通的。

踩过的坑 & 排查手册

• ⚠️Windows 上下载"卡死"不动：别急着杀进程。huggingface_hub 的并行下载在 Windows 上有文件锁竞争，代码里对 Windows 已经做了降级处理（改用串行+文件拷贝，见 buzz/model_loader.py 的打补丁逻辑），先给它 5~10 分钟，多数情况会自己动。
• 文件下了一半，重启后又从头下：这是残缺缓存，不是 Buzz 的问题。定位到对应平台的Buzz/models目录，删掉该模型对应的子目录再重新触发下载；有.buzz_complete标记的才是完整文件。
• 怎么判断文件是不是残缺：代码里维护了各档模型的预期体积（WHISPER_MODEL_SIZES）：tiny 约 73MB、base 约 139MB、small 约 462MB、medium 约 1.5GB、large 约 2.9GB。本地文件比预期小一截，就是没下完。
• 任务列表莫名清空：Buzz 的任务缓存在tasks.json里，JSON 解析失败时代码会自动重置缓存而不是崩溃，属于自恢复行为，重新建任务就行，不用手动清文件。
• ⚠️设置了代理却没生效：确认环境变量和python main.py在同一个 shell 会话里。新开终端环境变量就没了，可以先curl -I https://huggingface.co验证代理是否真的通。

让转录更快的几个点

1. 按场景换模型：实时转录、大批量先跑通用 Tiny/Base；要精度就上 Medium 或 Large-v3-turbo——turbo 版只有约 1.6GB，比 Large（约 2.9GB）小一半还多，解码速度也快。
2. 确认 GPU 加速真的开了：打开任务的"高级设置"，看 Device 选项里有没有 CUDA（NVIDIA）或 CoreML（Apple Silicon）。只有 CPU 的话检查 CUDA 环境，项目里有对应的初始化脚本 buzz/cuda_setup.py。
3. 批量文件别手动拖：偏好设置有文件夹监控选项，目录里新增音频会自动进任务队列，适合"丢一晚上、早上收结果"的用法。
4. 自动化场景走 CLI：docs/docs/cli.md 描述了命令行用法，脚本里调用比模拟点击界面稳定得多。

延伸材料

• 安装与系统依赖：docs/docs/installation.md
• 模型下载与缓存核心逻辑：buzz/model_loader.py
• 各类偏好设置（含 HF_ENDPOINT）：docs/docs/preferences.md
• 各转录引擎实现：buzz/transcriber/

如果还卡在某一步，把完整报错贴出来，比多试十遍都管用。

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