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

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/

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

bash

docker compose up -d

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

3. 进入容器内部：

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 .

3. 运行容器并进入：

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

2. 添加数据集信息：
   • 将你的数据文件（如 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

2. 根据提示，在物理机的浏览器中打开 http://localhost:7860（如果端口映射正确）。
3. 在 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

2. 执行转换：

bash

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

3. 在 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 和官方文档通常能找到解决方案。