CANN SHMEM Quick Start 实战指南：Ascend 平台多机多卡共享内存通信库的构建、安装与运行验证

CANN SHMEM Quick Start 实战指南：Ascend 平台多机多卡共享内存通信库的构建、安装与运行验证

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem

本篇技术指南面向昇腾（Ascend）平台的模型与算子开发者，系统讲解 CANN SHMEM 共享内存通信库的环境准备、源码构建、.run 软件包安装、allgather 示例验证、单元测试，以及 Python wheel 与 Unique ID 初始化等完整上手路径。阅读并跟随操作后，你将能够在 Atlas 系列硬件上独立完成 SHMEM 的编译安装、核心功能验证和多进程初始化，为开发跨设备数据同步及通信-计算融合算子打下基础。本文以 docs/quickstart_en.md 为主体，并结合仓库内 scripts/build.sh、scripts/run.sh 与 examples/allgather 等源码与脚本细节进行深化说明。

项目定位与核心能力

CANN SHMEM 面向昇腾平台的多机多卡内存通信场景，为模型与算子开发者提供可移植、易用的多设备多卡内存访问模式，帮助开发者快速搭建设备间数据同步能力，加速通信算子或通信-计算融合算子的开发。

从软件架构上看，SHMEM 的 API 分为两大类别：

• Host 侧 API：提供初始化（init）、内存管理（memory management）、团队管理（team management）与同步（synchronization）功能，对应仓库 include/host 目录下的头文件，以及 src/host 下的实现代码；
• Device 侧 API：提供内存访问（memory access）、同步与团队管理功能，对应 include/device 与 src/device。

这种"双端 API"设计遵循昇腾算子开发范式，支持 host-device 协作。关于 API 分类的更完整说明，可参考 代码组织结构文档。

仓库目录结构

仓库顶层目录布局如下：

├── 3rdparty // 依赖的第三方库 ├── docs // 文档 ├── examples // 使用示例 ├── include // 头文件 ├── scripts // 相关脚本 ├── src // 源码 └── tests // 测试用例

其中 include 按device/、host/、host_device/细分（如 include/device/gm2gm、include/device/ub2gm、include/device/team），src 下同样划分为device/、device_simt/、host/、host_device/、python/，其中 host 侧又细分为bootstrap/、data_plane/、mem/、sync/、team/、transport/、utils/等模块。更多结构细节见 代码组织结构文档。

软硬件版本要求

在开始构建之前，请确认环境满足以下条件：

需要说明的是，当前仓库仅支持昇腾平台，不支持其他硬件架构。此外，README_en.md 中提示：安装 Python wheel 后运行libshmem.so时建议 GLIBC 2.34 及以上，否则可能因缺少符号导致加载失败，可通过ldd --version检查本机 glibc 版本。

快速开始：环境准备与源码构建

1. 设置 CANN 环境变量

以 root 用户安装的默认路径为例：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

从 scripts/build.sh 的实现可以看到，构建脚本会自动定位并 sourceset_env.sh：优先使用${ascend_dir}/ascend-toolkit/set_env.sh，其次是${ascend_dir}/set_env.sh，如果两者同时存在会给出告警并优先使用新路径。

2. 构建共享内存库

在仓库根目录执行构建，并加载构建产物的环境变量：

cd shmem bash scripts/build.sh source install/set_env.sh

构建脚本默认构建 RELEASE 版本（对应 A2/A3 平台的 910 系列 SOC），若目标为 Ascend 950 平台，需追加-soc_type Ascend950。常用构建选项可通过 scripts/build.sh 的print_usage查看，核心参数如下：

注意：脚本默认会复用仓库根目录build/下的 CMake 缓存与编译产物；当切换工具链、清理过期配置或需要全量重编时，使用bash scripts/build.sh -clean。构建过程中会自动下载 googletest（v1.14.x）与 nlohmann/json（v3.11.3）等第三方依赖到3rdparty/，离线环境下需提前准备。

3. 使用 .run 安装包

软件包命名为SHMEM_{version}_linux-{arch}.run，其中{version}为软件版本，{arch}为 CPU 架构。安装（依赖 CANN 环境）步骤如下：

chmod +x Software package name.run # 授予软件包执行权限 ./Software package name.run --check # 检查安装包的一致性与完整性 ./Software package name.run --install # 安装软件，可用 --help 查询安装选项

若输出xxx install success!字样，说明安装成功。安装完成后同样可通过source /usr/local/Ascend/shmem/latest/set_env.sh加载环境（二进制包默认安装路径）。

