Qwen3.8-Max 完整微调教程：LoRA/QLoRA/ 全参显存测算 + LlamaFactory 部署步骤

# MS-SWIFT 云端微调示例（ModelScope Notebook 环境，以小参数Qwen3-8B为例）
# 安装 MS-SWIFT
pip install ms-swift -U

# 使用 MS-SWIFT 启动 LoRA 微调
swift sft \
    --model_type qwen3_8b \
    --dataset your_dataset \
    --output_dir ./output/qwen3_8b_lora \
    --finetuning_type lora \
    --lora_rank 16 \
    --lora_alpha 32 \
    --num_train_epochs 3 \
    --per_device_train_batch_size 4 \
    --learning_rate 1e-4

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

# 2. 创建 conda 环境（推荐 Python 3.11+，符合框架最低版本要求）
conda create -n llamafactory python=3.11
conda activate llamafactory

# 3. 安装依赖（CUDA 12.1+ 用户）
pip install -e .[torch,metrics]

# 4. 验证安装
llamafactory-cli version
# 预期输出：LLaMA-Factory version: x.x.x

[
  {
    "id": "sample_001",
    "conversations": [
      {"from": "user", "value": "请帮我写一封商务合作邮件，对方是医疗器械公司。"},
      {"from": "assistant", "value": "当然可以，以下是一封商务合作邮件模板……"}
    ]
  },
  {
    "id": "sample_002",
    "conversations": [
      {"from": "user", "value": "解释一下什么是量子计算。"},
      {"from": "assistant", "value": "量子计算是一种基于量子力学原理的计算方式……"}
    ]
  }
]

{
  "my_custom_dataset": {
    "file_name": "train.jsonl",
    "format": "sharegpt",
    "columns": {
      "messages": "conversations"
    },
    "tags": {
      "role_tag": "from",
      "content_tag": "value",
      "user_tag": "user",
      "assistant_tag": "assistant"
    }
  }
}

# 在本地启动 LlamaFactory WebUI
llamafactory-cli webui

# 然后在浏览器打开 http://localhost:7860
# 在界面中：
# 1. 选择模型：Qwen/Qwen3-8B（Qwen3.8-Max适配后可选择对应型号）
# 2. 选择微调类型：lora / qlora / full
# 3. 选择数据集：my_custom_dataset
# 4. 设置超参数：学习率、批次大小、训练轮次、序列长度
# 5. 多卡场景配置分布式策略：专家并行、张量并行、ZeRO分片
# 6. 点击「开始训练」

### model
model_name_or_path: Qwen/Qwen3-8B
trust_remote_code: true
finetuning_type: lora
template: qwen3

### dataset
dataset: my_custom_dataset
cutoff_len: 8192
max_samples: 10000

### output
output_dir: ./output/qwen3_8b_lora
per_device_train_batch_size: 4
gradient_accumulation_steps: 8
num_train_epochs: 3
lr_scheduler_type: cosine
logging_steps: 10
save_steps: 500
warmup_ratio: 0.1

### LoRA specific
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target: all

### quantization (for QLoRA)
quantization_bit: 4
bnb_4bit_compute_dtype: bf16
bnb_4bit_use_double_quant: true
bnb_4bit_quant_type: nf4

### 分布式训练（Qwen3.8-Max必选配置）
# deepspeed: ds_z3_config.json  # 启用ZeRO-3分片
# expert_parallel_size: 8      # 开启MoE专家并行，数值需匹配显卡数量

# 单卡调试
llamafactory-cli train train_qwen3_lora.yaml

# 多卡分布式训练（Qwen3.8-Max必选）
deepspeed --num_gpus 16 llamafactory-cli train train_qwen3_lora.yaml

# 合并 LoRA 权重到基座模型
llamafactory-cli export \
    --model_name_or_path Qwen/Qwen3-8B \
    --adapter_dir ./output/qwen3_8b_lora \
    --output_dir ./output/qwen3_8b_merged

# 启动推理
llamafactory-cli inference \
    --model_name_or_path ./output/qwen3_8b_merged \
    --template qwen3

# 安装 MS-SWIFT
pip install ms-swift -U

# LoRA 微调（单卡调试用）
swift sft \
    --model_type qwen3_8b \
    --dataset your_custom_dataset \
    --output_dir ./output/qwen3_lora \
    --finetuning_type lora \
    --lora_rank 16 \
    --lora_alpha 32 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --num_train_epochs 3 \
    --learning_rate 1e-4

# QLoRA 微调（4-bit，省显存）
swift sft \
    --model_type qwen3_8b \
    --dataset your_custom_dataset \
    --output_dir ./output/qwen3_qlora \
    --finetuning_type lora \
    --quantization_bit 4 \
    --bnb_4bit_quant_type nf4 \
    --bnb_4bit_compute_dtype bf16 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 16 \
    --num_train_epochs 3

from modelscope.msdatasets import MsDataset
from modelscope import snapshot_download
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer
from peft import LoraConfig, get_peft_model, TaskType
import torch

# 下载基座模型（以 Qwen3-8B 为例）
model_dir = snapshot_download('Qwen/Qwen3-8B')

# 加载 tokenizer
tokenizer = AutoTokenizer.from_pretrained(
    model_dir,
    trust_remote_code=True
)

# 加载模型（FP16，适配你的显存）
model = AutoModelForCausalLM.from_pretrained(
    model_dir,
    trust_remote_code=True,
    torch_dtype=torch.float16,
    device_map="auto"
)

# 配置 LoRA
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type=TaskType.CAUSAL_LM
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出示例：trainable params: 41,943,040 || all params: 7,737,000,000 || trainable%: 0.54