CANN Runtime pyACL 开发指南基于 CPython 封装 AscendCL 的 Python API 库构建与使用【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读pyACLPython Ascend Computing Language是 CANN Runtime 中基于 AscendCL C 语言 API通过 CPython 扩展机制封装的 Python 接口库让开发者可以用 Python 直接完成昇腾 AI 处理器的运行资源管理、内存管理、模型与算子加载执行、媒体数据处理等操作。本文围绕 CANN Runtime 仓库内的 pyACL 源码完整介绍其架构组成、CI 与非 CI 两种构建方式、运行依赖并结合py_init_acl.cpp、rt、mdl、blas等子模块源码剖析其 CPython 封装实现原理与接口划分帮助读者快速上手构建、集成与二次开发。pyACL 是什么AscendCL 的 Python 化身AscendCLAscend Computing Language是昇腾平台上用于开发深度神经网络应用的 C 语言 API 库提供运行资源管理、内存管理、模型加载与执行、算子加载与执行、媒体数据处理等能力可支撑昇腾硬件上的深度学习推理计算、图形图像预处理与单算子加速计算。它是统一调用昇腾资源的 API 框架其下的计算资源层是昇腾 AI 处理的硬件算力基础完成神经网络的矩阵相关计算、控制算子/标量/向量的通用计算与执行控制以及图像和视频数据的预处理为深度神经网络计算提供执行保障。pyACL 正是在 AscendCL 之上使用 CPython 封装得到的 Python API 库使用户可以直接通过 Python 语言进行昇腾 AI 处理器的运行管理、资源管理等操作。从代码结构看整个 pyACL 模块在初始化时见 python/pyACL/py_init_acl.cpp通过PyInit_acl注册了名为acl的顶层模块并挂载rt、mdl、media、op、blas、util、prof、himpi、fv共九个功能子模块分别对应运行时Runtime、模型管理、媒体处理、单算子、BLAS 运算、工具、性能采集、多媒体处理接口HiMPI与特征检索等能力面。仓库目录结构原文档给出的 pyACL 源码目录结构如下对应 python 目录python ├── build │ ├── bep // 构建产物相关配置 │ └── build.sh // 运行该脚本可完成 acl.so 的编译并生成 run 包 ├── ci // CI 构建的依赖项配置 ├── script // run 包的安装、卸载脚本help、patch 等 ├── output // run 包构建后的最终存放目录 └── pyACL // CPython 封装 ACL 源码其中各部分的实际内容为python/ci/dependency.xml声明 CI 构建的组件依赖包含 ACL 组件本身componentName 为ACL以及 Tuscany-ASL 平台依赖cann-npu-runtime、cann-acl-extend、cann-dvpp、cann-ge-executor 等 run 包。python/script存放install.sh、uninstall.sh、cann_uninstall.sh、spc_rollback.sh、total_rollback.sh等安装、卸载与回滚脚本。python/pyACLCPython 封装的 ACL 源码是核心代码所在按功能划分为rt、mdl、media、op、blas、util、prof、himpi、fv九个目录。python/CMakeLists.txt顶层构建配置定义project(acl)并最终生成无lib前缀的动态库acl.so。python/toolchain.cmake交叉编译/工具链配置。构建 pyACL在 CI 环境下构建在 CI 环境下进入build目录依次执行 cmake 与 make 即可cd build cmake .. make该流程在 python/README_en.md 中给出了官方说明。结合 python/CMakeLists.txt 可以看到构建的最终产物是名为acl的共享库通过set_target_properties(acl PROPERTIES PREFIX )去掉lib前缀并链接ascendcl、acl_dvpp、acl_cblas、acl_dvpp_mpi、acl_retr等动态库。在非 CI 环境下构建非 CI 环境与 CI 环境的依赖路径不同需要重新配置CMakeLists.txt替换 ACL_LIB 路径将ACL_LIB由默认值${PROJECT_SOURCE_DIR}/dependency/lib64替换为本机 CANN 安装包的动态库路径例如set(ACL_LIB /usr/local/Ascend/ascend-toolkit/latest/lib64/)通过 include_directories 设置 CANN 包路径将头文件目录指向本机 CANN 安装包include_directories(/usr/local/Ascend/ascend-toolkit/latest/include/)通过 include_directories 设置 Python 软件路径需要同时配置 Python 头文件与 numpy 头文件include_directories(/usr/local/python3.9.0/include/python3.9/) include_directories(/usr/local/python3.9.0/lib/python3.9/site-packages/numpy/core/include/)构建配置中的安全加固细节从源码可以进一步看到构建脚本的安全基线在 python/CMakeLists.txt 中编译选项启用了-fvisibilityhidden、-fstack-protector-all、-D_FORTIFY_SOURCE2、-fno-common、-fno-strict-aliasing等一系列安全与告警选项链接选项启用了-Wl,-z,now、-Wl,-z,relro、-Wl,-z,noexecstack、-pie等加固措施。同时通过set(CMAKE_SKIP_RPATH TRUE)与-Wno-builtin-macro-redefined配合-D__FILE__改写保证产物在运行时按系统 RPATH 规则加载并增强日志可读性。此外编译还通过add_definitions(-DENABLE_DVPP_INTERFACE)与add_definitions(-DASCEND_CI_LIMITED_PY37)开启 DVPP 媒体接口并适配 CI 环境下受限的 Python 3.7 构建。源码组织与编译顺序python/CMakeLists.txt 通过aux_source_directory依次收集pyACL及其rt、mdl、media、op、blas、util、prof、himpi、fv子目录下的全部.cpp源文件并在编译前执行list(SORT APP_SOURCES)对源文件排序以保证构建产物BEP一致性。头文件目录也按相同的子模块布局逐一加入include_directories。使用说明pyACL 集成在 cann-toolkit 中作为 CANN 工具链的组成部分随包发布。其运行依赖如下同版本的 driver 包提供昇腾设备驱动能力同版本的 runtime 组件提供运行时Runtime基础能力即本仓库CANN Runtime编译出的组件。因此在使用 pyACL 之前需确保环境中已安装与 pyACL 版本匹配的 driver 包和 runtime 组件避免版本不匹配导致的接口或行为差异。安装脚本位于 python/script如install.sh、uninstall.sh等构建出的 run 包则存放于output目录。开发指导CPython 封装深入解析对于希望为 pyACL 扩展接口或理解其实现机制的开发者原文档提供了三条官方参考见 python/README_en.md 的 Development GuideCPython 封装指导Python 官方扩展模块编写文档extending 章节说明如何编写扩展模块CPython 数据解析Python C API 的参数解析文档arg 章节说明PyArg_ParseTuple等解析规则的用法CPython 异常类型Python 标准库 exceptions 文档用于了解RuntimeError、ValueError、TypeError等异常在 C 层的设置方式。下面结合仓库源码对封装实现进行纵深解析。模块入口与子模块注册pyACL 的模块入口定义在 python/pyACL/py_init_acl.cppg_moduleMethods表列出了顶层acl模块直接暴露的接口包括生命周期与版本类init、finalize、get_version、get_soc_name、get_cann_version、get_version_str、finalize_reference数据类型转换类float16_to_float、float_to_float16、data_type_size数据缓冲类create_data_buffer、destroy_data_buffer、get_data_buffer_addr、get_data_buffer_size、update_data_buffer张量描述类create_tensor_desc、destroy_tensor_desc及大量get_tensor_desc_*/set_tensor_*系列接口信息查询类get_cann_attribute_list、get_cann_attribute、get_device_capability、get_recent_err_msg日志类app_log。在PyInit_aclpython/pyACL/py_init_acl.cpp中模块创建后通过AddSubModule将九个功能子模块以acl.rt、acl.mdl、acl.media、acl.op、acl.blas、acl.util、acl.prof、acl.himpi、acl.fv的命名空间注册进顶层模块字典使调用方式形如acl.rt.set_device(...)。各功能子模块的接口划分acl.rt运行时定义在 python/pyACL/rt/pyrt_methods.cpp。包含设备管理set_device、reset_device、get_device、get_device_count、get_run_mode、上下文管理create_context、destroy_context、set_context、get_context、流管理create_stream、create_stream_with_config、destroy_stream、synchronize_stream、事件管理create_event、record_event、query_event、synchronize_event、内存管理malloc、free、malloc_host、free_host、memcpy、memcpy_async、memset、memcpy2d、内核加载与执行binary_load_from_file、launch_kernel、kernel_args_init、launch_kernel_with_config、异常回调set_exception_info_callback、get_error_code_from_exception_info等以及共享内存导入导出mem_export_to_shareable_handle、mem_import_from_shareable_handle等能力是整个 pyACL 中接口最丰富的子模块。acl.mdl模型管理定义在 python/pyACL/mdl/pymdl_methods.cpp包含模型加载load_from_file、load_from_mem、load_from_file_with_mem、执行execute、execute_async、卸载unload、数据集管理create_dataset、add_dataset_buffer、get_dataset_buffer与描述信息查询create_desc、get_desc、get_num_inputs、get_num_outputs等接口。acl.blas矩阵运算定义在 python/pyACL/blas/pyblas_methods.cpp提供矩阵-向量乘gemv_ex、hgemv、s8gemv与矩阵-矩阵乘gemm_ex、hgemm、s8gemm以及配套的 handle 创建接口。acl.fv特征检索定义在 python/pyACL/fv/pyfv_methods.cpp提供特征库的初始化init、特征库增删repo_add、repo_del、检索search以及create_query_table、create_search_input、create_search_result等配套接口。acl.himpi多媒体处理定义在 python/pyACL/himpi/pyhimpi_methods.cpp提供sys_init、sys_exit、dvpp_malloc、dvpp_free等公共接口以及视频解码vdec_create_chn、vdec_send_stream、vdec_get_frame等、视频编码与图像处理VPC系列接口。acl.media媒体数据对应 python/pyACL/media 目录包含 JPEG 编解码media_jpeg.cpp、视频编解码media_vdec.cpp、media_venc.cpp、图像处理media_vpc.cpp与公共结构media_common.cpp。acl.op单算子对应 python/pyACL/op 目录提供单算子加载与执行相关接口。acl.prof性能采集对应 python/pyACL/prof 目录提供 Profiling 数据采集相关接口。acl.util工具与转换对应 python/pyACL/util 目录提供 numpy 与字节数据转换numpy_convert.cpp、bytes_convert.cpp、线程辅助thread.cpp等能力。封装范式参数解析、指针传递与返回值约定以acl.rt.create_context为例python/pyACL/rt/rt_context.cpp封装遵循统一的范式先用PyArg_ParseTuple解析 Python 参数再调用对应的 AscendCL C 接口最后通过Py_BuildValue构造返回值。由于aclrtContext等句柄是指针类型C 层返回时通过reinterpret_castuintptr_t将指针转为整数Py_BuildValue(k, ...)Python 侧拿到的是句柄的整数表示调用方再将该整数作为参数传回由封装层转回指针。返回值通常以(句柄整数, 错误码)或(值, 错误码)的元组形式返回便于 Python 侧同时获取结果与aclError状态码。Python 对象与 C 结构的转换工具跨语言转换的通用工具集中在 python/pyACL/utils_methods.cpp提供GetValueFromPyDict系列重载支持从 Python dict 中按 key 提取short、int、unsigned int、float、double、unsigned long long、void*及对应数组类型并带有类型检查与越界/溢出校验例如 int 数组会校验INT32_MAX/INT32_MIN范围提供GetValuesFromPyList系列重载将 Python list 转换为uint8_t、int32_t、int64_t、float等 C vector其中uint8_t版本会校验取值必须在 0~255 之间提供SetItem系列与SetItemToDict将 C 侧标量转换为 Python 对象针对多媒体结构实现了GetImgStreamFromPydict、GetVideoFrameFromPydict、GetVideoSupplementFromPydict等函数将 Python dict 形式的图像流、视频帧结构宽高、像素格式、物理/虚拟地址、stride、时间戳等逐字段映射到hi_img_stream、hi_video_frame结构。这些工具是 pyACL 能够以自然 Python 风格dict/list传递复杂结构、同时保持底层 C 接口性能的关键。典型使用流程结合上述模块划分一个典型的 pyACL 推理程序流程为调用acl.init()完成初始化调用acl.rt.set_device(deviceId)设置目标设备调用acl.rt.create_context(deviceId)创建上下文并用acl.rt.set_context()设为当前上下文调用acl.rt.malloc()/acl.rt.malloc_host()申请设备/主机内存使用acl.mdl.load_from_file()加载模型acl.rt.memcpy()或acl.rt.memcpy_async()拷贝输入数据再acl.mdl.execute()/acl.mdl.execute_async()执行推理使用acl.rt.create_stream()、acl.rt.create_event()等进行流/事件同步acl.rt.synchronize_stream()等待任务完成最后依次释放资源并调用acl.finalize()完成清理。总结pyACL 是 CANN Runtime 面向 Python 开发者提供的统一入口它以 CPython 扩展的形式将 AscendCL 的 C 接口完整映射为acl模块及九个功能子模块。本文不仅复现了原文档中 CI 与非 CI 两种构建流程和运行依赖说明还结合 python/CMakeLists.txt、python/pyACL/py_init_acl.cpp 及各子模块方法表源码梳理了安全加固编译选项、模块注册机制、接口划分与跨语言转换范式。开发者可以在此基础上为 pyACL 扩展新接口或直接按文中的典型流程编写昇腾推理应用。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考