4. 关于 TLS 通信加密

默认情况下，SHMEM 的 TLS 通信加密处于开启状态。如需关闭，可在初始化之前调用以下 C API：

int32_t ret = aclshmemx_set_conf_store_tls(false, NULL, 0);

务必在aclshmemx_init_attr之前调用该接口，初始化完成后 TLS 配置不可再修改。安全相关的详细说明见 安全说明文档；关闭加密后请确保通信网络为可信内网，防止数据泄露。

运行示例验证核心功能

以allgather示例为例，验证集群通信、数据搬运与精度校验功能：

1. 在shmem/根目录构建示例：

bash scripts/build.sh -examples

2. 进入shmem/examples/allgather目录运行 demo：

bash run.sh -pes 2 -type int32_t

该示例实现基于 SHMEM 的 allgather 集合通信：每个 PE 将本地数据收集到所有 PE，同时完成精度校验，并将性能数据输出到result.csv。

run.sh 参数说明

examples/allgather/run.sh 支持以下参数（完整说明见 examples/allgather/README_en.md）：

典型用法：

# 2 个设备、int32_t 数据类型 bash run.sh -pes 2 -type int32_t # 4 个设备、float16_t 数据类型，从 NPU 卡 2 开始使用 4 张卡 bash run.sh -pes 4 -type float16_t -fnpu 2

从 examples/allgather/run.sh 的脚本实现可以看到其工作流程：先用scripts/data_gen.py生成 golden 数据，随后设置SHMEM_UID_SESSION_ID=127.0.0.1:8899，按-gnpus指定的数量以 msprof 包装方式并行拉起多个allgather进程，最后用scripts/data_statistic.py汇总性能数据。示例代码仅供参考，请勿直接在生产环境使用。

说明：示例中展示的是本仓库的 C++ 示例。PyTorch 集成场景下，allgather.py与 C++ 示例共享同一套 kernel 实现，运行约束（PE 数量仅支持 2、4、8，数据类型为 int32/float16/bfloat16）也保持一致，详见 examples/python_extension/torch_test/README_en.md。

功能自测：单元测试

在项目根目录依次执行：

bash scripts/build.sh -uttests bash scripts/run.sh

scripts/run.sh 提供了-ranks、-test_filter等参数，用于指定执行测试的设备数量与 gtest 过滤规则：

示例：在 8 个设备上运行所有名称包含Init的测试用例：

bash scripts/run.sh -ranks 8 -test_filter Init

从 scripts/run.sh 的实现可以看到，脚本会：生成随机 bootstrap 端口并导出SHMEM_UID_SESSION_ID、关闭 TLS（SMEM_CONF_STORE_TLS_ENABLE=0），随后调用./bin/aclshmem_unittest执行 gtest 用例并输出 XML 报告；UT 运行前后还会通过 tests/unittest/scripts/hbm_leak_check.sh 对 HBM 内存进行泄漏采样比对，若环境未安装 lcov，则跳过覆盖率统计。单元测试需要在具备 NPU、驱动与 CANN 运行时的硬件环境中执行。

Python 测试用例与 wheel 安装

cann-shmemPython wheel 仅支持 Python 3.10 至 3.12，并依赖 TorchNPU（pip 包名torch-npu）。安装 wheel 前，请先按当前 CANN、Python 版本与 CPU 架构准备匹配的torch-npu。完整的 Python API 列表见 Python API 文档。

从昇腾私有索引安装时，可将公共 PyPI 配置为补充索引，以获取私有索引未镜像的依赖：

python3 -m pip install cann-shmem \ --index-url https://ascend.devcloud.huaweicloud.com/cann/pypi/simple/ \ --extra-index-url https://pypi.org/simple/

注意：pip 会合并两个索引的候选包，不保证来源优先级。生产环境建议先显式安装匹配的torch-npu版本，再仅使用昇腾私有索引安装cann-shmem。

本地构建并安装 wheel

1. 在仓库根目录构建 Python 扩展与 wheel 包：

bash scripts/build.sh -python_extension

从 scripts/build.sh 的fn_whl_build实现可以看到，该过程会依次构建 910、950（XSCALE）、950（HNS_1825）等多个 SOC 后端，将各后端libshmem.so拷贝到install/shmem/backends/<soc>/，最终通过python3 setup.py bdist_wheel打出多 SOC wheel；运行时__init__.py会根据当前 SOC 预加载对应后端的libshmem.so。

2. 加载环境变量：

