大模型微调：DeepSpeed、vLLM 及 LLaMA-Factory 使用指南

---

一、工具概览

工具	定位	核心能力
DeepSpeed	分布式训练框架	ZeRO 显存优化、数据并行、流水线并行
vLLM	推理引擎	PagedAttention、Continuous Batching、高吞吐推理
LLaMA-Factory	一站式微调平台	100+ 模型支持、LoRA/QLoRA、Web UI、一键训练

三者关系：LLaMA-Factory 作为上层框架，底层集成 DeepSpeed 做分布式训练，集成 vLLM 做推理部署。

---

二、环境准备

2.1 硬件要求

模型规模	微调方式	推荐显存	推荐 GPU
7B	LoRA (FP16)	16GB	RTX 4090 / A100 40GB
7B	QLoRA (INT4)	8GB	RTX 3090 / RTX 4080
13B	LoRA (FP16)	32GB	A100 40GB
13B	QLoRA (INT4)	12GB	RTX 4090
70B	LoRA (FP16)	160GB	H100 80GB x 2
70B	QLoRA (INT4)	48GB	A100 80GB / L40

2.2 软件依赖

# Python >= 3.9
python -m pip install --upgrade pip

# PyTorch (CUDA 12.1)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 验证 CUDA
python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"

---

三、LLaMA-Factory 安装与使用

3.1 安装

# 克隆仓库
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

# 安装基础依赖
pip install -e ".[torch,metrics]"

# 安装全部可选依赖（含 DeepSpeed、vLLM、FlashAttention）
pip install -e ".[torch,metrics,deepspeed,vllm,flash-attn]"

# 验证安装
llamafactory-cli version

国内镜像加速（可选）：

# 使用魔搭社区下载模型
export USE_MODELSCOPE_HUB=1

# 或使用魔乐社区
export USE_OPENMIND_HUB=1

3.2 启动 Web UI

llamafactory-cli webui

访问 http://localhost:7860，可视化界面包含：

• 模型选择与加载
• 数据集配置
• 训练参数调整
• 训练监控（Loss 曲线）
• 推理测试

3.3 命令行训练（推荐）

方式一：命令行参数

llamafactory-cli train \
  --stage sft \
  --do_train True \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --finetuning_type lora \
  --template qwen \
  --flash_attn auto \
  --dataset_dir data \
  --dataset alpaca_zh_demo \
  --cutoff_len 2048 \
  --learning_rate 5e-05 \
  --num_train_epochs 3.0 \
  --per_device_train_batch_size 2 \
  --gradient_accumulation_steps 8 \
  --lr_scheduler_type cosine \
  --max_grad_norm 1.0 \
  --logging_steps 5 \
  --save_steps 100 \
  --output_dir saves/Qwen2.5-7B/lora/sft \
  --bf16 True \
  --plot_loss True \
  --lora_rank 8 \
  --lora_alpha 16 \
  --lora_dropout 0 \
  --lora_target all

方式二：YAML 配置文件（推荐）

创建 train_lora.yaml：

### model
model_name_or_path: Qwen/Qwen2.5-7B-Instruct

### method
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 8
lora_alpha: 16
lora_dropout: 0

### dataset
dataset: alpaca_zh_demo
template: qwen
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### output
output_dir: saves/qwen2.5-7b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 5.0e-5
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000

执行训练：

llamafactory-cli train train_lora.yaml

3.4 关键参数说明

参数	说明	推荐值
finetuning_type	微调类型	lora / full / freeze
lora_rank	LoRA 秩 r	8（简单任务）/ 16-32（复杂任务）
lora_alpha	LoRA 缩放因子	2 * rank（通常）
lora_target	目标模块	all / q_proj,v_proj
per_device_train_batch_size	每设备 batch	1-4（根据显存调整）
gradient_accumulation_steps	梯度累积	8-16（等效大 batch）
learning_rate	学习率	1e-5 ~ 5e-5
cutoff_len	最大序列长度	2048 / 4096
bf16	BF16 混合精度	true（推荐，比 FP16 稳定）

3.5 自定义数据集

1. 准备数据文件 data/my_dataset.json：

[
  {
    "instruction": "请解释什么是机器学习",
    "input": "",
    "output": "机器学习是人工智能的一个分支..."
  }
]

1. 在 data/dataset_info.json 中注册：

