LlamaFactory

环境要求

• Python 3.11 环境（官方 Docker 镜像内置 PyTorch 2.6.0；Ascend NPU 需 Python 3.12）
• NVIDIA GPU 及可用 CUDA（Docker 方式以 --gpus=all 调用）
• 已安装 Git，用于克隆源码
• Windows 需手动安装 GPU 版 PyTorch；使用 uv 方式需先安装 uv

安装与启动步骤

1. 1克隆仓库

   下载 LlamaFactory 源码并进入目录，--depth 1 只拉取最新一次提交。

   git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
   cd LlamaFactory

   复制

2. 2装 Windows PyTorch

   仅 Windows 用户需手动安装 GPU 版 PyTorch，装完确认 CUDA 可用再继续。

   pip uninstall torch torchvision torchaudio
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
   python -c "import torch; print(torch.cuda.is_available())"

   复制

3. 3安装项目依赖

   在源码目录内以可编辑模式安装本体，并补充 metrics 指标依赖。

   pip install -e .
   pip install -r requirements/metrics.txt

   复制

4. 4安装可选依赖

   需要 DeepSpeed 等可选能力时，一次性安装 metrics 与 deepspeed 依赖。

   pip install -e . && pip install -r requirements/metrics.txt -r requirements/deepspeed.txt

   复制

5. 5Docker 方式运行

   不想配环境可直接拉官方镜像进入容器，需宿主机支持 GPU 容器运行时。

   docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest

   复制

6. 6启动 Web UI

   用 uv 创建隔离环境并启动 Gradio 网页界面，实现零代码微调。

   uv run llamafactory-cli webui

   复制

7. 7运行 LoRA 微调

   以 Qwen3-4B-Instruct 为例执行 LoRA 微调，配置路径相对仓库根目录。

   llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

   复制

8. 8推理与合并模型

   先加载微调结果对话验证效果，再导出合并后的完整模型权重。

   llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
   llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

   复制

关键配置

如何确认成功

执行 llamafactory-cli help 能显示帮助信息；Windows 下 python -c "import torch; print(torch.cuda.is_available())" 输出 True。

常见问题

注意事项

• 安装是必须步骤，README 明确标注 Installation is mandatory。
• 特定功能的额外依赖放在 examples/requirements/ 目录下，按需安装。
• Windows 安装 bitsandbytes 要注意 CUDA Toolkit 版本，RTX 50 系列需 CUDA 12.8–12.9 的构建。
• 除 README 列出的链接外，其他网站均为未授权第三方网站，请谨慎使用。