WhisperLiveKit 本地部署失败常见原因

依赖项缺失或版本不兼容
检查 Python 环境（建议 3.8+）与 PyTorch 版本是否匹配。CUDA/cuDNN 版本需与 PyTorch 对应。通过以下命令验证：

python --version
pip show torch

FFmpeg 未正确安装
WhisperLiveKit 依赖 FFmpeg 处理音频流。未安装或路径未配置会导致报错。通过命令安装并检查：

ffmpeg -version
# 若未安装，根据系统选择：
# Ubuntu: sudo apt install ffmpeg
# macOS: brew install ffmpeg

模型文件下载失败
默认自动下载的 Whisper 模型可能因网络问题失败。手动下载并指定路径：

model = whisper.load_model("medium", download_root="/path/to/cache")

常见报错与解决方案

报错：Could not locate libavformat
FFmpeg 动态链接库未找到。添加环境变量指向 FFmpeg 的 lib 目录：

export LD_LIBRARY_PATH=/path/to/ffmpeg/lib:$LD_LIBRARY_PATH

报错：CUDA out of memory
显存不足导致。尝试减小批处理大小或使用更小的模型：

model = whisper.load_model("base")  # 替换为 base 或 tiny 版本

报错：RuntimeError: No audio received
音频输入设备或配置问题。检查麦克风权限（Linux 需 PulseAudio），或显式指定设备：

audio = whisper.listen(source=0)  # 0 为默认设备索引

端口冲突处理

默认端口（如 5000）被占用时修改配置：

app.run(host="0.0.0.0", port=5001)  # 更换端口

通过命令行查找占用端口的进程并终止：

lsof -i :5000
kill -9 <PID>

日志分析与调试

启用详细日志定位问题：

import logging
logging.basicConfig(level=logging.DEBUG)

检查服务端日志输出，常见错误会显示具体堆栈信息。