本文档详细介绍了如何使用LLaMA-Factory框架，通过Docker实现大语言模型（LLM）的微调。从环境准备、Docker部署（支持CUDA、NPU、ROCm）、数据格式规范（Alpaca、ShareGPT）、模型训练（Web UI与CLI）、推理测试到模型导出（合并LoRA、转换为GGUF），提供了一站式的操作指导。文章还涵盖了多卡分布式训练、自定义Docker镜像以及常见的故障排除和优化建议，旨在帮助用户高效地在消费级显卡上微调大型语言模型。

🐳 LLaMA-Factory 提供了一个强大的Docker部署方案，支持CUDA、NPU和ROCm环境，用户可以通过`docker compose up -d`快速启动并进入容器，简化了环境配置和依赖安装过程，为模型微调奠定基础。

📊 数据准备支持Alpaca（单轮指令）和ShareGPT（多轮对话）两种格式。用户需将数据集挂载到Docker容器内，并在`data/dataset_info.json`中注册数据集信息，以供LLaMA-Factory识别和使用。

💻 模型训练可通过Web UI（`llamafactory-cli webui`）或命令行CLI（`llamafactory-cli train`）进行。Web UI提供可视化配置，CLI则适用于自动化脚本，两者均支持LoRA、QLoRA等多种微调方法，并可进行显存优化（如调整batch size、使用Unsloth）。

🚀 微调完成后，支持通过Web UI或CLI进行模型聊天测试。若使用LoRA，可执行`llamafactory-cli export`合并权重，或将模型转换为GGUF格式以兼容Ollama等推理框架，实现模型的灵活部署。

🛠️ 文章还提供了进阶配置如多卡分布式训练、自定义Docker镜像，以及故障排除指南，包括解决Docker构建错误、GPU显存不足(OOM)、训练速度慢、数据集识别问题等常见难题，确保用户能够顺利完成整个微调流程。

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 软件依赖安装

安装 Docker：访问 Docker 官方网站 获取适合你操作系统（Windows/Linux/macOS）的安装指南。

Windows 用户注意：建议安装时更改默认安装路径到非系统盘（如 D 盘），避免后期占用过多 C 盘空间。可以通过命令行指定安装路径：

powershell"Docker Desktop Installer.exe" install --installation-dir=D:\Docker

安装完成后，启动 Docker 服务。

安装 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 中正常识别。如果成功，你将看到显卡信息输出。

（可选）安装 Docker Compose：新版本的 Docker Desktop 通常已包含 Compose。如果没有，请参照官方文档安装。

2. LLaMA-Factory 项目获取与 Docker 环境配置

2.1 获取 LLaMA-Factory 源代码

使用 git 命令将 LLaMA-Factory 项目克隆到本地：

# 克隆项目代码（使用 --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 能简化容器的构建和运行过程。

进入 CUDA 目录：

cd docker/docker-cuda/

启动容器（后台运行）：

docker compose up -d

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

进入容器内部：

docker compose exec llamafactory bash# 或者使用# docker exec -it llamafactory /bin/bash

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

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

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

编写 Dockerfile：你可以参考或修改 docker/docker-cuda/Dockerfile。构建镜像：

# 在 Dockerfile 所在目录执行docker build -t llamafactory-cuda .

运行容器并进入：

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:... 类似的错误，可以尝试手动拉取基础镜像：

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：

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

{"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)：

{  "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 挂载数据并添加到项目

挂载数据卷：在启动 Docker 容器时，使用 -v 参数将存放数据集的本地目录挂载到容器内。

# 在 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

添加数据集信息：

将你的数据文件（如 my_data.json）放入已挂载的容器数据目录（如 /app/data）。关键步骤：你还需要在容器内 LLaMA-Factory 项目的 data 目录下的 dataset_info.json 配置文件中，为你新添加的数据集添加一条记录，LLaMA-Factory 才能识别它。例如，添加：

"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 界面，方便进行参数配置和训练监控。

启动 Web UI：

# 在容器内执行llamafactory-cli webui# 或者设置共享和CUDA设备# CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 llamafactory-cli webui

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

准备配置文件：参考项目 examples 目录下的配置文件（如 examples/train_lora/llama3_lora_sft.yaml）。修改配置文件：指定模型路径、数据集名称、训练参数等。启动训练：

# 在容器内执行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 进行聊天测试

启动 Web UI（同上）：llamafactory-cli webui。在 Chat 标签页中：

选择或输入模型路径。如果使用 LoRA 等适配器微调，需要在 Adapter 选项中选择对应的适配器检查点路径（通常在 output 目录下）。在下方输入框与模型进行对话，测试微调效果。

5.2 使用命令行进行推理

# 在容器内执行CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat examples/inference/llama3_lora_sft.yaml

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

5.3 模型导出与部署

5.3.1 合并 LoRA 适配器（如果使用了 LoRA）

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

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

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

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

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

获取转换工具：

git clone https://github.com/ggerganov/llama.cpp.gitpip install -r llama.cpp/requirements.txt

执行转换：

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

在 Ollama 中使用：

创建一个 Modelfile：

textFROM ./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|>"

创建并运行模型：

ollama create my-model -f Modelfileollama 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 进行自定义构建。

# 示例：基于官方CUDA镜像构建，安装中文依赖和常用工具FROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04ENV DEBIAN_FRONTEND=noninteractiveRUN 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