欢迎使用ACL_PyTorch

简介

为方便更多用户体验昇腾芯片澎湃推理算力，ACL_PyTorch目录下提供了经典和主流算法模型在昇腾设备上的端到端推理流程，覆盖计算机视觉、自然语言处理、语音、OCR、RAG、具身智能、时序序列预测等常见AI任务场景，并在持续更新中。如果您希望适配您的自定义模型，我们同时提供在昇腾设备上自行适配模型的迁移调优。

如何贡献

在开始贡献之前，请先阅读CONTRIBUTING。 谢谢！

版本说明

不同模型使用的版本配套可能存在差异，推荐基于维护策略中具体模型的文档所提供的版本配套使用。如您希望体验昇腾最新的版本配套关系，可参考下文内容。

最新版本配套如下：

依赖软件	软件安装指南
昇腾NPU驱动	《 驱动固件安装指南 》
昇腾NPU固件
Toolkit（开发套件）	《 CANN 软件安装指南 》
Kernel（算子包）
NNAL（Ascend Transformer Boost加速库）
PyTorch	《 Ascend Extension for PyTorch 配置与安装 》
torch_npu插件
apex

torch_npu插件版本配套表地址：链接。

除了单独安装依赖软件的方式，我们也提供了容器化部署的方案，集成了CANN、Pytorch、ONNX等必要软件：

完整镜像路径 (<仓库地址>/<镜像名>:<Tag>)	基础操作系统	目标硬件	Dockerfile 归档路径
torch-onnx-inference:cann8.3.rc1_torch2.1.0-300I-DUO-ubuntu22.04-py3.11-aarch64	Ubuntu 22.04	Atlas 300I DUO	ModelZoo-PyTorch/ACL_PyTorch/docker/cann8.3.rc1_torch2.1.0/Dockerfile.300IDUO.ubuntu
torch-onnx-inference:cann8.3.rc1_torch2.1.0-300I-DUO-openeuler24.03-py3.11-aarch64	openEuler 24.03	Atlas 300I DUO	ModelZoo-PyTorch/ACL_PyTorch/docker/cann8.3.rc1_torch2.1.0/Dockerfile.300IDUO.openeuler
torch-onnx-inference:cann8.3.rc1_torch2.1.0-800I-A2-ubuntu22.04-py3.11-aarch64	Ubuntu 22.04	Atlas 800I A2	ModelZoo-PyTorch/ACL_PyTorch/docker/cann8.3.rc1_torch2.1.0/Dockerfile.800I_A2.ubuntu
torch-onnx-inference:cann8.3.rc1_torch2.1.0-800I-A2-openeuler24.03-py3.11-aarch64	openEuler 24.03	Atlas 800I A2	ModelZoo-PyTorch/ACL_PyTorch/docker/cann8.3.rc1_torch2.1.0/Dockerfile.800I_A2.openeuler

---

具体介绍及使用方式可以参考：OVERVIEW

快速体验

如果您希望快速了解ACL_PyTorch中的模型使用方式，推荐先体验 YOLOV26 。该用例以目标检测任务为例，包含环境准备、模型转换（PyTorch模型导出为ONNX，再使用ATC工具转换为昇腾离线模型）、数据集准备以及离线推理脚本示例，适合作为首次上手的参考。

建议按如下顺序体验：

1. 参考本文档前文完成项目基础知识学习。
2. 进入 YOLOV26目录，阅读该用例下的 README.md。
3. 根据用例说明完成PyTorch原始模型导出ONNX，并使用ATC工具转换为昇腾离线模型（.om）。
4. 执行用例下的推理脚本，完成离线推理体验。

通过该用例，您可以快速熟悉ACL_PyTorch中模型目录组织方式、依赖安装方法以及标准离线推理流程。完成体验后，再根据具体场景选择其他模型继续使用。

模型推理

1. ACL_PyTorch包含多种模型用例，不同模型在环境依赖、模型转换、数据集准备以及推理脚本使用方式上可能存在差异。因此，模型推理请以各模型目录下的 README.md 说明为准。
2. 建议您根据下方“版本看护模型”列表，选择需要体验或推理的模型，点击对应链接进入模型目录后，按照该模型文档完成推理。

模型迁移调优

您可以根据ACL_PyTorch推理模型迁移调优指南进行模型的迁移、精度调试及性能调优。如果您希望将自定义PyTorch/ONNX模型迁移到昇腾设备进行推理，可参考ONNX推理流程和TorchAir推理流程进行迁移适配。

