基于 Docker 的 LLaMA-Factory 全流程部署指南

LLaMA-Factory 是一个强大且高效的大语言模型（LLM）微调框架，支持多种微调方法（如 LoRA、QLoRA）、完整的练习流程（SFT、RM、PPO、DPO）以及丰富的模型和数据集支持，能帮助你在消费级显卡上高效微调大型语言模型。
这份指南将带你从零开始，完成基于 Docker 的环境搭建、数据预备、模型练习、推理测试到模型导出的全过程。
🐳 基于 Docker 的 LLaMA-Factory 全流程部署指南
1. 环境预备与前置检查
在开始部署之前，需要确保你的体系环境满足基本要求，并精确安装所需的软件依赖。
1.1 硬件需求建议
以下是对硬件设置的基本建议，现实需求会根据模型规模和数据集大小有所变化：

资源类型	最低设置要求	推荐设置	大型模型练习建议
CPU	4 核心	8 核心或以上	16 核心或以上
内存	16 GB	32 GB	64 GB 或以上
GPU	NVIDIA GPU (8GB VRAM)	NVIDIA RTX 3090/4090 (24GB VRAM)	NVIDIA A100 (80GB VRAM)
存储空间	50 GB (用于体系和依赖)	100 GB (含基础模型)	500 GB 或以上 (模型缓存)

1.2 软件依赖安装

• 安装 Docker：访问 Docker 官方网站 获取适合你操作体系（Windows/Linux/macOS）的安装指南。
  
  
  
  • Windows 用户注意：建议安装时更改默认安装路径到非体系盘（如 D 盘），避免后期占用过多 C 盘空间。可以通过命令行指定安装路径：
    
  
  

powershell
"Docker Desktop Installer.exe" install --installation-dir=D:\Docker

• 安装完成后，启动 Docker 服务。
  


• 安装 NVIDIA Docker 支持（仅限 NVIDIA GPU 用户）：
  
  
  
  • 确保已安装最新的 NVIDIA 显卡驱动。
    
  • 参照 NVIDIA Container Toolkit 安装指南 安装和设置 NVIDIA Container Toolkit，以便 Docker 容器能够访问 GPU。
    
  • 安装后，在终端执行 docker run --rm --gpus all nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi 测试 GPU 是否可在 Docker 中正知识别。如果乐成，你将看到显卡信息输出。
    
  
  
• （可选）安装 Docker Compose：新版本的 Docker Desktop 通常已包含 Compose。如果没有，请参照官方文档安装。
  

2. LLaMA-Factory 项目获取与 Docker 环境设置
2.1 获取 LLaMA-Factory 源代码
使用 git 命令将 LLaMA-Factory 项目克隆到本地：
bash
# 克隆项目代码（使用 --depth 1 只克隆最新提交，节省时间和空间）
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
# 进入项目目录
cd LLaMA-Factory
2.2 Docker 部署方式选择
LLaMA-Factory 的 Docker 目录 (docker/) 下通常提供了针对不同硬件环境的设置1：

• docker-cuda/: 实用于 NVIDIA CUDA 用户（最常见）。
  
• docker-npu/: 实用于华为 Ascend NPU 用户。
  
• docker-rocm/: 实用于 AMD ROCm 用户。
  

本指南以最常用的 CUDA 为例。
2.2.1 使用 Docker Compose（推荐）
Docker Compose 能简化容器的构建和运行过程。

• 进入 CUDA 目录：
  

bash
cd docker/docker-cuda/

• 启动容器（背景运行）：
  

bash
docker compose up -d
此命令会读取同目录下的 docker-compose.yml 文件，构建或拉取镜像，并在背景启动容器。

• 进入容器内部：
  

bash
docker compose exec llamafactory bash
# 或者使用
# docker exec -it llamafactory /bin/bash
执行后，你将进入一个名为 llamafactory 的容器内部，并可以开始在容器内操作。
2.2.2 手动构建 Docker 镜像（可选）
如果你需要更多自定义设置，可以手动构建镜像。

• 编写 Dockerfile：你可以参考或修改 docker/docker-cuda/Dockerfile。
  
• 构建镜像：
  

bash
# 在 Dockerfile 所在目录执行
docker build -t llamafactory-cuda .

• 运行容器并进入：
  

bash
docker run -it --gpus all -v /path/to/your/data:/mnt/data llamafactory-cuda bash

• --gpus all: 将主机全部 GPU 分配给容器。
  
• -v /path/to/your/data:/mnt/data: 将主机上的数据目录挂载到容器内的 /mnt/data，方便容器内访问你的数据集和模型。
  

2.3 解决常见 Docker 部署问题

• 镜像拉取或构建错误：如果遇到 ERROR load metadata for docker.io/hiyouga/pytorch:... 类似的错误，可以尝试手动拉取基础镜像：
  

bash
docker pull hiyouga/pytorch:th2.6.0-cu124-flashattn2.7.4-cxx11abi0-devel
然后再重新执行 docker compose up -d。

• 内存分配错误 (cannot allocate memory in static TLS block)：如果在容器内运行某些命令时出现此错误，可以尝试在容器内的 ~/.bashrc 文件末尾添加以下环境变量并 source ~/.bashrc：
  

bash
export LD_PRELOAD=/usr/local/python3.10.13/lib/python3.10/site-packages/sklearn/utils/../../scikit_learn.libs/libgomp-d22c30c5.so.1.0.0

• 共享内存不足：在运行练习或 WebUI 时，如果提示共享内存不足，可以在 docker run 命令中添加 --shm-size 参数，例如 --shm-size 16g 或 --shm-size 32g。
  

3. 数据预备与格式规范
模型微调的结果很大水平上依赖于数据质量。LLaMA-Factory 重要支持两种数据格式5。
3.1 数据格式详解
3.1.1 Alpaca 格式（单轮对话）
实用于指令微调（Instruction Tuning），结构简朴，每条数据包含一个指令-输入-输出的三元组5。

• 示例 (JSON Line格式，.jsonl)：
  

json

{"instruction": "写一个Python函数，实现斐波那契数列。", "input": "", "output": "def fibonacci(n):\n if n

继续阅读请点击广告