作者：昇腾实战派，Gary13

原模型仓：https://gitcode.com/Ascend/MindSpeed-MM/blob/master/examples/qwen2.5vl/README.md

1 环境准备

​参考文档：https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/user-guide/installation.md

1.1 版本配套

本次实验使用如下版本配套：

模型开发时推荐配套的版本一般包含依赖如下：

1.2 驱动固件安装

驱动固件下载地址：https://www.hiascend.com/hardware/firmware-drivers/community?product=4&model=26&cann=8.2.RC1&driver=Ascend+HDK+25.2.0

安装NPU驱动固件参考文档：https://www.hiascend.com/document/detail/zh/canncommercial/82RC1/softwareinst/instg/instg_0005.html?Mode=PmIns&InstallType=local&OS=Debian&Software=cannToolKit

1.2.1 进入社区版下载地址，下载.run驱动和固件

1.2.2 安装前检查

用户可使用如下命令查询当前环境是否安装驱动，若返回驱动相关信息说明已安装。

• 首次安装场景：硬件设备刚出厂时未安装驱动，或者硬件设备前期安装过驱动和固件但是当前已卸载，上述场景属于首次安装场景，需按照​“驱动 > 固件”​的顺序安装驱动和固件。
• 覆盖安装场景：硬件设备前期安装过驱动和固件且未卸载，当前要再次安装驱动和固件，此场景属于覆盖安装场景，需按照​“固件 > 驱动”​的顺序安装。

1.2.3 准备用户

• 以root用户安装驱动、固件。
• 以非root用户HwHiAiUser（驱动固件的默认运行用户）为运行用户。

执行如下示例命令，创建HwHiAiUser用户和用户组：### 1.2.3 安装驱动固件

1. 以root用户登录安装环境，将驱动包和固件包上传到安装环境的任意目录如“/home”。
2. 进入软件包所在目录，执行如下命令增加执行权限。
3. 安装驱动和固件，软件包默认安装路径为“/usr/local/Ascend”。

   1. 执行如下命令安装驱动。

      若系统出现如下关键回显信息，则表示驱动安装成功。

   2. 执行如下命令安装固件。
      若系统出现如下关键回显信息，表示固件安装成功。

4. 根据系统提示信息决定是否重启系统，若需要重启，请执行以下命令；否则，请跳过此步骤。
5. 执行如下命令查看驱动加载是否成功

2 CANN安装

CANN下载地址：https://www.hiascend.com/developer/download/community/result?module=pt+cann&pt=7.1.0&cann=8.2.RC1&product=4&model=32

安装参考文档：https://www.hiascend.com/document/detail/zh/canncommercial/82RC1/softwareinst/instg/instg_0008.html?Mode=PmIns&InstallType=local&OS=Debian&Software=cannToolKit

2.1 CANN下载安装

选择推荐的CANN8.2版本，npu是arm64位系统，筛选出.run格式文件，本地PC分别下载toolkit、nnal、kernaels三个文件，通过Xshell上传至对应服务器某个路径下。

2.2 安装依赖

安装前需确保已具备Python环境及pip3，当前CANN支持Python3.7.x至3.11.4版本，若不满足可执行以下命令安装。

2.3 安装Toolkit开发套件包

1. 增加对软件包的可执行权限，以aarch64架构为例。

2. 安装软件包（安装命令支持–install-path=​ ​ 等参数，具体使用方式请参见参数说明）。

   如果用户未指定安装路径，则软件会安装到默认路径下，默认安装路径如下。root用户：“/usr/local/Ascend”，非root用户：“​*$HOME\ast /Ascend”，\ast${HOME}​*为当前用户目录。

3. 配置环境变量，当前以非root用户安装后的默认路径为例，请用户根据set_env.sh的实际路径执行如下命令。

   上述环境变量配置只在当前窗口生效，用户可以按需将以上命令写入环境变量配置文件（如.bashrc文件）。

2.4 安装Kernels算子包

​CANN二进制算子包​，包括单算子API执行（例如aclnn类API）动态库/静态库文件，以及kernel二进制文件。

Kernels算子包安装之前，需已安装配套版本的Toolkit并配置环境变量。

2.5 安装NNAL神经网络加速库

NNAL神经网络加速库中提供了ATB（Ascend Transformer Boost）加速库和SiP（AscendSiPBoost）信号处理加速库。

