CANN/ge C++ ES API兼容性设计
RFC-001: C++ ES API 兼容性设计
【免费下载链接】geGE（Graph Engine）是面向昇腾的图编译器和执行器，提供了计算图优化、多流并行、内存复用和模型下沉等技术手段，加速模型执行效率，减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力，并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/ge
概述和目标
背景
在 ES (Eager Style) 构图中，为了保证 C++ ES API 的向后 API 兼容性，生成工具需要掌握不同商发版本的 IR 原型演进情况。历史原型库负责沉淀并提供这些历史原型数据，供gen_esb在生成阶段对比差异、生成重载接口。
目标
- 建立历史原型库协议，实现跨版本算子 IR 原型信息的归档和查询
- 设计 C++ ES API 的重载生成机制，确保向后兼容性
- 解决重载接口的二义性问题，提供清晰的用户调用语义
- 建立完整的生成、发布、消费流程
详细设计
历史原型库协议设计
详细设计参考：历史原型库协议文档
关键设计要点：
- 定位与职责：历史原型库是一套长期维护的协议与数据产物，用于跨版本归档算子 IR 原型信息
- 目录结构：按算子分包组织，包含版本索引、元信息和算子原型数据
- 数据格式：采用 JSON 格式，包含最小字段集确保向后兼容
- 生成与发布：由
gen_esb --extract-history生成，随 Ops run 包发布 - 消费方式：通过文件系统接口读取，服务于ES或者其他场景
C++ API 兼容性设计
详细设计参考：C++ API 兼容性设计文档
关键设计要点：
模块架构与职责划分
- 历史原型库模块：负责存储和管理历史原型数据（Ops组件）
- gen_esb 工具模块：负责数据生成、读取、业务逻辑和代码生成（GE组件）
重载生成与二义性处理
核心问题：
- C++ 默认参数必须在参数列表末尾的限制
EsTensorLike支持标量类型隐式转换导致的二义性
数据流与构建流程
- 商发版本构建：同时生成 C++ 重载接口和历史原型库数据
- 非商发构建：仅生成 C++ 重载接口
- 工程-算子-GE 三方配合：通过编译宏传递信息，统一打包发布
实现计划
阶段一：接口对齐与基础模块开发（1周）
- M0阶段（0.5天）：数据结构定义与接口对齐
- 第1周：基础模块开发，包括公共提取器、历史数据读写器
阶段二：核心功能开发（1周）
- 第2周：重载规划器、二义性检测器、C++生成器对接
阶段三：集成联调（1周）
- 第3周：端到端测试、边界场景验证
总预计耗时：3~4周
影响分析
技术影响
- 正向影响：提供稳定的 C++ API 兼容性保障，提升用户体验
- 风险：重载二义性处理复杂度较高，需要严格的测试验证
架构影响
- 模块依赖：增加历史原型库模块，但职责边界清晰
- 构建流程：商发版本构建流程需要调整，增加历史数据生成步骤
兼容性影响
- 向后兼容：通过重载机制支持确保现有 API 调用不受影响
维护成本
- 协议维护：需要长期维护历史原型库协议
- 工具维护：
gen_esb工具需要持续维护重载生成逻辑
替代方案
方案B：版本命名空间
- 将不同版本 API 放到不同命名空间（如
ge::es与ge::es::v2） - 优点：完全避免重载二义性
- 缺点：用户调用习惯改变，Runnable Dump 成本较高
注：Runnable Dump指的是将内存中的图对象 dump为构图的代码，因此需要知道具体要写成什么样的构图代码
方案对比
| 维度 | 方案A（推荐） | 方案B |
|---|---|---|
| 二义性风险 | 低（通过防呆机制） | 无 |
| 用户习惯 | 稳定 | 需要显式选择命名空间 |
| 维护成本 | 中等 | 较高 |
| Dump 成本 | 低 | 高 |
推荐方案A：在保证兼容性的前提下，最大程度保持用户调用习惯稳定。
【免费下载链接】geGE（Graph Engine）是面向昇腾的图编译器和执行器，提供了计算图优化、多流并行、内存复用和模型下沉等技术手段，加速模型执行效率，减少模型内存占用。 GE 提供对 PyTorch、TensorFlow 前端的友好接入能力，并同时支持 onnx、pb 等主流模型格式的解析与编译。项目地址: https://gitcode.com/cann/ge
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考