如何完整部署基于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 软件依赖安装 安装 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 项目克隆到本地： 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 能简化容器的构建和运行过程。 进入 CUDA 目录： bash cd docker/docker-cuda/ 启动容器（后台运行）： bash docker compose up -d 此命令会读取同目录下的docker-compose.yml文件，构建或拉取镜像，并在后台启动容器。 进入容器内部： bash docker compose exec llamafactory bash # 或者使用 # docker exec -it llamafactory /bin/bash 执行后，你将进入一个名为llamafactory的容器内部，并可以开始在容器内操作。 2.2.2 手动构建 Docker 镜像（可选） 如果你需要更多自定义配置，可以手动构建镜像。 编写 Dockerfile：你可以参考或修改docker/docker-cuda/Dockerfile。 构建镜像： bash # 在 Dockerfile 所在目录执行 docker build -t llamafactory-cuda . 运行容器并进入： 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 挂载数据并添加到项目 挂载数据卷：在启动 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 添加数据集信息： 将你的数据文件（如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 界面，方便进行参数配置和训练监控。 启动 Web UI： bash # 在容器内执行 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）。 修改配置文件：指定模型路径、数据集名称、训练参数等。 启动训练： 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 进行聊天测试 启动 Web UI（同上）：llamafactory-cli webui。 在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。 获取转换工具： bash git clone https://github.com/ggerganov/llama.cpp.git pip install -r llama.cpp/requirements.txt 执行转换： bash python llama.cpp/convert-hf-to-gguf.py /path/to/your/merged_model --outfile my-model.fp16.gguf --outtype f16 在 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 和官方文档通常能找到解决方案。