Qwen3_5 使用指南
目录
版本说明
参考实现
url=https://github.com/huggingface/transformers.git
commit_id=fc91372
变更记录
2026.02.10: 首次支持Qwen3_5模型
环境安装
1. 环境准备
【模型开发时推荐使用配套的环境版本】
请参考安装指南，完成昇腾软件安装。
Python版本推荐3.10，torch和torch_npu版本推荐2.7.1版本，CANN推荐使用8.5.2版本；
‼️MoE部分的加速特性依赖较新版本的torch_npu和CANN，推荐使用以下版本
2. 环境搭建
拉取MindSpeed MM代码仓，并进入代码仓根目录：
git clone --branch 26.0.0 https://gitcode.com/Ascend/MindSpeed-MM.git
cd MindSpeed-MM
执行如下指令一键安装：
bash scripts/install.sh --msid eb10b92 && bash examples/qwen3_5/install_extensions.sh
权重下载及转换
1. 权重下载
从Huggingface库下载对应的模型权重:
- 模型地址: Qwen3.5-*B；
将下载的模型权重保存到本地的ckpt/hf_path/xxxxxxx目录下。(*表示对应的尺寸)
如果使用fsdp2的meta init初始化模型，需要先根据模型类型完成以下权重转换：
(1) 4B模型：
mm-convert Qwen35Converter hf_to_dcp \
--hf_dir ckpt/hf_path/xxxxxxx \
--dcp_dir ckpt/dcp_path/xxxxxxx \
--tie_weight_mapping '{"lm_head.weight":"model.language_model.embed_tokens.weight"}'
# 转换后的目录结构为：
# ———— xxxxxxx
# |—— release
# |—— latest_checkpointed_iteration.txt
(2) 其它模型:
mm-convert Qwen35Converter hf_to_dcp \
--hf_dir ckpt/hf_path/xxxxxxx \
--dcp_dir ckpt/dcp_path/xxxxxxx
# 转换后的目录结构为：
# ———— xxxxxxx
# |—— release
# |—— latest_checkpointed_iteration.txt
并在xxx_config.yaml中将init_model_with_meta_device参数配置为True，同时将load参数修改为转换后的dcp权重路径（写到release文件夹的上一级目录）。
MindSpeed MM保存权重的格式也为dcp格式。可使用如下命令将dcp权重转换回HF权重
# 待转换的dcp权重目录结构样例为：
# ———— xxxxxxx
# |—— release
# |—— latest_checkpointed_iteration.txt
mm-convert Qwen35Converter dcp_to_hf \
--save_hf_dir ckpt/save_hf_path/Qwen3.5-xxB-hf-save \
--dcp_dir ckpt/dcp_path/xxxxxxx/release \
--origin_hf_dir ckpt/hf_path/Qwen3.5-xxB
数据集准备及处理
1. 数据集下载(以coco2017数据集为例)
(1)用户需要自行下载COCO2017数据集COCO2017，并解压到项目目录下的./data/COCO2017文件夹中。
(2)获取图片数据集的描述文件（LLaVA-Instruct-150K），下载至./data/路径下。
(3)运行数据转换脚本python examples/qwen2vl/llava_instruct_2_mllm_demo_format.py，转换后参考数据目录结构如下：
$playground
├── data
├── COCO2017
├── train2017
├── llava_instruct_150k.json
├── mllm_format_llava_instruct_data.json
...
当前支持读取多个以,（注意不要加空格）分隔的数据集，配置方式为相应xxx_config.yaml中
data->dataset_param->basic_parameters->dataset
从"./data/mllm_format_llava_instruct_data.json"修改为"./data/mllm_format_llava_instruct_data.json,./data/mllm_format_llava_instruct_data2.json"
同时注意data->dataset_param->basic_parameters->max_samples的配置，会限制数据只读max_samples条，这样可以快速验证功能。如果正式训练时，可以把该参数去掉则读取全部的数据。
2.纯文本或有图无图混合训练数据(以LLaVA-Instruct-150K为例)
现在本框架已经支持纯文本/混合数据（有图像和无图像数据混合训练）。
在数据构造时，对于包含图片的数据，需要保留image这个键值。
{
"id": your_id,
"image": your_image_path,
"conversations": [
{"from": "human", "value": your_query},
{"from": "gpt", "value": your_response},
],
}
在数据构造时，对于纯文本数据，可以去除image这个键值。
{
"id": your_id,
"conversations": [
{"from": "human", "value": your_query},
{"from": "gpt", "value": your_response},
],
}
微调
1. 准备工作
配置脚本前需要完成前置准备工作，包括：环境安装、权重下载及转换、数据集准备及处理，详情可查看对应章节。
2. 配置参数
【数据目录配置】
根据实际情况修改xxx_config.yaml中的数据集路径，包括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需要配置为相对路径
注意cache_dir在多机上不要配置同一个挂载目录避免写入同一个文件导致冲突。
【模块冻结配置】
当前支持自定义冻结模块，在xxx_config.yaml中model->freeze字段中配置需要冻结的模块即可实现相应模块冻结。
【模型保存加载及日志信息配置】
根据实际情况配置xxx_config.yaml的training参数，包括保存路径以及保存间隔save、save_interval
根据实际情况配置xxx_config.yaml中的init_from_hf_path参数，该参数表示初始权重的加载路径。
【ulysses-cp并行配置】
根据实际情况配置xxx_config.yaml中的ulysses_parallel_size以调整ulysses-cp的并行度。（ulysses_parallel_size为1时不开启ulysses-cp）
注意在开启ulysses-cp时，请将xxx_config.yaml中的attn_implementation配置为flash_attention_2
【单机运行配置】
以qwen3_5模型为例：
配置examples/qwen3_5/finetune_qwen3_5.sh参数如下
# 根据实际情况修改 ascend-toolkit 路径
source /usr/local/Ascend/ascend-toolkit/set_env.sh
NPUS_PER_NODE=8
MASTER_ADDR=localhost
MASTER_PORT=6000
NNODES=1
NODE_RANK=0
WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))
【多机运行配置】 如需拉起多机训练，修改启动脚本下 MASTER_ADDR、NODE_ADDR、NODES以及NODE_RANK变量
MASTER_ADDR: 主节点IP地址
NODE_ADDR: 本机IP地址
NODE_RANK: 第几个节点
NODES: 一共几个节点
3. 启动微调
loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式vlm_model_loss_calculate_type.md
可在xxx_config.yaml的model参数中配置上述文档中的loss_type。
bash examples/qwen3_5/finetune_qwen3_5_xxB.sh
环境变量声明
| 环境变量 | 描述 | 取值说明 |
|---|---|---|
ASCEND_SLOG_PRINT_TO_STDOUT |
是否开启日志打印 | 0: 关闭日志打屏1: 开启日志打屏 |
ASCEND_GLOBAL_LOG_LEVEL |
设置应用类日志的日志级别及各模块日志级别，仅支持调试日志 | 0: 对应DEBUG级别1: 对应INFO级别2: 对应WARNING级别3: 对应ERROR级别4: 对应NULL级别，不输出日志 |
TASK_QUEUE_ENABLE |
用于控制开启task_queue算子下发队列优化的等级 | 0: 关闭1: 开启Level 1优化2: 开启Level 2优化 |
COMBINED_ENABLE |
设置combined标志。设置为0表示关闭此功能；设置为1表示开启，用于优化非连续两个算子组合类场景 | 0: 关闭1: 开启 |
CPU_AFFINITY_CONF |
控制CPU端算子任务的处理器亲和性，即设定任务绑核 | 设置0或未设置: 表示不启用绑核功能1: 表示开启粗粒度绑核2: 表示开启细粒度绑核 |
HCCL_CONNECT_TIMEOUT |
用于限制不同设备之间socket建链过程的超时等待时间 | 需要配置为整数，取值范围[120,7200]，默认值为120，单位s |
PYTORCH_NPU_ALLOC_CONF |
控制缓存分配器行为 | expandable_segments:<value>: 使能内存池扩展段功能，即虚拟内存特征 |
HCCL_EXEC_TIMEOUT |
控制设备间执行时同步等待的时间，在该配置时间内各设备进程等待其他设备执行通信同步 | 需要配置为整数，取值范围[68,17340]，默认值为1800，单位s |
ACLNN_CACHE_LIMIT |
配置单算子执行API在Host侧缓存的算子信息条目个数 | 需要配置为整数，取值范围[1, 10,000,000]，默认值为10000 |
TOKENIZERS_PARALLELISM |
用于控制Hugging Face的transformers库中的分词器（tokenizer）在多线程环境下的行为 | False: 禁用并行分词True: 开启并行分词 |
MULTI_STREAM_MEMORY_REUSE |
配置多流内存复用是否开启 | 0: 关闭多流内存复用1: 开启多流内存复用 |
NPU_ASD_ENABLE |
控制是否开启Ascend Extension for PyTorch的特征值检测功能 | 设置0或未设置: 关闭特征值检测1: 表示开启特征值检测，只打印异常日志，不告警2:开启特征值检测，并告警3:开启特征值检测，并告警，同时会在device侧info级别日志中记录过程数据 |
ASCEND_LAUNCH_BLOCKING |
控制算子执行时是否启动同步模式 | 0: 采用异步方式执行1: 强制算子采用同步模式运行 |
NPUS_PER_NODE |
配置一个计算节点上使用的NPU数量 | 整数值（如 1, 8 等） |