一、引言

本最佳實踐文檔旨在為用戶提供一個全面、高效的多模態圖文理解模型訓練樣例，涵蓋從單機訓練到多機分布式訓練的全過程。通過系統化的步驟指引，用戶可以快速熟悉并掌握在平臺上進行多模態圖文理解模型訓練的操作流程，并高效完成訓練任務。無論是單機訓練還是多機分布式訓練，本最佳實踐文檔均提供了詳細的操作步驟與注意事項，幫助用戶快速上手并解決可能遇到的問題。

二、訓練準備

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 //gitee.com/ascend/MindSpeed-MM.git 
git clone //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 //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文件夾中
#下載地址://cocodataset.org/#download

#(2)獲取圖片數據集的描述文件（LLaVA-Instruct-150K），下載至./data/路徑下，和第(1)步的COCO2017文件夾放同一路徑下
#下載地址://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 模型以及數據文件修改

修改對應的參數文件：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中的相應位置，修改方式與3.1.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中切分方式一致

四、總結

通過本文檔的實踐操作，用戶可以熟練掌握平臺多模態圖文理解模型訓練的關鍵流程，包括環境搭建、代碼管理、鏡像管理、數據處理、權重轉換以及單機和多機訓練等核心任務。在實際操作中，如果遇到任何問題，可以結合日志信息和平臺提供的工具進行排查和優化。隨著平臺功能的持續升級和優化，相信在未來，用戶將能夠更加高效地完成大模型的訓練任務，并不斷探索和應用前沿的人工智能技術。