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

AI大模型2025-08-20 17:39

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 软件依赖安装
  1. 安装 Docker：访问 Docker 官方网站 获取适合你操作系统（Windows/Linux/macOS）的安装指南。
  • Windows 用户注意：建议安装时更改默认安装路径到非系统盘（如 D 盘），避免后期占用过多 C 盘空间。可以通过命令行指定安装路径：
ini 复制代码 
powershell

"Docker Desktop Installer.exe" install --installation-dir=D:\Docker
  • 安装完成后，启动 Docker 服务。
  1. 安装 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 中正常识别。如果成功，你将看到显卡信息输出。
  1. （可选）安装 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 能简化容器的构建和运行过程。

  1. 进入 CUDA 目录：
bash 复制代码 
cd docker/docker-cuda/

  1. 启动容器（后台运行）：

    docker compose up -d

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

  1. 进入容器内部：
shell 复制代码 
docker compose exec llamafactory bash
# 或者使用
# docker exec -it llamafactory /bin/bash

执行后，你将进入一个名为 llamafactory 的容器内部，并可以开始在容器内操作。

2.2.2 手动构建 Docker 镜像（可选）

如果你需要更多自定义配置，可以手动构建镜像。

  1. 编写 Dockerfile：你可以参考或修改 docker/docker-cuda/Dockerfile。
  2. 构建镜像：
bash 复制代码 
# 在 Dockerfile 所在目录执行
docker build -t llamafactory-cuda .
  1. 运行容器并进入：
css 复制代码 
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)：
swift 复制代码 
{"instruction": "写一个Python函数，实现斐波那契数列。", "input": "", "output": "def fibonacci(n):\n if n <= 1:\n return n\n return fibonacci(n-1) + fibonacci(n-2)"}
{"instruction": "将以下英文翻译成中文", "input": "Hello, world!", "output": "你好，世界！"}
  • 字段说明：
  • instruction: 希望模型执行的任务描述。
  • input (可选): 任务所需的额外上下文或输入。
  • output: 期望模型给出的回答。
3.1.2 ShareGPT 格式（多轮对话）

模拟真实对话场景，适合训练聊天助手，结构为一个包含多轮对话的数组。

  • 示例 (JSON 格式，.json)：
swift 复制代码 
{
  "conversations": [
    {
      "role": "user",
      "content": "你好，可以给我写一段Python代码打印1到10吗？"
    },
    {
      "role": "assistant",
      "content": "当然可以：\n\n```python\nfor i in range(1, 11):\n print(i)\n```"
    },
    {
      "role": "user",
      "content": "那你能把它改成倒序输出吗？"
    },
    {
      "role": "assistant",
      "content": "当然，这是倒序输出的版本：\n\n```python\nfor i in range(10, 0, -1):\n print(i)\n```"
    }
  ]
}
  • 字段说明：
  • conversations: 一个字典列表。
  • role: 对话角色，通常是 "user" 或 "assistant"。
  • content: 该角色的对话内容。
3.2 挂载数据并添加到项目
  1. 挂载数据卷：在启动 Docker 容器时，使用 -v 参数将存放数据集的本地目录挂载到容器内。
javascript 复制代码 
# 在 docker run 命令中添加，例如
docker run -it --gpus all -v /path/on/host/data:/app/data llamafactory-cuda bash
# 或者在 docker-compose.yml 文件中配置 volumes
# volumes:
#   - /path/on/host/data:/app/data
#   - /path/on/host/output:/app/output
#   - /path/on/host/hf_cache:/root/.cache/huggingface
  1. 添加数据集信息：
  • 将你的数据文件（如 my_data.json）放入已挂载的容器数据目录（如 /app/data）。
  • 关键步骤：你还需要在容器内 LLaMA-Factory 项目的 data 目录下的 dataset_info.json 配置文件中，为你新添加的数据集添加一条记录，LLaMA-Factory 才能识别它。
  • 例如，添加：
json 复制代码 
"my_custom_dataset": {
  "file_name": "my_data.json",
  "format": "sharegpt" // 或者 "alpaca"
}

4. 模型训练与微调

进入 Docker 容器后，你就可以开始使用 LLaMA-Factory 进行模型微调了。

4.1 训练方式
4.1.1 使用 Web UI（可视化界面）

LLaMA-Factory 提供了友好的 Web 界面，方便进行参数配置和训练监控。

  1. 启动 Web UI：
