Chapter 02
环境准备与安装
2.1 装之前要先知道的事
LLaMA-Factory 是上层微调框架，它自己不实现底层 kernel，所有重活转给 transformers / accelerate / peft / deepspeed / trl / bitsandbytes / flash-attn 这一长串依赖。这件事带来两个后果：
- 装好它 ≠ 装好它能调用的全部能力。某些场景（DeepSpeed、量化、FlashAttention、NPU）需要额外的
requirements/*.txt。 - 依赖版本很挑。
transformers升一个小版本，LLaMA-Factory 内部模板就可能要跟着改。强烈建议要么用官方 Docker、要么严格按pyproject.toml锁版本。
最低硬件门槛（按本基线 commit 的 README）：
| 训练方式 | 显存 | 适用模型 |
|---|---|---|
| LoRA SFT | 16 GB | 7B 模型 |
| QLoRA (4bit) SFT | 8 GB | 7B 模型 |
| QLoRA (4bit) SFT | 24 GB | 70B 模型 |
| 全参 SFT (bf16) | 60 GB | 7B 模型 |
| 全参 SFT (bf16) | 8×A100 | 70B 模型 |
2.2 三条安装路线
路线 A：官方 Docker（强烈推荐第一次用）
docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest这个镜像基于：
- Ubuntu 22.04 (x86_64)
- CUDA 12.4
- Python 3.11
- PyTorch 2.6.0
- Flash-attn 2.7.4
进容器后所有依赖都装好了，不用再 pip install，直接 llamafactory-cli train ...。NPU 用户用 hiyouga/llamafactory:latest-npu-a2 或 -a3。
路线 B：从源码 pip 安装
git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt # rouge / bleu 等评测指标可选附加依赖：
pip install -r requirements/deepspeed.txt # ZeRO 训练
pip install -r requirements/npu.txt # 昇腾 NPU完整列表见 requirements/ 目录。
路线 C：从本地已克隆 repo 装
本项目已经把 LLaMA-Factory 拉到 /Users/zjw/Documents/LLM/train/repos/llama-factory/（commit 01398eb18dd4）：
cd /Users/zjw/Documents/LLM/train/repos/llama-factory
pip install -e .
pip install -r requirements/metrics.txt这条路线的好处是：源码就在手边，遇到 bug 可以直接改源码 / 加 print / 单步调试。
2.3 平台差异速查
Windows 用户必看（来自 README "Windows 用户指南"）
- PyTorch 单独装：
pip uninstall torch torchvision torchaudio && pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126 - bitsandbytes 用预编译 whl：参见
jllllll/bitsandbytes-windows-webui。 Can't pickle local object报错 → YAML 里dataloader_num_workers: 0。- FlashAttention-2 需自行编译，见
lldacing/flash-attention-windows-wheel。
昇腾 NPU 用户
- Python ≥ 3.10；
pip install -r requirements/npu.txt；- 还要装 Ascend CANN Toolkit 与 Kernels；
- 推荐直接拉
latest-npu-a2或-npu-a3镜像。
苹果 / AMD GPU
LLaMA-Factory 没有官方支持。Apple Silicon 上能 import，但训练不能跑。
2.4 验证安装
装完后跑这两条命令，都不报错就说明环境就绪：
# 1. 看 CLI 是否可用
llamafactory-cli version
llamafactory-cli env
# 2. 用最小 config 试跑 1 个 step（不会真训完，只验证依赖能 import）
llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml \
max_steps=1 num_train_epochs=null save_steps=10000
提示
llamafactory-cli env 会打印 transformers / peft / trl / accelerate / bitsandbytes / flash-attn 等关键库版本，遇到任何 issue 都建议把这份输出贴上去。
2.5 第一次启动常见报错
按出现频率排序：
| # | 报错 | 解决思路 |
|---|---|---|
| 1 | ImportError: cannot import name 'xxx' from 'transformers' | transformers 版本和 LLaMA-Factory 不一致。pip install transformers==<pyproject.toml-pin>。 |
| 2 | bitsandbytes was compiled without GPU support | CUDA 版本 / 显卡架构不匹配。Linux 装 GPU 版 bitsandbytes>=0.43；Windows 走 jllllll 预编译 whl。 |
| 3 | flash-attn 编译失败 | 加 --no-build-isolation，否则会重新拉 PyTorch 编译，几乎必失败。 |
| 4 | 加载 HuggingFace 模型超时 | 国内用 ModelScope：YAML 里 model_name_or_path 改成 MS 仓库 ID；或 export USE_MODELSCOPE_HUB=1。 |
| 5 | CUDA out of memory 在 LoRA 一上来就炸 | 看是不是同机器还跑着别的进程；YAML 里降 per_device_train_batch_size、cutoff_len，开 gradient_checkpointing: true。 |
完整调试合集见第 11 章。
2.6 llamafactory-cli 全部子命令速查
装好后这条 CLI 共 9 个子命令（来源：src/llamafactory/launcher.py:21–35）。下表按用得最多的排列：
| 子命令 | 对应函数 / 文件 | 典型用法 |
|---|---|---|
train | train/tuner.py:run_exp() | 所有训练（SFT/DPO/PPO/RM/PT/KTO） |
chat | chat/chat_model.py:run_chat() | 交互式聊天，支持 HF / vLLM / SGLang 后端 |
api | api/app.py:run_api() | OpenAI 兼容 HTTP server（默认 :8000） |
export | train/tuner.py:export_model() | merge LoRA、量化导出、Ollama 包 |
webui | webui/interface.py:run_web_ui() | LLaMA Board 全功能 UI（默认 :7860） |
webchat | webui/interface.py:run_web_demo() | 只有 chat 的轻量 UI |
eval | eval/evaluator.py | MMLU / C-Eval / CMMLU 评测 |
env | launcher.py | 打印 transformers/peft/trl/bnb 等版本 |
version | 同上 | banner + 版本号 |
额外可用别名：lmf = llamafactory-cli。
2.7 关键环境变量
这些 env 经常在不知不觉中影响行为，第一次跑训练前扫一眼：
| 变量 | 用途 | 典型值 |
|---|---|---|
FORCE_TORCHRUN | 强制走 torchrun 启动（多机 / DeepSpeed 单卡） | 1 |
USE_V1 | 切到 src/llamafactory/v1/ 新架构（实验） | 1 时启用 |
USE_MODELSCOPE_HUB | 从魔搭下载模型 / 数据，国内首选 | 1 |
USE_OPENMIND_HUB | 从 Modelers Hub 下载 | 1 |
API_HOST / API_PORT / API_MODEL_NAME / API_KEY | api 子命令的 host/port/模型名/鉴权 | — |
NNODES / NODE_RANK / MASTER_ADDR / MASTER_PORT | 多机训练的 torch.distributed 参数 | — |
RDZV_ID / MIN_NNODES / MAX_NNODES / MAX_RESTARTS | torchrun 弹性训练 | — |
OPTIM_TORCH | 设 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True + 关掉 NCCL stream 记录 | 1 |
DISABLE_VERSION_CHECK | 跳过启动期版本一致性检查 | — |