一、引言

本最佳实践文档旨在为用户提供一个全面、高效的多模态图文理解模型训练样例，涵盖从单机训练到多机分布式训练的全过程。通过系统化的步骤指引，用户可以快速熟悉并掌握在平台上进行多模态图文理解模型训练的操作流程，并高效完成训练任务。无论是单机训练还是多机分布式训练，本最佳实践文档均提供了详细的操作步骤与注意事项，帮助用户快速上手并解决可能遇到的问题。

二、训练准备

2.1 开发机

在进行大规模模型训练之前，确保所有的开发环境、模型代码、依赖库、权重文件以及数据集都已准备妥当是至关重要的一步。通过平台提供的模型开发工具，您可以使用vscode轻松实现可视化的IDE操作，简化训练环境的搭建与管理。

2.1.1 配置开发机

先创建开发机IDE任务，按照如下步骤展开操作：

2.1.2 打开IDE

提交任务后，点击“启动”按钮，任务状态将依次显示启动中->环境准备中->运行中（如果长时间（>1min）界面状态未更新, 可以手动刷新界面），当状态显示为运行中后，点击右侧操作栏“打开”按钮。

2.1.3 打开终端

打开后，进入vscode界面，左侧文件管理器中显示了当前集群的共享存储空间/work/home，用户可在此创建文件夹，确保所有节点对文件的访问。用户还可以在终端中进入共享存储目录，执行命令行操作。

2.1.4 镜像制作

若您使用天翼云算法团队推荐的qwen25vl镜像，则无论是单机训练还是多机训练，您均可跳过镜像制作步骤；若您想自行体验制作镜像，或是发现推荐的镜像内的cann版本与您当前驱动版本不匹配，则您可以在选择使用基础镜像作为开发机，然后重新在开发机内安装软件依赖以及cann包，最后将开发机中的运行环境保存为镜像。通过保存镜像，您不仅能够在日后快速复用该开发环境，还可以将其应用到多节点训练任务中，确保训练环境的一致性与稳定性。这种方式能够避免因环境差异导致的问题，实现从单机开发到多机分布式训练的无缝衔接。同时，镜像化管理还能在团队协作中发挥重要作用，便于其他成员直接使用统一环境，提升整体研发效率。

填写镜像名称与版本号后，点击“确定”按钮。

在左侧“我的镜像”选项卡中可查看镜像制作进度。

镜像制作完成后，下次创建开发机或训练任务时即可选择该自定义镜像。

2.2 模型准备

2.2.1 代码下载

将工程代码、第三方库下载，并切换到对应的版本号。

git clone https://gitee.com/ascend/MindSpeed-MM.git 
git clone https://github.com/NVIDIA/Megatron-LM.git
cd MindSpeed-MM
git checkout 2ad39f6
cd../Megatron-LM
git checkout core_v0.12.1
cp -r megatron ../MindSpeed-MM/
cd../MindSpeed-MM
mkdir logs
mkdir model_from_hf
mkdir model_weights
mkdir data
mkdir ckpt

2.2.2 环境搭建

安装加速包和其他依赖。

git clone https://gitee.com/ascend/MindSpeed.git
cd MindSpeed
git checkout 5176c6f5f133111e55a404d82bd2dc14a809a6ab 
pip install -e .
cd..#返回工作目录,确保在MindSpeed-MM目录下面
pip install -r requirements.txt
# 若MindSpeed-MM内没有requirements.txt文件，则需要手动进入pyproject.toml文件中，将dependencies中的依赖用pip安装

2.2.3 权重下载

通过 ModelScope 工具下载模型权重，例如：Qwen2.5-VL-32B-Instruct权重：

cd ./model_from_hf/
pip install modelscope
modelscope download --model Qwen/Qwen2.5-VL-32B-Instruct  --local_dir ./Qwen2.5-VL-32B-Instruct
modelscope download --model Qwen/Qwen2.5-VL-3B-Instruct  --local_dir ./Qwen2.5-VL-3B-Instruct#3B模型用于单机训练demo
cd..#返回工作目录,确保在MindSpeed-MM目录下面

2.2.4 权重转换(hf--->megatron)

将Huggingface格式的权重转换为可运行的切分后的megatron格式权重。

