MindSpeed MM CANN 安装路径批量替换指南

背景

出海版本中，CANN/HDK 的默认安装路径已由 /usr/local/Ascend 变更为 /usr/local/npu。 MindSpeed MM 仓库中的训练脚本、安装文档等均使用了硬编码的 /usr/local/Ascend 路径。若出海版本机器上的实际安装路径为 /usr/local/npu，需在使用前完成批量替换，确保环境变量可以正常加载。

本指南提供使用 replace_ascend_path.py 脚本进行批量路径替换的完整步骤。

前置条件

Python 3.7+
拥有仓库目录的读写权限
建议在执行替换前，先通过 git 将当前状态提交或备份

受影响的文件范围

文件类型	说明	典型路径示例
Shell 脚本（`.sh`）	训练/测试启动脚本	`examples//pretrain_.sh`、`scripts/install.sh`
Markdown 文档（`.md`）	安装指南、模型使用说明	`docs/zh/install_guide.md`、`docker/OVERVIEW.md`
RST 文档（`.rst`）	用户指南	`UserGuide/quick_start/环境搭建.rst`
Python 文件（`.py`）	源码（如有路径引用）	各模块源文件
Dockerfile	Docker 镜像构建脚本	`docker/Dockerfile`

路径变体说明：仓库中存在以下几种 Ascend 路径引用，均会被一并替换：

/usr/local/Ascend/cann/set_env.sh（最常见，环境变量初始化）

/usr/local/Ascend/ascend-toolkit/set_env.sh（Ascend Toolkit 初始化）

/usr/local/Ascend/nnal/atb/set_env.sh（ATB 库初始化）

/usr/local/Ascend/driver/lib64/（Docker 挂载路径）

使用步骤

第一步：进入仓库根目录

cd /path/to/MindSpeed-MM

第二步：预览将要修改的内容（推荐）

在实际修改前，先以 --dry-run 模式确认变更范围：

python3 scripts/replace_ascend_path.py --dry-run

输出示例：

[DRY RUN] Path replacement: /usr/local/Ascend -> /usr/local/npu
Scan directory : /path/to/MindSpeed-MM
File types     : .md, .py, .rst, .sh + Dockerfile
------------------------------------------------------------
Found XXX candidate file(s), processing...

  [would replace   1] UserGuide/dev_guide/新模型开发.rst
  [would replace   1] UserGuide/quick_start/Qwen3VL-30B-MoE模型微调实践.rst
  ...

============================================================
[DRY RUN] XXX file(s) would be modified, XXX replacement(s) total.
          Remove --dry-run to apply changes.

第三步：执行批量替换

确认预览无误后，执行实际替换：

# 默认：将 /usr/local/Ascend 替换为 /usr/local/npu
python3 scripts/replace_ascend_path.py

执行完毕后，脚本会输出修改的文件数和替换总次数。

第四步：验证替换结果

# 检查是否还有未替换的路径（结果应为 0）
grep -r "/usr/local/Ascend" . \
  --include='*.sh' --include='*.md' --include='*.rst' --include='*.py' \
  --exclude-dir='.git' | wc -l

执行后验证

1. 环境变量加载验证

# 验证新路径下的 set_env.sh 文件存在
ls /usr/local/npu/ascend-toolkit/set_env.sh

# 加载环境变量
# 根据实际情况修改 ascend-toolkit 路径
source /usr/local/npu/ascend-toolkit/set_env.sh

# 验证环境变量生效
echo $ASCEND_HOME_PATH

2. 组件安装验证

# 安装 MindSpeed MM
pip install -e .

# 验证安装成功
python3 -c "import mindspeed_mm; print('MindSpeed MM installed successfully')"

# 验证 NPU 可用
python3 -c "import torch_npu; print('NPU available:', torch_npu.npu.is_available())"

3. 核心功能冒烟验证

参考对应模型的readme进行配置，验证训练流程可正常启动

source /usr/local/npu/ascend-toolkit/set_env.sh

# 运行示例脚本（以具体模型为准）
bash examples/<model_name>/pretrain_<model_name>.sh

完整脚本参数说明

usage: replace_ascend_path.py [-h] [--source SOURCE] [--target TARGET]
                               [--dir DIR] [--extensions EXT [EXT ...]]
                               [--dry-run]

选项：
  -h, --help            显示帮助信息
  --source SOURCE       源路径（默认：/usr/local/Ascend）
  --target TARGET       目标路径（默认：/usr/local/npu）
  --dir DIR             扫描目录（默认：当前目录 .）
  --extensions EXT...   文件扩展名白名单（默认：.sh .md .rst .py）
  --dry-run             仅预览变更，不修改文件