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

一、环境准备与基础部署

1.1 系统要求

操作系统：Linux（推荐Ubuntu 20.04+）
GPU：NVIDIA显卡，显存建议≥16GB
软件依赖：Docker、NVIDIA Container Toolkit

1.2 下载代码

bash 复制代码

# 克隆仓库（仅最新版本）
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git

# 进入目录
cd LLaMA-Factory

# 切换到指定版本
git fetch --tags
git checkout v0.9.3

1.3 制作镜像

bash 复制代码

# 返回上级目录
cd ..

# 构建Docker镜像
docker-compose -f "LLaMA-Factory/docker/docker-cuda/docker-compose.yml" up --build

1.4 创建容器

bash 复制代码

# 后台启动容器
docker-compose -f "LLaMA-Factory/docker/docker-cuda/docker-compose.yml" up -d

# 查看容器状态
docker-compose ps

1.5 启动LLaMA-Factory服务

bash 复制代码

# 进入容器
docker exec -it llamafactory /bin/bash

# 设置目录权限
chmod -R 777 /app/data

# 启动WebUI服务
nohup llamafactory-cli webui > /app/webui.log 2>&1 &

1.6 访问服务

浏览器访问：http://<服务器IP>:7860

二、自定义数据集配置

2.1 数据格式（Alpaca格式）

json 复制代码

[
  {
    "instruction": "Summarize the following text.",
    "input": "Artificial intelligence (AI) is a rapidly growing field...",
    "output": "AI is an evolving technology that is growing quickly in various fields..."
  }
]

字段说明：

字段	说明
instruction	任务指令，告诉模型需要完成什么操作
input	任务所需的输入（开放式任务可为空字符串）
output	任务的期望输出

2.2 注册数据集

修改 /app/data/dataset_info.json 文件，添加数据集配置：

json 复制代码

"alpaca_crypto_security_assessment": {
    "file_name": "alpaca_crypto_security_assessment.json"
},
"alpaca_security_gateway": {
    "file_name": "alpaca_security_gateway.json"
},
"alpaca_super_sim_gm_pool": {
    "file_name": "alpaca_super_sim_gm_pool.json"
},
"alpaca_trusted_auth": {
    "file_name": "alpaca_trusted_auth.json"
}

数据集文件需放置在 /app/data/ 目录下。

三、微调参数详解

3.1 学习率（Learning Rate）

概念： 决定模型参数每次更新的调整幅度，范围通常在 (0, 1) 之间。

配置经验：

一般保持在 5e-5（0.00005）~ 4e-5（0.00004）之间
小数据集避免使用大学习率
全参数微调需要比LoRA小一个数量级

3.2 训练轮数（Number of Epochs）

概念： 模型完整遍历一次全部训练数据的次数。

配置经验：

一般3轮即可
观察LOSS：未平缓则增加轮数，提前收敛则减少
LOSS控制在 0.5 ~ 1.5 之间
不建议超过10轮（易过拟合）
数据集越小 → 需越多Epoch；数据集越大 → 需越少Epoch

3.3 批量大小（Batch Size）

概念： 每次更新模型参数时使用的样本数量。

配置经验：

大batch_size → 大学习率；小batch_size → 小学习率
小参数模型、小数据集：单GPU batch size建议从 2 甚至 1 开始
通过调大梯度累积步数（4或8）加快训练

3.4 截断长度（Cutoff Length）

概念： 模型处理文本时能接收的最大token数量。

配置经验：

避免单条超长数据导致显存溢出
建议计算数据集Token长度的P99、P95值
可剔除超长数据以减少对训练效果的影响

计算Token长度分布：

bash 复制代码

torchrun --nproc_per_node=1 \
    scripts/stat_utils/length_cdf.py \
    --model_name_or_path /app/DeepSeek-R1-Distill-Qwen-7B \
    --dataset alpaca_crypto_security_assessment \
    --dataset_dir data \
    --template qwen

3.5 LoRA秩（LoRA Rank）

概念： 决定参数更新"表达能力"的关键参数，值越小越保守，值越大特征复杂度越高。

配置经验：

日常微调建议从 8~16 开始
效果不佳可调大，最低建议≥8
小数据集避免调得过大

3.6 验证集比例（Val Size）

概念： 从训练数据中划分用于性能评估的比例。

配置经验：

数据集规模	推荐比例	建议样本数
小数据（<1000）	0.1 ~ 0.2	≥100
大数据（>10000）	0.05 ~ 0.1	≥1000

四、启动微调任务

4.1 完整训练命令示例

bash 复制代码

llamafactory-cli train \
    --stage sft \
    --do_train True \
    --model_name_or_path /app/DeepSeek-R1-Distill-Qwen-7B \
    --preprocessing_num_workers 16 \
    --finetuning_type lora \
    --template deepseekr1 \
    --flash_attn auto \
    --dataset_dir data \
    --dataset alpaca_crypto_security_assessment,alpaca_security_gateway,alpaca_super_sim_gm_pool,alpaca_trusted_auth \
    --cutoff_len 2000 \
    --learning_rate 4e-05 \
    --num_train_epochs 3.0 \
    --max_samples 100000 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 4 \
    --lr_scheduler_type cosine \
    --max_grad_norm 1.0 \
    --logging_steps 5 \
    --save_steps 100 \
    --warmup_steps 0 \
    --packing False \
    --report_to none \
    --use_swanlab True \
    --output_dir saves/DeepSeek-R1-7B-Distill/lora/train_2025-10-15-07-09-01 \
    --bf16 True \
    --plot_loss True \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --include_num_input_tokens_seen True \
    --optim adamw_torch \
    --lora_rank 8 \
    --lora_alpha 16 \
    --lora_dropout 0 \
    --lora_target all \
    --val_size 0.1 \
    --eval_strategy steps \
    --eval_steps 100 \
    --per_device_eval_batch_size 2

4.2 开始训练

在WebUI界面中，点击「开始训练」按钮即可启动微调任务。

五、常见问题与建议

问题	解决方案
显存不足	降低batch_size、cutoff_len，或启用梯度检查点
过拟合	减少epochs、增大验证集比例、降低LoRA rank
欠拟合	增加epochs、提高学习率、增大LoRA rank
训练中断	检查截断长度是否合理，剔除超长样本

本文档基于LLaMA-Factory v0.9.3编写，实际操作时请根据硬件配置和数据特点灵活调整参数。