LLaMa-Factory 部署问题日志路径配置

LLaMa-Factory 的日志默认存储在项目根目录下的 logs 文件夹中。如果 webui 启动失败，检查以下路径是否存在日志文件：

• ./logs/webui.log（主日志）
• ./logs/error.log（错误专用日志）

若未自动生成日志文件，需手动创建 logs 目录并确保脚本有写入权限：

mkdir -p logs && touch logs/webui.log logs/error.log
chmod -R 777 logs/

常见启动失败原因排查

端口冲突问题
默认端口（7860）可能被占用。通过以下命令确认端口使用情况：

netstat -tulnp | grep 7860

解决方案是修改启动命令指定新端口：

llamafactory-cli webui --port 7890

依赖库版本不匹配
检查 requirements.txt 中关键库的版本要求，特别是 transformers 和 torch。典型冲突包括：

• torch 版本与 CUDA 不兼容
• transformers 版本过旧

使用以下命令验证安装的版本：

pip list | grep -E "torch|transformers|peft"

环境变量配置错误

CUDA 环境问题
运行以下命令检查 CUDA 是否可用：

python -c "import torch; print(torch.cuda.is_available())"

若返回 False，需重新安装匹配的 PyTorch 版本：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

配置文件路径错误
检查 configs 目录中的模型配置文件路径是否正确。常见错误包括：

• 模型路径 model_name_or_path 指向不存在的本地目录
• 数据集路径 dataset_path 未正确配置

高级调试技巧

启用详细日志输出可通过修改启动命令：

llamafactory-cli webui --log_level DEBUG

对于内存不足问题，添加 --load_in_4bit 或 --load_in_8bit 参数：

llamafactory-cli webui --load_in_4bit

典型错误日志分析

ModuleNotFoundError
缺失依赖库的错误示例：

ModuleNotFoundError: No module named 'accelerate'

解决方案：

pip install -r requirements.txt --upgrade

CUDA Out of Memory
调整 max_shard_size 参数或减少批量大小：

model:
  max_shard_size: "2GB"

权限拒绝错误
对 /tmp 等系统目录的权限问题，需设置环境变量改变临时目录：

export TMPDIR=./tmp
mkdir -p tmp