cann-robotdocs: 新增 GE-Python API 参考文档及环境变量说明

文件	最后提交记录	最后更新时间
api	fix: ES接口ABI兼容性修复，新增pimpl形式的V2结构体和接口 Co-authored-by: kobemini<gengchao4@huawei.com> # message auto-generated for no-merge-commit merge: !2306 merge es_bugfix00005 into develop fix: ES接口ABI兼容性修复，新增pimpl形式的V2结构体和接口 Created-by: kobemini Commit-by: kobemini Merged-by: cann-robot Description: 20250710评审通过 # Pull Request ## 描述修复 ES (Eager Style) 对外接口中 std::string 导致的 ABI 不兼容问题。问题: IrAttrDef/IrInputDef/IrOutputDef 结构体包含 std::string 字段，当外部使用者与 GE 库使用不同的编译器 ABI（如不同的 _std::__cxx11 命名空间配置）时，会导致 std::string 内存布局不一致，引发内存访问异常。修复内容: - 新增 IrAttrDefV2/IrInputDefV2/IrOutputDefV2 pimpl 结构体，对外仅暴露稳定大小的 Impl 指针，内部拷贝字符串内容，确保 ABI 安全 - 新增 IrDefInputsV2/IrDefOutputsV2/IrDefAttrsV2 接口，支持指针+长度和 initializer_list 两种调用方式 - V2 结构体使用 std::nothrow 分配内存，setter/getter 均做判空保护 - 参数化构造函数使用初始化列表形式，避免默认构造+赋值的开销 - 旧接口使用 ATTRIBUTED_DEPRECATED 宏标记废弃，保持向后兼容 - 旧结构体文档标注非 ABI 兼容说明，接口文档同时保留新旧原型 - codegen 和单元测试已迁移至 V2 接口 ## 变更类型 - [x] Bug 修复 - [ ] 新功能 - [ ] 代码风格更新 - [ ] 重构 - [ ] 构建过程或辅助工具的变动 - [x] 文档内容更新 ## 修改文件 - compliant_node_builder.h - 新增 V2 结构体声明和 V2 接口，旧接口标记废弃 - compliant_node_builder.cc - 实现 V2 结构体的 pimpl 逻辑 - c_generator.h - codegen 迁移到 V2 接口 - docs/graph_engine_api/*.md - 文档更新 - tests/ - 单元测试迁移到 V2 接口 - examples/ - 示例迁移到 V2 接口 ## 核对清单 - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签 See merge request: cann/ge!2306	1 个月前
design	【PR】: 补充历史原型库中算子输入输出的dtype属性；gen_esb添加mode参数 Co-authored-by: du-hua1024<duhua2@huawei.com> # message auto-generated for no-merge-commit merge: !756 merge master into develop 【PR】: 补充历史原型库中算子输入输出的dtype属性；gen_esb添加mode参数 Created-by: du-hua1024 Commit-by: du-hua1024 Merged-by: cann-robot Description: # Pull Request ## 描述 1、补充历史原型库中算子的dtype属性 1）修改history_registry_types.h中dtype类型为string。 2）在OpDescUtils工具类中新增GetIrInputDtypeSymIds和GetIrOutputDtypeSymIds两个公共接口，获取参数类型定义。 3）在ir_proto_codec.cc中，修改IrProtoCodec::FromOpDesc函数，为每个输入/输出端口添加dtype字段。 4）同步更新了所有相关的单元测试，包括增强对dtype字段的断言检查、统一TensorType::ALL()的命名规范，并确保测试数据与实现逻辑保持一致。 2、在gen_esb中删除extract_history参数，添加mode参数，表示生成模式。修改了相关实现及用例。 ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [x] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [ ] 📝 文档内容更新 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在当前页面的右侧'关联Issue'部分添加相应Issue链接，并勾选'合并后关闭已关联的 Issue'选项。 --> ## 如何测试描述测试此变更的步骤和前提条件： 1. 2. ## 核对清单 <!-- [x] 表示选中 --> - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息在此添加任何其他关于本次 PR 的说明。 See merge request: cann/ge!756	2 个月前
rfc	【PR】: 添加历史原型协议文档和ES CXX兼容性RFC文档 Co-authored-by: kobemini<gengchao4@huawei.com> # message auto-generated for no-merge-commit merge: !420 merge es_doc_001 into develop 【PR】: 添加历史原型协议文档和ES CXX兼容性RFC文档 Created-by: kobemini Commit-by: kobemini Merged-by: cann-robot Description: # Pull Request ## 描述添加历史原型协议文档和ES CXX兼容性RFC文档 ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [ ] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在当前页面的右侧'关联Issue'部分添加相应Issue链接，并勾选'合并后关闭已关联的 Issue'选项。 --> ## 如何测试 NA ## 核对清单 <!-- [x] 表示选中 --> - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息在此添加任何其他关于本次 PR 的说明。 See merge request: cann/ge!420	3 个月前
tools	feat: generate_es_package 支持 OBJECT 原型库并兼容 OUTPUT_PATH 为可选参数 Co-authored-by: du-hua1024<duhua2@huawei.com> # message auto-generated for no-merge-commit merge: !1830 merge obj into develop feat: generate_es_package 支持 OBJECT 原型库并兼容 OUTPUT_PATH 为可选参数 Created-by: du-hua1024 Commit-by: du-hua1024 Merged-by: cann-robot Description: # Pull Request ## 描述本 PR 主要增强 `generate_es_package.cmake` 的易用性和兼容性，覆盖 OBJECT 原型库和未指定 `OUTPUT_PATH` 两类场景。 - 支持 `OPP_PROTO_TARGET` 为 `OBJECT_LIBRARY`：内部自动创建临时 SHARED 库，复用后续标准 OPP 路径拷贝、代码生成和依赖管理流程。 - 支持 `OUTPUT_PATH` 可选：构建产物保留在构建目录或 CMake 默认输出目录中，不再强制要求统一安装目录；历史原型库相关流程统一改为基于 `FINAL_OUTPUT_PATH` 处理。 - 调整 `DO_COPY_INSTALL` 分支逻辑，仅在需要拷贝到 `OUTPUT_PATH` 时创建和使用 `include`、`lib64`、`whl` 目录。 - 更新 README 示例、产物展示和 Target 说明，补充 OBJECT 类型原型库、未指定 `OUTPUT_PATH`、历史兼容等场景说明。 - 将 `graph_construction_test` 中的 `stub_geir_ops` 从 `SHARED` 调整为 `OBJECT`，用于覆盖新支持的场景。 ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [x] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue 无 ## 如何测试当前未在本地执行完整构建/UT，建议按以下方式验证： 1. 在测试目录使用 `OBJECT` 类型的 `stub_geir_ops` 配置并构建 ES 相关目标，确认代码生成、临时 SHARED 包装和依赖链正常。 2. 分别验证指定 `OUTPUT_PATH` 和不指定 `OUTPUT_PATH` 两种路径下的产物位置与 README 描述一致。 3. 结合历史原型库场景验证 `FINAL_OUTPUT_PATH` 在代码生成、归档与合并流程中的行为是否符合预期。 ## 核对清单 <!-- [x] 表示选中 --> - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息主要改动文件： - `cmake/generate_es_package.cmake` - `docs/es/tools/generate_es_package_cmake_readme.md` - `tests/ge/ut/ge/graph/eager_style_graph_builder/graph_construction_test/CMakeLists.txt` See merge request: cann/ge!1830	1 个月前
README.md	docs: 新增 GE-Python API 参考文档及环境变量说明 Co-authored-by: kobemini<gengchao4@huawei.com> # message auto-generated for no-merge-commit merge: !3181 merge docs/ge-python-api-doc into develop docs: 新增 GE-Python API 参考文档及环境变量说明 Created-by: kobemini Commit-by: kobemini Merged-by: cann-robot Description: # Pull Request ## 描述为 ge-python 模块全部公开接口生成标准化 API 参考文档，并补充环境变量说明。 ## 变更类型请选择本次引入的变更类型（勾选对应项）： - [ ] 🐛 Bug 修复 - [ ] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue 无 ## 如何测试 - 确认所有 Markdown 文件可正常渲染，无格式错误 - 确认文档中的模块导入路径与源码一致 - 确认文档中引用的接口与源码签名一致 ## 核对清单 - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md） ## 其他信息 ### 新增文件（16 个） API 参考文档（`docs/ge_python/api/`）： \| 文件 \| 模块/类 \| \|---\|---\| \| Graph.md \| graph 模块 — Graph 类 \| \| Node.md \| graph 模块 — Node 类 \| \| Tensor.md \| graph 模块 — Tensor 类 \| \| TensorDesc.md \| graph 模块 — TensorDesc 类 \| \| Shape.md \| graph 模块 — Shape 类 \| \| DataType.md \| graph 模块 — DataType 枚举 \| \| Session.md \| session 模块 — Session 类 \| \| Allocator.md \| allocator 模块 — Allocator/MemBlock \| \| GeApi.md \| ge_global 模块 — GeApi 类 \| \| OfflineCompile.md \| offline_compile 模块 \| \| GraphBuilder.md \| es 模块 — GraphBuilder 类 \| \| TensorHolder.md \| es 模块 — TensorHolder 类 \| \| GeUtils.md \| utils 模块 — GeUtils 类 \| \| Passes.md \| passes 模块 — FusionBasePass/PatternFusionPass/DecomposePass \| \| pyatc.md \| pyatc 模块 \| 环境变量文档（`docs/ge_python/env/`）： \| 文件 \| 说明 \| \|---\|---\| \| ASCEND_GE_PY_PASS_PATH.md \| Python Pass 插件路径发现环境变量 \| ### 修改文件 - `docs/ge_python/README.md` — 新增"API 参考"和"环境变量"导航章节 - `docs/es/README.md` — 链接修正 See merge request: cann/ge!3181	6 天前

