LLaMA-Factory教程：使用Docker快速部署微调环境

在AI大模型应用开发中，环境配置往往是开发者面临的第一道障碍。不同操作系统、依赖版本冲突、硬件加速配置等问题常常耗费大量时间。LLaMA-Factory提供了完善的Docker部署方案，让你无需复杂配置即可快速搭建专业的大模型微调环境。本文将以NVIDIA GPU环境为例，带你一步到位完成Docker化部署，轻松开启大模型微调之旅。

环境准备

系统要求

LLaMA-Factory的Docker部署方案目前仅支持Linux操作系统，需确保你的系统满足以下条件：

  • 已安装Docker引擎（推荐20.10以上版本）
  • 已安装Docker Compose工具（用于简化容器管理）
  • NVIDIA显卡驱动已正确安装（建议525.60.13以上版本）
  • 已安装NVIDIA Container Toolkit（实现Docker容器GPU访问）

安装依赖组件

首先通过以下命令安装Docker和Docker Compose：

# Ubuntu/Debian系统
sudo apt-get update
sudo apt-get install -y docker.io docker-compose

接着安装NVIDIA Container Toolkit以启用GPU支持：

# 添加NVIDIA Docker仓库
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-container-toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 重启Docker服务
sudo systemctl restart docker

验证GPU访问能力

安装完成后，运行以下命令验证Docker是否能正常访问GPU：

sudo docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

若成功显示GPU信息（类似下图），则说明环境准备就绪：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05             Driver Version: 535.104.05   CUDA Version: 12.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:01:00.0 Off |                  N/A |
| 30%   35C    P8    11W / 320W |      0MiB / 16384MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

快速部署步骤

获取项目代码

首先克隆LLaMA-Factory项目仓库：

git clone https://gitcode.com/GitHub_Trending/ll/LLaMA-Factory
cd LLaMA-Factory

使用Docker Compose部署（推荐）

LLaMA-Factory提供了便捷的Docker Compose配置文件，位于docker/docker-cuda/docker-compose.yml，通过以下命令即可一键启动：

cd docker/docker-cuda/
docker compose up -d
docker compose exec llamafactory bash

上述命令会自动完成：

  1. 构建包含CUDA支持的Docker镜像
  2. 创建并启动容器（后台运行模式）
  3. 进入容器内部命令行环境

手动构建与运行（高级选项）

如果需要自定义构建参数，可以使用docker build命令手动构建镜像：

# 构建Docker镜像
docker build -f ./docker/docker-cuda/Dockerfile \
    --build-arg PIP_INDEX=https://pypi.org/simple \
    --build-arg EXTRAS=metrics \
    -t llamafactory:latest .

# 运行容器
docker run -dit --ipc=host --gpus=all \
    -p 7860:7860 \
    -p 8000:8000 \
    --name llamafactory \
    llamafactory:latest

# 进入容器
docker exec -it llamafactory bash

其中关键参数说明：

  • --gpus=all：允许容器使用所有GPU设备
  • -p 7860:7860：映射WebUI端口
  • -p 8000:8000：映射API服务端口
  • --ipc=host：使用主机的IPC命名空间，提升性能

验证部署结果

容器启动后，可以通过以下方式验证环境是否正常工作：

检查WebUI访问

打开浏览器访问 http://localhost:7860，如果看到LLaMA-Factory的Web界面（类似下图），说明部署成功：

LLaMA-Factory WebUI

运行测试微调

在容器内部，执行以下命令运行一个简单的LoRA微调测试：

python src/train.py \
    --model_name_or_path meta-llama/Llama-2-7b-hf \
    --do_train \
    --dataset alpaca_zh_demo \
    --finetuning_type lora \
    --output_dir ./saved_models/llama2-7b-lora \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 4 \
    --learning_rate 2e-4 \
    --num_train_epochs 3 \
    --logging_steps 10 \
    --save_steps 100 \
    --fp16

如果训练正常开始并显示类似以下输出，则表明微调环境已完全就绪：

{'loss': 1.8243, 'learning_rate': 0.0002, 'epoch': 0.15}
{'loss': 1.6521, 'learning_rate': 0.000199943661971831, 'epoch': 0.3}
{'loss': 1.5874, 'learning_rate': 0.00019977464788732395, 'epoch': 0.45}

常见问题解决

GPU未被检测到

如果容器内无法识别GPU，请按以下步骤排查：

  1. 确认宿主机nvidia-smi命令能正常显示GPU
  2. 检查nvidia-container-toolkit是否正确安装： 
    dpkg -l | grep nvidia-container-toolkit
  3. 重启Docker服务：sudo systemctl restart docker
  4. 验证Docker GPU支持：docker run --rm --gpus all ubuntu nvidia-smi

权限问题

若执行Docker命令时出现"Permission denied"错误，将当前用户添加到docker用户组：

sudo usermod -aG docker $USER
# 注销并重新登录使更改生效

端口冲突

如果7860或8000端口已被占用，可以修改docker-compose.yml中的端口映射配置，例如：

ports:
  - "7861:7860"  # 将容器7860端口映射到主机7861端口
  - "8001:8000"  # 将容器8000端口映射到主机8001端口

总结与后续步骤

通过Docker部署LLaMA-Factory，你已成功搭建起专业的大模型微调环境。接下来可以：

  1. 探索examples/train_lora/目录下的微调配置示例
  2. 查看README_zh.md了解更多微调方法和参数说明
  3. 尝试使用WebUI或API接口进行模型微调与推理

LLaMA-Factory的Docker方案不仅解决了环境依赖问题，还保证了不同机器上的一致性体验，让你可以专注于模型调优而非环境配置。立即开始你的大模型微调之旅吧！

提示：定期执行git pull和docker compose up -d --build可以获取最新版本的LLaMA-Factory和Docker镜像。收藏本文档，随时查阅部署细节，祝你在大模型微调之路上取得成功！

Logo
智源数据社区

更多推荐

AI大模型微调~笔记本配置

最后提醒：如果只是学习微调小模型（如1.7B），RTX 4060/4070也够用；但若想长期深入，建议尽量投资。注：品牌也可选戴尔Alienware、惠普暗影精灵等，重点看GPU和散热。

avatar 智源数据社区

bert4keras预训练模型加载指南：支持BERT、RoBERTa、ALBERT

🤖 bert4keras是一个轻量级的Keras版Transformer模型库，让你能够快速加载BERT、RoBERTa、ALBERT等主流预训练模型，为自然语言处理任务提供强大支持！## 📋 项目简介bert4keras是一个专为人类设计的keras版transformer实现，核心目标是提供清晰、轻量级的代码，让你能够轻松加载和使用各种预训练模型。无论你是NLP新手还是资深开发者，

avatar 智源数据社区

零代码微调大模型：3步掌握LLaMA Factory核心功能

想要轻松微调上百种大型语言模型却担心编程门槛？LLaMA Factory正是为您量身打造的解决方案！作为业界领先的无代码大模型微调框架，LLaMA Factory让技术新手也能快速上手，在图形化界面中完成复杂的模型定制任务。无论您是希望构建个性化AI助手，还是需要针对特定领域优化模型性能，这个工具都能帮您实现从入门到精通的飞跃。## 🚀 快速入门：环境搭建与项目部署### 准备工作检查清

avatar 智源数据社区