环境依赖问题

检查 Python 版本是否 ≥3.8 且 ≤3.10，不符合版本要求会导致兼容性问题。使用 python --version 验证版本，建议通过 conda 或 pyenv 创建虚拟环境。

确保已安装 CUDA 11.7/11.8 和对应版本的 PyTorch（≥2.0.0）。运行 nvidia-smi 查看 CUDA 驱动版本，通过 PyTorch 官网命令安装匹配版本。

安装包冲突

常见于与其他机器学习库（如 transformers）版本冲突。执行 pip uninstall transformers accelerate 后重新安装指定版本：

pip install transformers==4.36.2 accelerate==0.25.0

端口占用问题

默认端口 7860 被占用时会出现 Address already in use 错误。通过 --port 参数指定新端口：

llamafactory-cli webui --port 7890

模型路径错误

当提示 Model not found 时需检查 --model_name_or_path 参数。本地模型需提供绝对路径，远程模型需确保名称正确：

llamafactory-cli webui --model_name_or_path meta-llama/Llama-2-7b-chat-hf

权限不足

Linux/Mac 系统可能出现文件读写权限问题。对模型缓存目录（通常为 ~/.cache/huggingface）授予权限：

chmod -R 755 ~/.cache/huggingface

内存不足

显存不足时抛出 CUDA out of memory 错误。添加 --load_in_4bit 或 --load_in_8bit 参数启用量化：

llamafactory-cli webui --load_in_4bit

配置文件缺失

自定义数据集时需确保 dataset_info.json 存在且格式正确。参考官方文档创建标准格式文件：

{
  "my_dataset": {
    "file_name": "data.json",
    "columns": {"prompt": "instruction", "response": "output"}
  }
}

浏览器兼容性问题

部分旧版浏览器无法正常渲染 WebUI 界面。建议使用 Chrome ≥100 或 Firefox ≥115，清除缓存后重试。

防火墙拦截

企业网络可能拦截 WebSocket 连接。临时关闭防火墙测试：

sudo ufw disable  # Ubuntu
netsh advfirewall set allprofiles state off  # Windows

日志分析技巧

通过 --verbose 参数获取详细日志，关键错误通常出现在最后 20 行。典型错误模式包括：

• ModuleNotFoundError: 缺失Python包
• OSError: [Errno 28]: 磁盘空间不足
• ValueError: Unrecognized argument: 参数拼写错误