基于 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 [archamd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable# 安装 Dockersudo apt install -y docker-ce# 启动并设置开机自启sudo systemctl start dockersudo systemctl enable docker# 将当前用户加入 docker 组避免每次使用 sudosudo usermod -aG docker $USER# 重新登录后生效### 3.2 安装 NVIDIA Container ToolkitGPU 支持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 datasets2.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 --frombuilder /opt/conda /opt/condaCOPY --frombuilder /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.8services: 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 1docker run --gpus device0,1 ...# 限制显存使用通过 NVIDIA_MEM_MAX 环境变量docker run -e NVIDIA_MEM_MAX8192M ...# 监控容器 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 状态。