加速库安装之前，需已安装同一版本的Toolkit并配置环境变量。

1. 增加对软件包的可执行权限，以aarch64架构为例。

2. 安装软件包（安装命令支持–install-path= 等参数，具体使用方式请参见 参数说明）。

   如果用户未指定安装路径，则软件会安装到默认路径下，默认安装路径如下。root用户：“/usr/local/Ascend”，非root用户：“​*$HOME\ast /Ascend”，\ast${HOME}​*为当前用户目录。

3. 配置环境变量，当前以非root用户安装后的默认路径为例，请用户根据加速库对应的set_env.sh的实际路径进行替换。
   需注意，不支持同时配置ATB和SiP的环境变量脚本。* ATB加速库：

   • SiP加速库：

   上述环境变量配置只在当前窗口生效，用户可以按需将以上命令写入环境变量配置文件（如.bashrc文件）。

如需同时安装静态库，请将**–install变更为–devel**参数，执行以上命令。

3 PTA安装

3.1 安装conda，进入conda虚拟环境

3.2 安装pytorch和torch_npu

注意：torch和torch_npu的版本需保持一致。

参考安装文档：https://www.hiascend.com/document/detail/zh/Pytorch/710/configandinstg/instg/insg_0004.html

3.2.1 安装pytorch

• 以二进制包形式安装，命令如下：

• 或者直接pip指令安装即可（可选）

3.2.2 安装torch_npu插件

3.2.3 验证是否安装成功

• 输入：
• 输出如下类似信息说明PyTorch框架与插件安装成功。

• 若未安装成功，按照指示安装相关python依赖包即可。

3.3 安装apex

apex安装参考文档：https://gitcode.com/Ascend/apex、

3.3.1 获取昇腾适配的Apex-patch源码

3.3.2 编译apex的二进制包

1、请确保torch已安装，setuptools版本小于等于65.7.0。推荐使用65.7.0，若安装其它版本请用户自行确保对应版本无重大漏洞。

2、执行（支持Python3.7-3.10，确保Python3.x命令存在）

过程中会自动拉取apex官方源码，请保证网络畅通，生成的二进制包在apex/dist目录下。

3.3.3 安装

进入apex/dist目录，执行以下命令：

如需要保存安装日志，可在pip3 install命令后面加上参数 --log <PATH>，并对您指定的目录<PATH>做好权限管控。

4 环境搭建

完成1-3基础环境准备后，执行如下命令搭建MindSpeed文件。

5 权重下载及转换

5.1 权重下载

• 模型地址: Qwen2.5-VL-3B；

将下载的模型权重保存到本地的ckpt/hf_path/Qwen2.5-VL-7B-Instruct目录下。

5.2 权重转换

MindSpeed-MM修改了部分原始网络的结构名称，使用mm-convert工具对原始预训练权重进行转换。该工具实现了huggingface权重和MindSpeed-MM权重的互相转换以及PP（Pipeline Parallel）权重的重切分。参考权重转换工具

6 数据集准备及处理

6.1 coco2017下载与处理

(1)用户需要自行下载COCO2017数据集COCO2017，并解压到项目目录下的./data/COCO2017文件夹中。

(2)获取图片数据集的描述文件（LLaVA-Instruct-150K），下载至./data/路径下。

(3)运行数据转换脚本python examples/qwen2vl/llava_instruct_2_mllm_demo_format.py，转换后参考数据目录结构如下：

7 微调训练

7.1 准备工作

配置脚本前需要完成前置准备工作，包括：​环境安装​、​权重下载及转换​、​数据集准备及处理​，详情可查看前面对应章节。

7.2 配置参数

【数据目录配置】

根据实际情况修改data.json中的数据集路径，包括model_name_or_path、dataset_dir、dataset等字段。

实例：如果数据及其对应的json都在/home/user/data/目录下，其中json目录为/home/user/data/video_data_path.json，此时配置如下： dataset_dir配置为/home/user/data/; dataset配置为./data/video_data_path.json 注意此时dataset需要配置为相对路径

以Qwen2.5VL-7B为例，data.json进行以下修改，注意model_name_or_path的权重路径为转换前的权重路径。

7.3 启动微调训练

loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式vlm_model_loss_calculate_type.md

微调已调通，如图下：