#Qwen2.5-VL-32B-Instruct,tp2pp8用于全参微调
python checkpoint/convert_cli.py Qwen2_5_VLConverter hf_to_mm \
  --cfg.mm_dir "./model_weights/qwen25vl_32b_tp2_pp8"\# megatron模型格式的目录
  --cfg.hf_config.hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct"\#原始huggingface权重目录
  --cfg.parallel_config.llm_pp_layers [[4,7,8,9,9,9,9,9]]\
  --cfg.parallel_config.vit_pp_layers [[32,0,0,0,0,0,0,0]]\
  --cfg.parallel_config.tp_size 2

#Qwen2.5-VL-32B-Instruct,tp4pp1用于LoRA微调
python checkpoint/convert_cli.py Qwen2_5_VLConverter hf_to_mm \
  --cfg.mm_dir "./model_weights/qwen25vl_32b_tp4_pp1"\# megatron模型格式的目录
  --cfg.hf_config.hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct"\#原始huggingface权重目录
  --cfg.parallel_config.llm_pp_layers [[64]]\
  --cfg.parallel_config.vit_pp_layers [[32]]\
  --cfg.parallel_config.tp_size 4

运行成功后，终端显示如下信息：

2.3 数据集准备

2.3.1 数据集下载(以coco2017数据集为例)

# 下载图文理解数据
#(1)用户需要自行下载COCO2017数据集COCO2017，并解压到项目目录下的./data/COCO2017文件夹中
#下载地址:https://cocodataset.org/#download

#(2)获取图片数据集的描述文件（LLaVA-Instruct-150K），下载至./data/路径下，和第(1)步的COCO2017文件夹放同一路径下
#下载地址:https://huggingface.co/datasets/liuhaotian/LLaVA-Instruct-150K/tree/main
#最终./data文件夹的呈现形式如下:
 ```
   $playground
   ├── data
       ├── COCO2017
           ├── train2017

       ├── llava_instruct_150k.json
       ├── mllm_format_llava_instruct_data.json
       ...
   ```

请将数据集文件下载到指定目录中，下载完成后请检查文件完整性，为后续的数据预处理环节做好准备。

2.3.2 数据集预处理

下载完成后，需要对原始数据集进行预处理，将图片以及图片描述放置同一文件内。以下是预处理的关键步骤：

vim ./examples/qwen2vl/llava_instruct_2_mllm_demo_format.py
#修改路径，以下分别是图片描述路径、数据预处理后的文件保存路径、图片路径

修改完成后，直接运行脚本：

python ./examples/qwen2vl/llava_instruct_2_mllm_demo_format.py

运行完成后，终端显示如下信息：

通过以上步骤，您已成功将原始数据集转换为可直接用于训练的数据格式，此时也可以在文件管理器中看到生成的数据预处理文件。

三、模型训练

3.1 开发机-单机训练

开发机训练是模型开发过程中快速验证代码准确性和训练全流程走通的重要环节。通过开发机训练，可以高效完成模型调试和小参数模型的微调训练，以下是开发机单机训练Qwen2.5-VL-32B-Instruct的LoRA微调的操作指南：

3.1.1 模型以及数据文件修改

修改对应的参数文件：examples/qwen2.5vl/data_32b.json以及examples/qwen2.5vl/model_32b.json，根据实际情况修改data_32b.json中的数据集路径，包括model_name_or_path、dataset_dir、dataset等字段，并根据切分方式以及是否开启激活值重计算修改model_32b.json中的相应位置。

"preprocess_parameters":{
"model_name_or_path":"/work/home/qwen25vl/MindSpeed-MM/model_from_hf/Qwen2.5-VL-32B-Instruct",#hf原始权重路径
...
}
"basic_parameters":{
"dataset_dir":"/work/home/qwen25vl/MindSpeed-MM/data",#data文件夹所在路径
"dataset":"/work/home/qwen25vl/MindSpeed-MM/data/mllm_format_llava_instruct_data.json",#2.3.2中处理好的数据文件路径
"cache_dir":"/work/home/qwen25vl/MindSpeed-MM/data/cache_dir_lora",#可指定为任意路径，但是注意cache_dir在多机上不要配置同一个路径避免写入同一个文件导致冲突
"val_rate":0.1,#指定将训练集划分为验证集的比例，若不设置默认不开启训练集切分
...
}

"vision_encoder":{
"pipeline_num_layers":[32],#vit中pp切分方式，list里每一个数字代表每一个pp_layer中的vision_transformers层的数量，总数为num_layers,需要和2.2.4中权重转换的vit_pp_layers一致
...
}
"text_decoder":{
"pipeline_num_layers":[64],#llm中pp切分方式，list里每一个数字代表每一个pp_layer中的transformers层的数量，总数为num_layers,需要和2.2.4中权重转换的llm_pp_layers一致
...
}