{
  "my_dataset": {
    "file_name": "my_dataset.json",
    "formatting": "alpaca",
    "columns": {
      "prompt": "instruction",
      "query": "input",
      "response": "output"
    }
  }
}

1. YAML 中引用：dataset: my_dataset

---

四、DeepSpeed 集成（分布式训练）

4.1 DeepSpeed 简介

DeepSpeed 是微软开源的分布式训练框架，核心特性：

• ZeRO（Zero Redundancy Optimizer）：分片优化器状态、梯度、参数，大幅降低显存占用
• 3D 并行：数据并行 + 张量并行 + 流水线并行
• Offload：将优化器状态卸载到 CPU/NVMe，进一步节省显存

4.2 在 LLaMA-Factory 中使用 DeepSpeed

单卡 LoRA 微调（ZeRO-2）

创建 ds_config_zero2.json：

{
  "train_batch_size": "auto",
  "train_micro_batch_size_per_gpu": "auto",
  "gradient_accumulation_steps": "auto",
  "gradient_clipping": "auto",
  "zero_allow_untested_optimizer": true,
  "fp16": {
    "enabled": "auto",
    "loss_scale": 0,
    "loss_scale_window": 1000,
    "initial_scale_power": 16,
    "hysteresis": 2,
    "min_loss_scale": 1
  },
  "bf16": {
    "enabled": "auto"
  },
  "zero_optimization": {
    "stage": 2,
    "offload_optimizer": {
      "device": "cpu",
      "pin_memory": true
    },
    "allgather_partitions": true,
    "allgather_bucket_size": 2e8,
    "overlap_comm": true,
    "reduce_scatter": true,
    "reduce_bucket_size": 2e8,
    "contiguous_gradients": true
  }
}

执行训练：

llamafactory-cli train train_lora.yaml --deepspeed ds_config_zero2.json

多卡全参数微调（ZeRO-3）

创建 ds_config_zero3.json：

{
  "train_batch_size": "auto",
  "train_micro_batch_size_per_gpu": "auto",
  "gradient_accumulation_steps": "auto",
  "gradient_clipping": "auto",
  "zero_allow_untested_optimizer": true,
  "bf16": {
    "enabled": true
  },
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": {
      "device": "cpu",
      "pin_memory": true
    },
    "offload_param": {
      "device": "cpu",
      "pin_memory": true
    },
    "overlap_comm": true,
    "contiguous_gradients": true,
    "sub_group_size": 1e9,
    "reduce_bucket_size": "auto",
    "stage3_prefetch_bucket_size": "auto",
    "stage3_param_persistence_threshold": "auto",
    "stage3_max_live_parameters": 1e9,
    "stage3_max_reuse_distance": 1e9,
    "stage3_gather_16bit_weights_on_model_save": true
  }
}

多卡启动：

torchrun --nproc_per_node=4 \
  src/train.py train_full.yaml \
  --deepspeed ds_config_zero3.json

4.3 ZeRO 阶段对比

ZeRO 阶段	优化内容	显存节省	适用场景
ZeRO-1	分片优化器状态	~4x	数据并行
ZeRO-2	+ 分片梯度	~8x	大模型微调
ZeRO-3	+ 分片参数	~N 倍（N=GPU 数）	超大模型训练
ZeRO-Offload	卸载到 CPU/NVMe	进一步节省	显存极度受限

4.4 DeepSpeed 关键配置说明

{
  "zero_optimization": {
    "stage": 2,                    // ZeRO 阶段：1/2/3
    "offload_optimizer": {         // 优化器状态卸载
      "device": "cpu",             // 卸载到 CPU 或 nvme
      "pin_memory": true           // 固定内存，加速传输
    },
    "overlap_comm": true,          // 通信与计算重叠
    "contiguous_gradients": true   // 连续梯度，减少碎片
  }
}

---

五、vLLM 集成（推理部署）

5.1 vLLM 简介

vLLM 是高性能大模型推理引擎，核心特性：

• PagedAttention：将 KV Cache 分页管理，显存利用率接近 100%
• Continuous Batching：动态合并请求，最大化 GPU 利用率
• 高吞吐：相比原生 Transformers，吞吐量提升 3-10 倍

5.2 在 LLaMA-Factory 中使用 vLLM

方式一：LLaMA-Factory 内置脚本

