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
$env:HF_ENDPOINT = “https://hf-mirror.com” # Windows PowerShell

3. 下载命令（以 deepseek-ai/DeepSeek-R1-Distill-Qwen-7B 为例）

huggingface-cli download
–resume-download \ # 断点续传
–local-dir-use-symlinks False \ # 禁用符号链接，直接存储文件
–local-dir ./models/deepseek-r1 \ # 指定本地目录
deepseek-ai/DeepSeek-R1-Distill-Qwen-7B # 模型ID

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