背景

LlamaFactory 已集成 MindSpore 社区的 HyperParallel，可作为 FSDP2 后端在昇腾 NPU 上训练。官方博客示例见 llamafactory-blog#35，其中使用的是较大的 Qwen3-VL-30B-A3B。

本 Issue 提供一份更轻量、可复现的入门示例：使用 Qwen3-VL-4B-Instruct，在 2 卡昇腾 上通过 Accelerate FSDP2，并开启 use_hyper_parallel: true 完成短程 SFT。

目的

1. 在独立 conda 环境中安装完整依赖（PyTorch 2.7.1 + torch-npu + HyperParallel + LlamaFactory）
2. 按步骤完成环境准备、模型/数据下载、2 卡训练与结果验收
3. 给出每一步的命令、期望输出，以及本机实测结果，便于用户自行复现

本机验证结论（摘要）

10 分钟跑通：LlamaFactory + HyperParallel 在昇腾上微调 Qwen3-VL-4B（2 卡）

参考：LlamaFactory Blog PR #35
本机已完整跑通（2026-07-25，Ascend 910B3 × 2）。

先看结果

本机实测（max_steps=10，2 卡）：

step      loss            lr
   1    2.8984     0.000e+00
   2    3.4453     1.000e-04
   3    2.6641     9.698e-05
   4    1.8633     8.830e-05
   5    1.6094     7.500e-05
   6    2.1211     5.868e-05
   7    1.9609     4.132e-05
   8    1.7969     2.500e-05
   9    2.2422     1.170e-05
  10    1.8125     3.015e-06

产物目录：saves/Qwen3-VL-4B-Instruct/full/sft_hp_demo_2npu/checkpoint-10/（HF 分片权重）。

环境约定

export DEMO_ROOT="${DEMO_ROOT:-$HOME/dev/lf_hp_qwen3vl4b_demo}"
export CONDA_ENV="${CONDA_ENV:-lf_hp_demo}"
export CANN_ROOT="${CANN_ROOT:-$HOME/ascend-cann-release/cann}"
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/
export HF_ENDPOINT=https://hf-mirror.com
mkdir -p "$DEMO_ROOT"

前置：≥2 张昇腾 NPU、CANN 9.1.0、conda。不要误 source ~/env.sh。

步骤 1｜新建 conda 环境

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda create -y -n "$CONDA_ENV" python=3.11
conda activate "$CONDA_ENV"

步骤 2｜克隆代码并写 2 卡配置

conda activate "$CONDA_ENV"
mkdir -p "$DEMO_ROOT"/{configs,scripts,logs,saves,models}
cd "$DEMO_ROOT"
git clone https://gitcode.com/mindspore/hyper-parallel.git
git clone https://github.com/hiyouga/LlamaFactory.git
git -C hyper-parallel checkout 5ff346786cb835eb1b5860e327e28f1fc94691bd
git -C LlamaFactory checkout ef2d8f9da66ef13378dc8068dabc99cfe89a9736

2.1 scripts/demo_env.sh（默认 2 卡 0,1）

cat > "$DEMO_ROOT/scripts/demo_env.sh" <<'EOF'
#!/usr/bin/env bash
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:-}"
export PYTHONPATH="${PYTHONPATH:-}"
CANN_ROOT="${CANN_ROOT:-${HOME}/ascend-cann-release/cann}"
source "${CANN_ROOT}/set_env.sh"
if [[ -n "${CONDA_PREFIX:-}" && -n "${LD_LIBRARY_PATH:-}" ]]; then
  LD_LIBRARY_PATH="$(echo "${LD_LIBRARY_PATH}" | tr ':' '\n' | grep -v "${CONDA_PREFIX}/Ascend/cann" | tr '\n' ':' | sed 's/:$//')"
  export LD_LIBRARY_PATH
fi
DEMO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
export HYPER_PARALLEL_ROOT="${DEMO_ROOT}/hyper-parallel"
if [[ -n "${PYTHONPATH:-}" ]]; then
  PYTHONPATH="$(echo "${PYTHONPATH}" | tr ':' '\n' | grep -v 'hyper-parallel' | tr '\n' ':' | sed 's/:$//')"
