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

Johny_Zhao2025-08-20 0:32

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 盘空间。可以通过命令行指定安装路径：

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 中正常识别。如果成功，你将看到显卡信息输出。
  2. （可选）安装 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. 启动容器（后台运行）：

bash

docker compose up -d

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

  1. 进入容器内部：

bash

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. 运行容器并进入：

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 <= 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)：

json

{

"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 参数将存放数据集的本地目录挂载到容器内。

bash

# 在 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. 启动训练：

bash

# 在容器内执行

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 使用命令行进行推理

bash

# 在容器内执行

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. 执行转换：

bash

python llama.cpp/convert-hf-to-gguf.py /path/to/your/merged_model --outfile my-model.fp16.gguf --outtype f16

  1. 在 Ollama 中使用：
    • 创建一个 Modelfile：

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|>"

  • 创建并运行模型：

bash

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 进行自定义构建。

Dockerfile

示例：基于官方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 https://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 和官方文档通常能找到解决方案。

相关推荐
MANONGMN2 小时前
Kubernetes（K8s）常用命令全解析：从基础到进阶
云原生·容器·kubernetes
lingggggaaaa2 小时前
小迪安全v2023学习笔记（六十二讲）—— PHP框架反序列化
笔记·学习·安全·web安全·网络安全·php·反序列化
Wy_编程4 小时前
Linux文件相关命令
linux·运维
Viking_bird4 小时前
centos 7.5 + Hadoop 3.2.4 集群搭建
linux·运维·服务器·hadoop·centos
真上帝的左手5 小时前
20. 云计算-云服务模型
云计算
wdxylb5 小时前
云原生俱乐部-RH134知识点总结（1）
linux·云原生
黑客影儿5 小时前
Kali Linux 环境中的系统配置文件与用户配置文件大全
linux·运维·程序人生·安全·网络安全·系统安全·学习方法
岚天start5 小时前
Linux系统网络排查工具总结
linux·运维·网络·监控·扫描·连通性·流量
陈陈CHENCHEN6 小时前
【Kubernetes】在 K8s 上部署 Prometheus
kubernetes·prometheus
热门推荐
01UV安装并设置国内源02蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接03Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code04KGG转MP3工具|非KGM文件|解密音频05【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）062025最新国内服务器可用docker源仓库地址大全（2025年8月更新）07TRAE 规则（Rules）配置指南：个人习惯、团队规范与最佳实践08NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南09阿里开源首个图像生成基础模型——Qwen-Image本地部署教程，超强中文渲染能力刷新SOTA！10TRAE Rules 实践：为项目配置 6A 工作流