检查 Python 环境变量

确保 Python 已正确添加到系统环境变量 PATH 中。打开命令提示符，输入以下命令验证 Python 是否可识别：

python --version

若提示“不是内部或外部命令”，需手动添加 Python 安装路径到 PATH。例如，Python 默认安装路径通常为 C:\Python3x 或 /usr/bin/python3。

验证 LLaMa-Factory 依赖项

运行以下命令检查项目依赖是否完整安装：

pip install -r requirements.txt

若存在版本冲突，可尝试指定版本号或使用虚拟环境隔离依赖：

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

检查 CUDA 和 GPU 驱动

若使用 GPU 加速，需确保 CUDA 和 cuDNN 已安装且版本匹配。运行以下命令验证 CUDA 是否可用：

nvcc --version

若未安装，需根据显卡型号下载对应版本的 CUDA Toolkit 并配置环境变量。

修复 WebUI 启动脚本

检查 webui.py 或启动脚本中的路径配置。常见问题包括相对路径错误或硬编码路径。修改脚本确保路径动态获取：

import os
script_dir = os.path.dirname(os.path.abspath(__file__))
os.chdir(script_dir)

查看日志文件

启动失败时通常会在项目目录生成日志文件（如 logs/error.log）。通过日志定位具体错误：

tail -f logs/error.log  # Linux/macOS
type logs\error.log    # Windows

端口冲突处理

默认端口（如 7860）可能被占用。尝试更换端口启动：

python src/webui.py --port 8080

使用以下命令检查端口占用情况：

netstat -ano | findstr 7860  # Windows
lsof -i :7860                # Linux/macOS

系统权限问题

在 Linux/macOS 中，确保脚本具有可执行权限：

chmod +x src/webui.py

Windows 系统需以管理员身份运行命令提示符。

环境变量动态加载

若修改 PATH 后仍需重启终端生效，可尝试临时加载：

export PATH=$PATH:/custom/path  # Linux/macOS
set PATH=%PATH%;C:\custom\path  # Windows

重新克隆仓库

若问题持续存在，可能是仓库文件损坏。删除旧仓库并重新克隆：

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

联系开发者支持

若上述方法无效，可提交 Issue 到 GitHub 仓库，附上错误日志和系统环境信息：

python --version
pip list
nvidia-smi  # GPU 用户