source install/set_env.sh

3. 安装dist目录下生成的 wheel 包：

python3 -m pip install --force-reinstall dist/cann_shmem-*.whl

4. 按需启用或禁用 TLS 认证（默认启用）：

import shmem as shm shm.set_conf_store_tls(False, "") # 禁用 TLS 认证

import shmem as shm tls_info = "xxx" shm.set_conf_store_tls(True, tls_info) # 启用 TLS 认证

5. 使用 Torchrun 运行测试 demo：

torchrun --nproc-per-node=k test.py // k 为要运行的 rank 数量

若日志输出test.py running success!，说明 demo 运行成功。

提示：安装 wheel 后可使用shmem-config --version查询版本、shmem-config --diagnose检查原生库加载与包完整性，详见 shmem-config 使用指南。

Unique ID 初始化方式

当使用 Unique ID 相关 API 进行初始化时，可手动配置环境变量SHMEM_UID_SESSION_ID或SHMEM_UID_SOCK_IFNAME：

• 若两个变量同时配置，仅读取SHMEM_UID_SESSION_ID；
• 若均未配置，默认自动搜索可用网络端口；搜索优先级为：非虚拟网口（排除 lo/docker/veth/br-/virbr/tun/tap）优先于虚拟网口；
• SHMEM_UID_SESSION_ID支持 IPv4 地址、IPv6 地址和主机名。

SHMEM_UID_SESSION_ID配置示例：

SHMEM_UID_SESSION_ID=127.0.0.1:1234 SHMEM_UID_SESSION_ID=[6666:6666:6666:6666:6666:6666:6666:6666]:886 SHMEM_UID_SESSION_ID=[6666:6666:6666:6666:6666:6666:6666:6666%eth]:886 SHMEM_UID_SESSION_ID=localhost:8888

SHMEM_UID_SOCK_IFNAME配置示例：

SHMEM_UID_SOCK_IFNAME=enpxxxx:inet4 # IPv4 SHMEM_UID_SOCK_IFNAME=enpxxxx:inet6 # IPv6 SHMEM_UID_SOCK_IFNAME=eth0 # 自动检测可用协议（优先 IPv4）

Python 初始化示例

将以下代码保存为init.py（可参考 examples/python_extension/test/unique_id_test.py 的完整用例）：

import shmem as ash # xxx uid = ash.aclshmem_get_unique_id() ret = ash.aclshmem_init_using_unique_id(rank, world_size, mem_size, uid) # xxx

随后使用torchrun --nproc-per-node 8 init.py启动（进程数可按需调整）。从 examples/python_extension/test/unique_id_test.py 的实现可以看到完整的初始化流程：rank 0 调用ash.aclshmem_get_unique_id()获取 uid，通过dist.broadcast_object_list广播给所有进程，各进程再以ash.aclshmem_init_using_unique_id(pe, world_size, g_ash_size, unique_id)完成初始化，随后可进行aclshmem_malloc分配、my_pe()/pe_count()校验与aclshmem_finalize()释放。

C++ 初始化示例

aclshmemx_uniqueid_t uid; aclshmemx_init_attr_t attributes; int ret = aclshmemx_get_uniqueid(&uid); ret = aclshmemx_set_attr_uniqueid_args(my_pe, n_pes, mem_size, &uid, &attributes); status = aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_UNIQUEID, &attributes);

常见问题速查

• 构建时提示 "CANN environment not found"：确认已安装 CANN 工具链并执行source /usr/local/Ascend/ascend-toolkit/set_env.sh，且 CANN 版本满足上文"软硬件版本要求"。
• 运行示例时提示 "inter-device communication timeout"：检查 RDMA 网卡可用性、节点间网络连通性、防火墙是否放行初始化通信端口（默认 8666）、交换机无损网络配置是否正确，以及各节点时钟是否同步。
• Python 导入 shmem 报 "module not found"：确认 wheel 已安装、已 sourceinstall/set_env.sh，且PYTHONPATH包含 shmem 路径。
• 关闭 TLS 后仍报加密失败：aclshmemx_set_conf_store_tls必须在aclshmemx_init_attr之前调用，初始化后无法修改。
• 离线环境构建报 git 拉取依赖失败：googletest（UT 构建用）与 nlohmann/json（Ascend 950 构建用）默认由构建脚本自动下载，离线环境需提前放入3rdparty/googletest与3rdparty/json。

更完整的排障指引见 故障排查 FAQ，术语与缩写说明见 术语表。

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem