--- title: Session到GeSession的迁移指导 description: "本节旨在指导用户从Session类迁移到新引入的GeSession类。GeSession是对原有Session类的重构和优化，主要变化包括：" url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/programug/graphdevg/atlasag_25_0115.html sourcePath: /source/zh/canncommercial/900/programug/graphdevg/atlasag_25_0115.html indexId: 46b561abd9d81fc4a37ed4493f369441e7b97456c45ff66995dfa9977498c05c70 --- # Session到GeSession的迁移指导 本节旨在指导用户从Session类迁移到新引入的GeSession类。GeSession是对原有Session类的重构和优化，主要变化包括： - 简化编译和加载流程：不需要手动调用CompileGraph和LoadGraph（除非需要显式控制）。详见 编译和运行接口变化 。 - 统一执行接口的参数类型：所有运行接口的输入输出从ge::Tensor改为gert::Tensor。详见 Tensor类型变化 。 - 优化接口命名和参数类型。详见 接口变化 。 其他变更点注意事项： - 头文件和库文件变化：头文件从ge/ge_api.h改为ge/ge_api_v2.h，库文件从libge_runner.so改为libge_runner_v2.so。详见 库链接变化 。 - 异步生命周期：使用RunGraphAsync时，inputs必须保持有效直到callback被调用。详见 Tensor生命周期说明 。 - 执行模式互斥：三种运行模式不能混用。详见 编译和运行接口变化 。 下面按照分类详细介绍上述变更点。 #### 库链接变化 **表1 库链接变化** | 类别 | Session | GeSession | | --- | --- | --- | | 库文件 | libge\_runner.so | libge\_runner\_v2.so | | 头文件 | ge/ge\_api.h | ge/ge\_api\_v2.h | #### 接口变化 | Session接口 | GeSession接口 | 迁移说明 | | --- | --- | --- | | GEInitialize(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0086.html)(options) | GEInitializeV2(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0176.html)(options) | 新增接口 | | GEFinalize(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0087.html)() | GEFinalizeV2(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0173.html)() | 新增接口 | | GEGetErrorMsg(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0115.html)() | GEGetErrorMsgV3(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0174.html)() | 新增接口 | | GEGetWarningMsg(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0116.html)() | GEGetWarningMsgV3(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0175.html)() | 新增接口 | | Session(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0088.html)(options) | GeSession(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0282.html)(options) | 构造函数基本一致，但只提供了ABI兼容的std::map类型版本 | | ~Session() | ~GeSession() | 析构函数，无变化 | | AddGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0091.html)(uint32\_t, const Graph&) | AddGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0170.html) (uint32\_t, const Graph&) | 接口保持一致 | | AddGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0091.html)(uint32\_t, const Graph&, options) | AddGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0170.html) (uint32\_t, const Graph&, options) | 只提供了ABI兼容的std::map类型版本 | | AddGraphWithCopy(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0092.html) | AddGraphClone(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0171.html) | 重命名，功能相同 | | RemoveGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0093.html) | RemoveGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0184.html) | 无变化 | | BuildGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0102.html) | CompileGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0172.html) | 重命名，功能相同。GeSession的CompileGraph支持Variable | | CompileGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0103.html) | CompileGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0172.html) | 合并了BuildGraph和CompileGraph的功能 | | LoadGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0094.html) | LoadGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0181.html) | 接口基本一致，但GeSession中会自动检查是否需要先CompileGraph | | RunGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0096.html) | RunGraph(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0185.html) | 重要变化：输入输出从ge::Tensor改为gert::Tensor | | RunGraphWithStreamAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0098.html) | RunGraphWithStreamAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0187.html) | 重要变化：输入输出从ge::Tensor改为gert::Tensor；CompileGraph和LoadGraph可省略 | | ExecuteGraphWithStreamAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0099.html) | RunGraphWithStreamAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0187.html) | Session中的ExecuteGraphWithStreamAsync（使用gert::Tensor）合并到GeSession的RunGraphWithStreamAsync | | RunGraphAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0097.html) | RunGraphAsync(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0186.html) | 重要变化：输入输出从ge::Tensor改为gert::Tensor；回调函数签名从RunAsyncCallback改为RunAsyncCallbackV2 | | RegisterCallBackFunc(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0104.html) | RegisterCallBackFunc(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0182.html) | 回调函数签名变化，使用RunCallback类型 | | GetCompiledGraphSummary(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0106.html) | GetCompiledGraphSummary(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0177.html) | 无变化 | | SetGraphConstMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0107.html) | SetGraphConstMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0188.html) | 无变化 | | UpdateGraphFeatureMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0108.html) | UpdateGraphFeatureMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0190.html) | 无变化 | | SetGraphFixedFeatureMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0109.html) | SetGraphFixedFeatureMemoryBaseWithType(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0189.html) | 接口名称变化，增加了type参数 | | UpdateGraphRefreshableFeatureMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0111.html) | UpdateGraphRefreshableFeatureMemoryBase(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0191.html) | 无变化 | | RegisterExternalAllocator(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0112.html) | RegisterExternalAllocator(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0183.html) | 无变化 | | UnregisterExternalAllocator(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0113.html) | UnregisterExternalAllocator(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0192.html) | 无变化 | | IsGraphNeedRebuild(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0105.html) | IsGraphNeedRebuild(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0180.html) | 无变化 | | GetSessionId(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0090.html) | GetSessionId(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0179.html) | 无变化 | | \- | GetCompiledModel(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0178.html) | 新增接口：获取编译后的模型数据 | | GetVariables(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0089.html) | \- | 已删除，无替代接口 | | ShardGraphsToFile(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0070.html) | \- | 已删除，图分片功能不再提供 | | ShardGraphs(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0069.html) | \- | 已删除，图分片功能不再提供 | | SaveGraphsToPb(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0071.html) | \- | 已删除，保存图到pb文件功能不再提供 | | PaRemapped(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendgraphapi/atlasgeapi\_07\_0114.html) | \- | 已删除，虚拟内存重映射功能不再提供 | #### Tensor类型变化 所有运行接口的输入输出从ge::Tensor改为gert::Tensor，详情如下： - 命名空间变化| 特性 | ge::Tensor | gert::Tensor | | --- | --- | --- | | 命名空间 | ge | gert | | 数据结构 | 使用std::shared\_ptr管理内部实现 | POD类型（Plain Old Data），所有数据内联存储 | | 内存布局 | 间接访问，通过impl\_指针 | 扁平化布局，支持直接memcpy | | Placement支持 | 通过TensorDesc设置Placement | 支持多种Placement类型 | | 拷贝行为 | 浅拷贝（shared\_ptr语义） | 浅拷贝，指针共享 | | 性能 | 一般 | 高性能 | | 适用场景 | 图构建阶段 | 运行时执行 | - 数据结构变化| ge::Tensor内部结构 | gert::Tensor内部结构 | | | | | | --- | --- | --- | --- | --- | --- | | 1 2 3 4 class Tensor { private: std::shared\_ptr impl\_; // 使用智能指针管理 }; 使用shared\_ptr管理TensorImpl 拷贝时共享底层实现 数据通过TensorDesc描述 | 1 2 3 4 | class Tensor { private: std::shared\_ptr impl\_; // 使用智能指针管理 }; | 1 2 3 4 5 6 7 8 9 10 class Tensor { private: StorageShape storage\_shape\_; // Shape信息 StorageFormat storage\_format\_; // Format信息 TensorVersion version\_; // 版本 uint8\_t reserved\_[3]; // 预留字段 ge::DataType data\_type\_; // 数据类型 TensorData tensor\_data\_; // 数据指针和placement uint8\_t reserved\_field\_[40]; // 预留字段 }; 所有字段直接内联在对象中 是标准布局类型（std::is\_standard\_layout） | 1 2 3 4 5 6 7 8 9 10 | class Tensor { private: StorageShape storage\_shape\_; // Shape信息 StorageFormat storage\_format\_; // Format信息 TensorVersion version\_; // 版本 uint8\_t reserved\_[3]; // 预留字段 ge::DataType data\_type\_; // 数据类型 TensorData tensor\_data\_; // 数据指针和placement uint8\_t reserved\_field\_[40]; // 预留字段 }; | | 1 2 3 4 | class Tensor { private: std::shared\_ptr impl\_; // 使用智能指针管理 }; | | | | | | 1 2 3 4 5 6 7 8 9 10 | class Tensor { private: StorageShape storage\_shape\_; // Shape信息 StorageFormat storage\_format\_; // Format信息 TensorVersion version\_; // 版本 uint8\_t reserved\_[3]; // 预留字段 ge::DataType data\_type\_; // 数据类型 TensorData tensor\_data\_; // 数据指针和placement uint8\_t reserved\_field\_[40]; // 预留字段 }; | | | | | 下面给出gert::Tensor生命周期的说明以及构造gert::Tensor的方法： - Tensor生命周期说明 - RunGraph接口 1 2 3 4 std::vector inputs = ...; std::vector outputs; session->RunGraph(graph_id, inputs, outputs); // inputs和outputs在调用完成后可以安全释放 - RunGraphWithStreamAsync接口 1 2 3 4 5 6 // 注意：可以不先调用CompileGraph和LoadGraph，会自动处理 std::vector inputs = ...; std::vector outputs; session->RunGraphWithStreamAsync(graph_id, stream, inputs, outputs); // inputs和outputs在stream同步之前不能释放 // 需要调用aclrtSynchronizeStream或其他同步机制 - RunGraphAsync接口（重要） 1 2 3 4 5 6 7 8 9 using RunAsyncCallbackV2 = std::function&)>; std::vector inputs = ...; session->RunGraphAsync(graph_id, inputs, [](Status ret, std::vector& outputs) { // 处理输出 }); // 重要：inputs不能立即释放！ // 必须等到callback函数被调用后才能释放inputs // 因为模型执行的时候会读取inputs、callback被调用可保证模型执行完成 - 构造gert::Tensor的方法 - 方法1: 使用TensorData构造（推荐） 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 #include "exe_graph/runtime/tensor.h" #include "acl_rt.h" // 构造 Host Tensor void* host_buf = nullptr; aclError ret = aclrtMallocHost(&host_buf, data_len); // 分配Host内存 if (ret != ACL_ERROR_NONE) { // 处理错误 } // 使用TensorData构造 gert::TensorData td(host_buf, nullptr, data_len, gert::kOnHost); gert::Tensor tensor; tensor.SetData(std::move(td)); // 设置数据类型（如果需要） // tensor.SetDataType(ge::DT_FLOAT); - 方法2: 使用构造函数直接创建 1 2 3 4 5 6 7 8 9 10 // 从 shape、format 和 dtype 构造 gert::StorageShape shape = {{batch_size, channels, height, width}, {4}}; gert::StorageFormat format = {ge::FORMAT_ND, ge::FORMAT_ND, {}}; gert::Tensor tensor(shape, format, ge::DT_FLOAT); // 然后分配内存 void* host_buf = nullptr; aclrtMallocHost(&host_buf, tensor.GetSize()); gert::TensorData td(host_buf, nullptr, tensor.GetSize(), gert::kOnHost); tensor.SetData(std::move(td)); - 方法3: 构造Device Tensor 1 2 3 4 5 6 7 8 9 10 11 // 分配Device内存 void* dev = nullptr; aclError ret = aclrtMalloc(&dev, bytes, ACL_MEM_MALLOC_NORMAL_ONLY); if (ret != ACL_ERROR_NONE) { // 处理错误 } // 构造 Device Tensor gert::TensorData td(dev, nullptr, bytes, gert::kOnDeviceHbm); gert::Tensor device_tensor; device_tensor.SetData(std::move(td)); - 释放gert::Tensor内存 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 // 释放Host Tensor内存 void FreeHostTensor(gert::Tensor &tensor) { if (tensor.GetAddr() != nullptr) { aclrtFreeHost(tensor.GetAddr()); } } // 释放Device Tensor内存 void FreeDeviceTensor(gert::Tensor &tensor) { if (tensor.GetAddr() != nullptr) { aclrtFree(tensor.GetAddr()); } } // 批量释放 void FreeTensorVector(std::vector &tensors, bool is_device) { for (auto &t : tensors) { if (t.GetAddr() != nullptr) { if (is_device) { aclrtFree(t.GetAddr()); } else { aclrtFreeHost(t.GetAddr()); } } } } aclrtMallocHost、aclrtMalloc、aclrtFreeHost、aclrtFree等接口详细说明请参见“内存管理(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/runtimeapi/aclcppdevg_03_0093.html)”。 #### 编译和运行接口变化 - CompileGraph/LoadGraph不再必需 在GeSession中，RunGraph、RunGraphAsync和RunGraphWithStreamAsync三个执行接口会自动检查图是否已编译和加载。如果未编译，会先自动编译；如果未加载，会先自动加载。 1 2 3 4 5 6 // GeSession的自动处理机制 GeSession session(options); session.AddGraph(graph_id, graph); // 直接执行，无需手动CompileGraph和LoadGraph session.RunGraph(graph_id, inputs, outputs); // 自动编译和加载 - 执行模式互斥 GeSession的三种执行模式RunGraph、RunGraphAsync、RunGraphWithStreamAsync是互斥的，不能混用。一旦使用了某种执行模式，该图就必须继续使用同一种模式。 #### 编译配置变化 Makefile或CMakeLists.txt需要更新： | Session接口 | GeSession接口 | | --- | --- | | \# 旧配置 target\_link\_libraries(your\_app libge\_runner.so) | \# 新配置 target\_link\_libraries(your\_app libge\_runner\_v2.so) |