3.1.2 训练脚本准备

在完成环境和权重准备后，可以通过以下步骤启动开发机的单机训练任务：修改examples/qwen2.5vl/finetune_qwen2_5_vl_32b.sh脚本。

# 根据实际情况配置权重保存、权重加载、词表、数据集路径
MM_DATA="./examples/qwen2.5vl/data_32b.json"#数据集路径
MM_MODEL="./examples/qwen2.5vl/model_32b.json"#模型参数路径
MM_TOOL="./mindspeed_mm/tools/tools.json"#mm工具路径，可不修改
LOAD_PATH="./model_from_hf/qwen25vl_32b_tp4_pp1"#2.2.4中转换好的权重加载路径
SAVE_PATH="./ckpt/qwen25vl_32b_lora_tp4_pp1"#新权重保存路径
...
# 单机可以支持32B模型的LoRA微调
GPT_ARGS="
    --use-mcore-models \
...
    --num-workers 8 \
--lora-r 8 \ # lora参数，若显存占用不多，可增大该参数
    --lora-alpha 16 \ # lora参数
    --lora-target-moduleslinear_qkv linear_proj linear_fc1 linear_fc2 \ # lora参数
"
OUTPUT_ARGS="
    --log-interval 1 \
    --save-interval 50 \ #权重保存间隔，即训练多少个iterations保存一个权重
    --eval-interval 50 \#验证间隔，即训练多少个iterations验证一次
    --eval-iters 20 \ #每次验证的iterations数
    --save $SAVE_PATH \
    --ckpt-format torch \
"

可直接在vscode中，对文本或者代码内容进行修改，文件会自动保存更改，无需每次手动保存。

3.1.3 配置分布式参数

单机 8 卡训练参数示例：

GPUS_PER_NODE=8
MASTER_ADDR=locahost
MASTER_PORT=6000
NNODES=1
NODE_RANK=0
WORLD_SIZE=$(($GPUS_PER_NODE * $NNODES))

3.1.4 启动训练

在终端的MindSpeed-LLM工作目录下直接执行训练脚本。

bash examples/qwen2.5vl/finetune_qwen2_5_vl_32b.sh

训练任务启动后，终端将实时打印训练日志。

3.2 训练任务-多机训练

多节点训练是提升模型训练效率、实现大规模分布式计算的关键方式。借助平台提供的训练任务功能，通过动态分配计算资源、自动化参数配置和高效的资源管理，能够快速完成大规模的大模型分布式训练。以下是多节点训练Qwen2.5-VL-32B-Instruct的全参微调的详细操作指南：

3.2.1 模型以及数据文件修改

"preprocess_parameters":{
"model_name_or_path":"/work/home/qwen25vl/MindSpeed-MM/model_from_hf/Qwen2.5-VL-32B-Instruct",#hf原始权重路径
...
}
"basic_parameters":{
"dataset_dir":"/work/home/qwen25vl/MindSpeed-MM/data",#data文件夹所在路径
"dataset":"/work/home/qwen25vl/MindSpeed-MM/data/mllm_format_llava_instruct_data.json",#2.3.2中处理好的数据文件路径
"cache_dir":"/work/home/qwen25vl/MindSpeed-MM/data/cache_dir_full",#可指定为任意路径，但是注意cache_dir在多机上不要配置同一个路径避免写入同一个文件导致冲突,推荐使用非hpfs路径
"val_rate":0.1,#指定将训练集划分为验证集的比例，若不设置默认不开启训练集切分
...
}

"vision_encoder":{
"pipeline_num_layers":[32,0,0,0,0,0,0,0],#vit中pp切分方式，list里每一个数字代表每一个pp_layer中的vision_transformers层的数量，总数为num_layers,需要和2.2.4中权重转换的vit_pp_layers一致
...
}
"text_decoder":{
"pipeline_num_layers":[4,7,8,9,9,9,9,9],#llm中pp切分方式，list里每一个数字代表每一个pp_layer中的transformers层的数量，总数为num_layers,需要和2.2.4中权重转换的llm_pp_layers一致
...
}

3.2.2 训练脚本准备

多节点全参微调的脚本与单节点LoRA微调的脚本基本一致，但是需要针对分布式参数部分进行相应调整以及去除LoRA参数：

