LLaMa-Factory MacOS 依赖问题排查

报错场景分析
当通过llamafactory-cli webui启动时，MacOS可能因缺少系统级依赖或环境配置问题导致报错，常见问题包括：Python版本冲突、CUDA驱动缺失（Apple Silicon需转译）、Homebrew包未安装等。

---

依赖补装步骤

Homebrew基础工具链安装
确保Homebrew已安装并更新至最新版本，运行以下命令安装基础编译工具：

brew update
brew install cmake git wget

Python环境管理
推荐使用pyenv管理Python版本（如3.10+），避免系统Python冲突：

brew install pyenv
pyenv install 3.10.12
pyenv global 3.10.12

CUDA与加速库配置（Apple Silicon）
若使用M系列芯片，需通过conda安装ARM兼容的PyTorch版本：

conda install -c pytorch pytorch torchvision torchaudio

FFmpeg与音频依赖
部分功能需要音频处理支持：

brew install ffmpeg
pip install librosa soundfile

WebUI前端依赖
确保Node.js和npm已安装以支持前端组件：

brew install node
npm install -g yarn

---

常见报错解决方案

报错：libomp缺失
安装LLVM提供的OpenMP库：

brew install libomp
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"

报错：libiconv链接失败
强制链接Homebrew的iconv版本：

brew link --force libiconv

报错：端口占用
检查并释放默认端口（通常为7860）：

lsof -i :7860
kill -9 <PID>

---

验证安装成功

重新运行WebUI并检查日志：

llamafactory-cli webui --debug

若无报错且终端输出Running on local URL，则表明依赖问题已解决。

---

附加说明

• 若使用Intel芯片，需单独安装NVIDIA CUDA驱动
• 建议通过virtualenv或conda创建隔离环境
• 完整日志可通过--log-level DEBUG参数输出到文件