权重转换命令行工具

新版权重转换接口 2025/1/20引入，当前支持qwen2vl各规格模型转换。

权重转换接口在pyproject.toml中定义了如下命令行参数，因此在按照readme安装完mindspeed-mm后当前环境中即可执行mm-convert命令行工具。

[project.scripts]
mm-convert = "checkpoint.convert_cli:main"

使用方式：

[root@node-xx-xx MindSpeed-MM]# mm-convert  -h
usage: mm-convert [-h] [--config CONFIG] [--print_config[=flags]] {Qwen2VLConverter,InternVLConverter} ...

options:
  -h, --help            Show this help message and exit.
  --config CONFIG       Path to a configuration file.
  --print_config[=flags]
                        Print the configuration after applying all other arguments and exit. The optional flags customizes the output and are one or more
                        keywords separated by comma. The supported flags are: comments, skip_default, skip_null.

subcommands:
  For more details of each subcommand, add it as an argument followed by --help.

  Available subcommands:
    Qwen2VLConverter    Qwen2VL模型转换工具
    InternVLConverter   InternVL2.5/InternVL3模型转换工具

可用到其中支持的子命令包括Qwen2VLConverter、InternVLConverter。

继续对Qwen2VLConverter命令进行help可以看到

[root@node-xx-xx MindSpeed-MM]# mm-convert  Qwen2VLConverter -h
usage: mm-convert [options] Qwen2VLConverter [-h] [--config CONFIG] [--print_config[=flags]] {hf_to_mm,mm_to_hf,resplit} ...
...
subcommands:
  For more details of each subcommand, add it as an argument followed by --help.

  Available subcommands:
    hf_to_mm            模型转换mindspeed-mm模型权重
    mm_to_hf            mindspeed-mm模型转换模型权重
    resplit             mindspeed-mm模型权重重新切分

继续对子命令hf_to_mm命令进行help可以看到具体的参数

mm-convert  Qwen2VLConverter hf_to_mm -h

传参方式

支持三种传参方式：

命令行参数

mm-convert  Qwen2VLConverter hf_to_mm \
  --cfg.mm_dir "mm/Qwen2-VL-7B-Instruct" \
  --cfg.hf_config.hf_dir "hf/Qwen2-VL-7B-Instruct" \
  --cfg.parallel_config.llm_pp_layers [[1,10,10,7]] \
  --cfg.parallel_config.vit_pp_layers [[32,0,0,0]] \
  --cfg.parallel_config.tp_size 1

yaml文件

yaml配置文件可自动生成基础版本，然后手动修改必要的配置

 mm-convert  Qwen2VLConverter hf_to_mm --print_config=comments > hf_to_mm.yaml

会生成如下配置文件

# Hugging Face模型转换mindspeed-mm模型权重

# Hugging Face权重转换为mindspeed-mm权重配置
cfg:

  # mm保存的路径 (required, type: <class 'Path'>)
  mm_dir:

  # 并行配置
  parallel_config:

    # llm模块pipeline parallel切分每张卡上切分几层 (required, type: list[list[Annotated[int, Ge(ge=0)]]])
    llm_pp_layers:

    # vit模块pipeline parallel切分每张卡上切分几层 (required, type: list[list[Annotated[int, Ge(ge=0)]]])
    vit_pp_layers:

    # tensor parallel张量并行组，模型转换时不同的tp组要切分到不同的目录下 (type: Annotated[int, Gt(gt=0)], default: 1)
    tp_size: 1

  # hf下载的原始权重路径配置
  hf_config:

    # Hugging Face下载的路径 (required, type: Annotated[Path, PathType(path_type='dir')])
    hf_dir:

修改配置文件中的内容

# Hugging Face模型转换mindspeed-mm模型权重

# Hugging Face权重转换为mindspeed-mm权重配置
cfg:

  # mm保存的路径 (required, type: <class 'Path'>)
  mm_dir: "mm/Qwen2-VL-7B-Instruct"

  # 并行配置
  parallel_config:

    # llm模块pipeline parallel切分每张卡上切分几层 (required, type: list[Annotated[int, Ge(ge=0)]])
    llm_pp_layers: [[1,10,10,7]]

    # vit模块pipeline parallel切分每张卡上切分几层 (required, type: list[Annotated[int, Ge(ge=0)]])
    vit_pp_layers: [[32,0,0,0]] 

    # tensor parallel张量并行组，模型转换时不同的tp组要切分到不同的目录下 (type: Annotated[int, Gt(gt=0)], default: 1)
    tp_size: 1

  # hf下载的原始权重路径配置
  hf_config:

    # Hugging Face下载的路径 (required, type: Annotated[Path, PathType(path_type='dir')])
    hf_dir: "hf/Qwen2-VL-7B-Instruct"

执行转换脚本

mm-convert  Qwen2VLConverter hf_to_mm --config hf_to_mm.yaml

环境变量

环境变量模式当前默认未开启，如需开启可以使用配置环境变量
```
 export JSONARGPARSE_DEFAULT_ENV=true
```
使用-h命令可以查看每个配置对应的环境变量
```
mm-convert  Qwen2VLConverter hf_to_mm -h
```

配置环境变量

export MM_CONVERT_QWEN2VLCONVERTER__HF_TO_MM__CFG__PARALLEL_CONFIG__LLM_PP_LAYERS="[[1,10,10,7]]"
export MM_CONVERT_QWEN2VLCONVERTER__HF_TO_MM__CFG__PARALLEL_CONFIG__VIT_PP_LAYERS="[[32,0,0,0]]"
export MM_CONVERT_QWEN2VLCONVERTER__HF_TO_MM__CFG__PARALLEL_CONFIG__TP_SIZE="1"
export MM_CONVERT_QWEN2VLCONVERTER__HF_TO_MM__CFG__HF_CONFIG__HF_DIR="Qwen2-VL-7B-Instruct"
export MM_CONVERT_QWEN2VLCONVERTER__HF_TO_MM__CFG__MM_DIR="hf/Qwen2-VL-7B-Instruct"

执行
```
mm-convert  Qwen2VLConverter hf_to_mm
```

权重转换注意事项

如果在权重转换过程中发生错误，请从Hugging Face等网站下载最新权重并重新转换。如问题仍然存在，请提交issue，我们会第一时间为您解答。

为什么需要下载最新权重？

权重转换过程中会调用transformers的相关API（如AutoConfig）。随着transformers版本的升级，旧版本权重文件可能与新版本的transformers不兼容，因此建议使用最新权重以确保转换成功。