메뉴
Provides detailed procedures for setting up Ascend NPU development environment. Invoke when installing Ascend drivers, CANN toolkit, torch\_npu, or resolving environment compatibility issues.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | migration-ascend-torchnpu-skills-environment-setup |
| description | Provides detailed procedures for setting up Ascend NPU development environment. Invoke when installing Ascend drivers, CANN toolkit, torch\_npu, or resolving environment compatibility issues. |
你是一位专注于昇腾NPU环境配置的工程师。本Skill提供从驱动安装到Python环境配置的完整操作流程。
- MUST 优先采用昇腾官方Docker镜像搭建环境，避免手动安装带来的依赖问题 - MUST 优先保持原项目PyTorch版本不变；若与昇腾不兼容，则采用昇腾支持的最新版本 - MUST 保持torch_npu版本与PyTorch版本严格对应 - NEVER 在未验证版本兼容性的情况下安装软件包 - MUST 记录每一步操作命令，用于迁移报告 - MUST 使用pip安装时优先指定第三方镜像源（如阿里源、清华源），仅在镜像源失败时回退至pip默认源 - MUST 优先使用镜像站或ModelScope获取模型/数据集资源，NEVER默认使用HuggingFace官网；仅在用户明确确认网络可达HuggingFace时方可使用HuggingFace官网<version_notice> 本Skill中的版本配套信息基于编写时的最新数据。昇腾软件栈版本迭代较快，后续出现新版本时，MUST以昇腾官网发布的版本配套表为准：
⚠ 版本会持续更新，MUST实时访问上述官网链接获取最新版本配套关系，不可依赖本Skill中已固化的版本信息。 每次执行迁移任务时，应首选查阅官方文档获取最新版本信息，仅在无法访问官网时回退使用本Skill中的参考数据。 </version_notice>
以下数据来源于 torch_npu 官方仓库（gitcode.com/Ascend/pytorch），仅为编写时快照，新版本请查阅官方文档。
| CANN版本 | PyTorch版本 | torch_npu版本 | Python版本 | 备注 |
|---|---|---|---|---|
| CANN 9.0.0 | 2.10.0 | 2.10.0 | 3.9-3.13 | 最新版，支持Python3.13 |
| CANN 9.0.0 | 2.9.0 | 2.9.0.post2 | 3.9-3.12 | |
| CANN 9.0.0 | 2.8.0 | 2.8.0.post2 | 3.9-3.12 | |
| CANN 9.0.0 | 2.7.1 | 2.7.1.post3 | 3.9-3.11 | |
| CANN 8.5.2 | 2.9.0 | 2.9.0.post1 | 3.9-3.12 | |
| CANN 8.5.2 | 2.8.0 | 2.8.0.post1 | 3.9-3.11 | |
| CANN 8.5.2 | 2.7.1 | 2.7.1.post2 | 3.9-3.11 | |
| CANN 8.5.2 | 2.6.0 | 2.6.0.post6 | 3.9-3.11 | |
| CANN 8.5.1 | 2.9.0 | 2.9.0.post1 | 3.9-3.12 | |
| CANN 8.5.1 | 2.8.0 | 2.8.0.post1 | 3.9-3.11 | |
| CANN 8.5.1 | 2.7.1 | 2.7.1.post2 | 3.9-3.11 | |
| CANN 8.5.1 | 2.6.0 | 2.6.0.post6 | 3.9-3.11 | |
| CANN 8.5.0 | 2.9.0 | 2.9.0 | 3.9-3.12 | |
| CANN 8.5.0 | 2.8.0 | 2.8.0 | 3.9-3.11 | |
| CANN 8.5.0 | 2.7.1 | 2.7.1 | 3.9-3.11 | |
| CANN 8.5.0 | 2.6.0 | 2.6.0.post5 | 3.9-3.11 | |
| CANN 8.3.RC1 | 2.8.0 | 2.8.0 | 3.9-3.11 | |
| CANN 8.3.RC1 | 2.7.1 | 2.7.1 | 3.9-3.11 | |
| CANN 8.3.RC1 | 2.6.0 | 2.6.0.post3 | 3.9-3.11 | |
| CANN 8.2.RC1 | 2.6.0 | 2.6.0 | 3.9-3.11 | |
| CANN 8.2.RC1 | 2.5.1 | 2.5.1.post1 | 3.9-3.11 | |
| CANN 8.2.RC1 | 2.1.0 | 2.1.0.post13 | 3.8-3.11 | |
| CANN 8.1.RC1 | 2.5.1 | 2.5.1 | 3.9-3.11 | |
| CANN 8.1.RC1 | 2.4.0 | 2.4.0.post4 | 3.8-3.11 | |
| CANN 8.1.RC1 | 2.3.1 | 2.3.1.post6 | 3.8-3.11 | |
| CANN 8.1.RC1 | 2.1.0 | 2.1.0.post12 | 3.8-3.11 | |
| CANN 8.0.0 | 2.4.0 | 2.4.0.post2 | 3.8-3.11 | |
| CANN 8.0.0 | 2.3.1 | 2.3.1.post4 | 3.8-3.11 | |
| CANN 8.0.0 | 2.1.0 | 2.1.0.post10 | 3.8-3.11 | |
| CANN 7.0.0 | 2.1.0 | 2.1.0 | 3.8-3.10 | |
| CANN 7.0.0 | 2.0.1 | 2.0.1.post1 | 3.7-3.10 |
小版本迭代说明：实际使用时，CANN版本号可能会有小迭代（如 CANN 9.0.0 → CANN 9.0.1），此类小版本迭代通常保持与主版本的兼容性，可按照主版本（如9.0.0）的兼容性进行判断。但MUST在安装后通过
torch.npu.is_available()验证实际可用性。
以下数据来源于CANN社区版各版本说明文档（hiascend.com），仅为编写时快照。版本持续更新，MUST实时查阅官网获取最新对应关系： https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/releasenote/release-notes.md
| CANN版本 | 配套 Ascend HDK 版本 | 备注 |
|---|---|---|
| CANN 9.0.0 | 26.0.RC1 / 25.5.2 / 25.5.1 | 最新版 |
| CANN 8.5.2 | 25.5.x | — |
| CANN 8.5.1 | 25.5.x | — |
| CANN 8.5.0 | 25.5.x | — |
| CANN 8.3.RC1 | 25.x.x | — |
| CANN 8.2.RC1 | 25.2.0 | — |
| CANN 8.1.RC1 | 24.x.x | — |
| CANN 8.0.0 | 24.x.x | — |
| CANN 7.0.0 | 23.x.x | — |
说明：
- Ascend HDK 版本号即昇腾驱动固件版本号，驱动安装包文件名格式为
Ascend-hdk-{HDK版本}-npu-driver_linux-{arch}.run26.0.RC1中的 RC 表示 Release Candidate（发布候选版）- 同一CANN版本可能兼容多个HDK版本，以官网版本说明中的配套关系为准
- HDK版本与CANN版本之间的兼容性是单向的：必须先确定CANN版本，再确定配套的HDK版本
- ⚠ 版本会更新，上表仅作参考，MUST在官网实时查询： 通过访问对应CANN版本的版本说明页面（将URL中的版本号替换为目标版本），可查到该版本的精确配套HDK版本
场景：原项目使用 PyTorch 2.1.0
1. 查表：PyTorch 2.1.0 在多个CANN版本中均有支持
2. 选择策略：选择最新的CANN版本（8.2.RC1），对应的torch_npu为 2.1.0.post13
3. 查CANN-HDK对应关系：CANN 8.2.RC1 配套 Ascend HDK 25.2.0（见 1.1b 节表）
4. 确认驱动：需要安装 25.2.0 版本的昇腾驱动
场景：原项目使用 PyTorch 2.9.0
1. 查表：PyTorch 2.9.0 在 CANN 9.0.0/8.5.2/8.5.1/8.5.0 中均有支持
2. 选择策略：选择最新的CANN版本（9.0.0），对应的torch_npu为 2.9.0.post2
3. 查CANN-HDK对应关系：CANN 9.0.0 配套 Ascend HDK 26.0.RC1 / 25.5.2 / 25.5.1（见 1.1b 节表）
4. 确认驱动：需要安装 26.0.RC1 或 25.5.x 版本的昇腾驱动
场景：原项目使用 PyTorch 2.6.0
1. 查表：PyTorch 2.6.0 在 CANN 8.5.2/8.5.1/8.5.0/8.3.RC1/8.2.RC1 中均有支持
2. 选择策略：选择最新的CANN版本（8.5.2），对应的torch_npu为 2.6.0.post6
3. 查CANN-HDK对应关系：CANN 8.5.2 配套 Ascend HDK 25.5.x（见 1.1b 节表）
4. 确认驱动：需要安装 25.5.x 版本的昇腾驱动
MUST优先使用Docker镜像方式搭建环境。昇腾官方镜像已预集成CANN toolkit、kernels、NNAL等软件包和系统依赖，可大幅减少手动安装的工作量和出错概率。建议以最新版本的CANN镜像作为基础进行搭建。
从昇腾镜像仓库选择镜像：https://www.hiascend.com/developer/ascendhub
CANN基础镜像（推荐，最灵活）：
镜像仓库地址：swr.cn-south-1.myhuaweicloud.com/ascendhub/cann
具体Tag请查阅以下官方渠道（Tag随CANN版本持续更新）：
Tag命名规则：{CANN版本}-{芯片型号}-{OS}-py{Python版本}
镜像内已集成 Toolkit开发套件包、Kernels算子包、NNAL加速库，无需额外安装。
示例（以编写时可查到的Tag为例，新版本请查阅上述官方渠道）：
| Tag组成部分 | 可选值 | 说明 |
|---|---|---|
| CANN版本 | 8.5.0、8.1.rc1、9.0.0 等 | 选择与torch_npu匹配的CANN版本 |
| 芯片型号 | 910b、910c、310p、910、950 | 910C对应A3系列，其他请查阅昇腾官网 |
| OS | ubuntu22.04、openeuler24.03 | 建议选择Ubuntu版本 |
| Python版本 | py3.10、py3.11 | 选择与项目匹配的Python版本 |
芯片型号与产品系列的对应关系请查阅昇腾官方文档，不要自行推断
# 根据实际需求替换Tag，示例：CANN 8.5.0 + 910B + Ubuntu22.04 + Python3.10
# 具体Tag请查阅：https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884
# ARM架构（鲲鹏，推荐）
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10
# x86_64架构
docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10
宿主机MUST已安装昇腾驱动和固件，且Docker版本 >= 1.11.2。
# 查看镜像ID
docker images | grep ascendhub/cann
# 启动容器（MUST挂载NPU设备相关路径）
# 参考官方镜像说明：https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884
docker run --name npu_dev -dit --privileged --net=host --shm-size=500g \
-w /home \
--device=/dev/davinci0 \
--device=/dev/davinci1 \
--device=/dev/davinci2 \
--device=/dev/davinci3 \
--device=/dev/davinci4 \
--device=/dev/davinci5 \
--device=/dev/davinci6 \
--device=/dev/davinci7 \
--device=/dev/davinci_manager \
--device=/dev/devmm_svm \
--device=/dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /home:/home \
-v /data:/data \
-v /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime \
{镜像ID} \
bash
设备挂载参数说明：
| 参数 | 说明 |
|---|---|
--privileged | 开启特权模式，确保NPU设备完整可用 |
--device=/dev/davinci0~7 | 映射所有NPU卡（davinci0~davinci7） |
--device=/dev/davinci_manager | 映射NPU设备管理接口 |
--device=/dev/devmm_svm | 映射设备内存管理接口 |
--device=/dev/hisi_hdc | 映射主机与设备间通信接口 |
-v /usr/local/dcmi | 挂载DCMI工具和库 |
-v /usr/local/Ascend/driver/lib64/ | 挂载驱动库 |
-v /usr/local/Ascend/driver/version.info | 挂载驱动版本信息 |
-v /etc/ascend_install.info | 挂载驱动安装信息 |
容器内不建议使用conda或venv，直接使用pip管理Python环境即可，避免与容器内已有环境冲突。
# 先启动容器（后台运行）
docker start npu_dev
# 再进入容器
docker exec -it npu_dev bash
# 配置CANN环境变量（镜像内已安装CANN）
source /usr/local/Ascend/ascend-toolkit/set_env.sh
# 配置NNAL环境变量（CANN 8.1.RC1及以后版本需要）
source /usr/local/Ascend/nnal/atb/set_env.sh
# 安装PyTorch和torch_npu
# 优先从官方安装指南获取对应版本的下载链接
# 官方安装指南（MUST实时查阅昇腾官网最新版本文档，以下链接仅供参考）：
# 昇腾官网 → 文档 → PyTorch框架适配 → 软件安装指南 → 安装 → 使用二进制包安装
# 参考链接：https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md
# 根据目标PyTorch版本、架构(aarch64/x86_64)、Python版本，从上述文档查找对应的wget下载链接
# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：PyTorch 2.6.0 + aarch64 + Python 3.10 + CANN 8.5.0
pip install pyyaml setuptools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
wget https://download.pytorch.org/whl/cpu/torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
wget https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
# 方式2：pip直接安装（备选，网络通畅时使用）
# aarch64架构
# pip install torch==2.6.0
# x86_64架构
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
# pip install torch-npu==2.6.0.post5
# 验证
python -c "import torch; import torch_npu; print(torch.npu.is_available())"
-it 参数以交互模式启动，或使用 docker start 重新启动已停止的容器npu-smi info 无输出
→ 检查宿主机驱动是否安装，检查 --device=/dev/davinci_manager 是否添加torch.npu.is_available() 返回 False
→ 检查驱动库是否正确挂载：ls /usr/local/Ascend/driver/lib64/仅在无法使用Docker时采用手动安装方式。手动安装需依次完成：驱动安装 → CANN安装 → Python环境配置。
npu-smi info
uname -m
# aarch64 = ARM架构（鲲鹏）
# x86_64 = x86架构
首次安装按"驱动 > 固件"顺序；覆盖安装按"固件 > 驱动"顺序。
# 1. 创建驱动运行用户（如尚未创建）
groupadd HwHiAiUser
useradd -g HwHiAiUser -d /home/HwHiAiUser -m HwHiAiUser -s /bin/bash
# 2. 下载对应版本的驱动包
# https://www.hiascend.com/developer/download/community
# 3. 安装驱动（需要root权限）
# 根据CANN版本选择对应的驱动版本，查阅 1.1b CANN与Ascend HDK版本对应关系 和CANN版本说明中的配套HDK版本
chmod +x Ascend-hdk-xxx-npu-driver_linux-aarch64.run
./Ascend-hdk-xxx-npu-driver_linux-aarch64.run --full --install-for-all
# 4. 安装固件
chmod +x Ascend-hdk-xxx-npu-firmware_linux-aarch64.run
./Ascend-hdk-xxx-npu-firmware_linux-aarch64.run --full
# 5. 重启系统
reboot
# 6. 验证安装
npu-smi info
npu-smi info 无输出
→ 检查驱动是否安装成功，检查 /usr/local/Ascend/driver 目录是否存在HwHiAiUser 组：usermod -aG HwHiAiUser $USERapt-mark hold linux-image-generic linux-headers-generic# Ubuntu/Debian
apt-get update
apt-get install -y gcc g++ make cmake zlib1g zlib1g-dev openssl libsqlite3-dev libssl-dev libffi-dev unzip pciutils net-tools libblas-dev gfortran libblas3
# openEuler/EulerOS
yum install -y gcc gcc-c++ make cmake zlib zlib-devel openssl-devel sqlite-devel libffi-devel unzip pciutils net-tools blas-devel gfortran
安装toolkit前确保安装目录可用空间大于9G。MUST先安装toolkit再安装kernels。
# 下载CANN toolkit
# https://www.hiascend.com/developer/download/community
# 安装（根据实际CANN版本替换文件名）
chmod +x Ascend-cann-toolkit_linux-aarch64.run
./Ascend-cann-toolkit_linux-aarch64.run --install --install-for-all --quiet
chmod +x Ascend-cann-kernels_linux-aarch64.run
./Ascend-cann-kernels_linux-aarch64.run --install --install-for-all --quiet
source /usr/local/Ascend/ascend-toolkit/set_env.sh
echo "source /usr/local/Ascend/ascend-toolkit/set_env.sh" >> ~/.bashrc
source ~/.bashrc
cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
裸机环境建议使用conda管理Python环境；容器环境直接使用pip即可，不需要conda或venv。
# 裸机环境：使用conda创建环境（推荐）
conda create -n npu_env python=3.10 -y
conda activate npu_env
# 容器环境：直接使用pip，无需conda或venv
MUST优先从官方安装指南获取对应版本的wget下载链接： https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md
根据目标PyTorch版本、架构(aarch64/x86_64)、Python版本，从上述文档查找对应的下载链接。
# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：PyTorch 2.6.0 + aarch64 + Python 3.10
wget https://download.pytorch.org/whl/cpu/torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
# 示例：PyTorch 2.6.0 + x86_64 + Python 3.10
# wget https://download.pytorch.org/whl/cpu/torch-2.6.0%2Bcpu-cp310-cp310-linux_x86_64.whl
# pip install torch-2.6.0+cpu-cp310-cp310-linux_x86_64.whl
# 方式2：pip直接安装（备选，网络通畅时使用）
# aarch64架构（ARM/鲲鹏）
# pip install torch==2.6.0
# x86_64架构
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
MUST优先从官方安装指南获取对应版本的wget下载链接： https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md
torch_npu版本必须与PyTorch版本和CANN版本严格对应，从上述文档查找对应的下载链接。
pip install pyyaml setuptools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：torch_npu 2.6.0.post5 + aarch64 + Python 3.10
wget https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
# 方式2：pip直接安装（备选，网络通畅时使用）
# pip install torch-npu==2.6.0.post5
import torch
import torch_npu
print(f"PyTorch version: {torch.__version__}")
print(f"torch_npu version: {torch_npu.__version__}")
print(f"NPU available: {torch.npu.is_available()}")
if torch.npu.is_available():
print(f"NPU device count: {torch.npu.device_count()}")
print(f"NPU device name: {torch.npu.get_device_name(0)}")
x = torch.randn(3, 3).npu()
y = torch.randn(3, 3).npu()
z = x + y
print(f"NPU compute test passed: {z.shape}")
# CANN环境（MUST）
source /usr/local/Ascend/ascend-toolkit/set_env.sh
# torch_npu日志级别（可选，调试时设置）
export ASCEND_LOG_LEVEL=3 # 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR
# NPU可见设备（可选）
export ASCEND_RT_VISIBLE_DEVICES="0" # 只使用NPU:0
# 算子编译优化
export ASCEND_AICPU_PATH=/usr/local/Ascend/ascend-toolkit
export TASK_QUEUE_ENABLE=1
# 内存优化
export PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:32
# HCCL通信超时（分布式训练时建议设置）
export HCCL_CONNECT_TIMEOUT=1800
昇腾NPU服务器通常为ARM（aarch64）架构，部分第三方库的预编译wheel包可能不兼容，优先建议通过编译安装。
安装第三方库前，MUST从昇腾官网实时查阅最新版本的第三方库支持列表，优先使用昇腾已适配的版本，并严格按照其版本要求安装。昇腾已对部分主流第三方库进行了NPU适配，使用已适配的库可获得更好的性能和兼容性。
查阅路径：昇腾官网 → 文档 → PyTorch框架适配 → 第三方库适配 → 支持的套件和第三方库
参考链接（版本迭代较快，MUST以官网最新版本文档为准）：https://www.hiascend.com/document/detail/zh/Pytorch/2600/modthirdparty/modparts/FrameworkPTAdapter/26.0.0/zh/supported_suites_and_third_party_libraries/supported_suites_and_third_party_libraries.md
已知昇腾原生支持的第三方库包括（以官方文档为准）：
- transformers：
pip install transformers，原生支持Ascend NPU- accelerate：
pip install accelerate，原生支持Ascend NPU- peft：
pip install peft，原生支持Ascend NPU- trl：
pip install trl，原生支持Ascend NPU- deepspeed：需安装昇腾适配版本，参见官方文档
安装原则：
- 优先查阅上述官方文档，确认目标库是否已有昇腾适配版本
- 如有适配版本，严格按照官方文档的版本要求和安装指导操作
- 如无适配版本，再采用编译安装或pip安装方式
# 编译安装（ARM架构下pip可能无预编译包）
# 1. 下载FFmpeg源码
wget https://ffmpeg.org/releases/ffmpeg-8.1.tar.gz
tar -zxvf ffmpeg-8.1.tar.gz
# 2. 编译
cd ffmpeg-8.1
./configure --enable-shared
make -j$(nproc)
sudo make install
# 3. 验证
ffmpeg -version
git clone https://github.com/opencv/opencv.git -b 4.8.0 --depth 1
cd opencv && mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE \
-D CMAKE_INSTALL_PREFIX=/usr/local \
-D BUILD_opencv_python3=ON \
-D PYTHON3_EXECUTABLE=$(which python3) \
..
make -j$(nproc)
sudo make install
| 库名称 | aarch64安装建议 |
|---|---|
| numpy | pip install numpy 通常可直接安装 |
| scipy | pip install scipy 通常可直接安装；如失败需编译安装 |
| pillow | pip install pillow 通常可直接安装 |
| scikit-learn | pip install scikit-learn 通常可直接安装；如失败需编译安装 |
| onnx | pip install onnx 通常可直接安装 |
| onnxruntime | 需检查是否有aarch64预编译包；如无可从源码编译 |
| tokenizers | pip install tokenizers 通常可直接安装 |
| transformers | pip install transformers 通常可直接安装 |
git clone <repo_url> -b <version_tag> --depth 1
cd <repo_name>
pip install -e .
# 或
python setup.py build_ext --inplace
pip install .
NPU服务器通常位于内网环境，部分网站如HuggingFace、GitHub等可能无法访问或网速较慢。MUST优先使用镜像站或国内替代平台获取资源。
MUST优先使用以下方式获取模型/数据集，NEVER默认使用HuggingFace官网（仅在用户明确确认网络可达HuggingFace时方可使用）：
| 优先级 | 方式 | 说明 |
|---|---|---|
| 1 | ModelScope（https://www.modelscope.cn） | 国内平台，网络稳定，大量模型与HuggingFace等价 |
| 2 | HuggingFace镜像站（https://hf-mirror.com） | 设置 export HF_ENDPOINT=https://hf-mirror.com 后正常使用huggingface_hub |
| 3 | HuggingFace官网（https://huggingface.co） | 仅在用户明确确认网络可达时使用 |
ModelScope使用示例：
# 安装modelscope
pip install modelscope -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 从ModelScope下载模型（替代HuggingFace的from_pretrained）
from modelscope import snapshot_download
model_dir = snapshot_download('模型ID')
# 使用transformers加载ModelScope下载的模型
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(model_dir)
HuggingFace镜像站使用方式：
# 设置环境变量后，huggingface_hub会自动使用镜像站
export HF_ENDPOINT=https://hf-mirror.com
# 或在Python代码中设置
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
| 原始站点 | 镜像站 | 用法示例 |
|---|---|---|
| GitHub | https://bgithub.xyz | 将 github.com 替换为 bgithub.xyz，如 git clone https://bgithub.xyz/user/repo.git |
| GitHub | https://gitcode.com | 部分仓库在gitcode上有镜像 |
根据代码仓的 requirements.txt 安装依赖时，遵循以下原则：
# 1. 先尝试使用阿里源安装requirements.txt
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 如阿里源失败，尝试清华源
# pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 如镜像源均失败，回退至pip默认源
# pip install -r requirements.txt
# 2. 如遇版本冲突，逐个安装并记录
# 记录格式：包名 | 原要求版本 | 实际安装版本 | 是否有变更 | 变更原因
pip install package_name==specific_version -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 3. 如严格版本与torch_npu环境冲突，尝试放宽版本
# 示例：原要求 numpy==1.24.0，假设不兼容
# 放宽为 numpy>=1.24.0
pip install "numpy>=1.24.0" -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 记录：numpy | ==1.24.0 | >=1.24.0 | 是 | 与某某版本冲突
nvidia-* 库
→ 检查是否为硬依赖，如仅为可选加速则可忽略torch==x.y.z+cu118 等CUDA后缀
→ 替换为 torch==x.y.z（无CUDA后缀），安装后由torch_npu提供NPU支持source set_env.sh，导致找不到CANN库
→ 将 source 命令写入 ~/.bashrc 或虚拟环境激活脚本-dit 参数以交互+后台模式启动，先 docker start 再 docker exec -it 进入torch.npu.is_available() 返回 False
→ 启动容器时MUST添加 --device=/dev/davinci_manager 等参数，并挂载驱动库apt-mark hold linux-image-generic linux-headers-generic linux-image-extra
→ openEuler：yum install yum-plugin-versionlock && yum versionlock add kernel-$(uname -r)
→ 出处：Atlas 800T A2 安装指南 EDOC1100349380、Atlas 800I A3 安装指南 EDOC1100471070评估 CANN 算子仓的「进阶教程 / 开发指南」类文档质量——通读文档 + 对照算子代码**静态**查证(默认不跑),按五轴(找得到/信得过/学得会/可操作/读得懂)找出 漏讲/讲不清/过时/对不上代码/概念讲错,产出带证据与改进建议的体检报告(MD + HTML)。涉及「评进阶教程 / 开发指南文档质量 / 文档对不对得上代码 / 教程审稿 / tutorial 体检 / 文档信不信得过」等意图时使用。只评不改不跑,只对着文档与代码出诊断。
Run NPU inference/training tests on a remote SSH server with vllm-ascend Docker container. Use when the user asks to test models on NPU, run inference on Ascend devices, or deploy models to an SSH server.
Track daily PRs and Issues from vllm-project/vllm and vllm-project/vllm-ascend, filter by model (DeepSeek/Qwen/GLM/MiniMax/Kimi) and tech topics (PD disaggregation, MTP, quantization, graph mode, performance), analyze with LLM, and generate a Markdown report. Use when user wants vllm daily tracker, PR/Issue digest, or Ascend inference ecosystem monitoring.
Automatically fetch InferenceX benchmark data and generate daily performance reports for LLM inference on various hardware (NVIDIA, AMD, etc.). Supports email delivery, data change detection, and 8k1k sequence length performance analysis. Use when needing to track LLM inference performance trends, compare hardware configurations, or monitor benchmark updates.
通用 PyTorch 项目 Ascend NPU 迁移可行性分析。系统化扫描代码库中的 CUDA/GPU 依赖，按 7 大域分类评估（设备层、注意力机制、自定义算子、分布式通信、精度策略、第三方依赖、编译加速），并基于 Wan2.2 实际迁移经验提供逐项替代方案。适用于评估任何 DiT/Transformer 类模型（视频生成、LLM、多模态等）在昇腾 NPU 上的运行可行性与迁移工作量估算。
End-to-end AscendC custom operator development for Ascend NPU in an ascend-kernel (csrc/ops + build.sh + torch_npu PyTorch custom op) project. Use to design, generate, build, test, document, and tune a new AscendC operator from a name and a math/functional spec. Covers project init, two-level tiling design, op_host/op_kernel code generation, framework registration, compile/install/debug, PyTorch-style API docs, precision evaluation and root-cause debugging, torch_npu.profiler performance benchmarking, performance optimization, and security code review.