python scripts/vllm_infer.py \
  --model_name_or_path saves/qwen2.5-7b/lora/sft \
  --template qwen \
  --dataset data_sample \
  --cutoff_len 512 \
  --max_samples 1000 \
  --batch_size 32 \
  --max_new_tokens 512

方式二：启动 OpenAI 兼容 API 服务

# 合并 LoRA 权重后部署
llamafactory-cli export merge_lora.yaml

# 使用 vLLM 启动 API 服务
python -m vllm.entrypoints.openai.api_server \
  --model saves/qwen2.5-7b/lora/sft_merged \
  --template qwen \
  --dtype half \
  --gpu_memory_utilization 0.95 \
  --max_model_len 4096 \
  --port 8000

调用 API：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")

response = client.chat.completions.create(
    model="saves/qwen2.5-7b/lora/sft_merged",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

方式三：LLaMA-Factory 一键部署

# 使用 LLaMA-Factory 的 API 模式（底层调用 vLLM）
llamafactory-cli api \
  --model_name_or_path saves/qwen2.5-7b/lora/sft \
  --template qwen \
  --finetuning_type lora \
  --infer_backend vllm

5.3 vLLM 关键参数

参数	说明	推荐值
--dtype	数据类型	half / bfloat16 / float16
--gpu_memory_utilization	GPU 显存利用率	0.90-0.95
--max_model_len	最大序列长度	根据模型支持设置
--tensor_parallel_size	张量并行 GPU 数	1（单卡）/ 2/4/8
--quantization	量化方式	awq / gptq / fp8
--block_size	PagedAttention 块大小	16（默认）/ 32

5.4 性能优化

# 启用 AWQ 量化部署
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --dtype half \
  --gpu_memory_utilization 0.95

# 多卡张量并行
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-72B-Instruct \
  --tensor_parallel_size 4 \
  --dtype bfloat16

---

六、完整工作流示例

6.1 微调 + 合并 + 部署（单卡）

# 1. 准备环境
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics,deepspeed,vllm]"

# 2. 准备数据集（放入 data/ 目录并注册）

# 3. LoRA 微调
llamafactory-cli train configs/train_lora.yaml

# 4. 合并 LoRA 权重
cat > merge.yaml << 'EOF'
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
adapter_name_or_path: saves/qwen2.5-7b/lora/sft
template: qwen
finetuning_type: lora
export_dir: saves/qwen2.5-7b/lora/sft_merged
export_size: 2
export_device: cpu
export_legacy_format: false
EOF

llamafactory-cli export merge.yaml

# 5. vLLM 部署
python -m vllm.entrypoints.openai.api_server \
  --model saves/qwen2.5-7b/lora/sft_merged \
  --template qwen \
  --dtype half \
  --gpu_memory_utilization 0.95 \
  --port 8000

6.2 多卡分布式微调（DeepSpeed + ZeRO-3）

# 使用 torchrun 启动多卡训练
torchrun --nproc_per_node=4 \
  --nnodes=1 \
  --node_rank=0 \
  src/train.py \
  --deepspeed configs/ds_config_zero3.json \
  configs/train_full.yaml

6.3 量化微调（QLoRA）

# train_qlora.yaml
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
stage: sft
do_train: true
finetuning_type: lora
quantization_bit: 4          # 4-bit 量化
quantization_method: bitsandbytes

lora_rank: 64
lora_alpha: 16
lora_target: all

dataset: alpaca_zh_demo
template: qwen
cutoff_len: 2048

per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0

output_dir: saves/qwen2.5-7b/qlora/sft
bf16: true

llamafactory-cli train train_qlora.yaml

---

七、监控与调试

7.1 训练监控

# 启用 WandB 监控
pip install wandb
wandb login

# YAML 中添加
report_to: wandb
run_name: qwen2.5-7b-lora-sft

7.2 显存监控

# 实时监控 GPU
watch -n 1 nvidia-smi

# 或使用 nvitop
pip install nvitop
nvitop

7.3 常见问题

问题	原因	解决
CUDA OOM	显存不足	减小 batch_size / 启用 gradient_checkpointing / 使用 ZeRO-Offload
Loss = NaN	学习率过大	降低 learning_rate，启用 warmup
训练速度慢	数据加载瓶颈	增加 num_workers，启用 pin_memory
vLLM 启动失败	CUDA 版本不匹配	检查 nvidia-smi 和 torch.version.cuda
模型加载慢	网络下载	使用 USE_MODELSCOPE_HUB=1 或本地缓存

---