复制单节点训练脚本：

# 参考单机训练脚本拷贝出一份多机训练脚本
cp examples/qwen2.5vl/finetune_qwen2_5_vl_32b.sh examples/qwen2.5vl/finetune_qwen2_5_vl_32b_multinodes.sh

修改分布式参数以及去除LoRA参数：在脚本中，调整以下配置：

# 根据实际情况配置权重保存、权重加载、词表、数据集路径
MM_DATA="./examples/qwen2.5vl/data_32b.json"#数据集路径
MM_MODEL="./examples/qwen2.5vl/model_32b.json"#模型参数路径
MM_TOOL="./mindspeed_mm/tools/tools.json"#mm工具路径，可不修改
LOAD_PATH="./model_weights/qwen25vl_32b_tp2_pp8"#2.2.4中转换好的权重加载路径
SAVE_PATH="./ckpt/qwen25vl_32b_full_tp2_pp8"#新权重保存路径
...
GPUS_PER_NODE=8
DISTRIBUTED_ARGS="
    --nproc_per_node $GPUS_PER_NODE \
    --nnodes $PET_NNODES \#由平台提供的系统变量自动配置
    --node_rank $PET_NODE_RANK \#由平台提供的系统变量自动配置
    --master_addr $PET_MASTER_ADDR \#由平台提供的系统变量自动配置
    --master_port $PET_MASTER_PORT#由平台提供的系统变量自动配置
"
GPT_ARGS="
    --use-mcore-models \
    ...
    --num-workers 8 \
#--lora-r 8 \ # lora参数，全参微调场景下需剔除
#--lora-alpha 16 \ # lora参数，全参微调场景下需剔除
#--lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \ # lora参数，全参微调场景下需剔除
"
OUTPUT_ARGS="
    --log-interval 1 \
    --save-interval 50 \ #权重保存间隔，即训练多少个iterations保存一个权重
    --eval-interval 50 \ #验证间隔，即训练多少个iterations验证一次
    --eval-iters 20 \ #每次验证的iterations数
    --save $SAVE_PATH \
    --ckpt-format torch \
"

3.2.3 创建任务

多节点集群训练可使用训练任务工具创建多机多卡训练任务，创建任务可通过以下两种方式创建：

方法一：通过开发机任务创建

在开发机任务页面中创建训练任务，点击“开始训练”系统会自动选择与开发机一致的镜像版本，保证环境一致性。

方法二：通过训练任务工具创建

打开平台左侧“训练任务”选项卡，点击“新建任务”按钮。

3.2.4 配置任务

两种方法均会进入任务创建页面：

启动命令：

cd /work/home/qwen25vl/MindSpeed-MM;
bash ./examples/qwen2.5vl/finetune_qwen2_5_vl_32b_multinodes.sh

此模式下，不要打开容错训练开关！

完成所有配置后，点击“提交”按钮，您的训练任务将被创建并开始执行。

3.2.5 监控任务

若训练任务成功拉起，任务状态变为运行中。

点击日志按钮，可实时查看所有节点的训练日志，支持筛选单节点日志或查看全量日志，方便定位问题。

若启动命令存在错误，任务无法正常启动，可以进入“事件”页面查看错误原因是否存在资源不足、网络超时等提示。或者检查日志中，根据具体报错情况，调整模型配置或训练脚本，并重新提交任务。

3.3权重转换(megatron--->hf)

注意：该步骤可以根据客户的具体需要省略或训练完毕并保存权重后执行。

3.3.1 全参微调

#以下命令用于将全参微调后的Qwen2.5-VL-32B-Instruct权重转换为Huggingface格式
python checkpoint/convert_cli.py Qwen2_5_VLConverter mm_to_hf \
--cfg.save_hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct-Full" \# 新的hf模型格式的目录
--cfg.mm_dir "./ckpt/qwen25vl_32b_full_tp2_pp8" \#全参微调后保存的权重目录
--cfg.hf_config.hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct" \#原始huggingface权重目录
--cfg.parallel_config.llm_pp_layers [4,7,8,9,9,9,9,9] \#需与2.2.4中切分方式一致
--cfg.parallel_config.vit_pp_layers [32,0,0,0,0,0,0,0] \#需与2.2.4中切分方式一致
--cfg.parallel_config.tp_size 2#需与2.2.4中切分方式一致

3.3.2LoRA微调