模型支持清单

💡 ACL_PyTorch中的模型区分为随版本看护模型和其他模型。

• 针对随版本看护模型：这些模型会时常更新及维护，代码和文档质量较高，您可以优先选择这些模型。
• 针对其他模型：这些模型看护频率较低，由各方角色贡献，如有需要您也可根据对应模型的README进行部署。 如果您想检索某个模型是否支持，可以在ACL_Pytorch全量支持清单中查询。

💡 除了ACL_PyTorch，Ascend-SACT组织中也存在很多推理模型，可以在Ascend-SACT中查询。

版本看护模型

计算机视觉

• YOLOV8
• YOLOV11
• YOLOV26
• SAM2
• SAM3

语音

• CosyVoice2
• CosyVoice3
• Paraformer
• Whisper
• Index-TTS
• Index-TTS2

嵌入

• Qwen3-Embedding
• Qwen3-Reranker

OCR

• PaddleOCR-VL
• PaddleOCR-VL-1.5
• PPOCRv5
• DeepseekOCR2

具身智能

• pi0
• pi0.5
• GraspNet
• GenPosePlus
• GR00T N1.7

其他模型

除以上版本看护模型范围外，其余ACL_PyTorch中的模型都界定为其他模型。这些模型涵盖了 built-in 与 contrib 目录下的计算机视觉、自然语言处理、语音、OCR、RAG、具身智能、时序序列预测等多个方向的经典与主流网络，可作为历史适配参考。

安全声明

运行用户建议

出于安全性及权限最小化角度考虑，不建议使用root等管理员类型账户使用。

文件权限控制

1. 建议用户在主机（包括宿主机）及容器中设置运行系统umask值为0027及以上，保障新增文件夹默认最高权限为750，新增文件默认最高权限为640。

2. 建议用户对个人数据、商业资产、源文件、推理过程中保存的各类文件等敏感内容做好权限管控，管控权限可参考表1进行设置。

   表1 文件（夹）各场景权限管控推荐最大值

   类型	linux权限参考最大值
   用户主目录	750（rwxr-x---）
   程序文件(含脚本文件、库文件等)	550（r-xr-x---）
   程序文件目录	550（r-xr-x---）
   配置文件	640（rw-r-----）
   配置文件目录	750（rwxr-x---）
   日志文件(记录完毕或者已经归档)	440（r--r-----）
   日志文件(正在记录)	640（rw-r-----）
   日志文件目录	750（rwxr-x---）
   Debug文件	640（rw-r-----）
   Debug文件目录	750（rwxr-x---）
   临时文件目录	750（rwxr-x---）
   维护升级文件目录	770（rwxrwx---）
   业务数据文件	640（rw-r-----）
   业务数据文件目录	750（rwxr-x---）
   密钥组件、私钥、证书、密文文件目录	700（rwx—----）
   密钥组件、私钥、证书、加密密文	600（rw-------）
   加解密接口、加解密脚本	500（r-x------）

运行安全声明

1. 建议用户结合运行环境资源状况编写对应推理脚本。若推理脚本与资源状况不匹配，如数据集加载内存大小超出内存容量限制、推理脚本在本地生成数据超过磁盘空间大小等情况，可能引发错误并导致进程意外退出。

公网地址声明

详见模型目录下的public_address_statement.md

免责声明

致ACL_PyTorch使用者

1. ACL_PyTorch提供的模型仅供您用于非商业目的。
2. 对于各模型，ACL_PyTorch平台仅提示性地向您建议可用于推理的数据集，华为不提供任何数据集，如您使用这些数据集进行推理，请您特别注意应遵守对应数据集的License，如您因使用数据集而产生侵权纠纷，华为不承担任何责任。
3. 如您在使用ACL_PyTorch模型过程中，发现任何问题（包括但不限于功能问题、合规问题），请在Gitcode提交issue，我们将及时审视并解决。

致数据集所有者

如果您不希望您的数据集在ACL_PyTorch中的模型被提及，或希望更新ACL_PyTorch中的模型关于您的数据集的描述，请在Gitcode提交issue，我们将根据您的issue要求删除或更新您的数据集描述。衷心感谢您对ACL_PyTorch的理解和贡献。

License声明

Ascend ModelZoo提供的模型，如模型目录下存在License的，以该License为准。如模型目录下不存在License的，以Apache 2.0许可证许可，对应许可证文本可查阅Ascend ModelZoo根目录。