ES (Eager Style)文档

概述

ES (Eager Style)是 GraphEngine 中用于构建计算图的函数式接口模块，提供了便捷的图构建功能。ES 模块支持多种编程语言（C、C++、Python），为用户提供了灵活且易用的图构建方式。

ES 系列 API 核心特点：

自动生成：API 并非手写，而是基于算子原型定义自动生成，减少算子开发者负担，特别是自定义算子也需要使用ES的API的构图场景。
多语言支持：原生支持 C、C++，并可扩展支持 Python，满足不同开发习惯。
全维度兼容：通过良好的API设计和代码生成机制，结合IR语义兼容处理，从源头实现了前后向API,ABI的兼容性保障。

ES 三大关键组件：

ES 基础数据结构（GE仓/GE包）：提供 EsGraphBuilder（图构建器）、EsTensorHolder（张量持有者）等核心基础设施，是构图的基石。
ES Code Generator（GE仓/GE包）：核心工具 gen_esb，负责读取算子原型定义，自动化生成每个算子对应的构图 API 代码。
Generated ES API（OPP包）：由生成器构建的最终产物，包含在算子包中，是用户直接调用的函数接口。

快速导航

API 参考文档

Python API - Eager Style Graph Builder Python 接口文档
- GraphBuilder、TensorHolder 等基础类的主要接口
C++/C API - Eager Style Graph Builder C++/C 接口文档
- EsGraphBuilder、EsTensorHolder 等基础类的主要接口

