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

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

1. 引言：为什么选择 Docker + LLaMA-Factory？在大语言模型（LLM）快速演进的今天，LLaMA-Factory 作为一款高效、易用的微调框架，允许开发者基于 LLaMA、Mistral、Qwen 等主流模型进行参数高效微调（PEFT）。然而，环境配置复杂、依赖冲突、GPU 驱动不兼容等问题常常成为部署路上的"拦路虎"。Docker 容器技术通过将应用及其依赖打包为一个标准化的镜像，解决了"在我机器上能跑"的尴尬。本指南将带你从零开始，循序渐进地掌握基于 Docker 的 LLaMA-Factory 全流程部署，从基础概念到高级用法，每一步都配有可运行的代码示例。---## 2. 基础概念：Docker 与 LLaMA-Factory 核心原理### 2.1 Docker 核心组件- 镜像（Image） ：一个只读的模板，包含操作系统、依赖库、代码等。- 容器（Container） ：镜像的运行实例，可读写、可删除。- Dockerfile ：构建镜像的自动化脚本。- 卷（Volume） ：持久化数据，避免容器删除后丢失模型文件。### 2.2 LLaMA-Factory 基本工作流LLaMA-Factory 的核心是将预训练模型加载到内存，通过 LoRA、QLoRA 等技术在特定数据集上微调。它依赖 PyTorch、Transformers 等库，并需要 CUDA 驱动支持 GPU 加速。---## 3. 环境准备：安装 Docker 与 NVIDIA Container Toolkit### 3.1 安装 Docker在 Ubuntu 系统上：bash# 更新包索引sudo apt update# 安装 Docker 依赖sudo apt install -y apt-transport-https ca-certificates curl software-properties-common# 添加 Docker 官方 GPG 密钥curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -# 添加稳定版仓库sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"# 安装 Dockersudo apt install -y docker-ce# 启动并设置开机自启sudo systemctl start dockersudo systemctl enable docker# 将当前用户加入 docker 组（避免每次使用 sudo）sudo usermod -aG docker $USER# 重新登录后生效### 3.2 安装 NVIDIA Container Toolkit（GPU 支持）bash# 添加 NVIDIA 仓库distribution=$(. /etc/os-release;echo $ID$VERSION_ID)curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list# 安装 nvidia-docker2sudo apt update && sudo apt install -y nvidia-docker2# 重启 Docker 服务sudo systemctl restart docker# 验证 GPU 是否可用docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi输出应显示 GPU 信息，如 "Tesla T4"、"RTX 3090" 等。---## 4. 初级部署：使用官方镜像快速启动容器### 4.1 拉取 LLaMA-Factory 官方镜像LLaMA-Factory 提供了预构建的 Docker 镜像，支持 CUDA 11.8 和 PyTorch 2.x。bash# 拉取最新版镜像docker pull hiyouga/llama-factory:latest### 4.2 运行交互式容器使用 --gpus all 启用 GPU，并挂载本地目录存储模型和数据集：bashdocker run -it --rm \ --gpus all \ -v /path/to/your/models:/workspace/models \ -v /path/to/your/data:/workspace/data \ -p 7860:7860 \ hiyouga/llama-factory:latest \ bash- -it：交互模式- --rm：容器退出时自动删除（适合测试）- -v：挂载卷，将本地模型文件夹映射到容器内- -p 7860:7860：映射 Gradio Web 界面端口### 4.3 第一个微调示例：使用 QLoRA 微调 Qwen2.5-0.5B以下代码在容器内执行，展示了从加载模型到启动训练的完整流程。python# train_qwen.py# 功能：使用 QLoRA 方法微调 Qwen2.5-0.5B 模型# 依赖：已安装 LLaMA-Factory 环境（容器内已预装）import osfrom llama_factory.train import train# 定义训练参数training_args = { "model_name_or_path": "/workspace/models/Qwen2.5-0.5B", # 模型路径 "dataset_dir": "/workspace/data", # 数据集目录 "dataset": "alpaca_zh_demo", # 数据集名称 "output_dir": "/workspace/output/qwen_lora", # 输出目录 "per_device_train_batch_size": 2, # 批次大小 "num_train_epochs": 3, # 训练轮数 "learning_rate": 1e-4, # 学习率 "finetuning_type": "lora", # 微调类型 "lora_rank": 8, # LoRA 秩 "lora_target": "q_proj,v_proj", # LoRA 目标模块 "quantization_bit": 4, # 4-bit 量化 "fp16": True, # 混合精度训练 "logging_steps": 10, # 日志间隔 "save_steps": 100, # 保存间隔 "overwrite_output_dir": True, # 覆盖输出目录}# 执行训练train(training_args)print("微调完成！模型保存在 /workspace/output/qwen_lora")在容器内执行：bashpython train_qwen.py---## 5. 中级实践：自定义 Dockerfile 构建专属镜像### 5.1 为什么需要自定义？官方镜像可能不包含你需要的特定数据集、额外依赖（如 transformers 最新版）或自定义脚本。通过 Dockerfile，我们可以精确控制环境。### 5.2 编写 Dockerfile创建一个 Dockerfile 文件，基于官方镜像添加自定义内容：dockerfile# Dockerfile# 作用：构建包含自定义数据集和脚本的 LLaMA-Factory 镜像# 基础镜像FROM hiyouga/llama-factory:latest# 设置工作目录WORKDIR /workspace# 复制自定义数据集（假设在本地 data 文件夹）COPY ./my_dataset /workspace/data/my_dataset# 复制自定义训练脚本COPY ./train_custom.py /workspace/train_custom.py# 安装额外依赖（如需安装特定版本的库）RUN pip install --no-cache-dir datasets==2.18.0# 暴露 Gradio Web 端口EXPOSE 7860# 默认命令：启动交互式 shellCMD ["bash"]### 5.3 构建和运行自定义镜像bash# 构建镜像，命名为 my-llama-factory:v1docker build -t my-llama-factory:v1 .# 运行自定义镜像docker run -it --rm --gpus all my-llama-factory:v1 bash### 5.4 高级示例：使用多阶段构建减小镜像体积对于生产环境，多阶段构建可以显著缩小镜像大小：dockerfile# 第一阶段：构建阶段FROM hiyouga/llama-factory:latest AS builder# 安装编译工具（如需编译扩展）RUN apt-get update && apt-get install -y build-essential# 第二阶段：运行阶段FROM nvidia/cuda:11.8.0-runtime-ubuntu22.04# 从 builder 阶段复制所需文件COPY --from=builder /opt/conda /opt/condaCOPY --from=builder /workspace /workspace# 设置环境变量ENV PATH /opt/conda/bin:$PATHENV CUDA_HOME /usr/local/cuda# 暴露端口EXPOSE 7860CMD ["bash"]---## 6. 高级用法：生产环境部署与优化### 6.1 使用 Docker Compose 编排多服务当需要同时运行 Web 界面、API 服务和定时任务时，Docker Compose 可以简化管理：yaml# docker-compose.yml# 功能：编排 LLaMA-Factory Web 界面和 API 服务version: '3.8'services: web-ui: image: hiyouga/llama-factory:latest container_name: llama-web deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] ports: - "7860:7860" volumes: - ./models:/workspace/models - ./data:/workspace/data command: ["python", "-m", "llama_factory.webui"] restart: unless-stopped api-service: image: hiyouga/llama-factory:latest container_name: llama-api deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] ports: - "8000:8000" volumes: - ./models:/workspace/models command: ["python", "-m", "llama_factory.api", "--port", "8000"] restart: unless-stopped启动服务：bashdocker-compose up -d### 6.2 GPU 资源分配与监控在生产环境中，需要精细控制 GPU 使用：bash# 限制使用特定 GPU（如 GPU 0 和 GPU 1）docker run --gpus '"device=0,1"' ...# 限制显存使用（通过 NVIDIA_MEM_MAX 环境变量）docker run -e NVIDIA_MEM_MAX=8192M ...# 监控容器 GPU 使用docker stats --no-streamnvidia-smi### 6.3 数据持久化与模型备份使用 Docker 卷（Volume）而非绑定挂载，便于备份和迁移：bash# 创建命名卷docker volume create llama-modelsdocker volume create llama-data# 使用命名卷运行容器docker run -it --rm \ --gpus all \ -v llama-models:/workspace/models \ -v llama-data:/workspace/data \ hiyouga/llama-factory:latest bash---## 7. 总结本指南从 Docker 和 LLaMA-Factory 的基础概念出发，逐步深入到生产级部署。我们学会了：1. 环境搭建 ：安装 Docker 和 NVIDIA Container Toolkit，确保 GPU 可用。2. 快速上手 ：使用官方镜像运行交互式容器，并执行第一个微调脚本。3. 自定义构建 ：通过 Dockerfile 精确控制环境，实现多阶段构建优化。4. 生产实践 ：使用 Docker Compose 编排多服务，管理 GPU 资源和数据持久化。Docker 容器化不仅解决了环境一致性问题，还让 LLaMA-Factory 的部署变得可重复、可扩展。下一次当有人问"怎么部署 LLM 微调环境"时，你可以自信地回答："写个 Dockerfile，跑个容器，搞定！"> 提示：实际部署时请根据模型大小调整显存和内存配置，建议使用 nvidia-smi 实时监控 GPU 状态。