fi
export PYTHONPATH="${HYPER_PARALLEL_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
export HYPER_PARALLEL_PLATFORM=torch
export ASCEND_RT_VISIBLE_DEVICES="${ASCEND_RT_VISIBLE_DEVICES:-0,1}"
export HCCL_NPU_SOCKET_PORT_RANGE="${HCCL_NPU_SOCKET_PORT_RANGE:-60000-60050}"
export MASTER_PORT="${MASTER_PORT:-29501}"
export PIP_INDEX_URL="${PIP_INDEX_URL:-https://repo.huaweicloud.com/repository/pypi/simple/}"
export HF_ENDPOINT="${HF_ENDPOINT:-https://hf-mirror.com}"
echo "[demo_env] ASCEND_RT_VISIBLE_DEVICES=${ASCEND_RT_VISIBLE_DEVICES}"
EOF
chmod +x "$DEMO_ROOT/scripts/demo_env.sh"

检查：source demo_env.sh 后应 npu_count=2。

2.2 FSDP2 配置（保持 2 进程）

cp "$DEMO_ROOT/LlamaFactory/examples/accelerate/fsdp2_config.yaml" \
  "$DEMO_ROOT/configs/fsdp2_config_2npu.yaml"
# 默认即为 num_processes: 2

2.3 训练 YAML

基于 examples/ascend/qwen3vlmoe_full_sft_fsdp2.yaml，改为 4B、use_hyper_parallel: true、max_steps: 10、output_dir: .../sft_hp_demo_2npu。

步骤 3｜安装依赖

conda activate "$CONDA_ENV"
source "$DEMO_ROOT/scripts/demo_env.sh"
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 torch-npu==2.7.1
cd "$DEMO_ROOT/hyper-parallel" && pip install -e .
cd "$DEMO_ROOT/LlamaFactory" && pip install -e .
pip install qwen-vl-utils==0.0.14 transformers==4.57.1

必须钉死 transformers==4.57.1，避免 5.x 导入失败。

步骤 4｜下载模型/数据并写本地路径

ModelScope 下载 Qwen/Qwen3-VL-4B-Instruct；数据集 BUAADreamer/llava-en-zh-2k（llava_1k_en, llava_1k_zh）。把 model_name_or_path / output_dir 写成绝对路径。

步骤 5｜启动 2 卡训练

conda activate "$CONDA_ENV"
unset ASCEND_RT_VISIBLE_DEVICES HYPER_PARALLEL_ROOT
export LD_LIBRARY_PATH="" PYTHONPATH=""
source "$DEMO_ROOT/scripts/demo_env.sh"
cd "$DEMO_ROOT/LlamaFactory"
accelerate launch \
  --config_file "$DEMO_ROOT/configs/fsdp2_config_2npu.yaml" \
  src/train.py \
  "$DEMO_ROOT/configs/qwen3vl4b_full_sft_fsdp2_hp.yaml"

或：

bash "$DEMO_ROOT/scripts/run_demo_train_2npu.sh"

关键日志：

Process rank: 0, world size: 2, device: npu:0
Process rank: 1, world size: 2, device: npu:1
Total train batch size ... = 4
Number of trainable parameters = 4,022,468,096
train_loss = 2.24140625

步骤 6｜验收

确认：

1. 日志含 world size: 2
2. 存在 .../sft_hp_demo_2npu/checkpoint-10/model.safetensors.index.json
3. trainer_log.jsonl 有 10 步 loss

版本锁定（2026-07-25 本机）

CANN 9.1.0 | Ascend 910B3 × 2 | python 3.11.15
torch 2.7.1 | torch-npu 2.7.1 | transformers 4.57.1
hyper_parallel @ 5ff34678 | LlamaFactory @ ef2d8f9d
fsdp2 num_processes=2 | use_hyper_parallel=true | max_steps=10

常见问题

结语：本机已用 2 卡跑通 max_steps=10，产出 HF 检查点。