设计文档

整体架构设计 - ES模块整体架构设计说明
所有权关系分析 - ES模块Python 层和 C++ 层资源管理机制说明

工具文档

gen_esb 代码生成工具 - ES 代码生成工具使用说明
- 工具功能说明
- 使用方法和参数说明
generate_es_package.cmake - ES 代码生成、构建、安装一键式 cmake 函数
- 函数功能说明
- 使用方法和参数说明

RFC 文档

RFC 目录 - 设计提案文档
- 新功能提案
- 架构改进方案
- API 变更建议

文档结构

docs/es/
├── README.md                    # 本文件，文档导航入口
├── api/                         # API 参考文档
├── design/                      # 设计和技术分析文档
├── tools/                       # 工具使用文档
└── rfc/                         # RFC 提案文档

sample

开发路线图

我们在2025年首次推出了ES的功能，目标是提供便捷的多语言图构建能力，支持全量算子的自动API生成，并实现良好的前后向兼容性。2026年Q1阶段我们将重点完成API集成和C++构图场景的向后兼容能力，让用户可以直接安装ops包后使用ES构图能力，无需手动生成代码。具体的研发Roadmap如下：

核心架构

[December 2025]ES核心架构设计完成并落地，支持全量原型的代码生成和多语言(C, C++, Python)构图。

API 集成

[December 2025]math 分包已完成ES API集成。
[February 2026]nn、cv、transformer完成ES API集成。
[June 2026]hcom分包完成ES API集成。

注：在全量原型的ES API打包到各个算子分包之前，如需使用 ES API，可以参考工具文档中的 generate_es_package.cmake 进行代码生成和集成。

sample和相关文档

[December 2025]已提供多语言的 sample，涵盖常见使用场景。
[December 2025]已提供细化的文档，即本目录。
[January 2026]集合通信的样例完成交付。

后向兼容

[December 2025]Python API后向兼容完成设计并落地。
[January 2026]C++ API后向兼容性设计完成；C++ API的后向兼容依赖完成历史原型库的设计方案。
[March 2026]C++ API后向兼容性代码开发完成；实现C++构图场景的完整向后兼容能力。

自定义算子工程集成

[TBD]ascendc 自定义算子工程集成 ES 的代码生成能力，暂无规划。