LoRA微调后的权重需要先使用权重合并工具merge_lora.py将LoRA权重merge进原始megatron权重，然后通过3.3.1中类似全参微调的方式将合并后的权重转换为Huggingface格式。

修改examples/qwen2vl/merge_lora.py中的权重路径：

if __name__ =='__main__':
    base_save_dir ="./model_weights/qwen25vl_32b_tp4_pp1"#原始megatron格式权重路径
    lora_save_dir ="./ckpt/qwen25vl_32b_lora_tp4_pp1"#训练好的lora权重路径
    merge_save_dir ="./ckpt/qwen25vl_32b_lora_merge_tp4_pp1"#合并后的megatron权重路径
    lora_target_modules =['linear_qkv','linear_proj','linear_fc1','linear_fc2']

    lora_alpha =16#lora参数，与微调时的参数一致
    lora_r =8#lora参数，与微调时的参数一致
    scaling = lora_alpha / lora_r

# PP parameters: 72B
    pp_size =1#pp与微调时的参数一致
    tp_size =4#tp与微调时的参数一致

    use_npu =True
    merge_model(base_save_dir, lora_save_dir, merge_save_dir, pp_size, tp_size)
print('Finished!')

进行最后的权重转化：

#以下命令用于将LoRA权重合并后的Qwen2.5-VL-32B-Instruct权重转换为Huggingface格式
python checkpoint/convert_cli.py Qwen2_5_VLConverter mm_to_hf \
--cfg.save_hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct-LoRA" \ # 新的hf模型格式的目
--cfg.mm_dir "./ckpt/qwen25vl_32b_lora_merge_tp4_pp1" \ #合并后的megatron权重目录
--cfg.hf_config.hf_dir "./model_from_hf/Qwen2.5-VL-32B-Instruct" \ #原始huggingface权重目录
--cfg.parallel_config.llm_pp_layers [64] \ #需与2.2.4中切分方式一致
--cfg.parallel_config.vit_pp_layers [32] \ #需与2.2.4中切分方式一致
--cfg.parallel_config.tp_size 4#需与2.2.4中切分方式一致

四、总结

通过本文档的实践操作，用户可以熟练掌握平台多模态图文理解模型训练的关键流程，包括环境搭建、代码管理、镜像管理、数据处理、权重转换以及单机和多机训练等核心任务。在实际操作中，如果遇到任何问题，可以结合日志信息和平台提供的工具进行排查和优化。随着平台功能的持续升级和优化，相信在未来，用户将能够更加高效地完成大模型的训练任务，并不断探索和应用前沿的人工智能技术。

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

训推服务

训推服务

一、引言

二、训练准备

2.1 开发机

2.1.1 配置开发机

2.1.2 打开IDE

2.1.3 打开终端

2.1.4 镜像制作

2.2 模型准备

2.2.1 代码下载

2.2.2 环境搭建

2.2.3 权重下载

2.2.4 权重转换(hf--->megatron)

2.3 数据集准备

2.3.1 数据集下载(以coco2017数据集为例)

2.3.2 数据集预处理

三、模型训练

3.1 开发机-单机训练

3.1.1 模型以及数据文件修改

3.1.2 训练脚本准备

3.1.3 配置分布式参数

3.1.4 启动训练

3.2 训练任务-多机训练

3.2.1 模型以及数据文件修改

3.2.2 训练脚本准备

3.2.3 创建任务

3.2.4 配置任务

3.2.5 监控任务

3.3权重转换(megatron--->hf)

3.3.1 全参微调

3.3.2LoRA微调

四、总结

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

训推服务

训推服务

一、引言

二、训练准备

2.1 开发机

2.1.1 配置开发机

2.1.2 打开IDE

2.1.3 打开终端

2.1.4 镜像制作

2.2 模型准备

2.2.1 代码下载

2.2.2 环境搭建

2.2.3 权重下载

2.2.4 权重转换(hf--->megatron)

2.3 数据集准备

2.3.1 数据集下载(以coco2017数据集为例)

2.3.2 数据集预处理

三、模型训练

3.1 开发机-单机训练

3.1.1 模型以及数据文件修改

3.1.2 训练脚本准备

3.1.3 配置分布式参数

3.1.4 启动训练

3.2 训练任务-多机训练

3.2.1 模型以及数据文件修改

3.2.2 训练脚本准备

3.2.3 创建任务

3.2.4 配置任务

3.2.5 监控任务

3.3权重转换(megatron--->hf)

3.3.1 全参微调

3.3.2LoRA微调

四、总结