bash 复制代码 
# 在容器内执行
llamafactory-cli webui
# 或者设置共享和CUDA设备
# CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 llamafactory-cli webui
  1. 根据提示，在物理机的浏览器中打开 http://localhost:7860（如果端口映射正确）。
  2. 在 Web 界面中：
  • 选择 Train 标签页。
  • 在 Model Name 中填写或选择模型路径（如 meta-llama/Meta-Llama-3-8B 或 /app/models/llama-3-8b）。
  • 在 Dataset 中选择你在 dataset_info.json 中配置的数据集名称。
  • 选择 Fine-tuning Method (如 LoRA, QLoRA)。
  • 调整其他超参数（学习率、批次大小、训练轮数等）。
  • 点击 Start Training 开始训练。
4.1.2 使用命令行（CLI）

如果你更喜欢命令行操作，或者需要进行自动化脚本处理，CLI 方式更合适。

  1. 准备配置文件：参考项目 examples 目录下的配置文件（如 examples/train_lora/llama3_lora_sft.yaml）。
  2. 修改配置文件：指定模型路径、数据集名称、训练参数等。
  3. 启动训练：
ini 复制代码 
# 在容器内执行
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
  • CUDA_VISIBLE_DEVICES=0 指定使用第一块 GPU。
4.2 训练注意事项
  • 显存管理：根据你的 GPU 显存调整 per_device_train_batch_size 和 gradient_accumulation_steps。如果遇到 OOM（内存溢出）错误，请减小批次大小或使用 QLoRA 等更节省显存的方法。
  • 性能优化：可以尝试启用 DeepSpeed（配置 deepspeed 参数）或 Unsloth（添加 --use_unsloth True 参数）来加速训练并减少显存消耗。注意，Unsloth 可能需要额外的安装步骤。
  • 模型缓存：建议将 Hugging Face 模型缓存目录 (~/.cache/huggingface/) 通过 -v 参数挂载到主机，避免每次重启容器后重复下载模型。

5. 模型推理、测试与导出

训练完成后，你可以对微调后的模型进行测试和导出。

5.1 使用 Web UI 进行聊天测试
  1. 启动 Web UI（同上）：llamafactory-cli webui。
  2. 在 Chat 标签页中：
  • 选择或输入模型路径。
  • 如果使用 LoRA 等适配器微调，需要在 Adapter 选项中选择对应的适配器检查点路径（通常在 output 目录下）。
  • 在下方输入框与模型进行对话，测试微调效果。
5.2 使用命令行进行推理
ini 复制代码 
# 在容器内执行
CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat examples/inference/llama3_lora_sft.yaml

你需要准备并修改对应的推理配置文件，指定模型和适配器路径。

5.3 模型导出与部署
5.3.1 合并 LoRA 适配器（如果使用了 LoRA）

如果你希望将微调得到的 LoRA 权重合并到基础模型中，得到一个完整的、可独立部署的模型，可以执行：

bash 复制代码 
# 在容器内执行
CUDA_VISIBLE_DEVICES=0 llamafactory-cli export examples/merge_lora/llama3_lora_sft.yaml

合并后的模型将保存在配置文件中指定的 output_dir 目录。

5.3.2 转换为 GGUF 格式（用于 Ollama 等框架）

合并后的模型可以转换为 GGUF 格式，以便在 Ollama 或其他支持该格式的推理引擎中使用7。

  1. 获取转换工具：
bash 复制代码 
git clone https://github.com/ggerganov/llama.cpp.git
pip install -r llama.cpp/requirements.txt
  1. 执行转换：
css 复制代码 
python llama.cpp/convert-hf-to-gguf.py /path/to/your/merged_model --outfile my-model.fp16.gguf --outtype f16
  1. 在 Ollama 中使用：
  • 创建一个 Modelfile：
yaml 复制代码 
text

FROM ./my-model.fp16.gguf

# 添加适当的模板，例如对于 Llama 3：

TEMPLATE "{{ if .System }}<|start_header_id|>system<|end_header_id|>\n\n{{ .System }}<|eot_id|>{{ end }}{{ if .Prompt }}<|start_header_id|>user<|end_header_id|>\n\n{{ .Prompt }}<|eot_id|>{{ end }}<|start_header_id|>assistant<|end_header_id|>\n\n{{ .Response }}<|eot_id|>"
  • 创建并运行模型：
perl 复制代码 
ollama create my-model -f Modelfile
ollama run my-model

