add_es_library 使用指南【免费下载链接】geGEGraph Engine是面向昇腾的图编译器和执行器提供了计算图优化、多流并行、内存复用和模型下沉等技术手段加速模型执行效率减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/ge概述提供如下 CMake 函数用于生成 Eager Style (ES)产物add_es_library_and_whl: 生成 C/C 动态库 Python wheel 包完整产物add_es_library: 只生成 C/C 动态库纯 C/C 项目使用快速开始前置要求通过安装指导正确安装toolkit包并按照指导正确配置环境变量定义原型动态库add_library(opgraph_math SHARED #要求是so的形式 )1. 引入函数使用 find_package# 在你的 CMakeLists.txt 中添加模块路径(ASCEND_HOME_PATH来自前置要求中的配置环境变量) list(APPEND CMAKE_MODULE_PATH ${ASCEND_HOME_PATH}/include/ge/cmake) # 查找模块 find_package(GenerateEsPackage REQUIRED)说明当前版本需要在 CMakeLists.txt 中手动添加CMAKE_MODULE_PATH计划支持未来版本将支持只source set_env.sh后直接find_package无需手动添加路径2. 生成 ES API生成完整产物add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math #前置要求中的原型库target OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )只生成 C/C 库add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )3. 使用生成的产物# 在你的应用中链接 add_executable(my_app main.cpp) target_link_libraries(my_app PRIVATE es_math)4. 构建# 直接构建你的应用即可 make my_app # → 会自动触发 ES 包的构建参数说明函数参数两个函数参数完全相同参数必需性说明示例ES_LINKABLE_AND_ALL_TARGET✅ 必需对外暴露的库 target 名称es_math,es_nn,es_cvOPP_PROTO_TARGET✅ 必需算子原型库的 CMake target 名称支持 SHARED/STATIC/INTERFACE/OBJECT 类型opgraph_math,opgraph_nnOUTPUT_PATH☑️ 可选产物输出的根目录。如果不指定产物将保留在构建目录中${CMAKE_BINARY_DIR}/outputEXCLUDE_OPS☑️ 可选需要排除生成的算子Add,Conv2D区别add_es_library_and_whl: 生成库 wheel 包add_es_library: 只生成库跳过 wheel 包生成重要因为 ES 产物是函数内部动态生成而 cmake 整体又是配置和构建分阶段处理所以我们的函数内部会有重配置和构建的操作这也是我们目前直接提供一个 interface 类型的ES_LINKABLE_AND_ALL_TARGET的原因函数会自动从OPP_PROTO_TARGET的LIBRARY_OUTPUT_DIRECTORY推导原型库路径这是生成原型库对应的 ES 产物的基本条件历史原型库相关 CMake 变量以下变量在调用函数前通过set()设置用于控制历史原型库功能变量类型说明示例GE_ES_EXTRACT_HISTORYbool可选ON 时向 gen_esb 传入--es_modeextract_history启用历史原型库生成模式归档当前原型为 JSON供后续版本代码生成时使用不设置或 OFF 则 gen_esb 默认codegen仅生成 C APIset(GE_ES_EXTRACT_HISTORY ON)GE_ES_RELEASE_VERSION可选当前新版本号归档步骤将当前原型归档为此版本历史原型库生成模式下必须设置set(GE_ES_RELEASE_VERSION 8.0.RC1)GE_ES_RELEASE_DATE可选历史原型库生成模式下指定发布日期格式YYYY-MM-DD不设置则由 gen_esb 使用当前日期set(GE_ES_RELEASE_DATE 2026-02-28)GE_ES_BRANCH_NAME可选历史原型库生成模式下指定发布分支名。注意当设为master时函数会忽略所有归档相关变量GE_ES_EXTRACT_HISTORY/GE_ES_RELEASE_VERSION/GE_ES_RELEASE_DATE仅走纯代码生成模式set(GE_ES_BRANCH_NAME release/8.0)历史原型库路径自动推导函数内部根据 cmake 文件安装位置自动推导${CANN_INSTALL_PATH}/cann/opp/history_registry/module路径路径存在且非空时自动向 gen_esb 传入--history_registry调用方无需显式设置历史原型库路径。完整商发模式GE_ES_EXTRACT_HISTORYON且 ops 包中存在历史原型库时add_es_library内部自动串行执行两次 gen_esb代码生成 历史原型库归档合并调用方无需额外处理一次add_es_library调用即可完成完整商发所需的全部操作参见示例 11。输出产物add_es_library_and_whl 生成的产物OUTPUT_PATH/ ├── include/ │ └── es_math/ # 头文件目录 │ ├── es_math_ops.h # C 接口聚合头文件 │ ├── es_math_ops_c.h # C 接口聚合头文件 │ └── es_add.h ... # 单个算子头文件(一般是有多个文件) ├── lib64/ │ ├── libes_math.so # 动态库 │ └── libes_math.a # 静态库 └── whl/ └── es_math-1.0.0-py3-none-any.whl # Python 包add_es_library 生成的产物OUTPUT_PATH/ ├── include/ │ └── es_math/ # 头文件目录 │ ├── es_math_ops.h # C 接口聚合头文件 │ ├── es_math_ops_c.h # C 接口聚合头文件 │ └── es_add.h ... # 单个算子头文件(一般是有多个文件) └── lib64/ ├── libes_math.so # 动态库 └── libes_math.a # 静态库说明聚合的含义包含 es_math 下所有算子的构图 API动态库与静态库每次生成会同时产出libname.so与libname.a。对外接口 target如es_math默认链接动态库若需静态链接可手动指定lib64/libname.a或通过target_link_libraries(your_target PRIVATE ${OUTPUT_PATH}/lib64/libes_math.a)等方式链接静态库。启用历史原型库相关模式后的额外产物历史原型库生成模式GE_ES_EXTRACT_HISTORYONgen_esb 直接输出到OUTPUT_PATH生成以下 JSON 结构OUTPUT_PATH/ ├── index.json # 版本索引所有已归档版本的列表 └── registry/ └── GE_ES_RELEASE_VERSION/ ├── metadata.json # 版本元信息版本号、发布日期、分支名等 └── operators.json # 算子原型数据IR 结构化描述代码生成模式含历史兼容自动检测到历史原型库时C 头文件中同一算子会出现多版本重载签名历史版本签名 当前版本签名.so同时包含所有版本的实现向前兼容旧版本调用方式。产物目录结构与标准模式相同仅头文件内容有差异。生成的 Target对外使用的 TargetTarget 名称用途说明es_math链接依赖使用方通过此 target 链接自动触发构建默认链接动态库.so静态库.a也会同时生成。若指定了OUTPUT_PATH可直接从lib64/获取静态库文件未指定时则保留在 CMake 默认输出目录中。使用示例示例 1基本用法# 1. 定义原型动态库(前置要求) add_library(opgraph_math SHARED ) # 2. 生成 ES API 包库 wheel 包 add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 3. 在应用中使用 add_executable(my_app main.cpp) target_link_libraries(my_app PRIVATE es_math)提示如果工程中还有在编译阶段就需要 ES 头文件的 OBJECT/STATIC 中间目标可额外添加add_dependencies(中间目标 build_es_math)build_es_***名称会随包名变化以确保在编译该 目标前已完成代码生成。最终的可执行或共享库只需target_link_libraries(... es_math)即可自动触发 相关依赖。补充示例包含对象库add_library(my_obj OBJECT foo.cc bar.cc) # 保证编译对象前先生成 es_math 头文件(推荐显示添加) add_dependencies(my_obj build_es_math) # 传递头文件搜索路径的作用 target_link_libraries(my_obj PRIVATE es_math) add_executable(my_app $TARGET_OBJECTS:my_obj) target_link_libraries(my_app PRIVATE es_math )示例 2只生成 C/C 库# 只生成 C/C 库跳过 Python wheel 包 add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )示例 3排除部分算子生成# 生成 math TARGET # 生成产物不会包含 es_Add_c.h; es_Add.h, es_Add.cpp, es_Add.py add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output EXCLUDE_OPS Add )示例 4使用 OBJECT 类型的原型库# 定义 OBJECT 类型的原型库 add_library(opgraph_math OBJECT src/math_op1.cpp src/math_op2.cpp ) # 生成 ES API函数内部自动创建临时 SHARED 库包装 add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math # OBJECT 类型 OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )示例 5不指定 OUTPUT_PATH# 不指定 OUTPUT_PATH产物将保留在构建目录中 add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math # OUTPUT_PATH 未指定 )产物展示构建产物保留在构建目录与 CMake 默认目标输出目录中不会额外整理到统一的include/、lib64/、whl/目录。build_dir/es_math_build/ ├── generated_code/ # gen_esb 与 wrapper 输出 │ ├── es_math_ops.h # C 接口聚合头文件 │ ├── es_math_ops_c.h # C 接口聚合头文件 │ ├── es_add.h ... # 单个算子头文件(一般是有多个文件) │ ├── es_add.cpp ... # 单个算子实现文件(一般是有多个文件) │ └── es_math_all_in_one.cpp # 聚合 wrapper ├── python_package/ │ └── dist/ │ └── es_math-1.0.0-py3-none-any.whl # Python 包 ├── libes_math.so # 动态库CMake 默认库输出目录 └── libes_math.a # 静态库示例 6多个 TARGET# 生成 math TARGET add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 生成 nn TARGET add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_nn OPP_PROTO_TARGET opgraph_nn OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 使用多个TARGET add_executable(my_inference_app main.cpp) target_link_libraries(my_inference_app PRIVATE es_math es_nn )示例 7C 代码中使用#include es_math/es_math_ops.h #include ge/es/graph_builder.h using namespace ge::es; int main() { EsGraphBuilder builder(my_graph); // 创建输入 auto input1 builder.CreateConstFloat(1.0f); auto input2 builder.CreateConstFloat(2.0f); // 使用生成的 ES API auto result Add(input1, input2); auto graph builder.build_and_reset(); return 0; }示例 8Python 中使用# 安装 wheel 包 pip install output/whl/es_math-1.0.0-py3-none-any.whl# 通过 entry_point 机制自动加载的插件使用统一的导入方式 from ge.es.math import Add from ge.es import GraphBuilder builder GraphBuilder(my_graph) input1 builder.create_const_float(1.0) input2 builder.create_const_float(2.0) result Add(input1, input2) graph builder.build_and_reset()说明插件通过 entry_point 机制自动加载导入路径为ge.es.module_namemodule_name是从ES_LINKABLE_AND_ALL_TARGET去掉es_前缀得到的如es_math→math可以使用ge.es.list_plugins()查看所有已加载的插件名称可以使用ge.es.get_plugin(math)检查插件是否存在返回模块对象或 None。示例 9历史原型库生成模式商发首次构建归档当前版本原型# 从已安装的算子原型 .so 中提取 IR 原型归档为 JSON 供下次商发使用 set(GE_ES_EXTRACT_HISTORY ON) set(GE_ES_RELEASE_VERSION 8.0.RC1) set(GE_ES_RELEASE_DATE 2026-02-28) # 可选不设置则使用当前日期 set(GE_ES_BRANCH_NAME release/8.0) # 可选若设为 master 则不会执行归档仅走代码生成 add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 产物output/index.json, output/registry/8.0.RC1/metadata.json, output/registry/8.0.RC1/operators.json示例 10代码生成模式含历史兼容自动消费已有历史数据生成带重载的 C API# 函数内部自动检测 ${CANN_INSTALL_PATH}/cann/opp/history_registry/math # 路径存在且非空时自动生成带历史兼容重载签名的 C 接口无需手动设置路径 set(GE_ES_RELEASE_VERSION 8.0.RC2) add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 产物头文件中同一算子出现多版本重载旧签名 新签名向前兼容旧版本调用示例 11完整商发模式单次调用函数内部自动完成代码生成 历史原型库归档合并# GE_ES_EXTRACT_HISTORYON ops 包中存在历史原型库自动检测 完整商发模式 # add_es_library 内部自动串行执行两次 gen_esb调用方无需额外处理 # gen_esb 调用1默认 codegen 模式以当前日期为锚点自动选取窗口内历史版本 → 对比当前原型 → 生成带重载 C API # gen_esb 调用2--es_modeextract_history将已有历史库从 _AUTO_HISTORY_REGISTRY 复制至 OUTPUT_PATH在 OUTPUT_PATH 追加当前版本原型 → OUTPUT_PATH 包含完整历史原型库 set(GE_ES_EXTRACT_HISTORY ON) set(GE_ES_RELEASE_VERSION 8.0.RC2) # 当前新版本号用于归档步骤 set(GE_ES_RELEASE_DATE 2026-02-28) # 可选 set(GE_ES_BRANCH_NAME develop) # 可选若设为 master 则不会归档仅走代码生成 add_es_library( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output )命名规则产物命名产物类型命名规则示例 (ES_LINKABLE_AND_ALL_TARGETes_math)动态库libES_LINKABLE_AND_ALL_TARGET.solibes_math.so静态库libES_LINKABLE_AND_ALL_TARGET.alibes_math.aPython 包ES_LINKABLE_AND_ALL_TARGET-1.0.0-py3-none-any.whles_math-1.0.0-py3-none-any.whl聚合头文件es_name_ops.hes_math_ops.hTarget 命名Target 类型命名规则示例 (ES_LINKABLE_AND_ALL_TARGETes_math)对外库ES_LINKABLE_AND_ALL_TARGETes_math注意事项ES_LINKABLE_AND_ALL_TARGET 命名建议使用es_前缀如es_math,es_nn使用小写字母和下划线避免使用特殊字符和 C 关键字历史原型库相关变量历史原型库路径由函数自动推导${CANN_INSTALL_PATH}/cann/opp/history_registry/module路径存在且非空时自动启用调用方无需传参master 分支当GE_ES_BRANCH_NAME为master时会忽略GE_ES_EXTRACT_HISTORY/GE_ES_RELEASE_VERSION/GE_ES_RELEASE_DATE仅走纯代码生成模式历史原型库路径仍会传递用于生成带重载的 C APIGE_ES_EXTRACT_HISTORYON且 ops 包中存在历史原型库自动检测到即为完整商发模式函数内部自动执行两次 gen_esb代码生成 历史原型库归档合并调用方无需任何额外处理参见示例 11版本去重若历史原型库的index.json中已存在与GE_ES_RELEASE_VERSION相同的版本号则跳过归档步骤仅执行代码生成避免重复归档同时将 CANN 安装路径中的历史原型库完整复制到OUTPUT_PATH方便后续换路径安装纯历史归档模式仅设置GE_ES_EXTRACT_HISTORYONops 包中无历史原型库gen_esb 输出到OUTPUT_PATH只生成 JSON不生成 C API完整商发模式下代码生成步骤 gen_esb 不传--release_version以当前日期为锚点自动选取窗口内历史版本对比归档步骤使用GE_ES_RELEASE_VERSION作为新版本号写入历史库完整商发模式下归档步骤将已有历史库从_AUTO_HISTORY_REGISTRYCANN 安装路径只读复制到OUTPUT_PATH构建目录可写gen_esb 在OUTPUT_PATH追加当前版本条目首次构建CANN 路径中无已有历史库时直接输出至OUTPUT_PATH最终OUTPUT_PATH包含所有历史版本 当前版本的完整合并结果GE_ES_RELEASE_VERSION归档时必须设置否则归档版本无法识别历史原型库数据JSON 文件通常随 ops 包安装默认位于${CANN_INSTALL_PATH}/cann/opp/history_registry/package_name/依赖要求CMake 版本: 3.16CANN run 包: 已安装并设置环境变量或手动指定路径gen_esb: 此为内部es api的代码生成二进制工具已在run包中集成可以通过gen_esb--help信息查看使用说明OPP_PROTO_TARGET: 必须存在Python3: 3.7仅add_es_library_and_whl需要Python 包: setuptools, wheel仅add_es_library_and_whl需要,推荐使用setuptools59.6.0、wheel0.37. 1的配套版本或更高版本常见问题Q多个 TARGET 如何共享输出目录A: 所有TARGET可以使用同一个OUTPUT_PATH头文件会按包名组织在子目录中add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output # 共享路径 ) add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_nn OPP_PROTO_TARGET opgraph_nn OUTPUT_PATH ${CMAKE_BINARY_DIR}/output # 共享路径 ) # 输出结构 # output/ # ├── include/ # │ ├── es_math/ # │ └── es_nn/ # ├── lib64/ # │ ├── libes_math.so, libes_math.a # │ └── libes_nn.so, libes_nn.a # └── whl/ # ├── es_math-1.0.0-py3-none-any.whl # └── es_nn-1.0.0-py3-none-any.whlQgen_esb 找不到怎么办A: 函数会自动查找 gen_esb如果失败请检查确认已安装 CANN run 包执行source ${ASCEND_HOME_PATH}/set_env.sh或者设置了正确的CMAKE_MODULE_PATHgen_esb 会从 PATH 环境变量或者从 cmake 文件路径自动推导函数会输出详细的检测信息根据日志排查问题。完整示例# 基础设置 cmake_minimum_required(VERSION 3.16) project(my_es_project LANGUAGES CXX) # 引入函数推荐使用 find_package list(APPEND CMAKE_MODULE_PATH ${ASCEND_HOME_PATH}/include/ge/cmake) find_package(GenerateEsPackage REQUIRED) # 第一部分: 前置要求定义原型库 add_library(opgraph_math SHARED ) # 第二部分: 生成 ES API 包 add_es_library_and_whl( ES_LINKABLE_AND_ALL_TARGET es_math OPP_PROTO_TARGET opgraph_math OUTPUT_PATH ${CMAKE_BINARY_DIR}/output ) # 第三部分: 在应用中使用 add_executable(my_app src/main.cpp src/inference.cpp ) # 链接ES_LINKABLE_AND_ALL_TARGET target_link_libraries(my_app PRIVATE es_math # 自动获得依赖、头文件和库 )构建命令# 只需一条命令 make my_app【免费下载链接】geGEGraph Engine是面向昇腾的图编译器和执行器提供了计算图优化、多流并行、内存复用和模型下沉等技术手段加速模型执行效率减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/ge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考