3分钟解决90%问题：Buzz错误代码速查手册

你还在为Buzz转录失败而抓狂？导入音频就崩溃、模型下载到99%失败、实时录音无声？这份手册汇总了8大高频错误场景，附带代码级解决方案和官方配置指南，让你秒变故障排除专家。

一、模型加载失败：Whisper模型相关错误

1.1 "ggml-model.bin文件不存在"

错误表现：启动转录时提示模型文件缺失，日志显示FileNotFoundError: [Errno 2] No such file or directory: 'ggml-tiny.bin'

解决方案：

1. 检查模型路径配置是否正确：
   官方默认路径：~/.cache/Buzz/models/（可通过BUZZ_MODEL_ROOT环境变量自定义）
2. 手动下载模型文件：
   • 访问ggerganov/whisper.cpp仓库
   • 下载对应尺寸模型（如ggml-tiny.bin）到模型目录
3. 验证文件权限：确保模型文件有读取权限

代码参考：buzz/model_loader.py中的模型路径检查逻辑

1.2 "CUDA版本不兼容"

错误表现：加载模型时提示CUDA error: invalid device function或CUDA version < 12

解决方案：

• 若CUDA版本<12，系统会自动切换至CPU模式：buzz/transcriber/whisper_file_transcriber.py
• 强制CPU运行：设置环境变量export BUZZ_FORCE_CPU=true
• 推荐配置：CUDA 12.1+搭配faster-whisper模型

二、音频处理错误：文件导入与格式问题

2.1 "不支持的音频格式"

错误表现：导入.m4a/.flac文件时提示Unsupported audio format

解决方案：

1. 检查FFmpeg安装：Buzz依赖FFmpeg处理音频编解码

   # Ubuntu/Debian安装
   sudo apt install ffmpeg
   # macOS安装
   brew install ffmpeg
   

2. 格式转换：将音频转为WAV/MP3后重试
3. 代码验证：buzz/transcriber/whisper_file_transcriber.py中的音频加载逻辑

2.2 长音频转录崩溃

错误表现：处理>1小时音频时程序无响应或内存溢出

解决方案：

1. 调整批量处理参数：
   在偏好设置→模型→Faster Whisper中降低batch_size至8
2. 使用分段转录：通过ffmpeg -i input.mp3 -f segment -segment_time 3600 output_%03d.mp3分割音频
3. 硬件加速配置：确保启用CUDA（需NVIDIA显卡）

三、实时录音故障：设备与权限问题

3.1 录音设备无法选择

错误表现：录音界面下拉框为空，提示"未检测到麦克风"

解决方案：

1. 权限检查：
   • Linux: sudo usermod -aG audio $USER
   • Windows: 设置→隐私→麦克风→允许Buzz访问
2. 设备测试：通过系统录音工具验证麦克风工作正常
3. 代码参考：buzz/widgets/audio_devices_combo_box.py中的设备检测逻辑

3.2 录音无声但不报错

错误表现：录音进度条不动，波形无显示

解决方案：

1. 输入源选择：确认在录音设置中选择了正确的麦克风
2. 音量调节：系统音量 mixer 中确保麦克风未静音
3. 驱动更新：检查声卡驱动（尤其Realtek设备需安装官方驱动）

四、高级解决方案：配置与环境优化

4.1 自定义模型路径设置

当系统盘空间不足时，可通过环境变量指定模型存储路径：

# Linux/macOS终端
export BUZZ_MODEL_ROOT="/mnt/external_drive/buzz_models"
# Windows命令提示符
set BUZZ_MODEL_ROOT=D:\buzz_models

配置文件位置：buzz/model_loader.py

4.2 日志调试指南

遇到疑难问题时，通过日志定位根本原因：

1. 启用详细日志：
   启动时添加参数--debug（如buzz --debug）
2. 日志文件位置：
   • Linux: ~/.local/share/Buzz/logs/
   • Windows: %APPDATA%\Buzz\logs\
3. 关键日志分析：搜索ERROR和Exception关键字

五、官方资源与社区支持

• 完整文档：docs/usage/
• 常见问题：CONTRIBUTING.md
• 社区论坛：GitHub Discussions（需替换为国内镜像）
• 错误报告模板：提交issue时务必包含日志文件和系统信息

通过以上方案，90%的Buzz使用问题都能在3分钟内解决。若遇到特殊错误，建议先检查官方FAQ或提交包含完整日志的issue。记住：保持模型和软件为最新版本是避免大多数问题的关键！