llama factory本地部署常见问题

问题1：启动微调时报错：safetensors_rust.SafetensorError: Error while deserializing header: HeaderTooLarge

根因：

使用git clone 下载的模型，没有提前安装lfs（large file storage），导致模型文件没有下载完成；

解决方案1：安装lfs

安装 Git

sudo apt-get install git -y # Ubuntu/Debian
brew install git # macOS

安装 Git LFS

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
git lfs install # 初始化 LFS

方案2：使用huggingface客户端下载模型：

1. 安装工具
   pip install -U huggingface_hub

2. 设置镜像源（国内用户必选）

export HF_ENDPOINT=https://hf-mirror.com # Linux/macOS

3. 下载命令

sudo hf download --token 替换成自己的token Qwen/Qwen2.5-VL-3B-Instruct --local-dir /opt/models/Qwen2_5_VL_3B

下载需要登录鉴权的私有模型：
huggingface-cli login

推荐使用方案2，下载速度更快。