6. 进阶配置与优化

6.1 多卡分布式训练

对于更大的模型或更快的训练速度，可以使用多 GPU 进行分布式训练。

  • 使用 accelerate 配置：LLaMA-Factory 集成了 Hugging Face Accelerate 库。你可能需要配置 /root/.cache/huggingface/accelerate/default_config.yaml 文件来设置分布式训练参数（如 deepspeed_config）。
  • 使用 Docker Compose 扩展：确保 Docker Compose 配置能够访问所有 GPU (docker compose.yml 中配置 deploy 资源或使用 --gpus all)。
6.2 自定义 Docker 镜像

如果你有特殊需求（如特定版本的库、额外工具），可以基于提供的 Dockerfile 进行自定义构建。

csharp 复制代码 
# 示例：基于官方CUDA镜像构建，安装中文依赖和常用工具
FROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y wget git vim unzip fonts-wqy-microhei
# ... 其余步骤参考 LLaMA-Factory 的 Dockerfile 或上文手动构建部分

构建自定义镜像：docker build -t my-llamafactory:latest .

7. 故障排除与常见问题

问题现象 可能原因及解决方案
Docker 构建时无法下载依赖或镜像 更换国内镜像源（如清华大学源）。在 Dockerfile 中使用 pip install -i pypi.tuna.tsinghua.edu.cn/simple some-package。检查网络连接。
训练时 GPU 显存不足 (OOM) 减小 per_device_train_batch_size。增加 gradient_accumulation_steps 补偿。尝试使用 --fp16 或 --bf16。使用 QLoRA 而非全量微调。使用梯度检查点 (gradient checkpointing)。
训练速度很慢 启用 DeepSpeed Stage 2 或 33。尝试使用 Unsloth (如果支持)6。检查 CPU 内存是否不足导致频繁交换。检查 Docker 的共享内存 (--shm-size) 是否设置过小。
Web UI 无法访问或报错 检查 Docker 容器的端口映射是否正确（主机端口:容器端口，容器内默认是7860）。检查防火墙设置。
无法识别自定义数据集 检查数据格式是否正确（JSON/JSONL）。确认是否在 data/dataset_info.json 中添加了数据集信息5。检查文件路径和挂载点是否正确。
cannot allocate memory in static TLS block 在容器内的 ~/.bashrc 中添加 export LD_PRELOAD=... 并 source ~/.bashrc4。

希望这份详细的指南能帮助你顺利完成 LLaMA-Factory 的 Docker 化部署和模型微调工作。如果在实际操作中遇到更多问题，查阅项目的 GitHub Issues 和官方文档通常能找到解决方案。

8. 学习资源推荐

如果你想更深入地学习大模型，以下是一些非常有价值的学习资源，这些资源将帮助你从不同角度学习大模型，提升你的实践能力。

Github

相关推荐
AI大模型3 小时前
强推！大模型学习书籍合集推荐 | （含PDF地址）
程序员·llm·agent
tb_first3 小时前
k8sday11服务发现（2/2）
docker·云原生·容器·kubernetes·k8s
字节跳动安全中心3 小时前
智能体防御 | 一文了解3种系统提示词加固方法
安全·llm
发愤图强的羔羊4 小时前
Docker 搭建 SVN 服务器
docker
为了摸鱼而战4 小时前
Dockerfile知识点梳理，你要搞懂的都在这
docker
聚客AI4 小时前
🧩万亿级Token训练！解密大模型预训练算力黑洞与RLHF对齐革命
人工智能·llm·强化学习
Clownseven5 小时前
Docker+Nginx+Node.js实战教程：从零搭建高可用的前后端分离项目
nginx·docker·node.js
用户84913717547168 小时前
为什么大模型都离不开SSE？带你搞懂第1章〈SSE技术基础与原理〉
前端·网络协议·llm
数据智能老司机8 小时前
MCP 实战——全局视角：为什么 MCP 将成为 AI 的颠覆者
python·llm·mcp
热门推荐
01UV安装并设置国内源02DeepSeek更新！速览DeepSeek V3.1新特性03Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code04KGG转MP3工具|非KGM文件|解密音频05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接06【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）072025最新国内服务器可用docker源仓库地址大全（2025年8月更新）08阿里开源首个图像生成基础模型——Qwen-Image本地部署教程，超强中文渲染能力刷新SOTA！09NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南10TRAE 规则（Rules）配置指南：个人习惯、团队规范与最佳实践