检查 GPU 驱动与 CUDA 版本兼容性

LLaMa-Factory 的 WebUI 依赖 GPU 加速，需确保驱动与 CUDA 版本严格匹配。运行以下命令验证驱动版本：

nvidia-smi

输出顶部的 Driver Version 需与 NVIDIA 官方文档 中列出的 CUDA 版本要求一致。

若版本不匹配，需升级或降级驱动。例如 CUDA 12.x 通常要求驱动版本 ≥525.60.13，而 CUDA 11.8 需驱动 ≥450.80.02。

---

验证 PyTorch 的 CUDA 支持

安装的 PyTorch 必须与本地 CUDA 版本兼容。在 Python 环境中执行：

import torch
print(torch.__version__, torch.cuda.is_available())

若输出为 False，说明 PyTorch 未正确识别 GPU。需重新安装与 CUDA 匹配的 PyTorch 版本：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118  # 示例：CUDA 11.8

---

检查环境变量冲突

错误的 LD_LIBRARY_PATH 或 CUDA_HOME 可能导致库加载失败。运行以下命令检查路径：

echo $LD_LIBRARY_PATH
echo $CUDA_HOME

确保路径指向正确的 CUDA 安装目录（如 /usr/local/cuda-12.1）。若存在冲突，临时清除变量测试：

unset LD_LIBRARY_PATH

---

排查端口占用问题

WebUI 默认使用端口 7860。若端口被占用，可尝试更改端口：

llamafactory-cli webui --port 7890  # 指定新端口

检查端口占用情况：

lsof -i :7860

---

重新安装依赖项

依赖包版本冲突可能导致服务启动失败。建议创建干净的 Python 虚拟环境后重新安装：

python -m venv llama-env
source llama-env/bin/activate
pip install -U llamafactory[webui]