ElasticBuffer

产品支持情况

  • Ascend 950DT系列产品:支持
  • Atlas A3系列产品:不支持
  • Atlas A2系列产品:不支持
  • Atlas 200I/500 A2推理产品:不支持
  • Atlas推理系列产品:不支持
  • Atlas训练系列产品:不支持

功能说明

ElasticBuffer类提供统一的分布式通信buffer管理能力:

  • Engram存储接口用于分布式Engram存储管理,支持将本rank的表注册为通信可达的存储(推理模式可写入host pinned共享内存段或显式零拷贝注册调用方内存,训练模式直接映射上层锁页表内存),以及通过URMA从远端rank抓取Engram数据。group=None 表示full-vocab local推理,不初始化HCCL。
  • Engram训练接口在推理接口的基础上,通过 with_grad=True 开启训练模式。前向 engram_fetch 在抓取数据的同时保存反向所需的通信元数据(封装为 EngramFetchCtx),反向 engram_fetch_grad 根据这些元数据将梯度沿前向路径反向交换并按local entry稀疏累加,产出稀疏梯度用于优化器更新。
  • Dispatch/Combine接口用于MoE的Expert Parallelism(EP)并行部署,支持通过dispatch将token数据分发到对应专家卡,再通过combine将专家输出按原路由聚合回原始序列。所需的HCCL通信buffer由ElasticBuffer内部按算子参数自动计算并申请,无需手动配置。

函数原型

class ElasticBuffer:
    def __init__(
        self,
        group: Optional[torch.distributed.ProcessGroup],
        *,
        num_cpu_bytes: int = 0,
        num_max_tokens_per_rank: Optional[int] = None,
        hidden: Optional[int] = None,
        num_topk: Optional[int] = None,
        with_grad: bool = False,
        explicitly_destroy: bool = False,
        netlayer: str = "auto",
        comm_alg: str = "auto",
    )

    def engram_write(
        self,
        storage: torch.Tensor,
        sf: Optional[torch.Tensor] = None,
        *,
        zero_copy: Optional[bool] = None,
    ) -> None

    def engram_fetch(self, indices: torch.Tensor) -> Callable

    def engram_fetch_grad(
        self,
        grad_fetched: torch.Tensor,
        fetch_ctx: EngramFetchCtx,
    ) -> Tuple[torch.Tensor, torch.Tensor]

    def barrier(self, use_comm_stream: bool = True, with_cpu_sync: bool = False) -> None

    @staticmethod
    def get_engram_storage_size_hint(
        num_entries: int,
        hidden: int,
        dtype: torch.dtype = torch.bfloat16,
    ) -> int

    def dispatch(
        self,
        x: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
        *,
        topk_idx: Optional[torch.Tensor] = None,
        topk_weights: Optional[torch.Tensor] = None,
        handle: Optional[EPHandle] = None,
        num_experts: Optional[int] = None,
        num_max_tokens_per_rank: Optional[int] = None,
        expert_alignment: Optional[int] = None,
        do_cpu_sync: Optional[bool] = None,
        async_with_compute_stream: bool = False,
    ) -> Union[Tuple[Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]],
                     Optional[torch.Tensor], Optional[torch.Tensor], EPHandle],
               object]

    def combine(
        self,
        x: torch.Tensor,
        handle: EPHandle,
        *,
        topk_weights: Optional[torch.Tensor] = None,
        bias: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor], None] = None,
        async_with_compute_stream: bool = False,
    ) -> Union[Tuple[torch.Tensor, Optional[torch.Tensor]], object]

    @staticmethod
    def get_moe_ep_ccl_buffer_size(
        world_size: int,
        num_max_tokens_per_rank: int,
        hidden: int,
        num_experts: int,
        topk: int,
    ) -> int

    def destroy(self) -> None

EngramFetchCtx

前向 engram_fetch 在 with_grad=True 时返回的save-for-backward上下文,需原样传递给反向 engram_fetch_grad。该对象由内部自动构造,无需手动创建。

属性 类型 shape 说明
perm Tensor (num_tokens,) int32 桶排列序索引,反向按此重排梯度
send_counts Tensor (world_size*8,) int32 每rank发送的index数量(填充至32字节对齐,前world_size个元素有效),反向a2a的send量
recv_counts Tensor (world_size,) int32 每rank接收的index数量,反向a2a的recv量
recv_local_entry Tensor (R_max,) int32 前向a2a交换收到的全局索引,前 num_recv 个元素有效,其中 R_max = num_max_tokens_per_rank × world_size
num_recv Tensor (1,) int32 实际接收的全局索引数量 num_recv,其中num_recv ≤ R_max

成员函数说明

init

功能:构造ElasticBuffer实例,记录Engram和Dispatch/Combine所需配置。Engram运行时资源在首次调用 engram_write 时初始化;Dispatch/Combine通信上下文在首次调用 dispatch 或 combine 时初始化。

输入参数:

  • group (Optional[torch.distributed.ProcessGroup]):必选参数。非 None 时为HCCL分布式进程组;None 表示full-vocab local推理,固定 world_size=1,不初始化HCCL、不支持训练。
  • *:其之前的变量是位置相关的;之后的变量是可选参数,需要使用键值对赋值,不赋值会使用默认值。
  • num_cpu_bytes (int):可选参数,CPU buffer大小(字节),用于host pinned存储区分配(仅推理模式生效;训练模式不分配内部存储区,该参数不生效)。默认值为0,且必须2MB对齐。
  • num_max_tokens_per_rank (int):可选参数,表示每张卡上的最大token数量上限。使用 dispatch 和 combine 时必须与 hidden、num_topk 一起指定;使用 with_grad=True 训练模式时必须指定且大于0。
  • hidden (int):可选参数,hidden size隐藏层大小。
  • num_topk (int):可选参数,表示选取topK个专家。
  • with_grad (bool):可选参数,是否开启训练。默认为 False(推理)。设为 True 时,前向 engram_fetch 会额外保存反向所需的通信元数据(封装为 EngramFetchCtx),并可通过 engram_fetch_grad 执行反向。
  • explicitly_destroy (bool):可选参数,是否需要显式调用 destroy 释放资源。默认为 False,实例被垃圾回收时会自动调用 destroy 释放资源;设为 True 时,调用方需要显式调用 destroy 释放资源。推荐设置为 True 并在使用结束后手动调用 destroy 释放资源,以确保资源释放时机确定。
  • netlayer (str):可选参数,HCCL网络分层(netlayer)选择,仅作用于Engram建链。取值:"auto"(默认)自netlayer 0起逐层探测尝试建链;非负整数字符串(如 "1")表示netlayer编号,仅在该分层内建链,失败则报错返回。建议按“d2d与h2d同die”的原则选择分层建链:使对端访问本卡host映射内存的d2d链路,与本卡NPU访问该内存的h2d路径位于同一die,避免跨die转发,获得更优通信带宽与时延。
  • comm_alg (str):可选参数,指定Dispatch/Combine使用的通信端口策略。仅支持 "auto" 和 "clos_only",默认值为 "auto"。"auto" 表示组网中的FullMesh端口和Clos端口都会使用;"clos_only" 表示只使用Clos端口、不使用FullMesh端口。在clos_only下,不支持UBG(UB_RTP)协议链路。

输出说明:无返回值,构造ElasticBuffer实例。

engram_write

功能:将本rank的Engram表注册为通信可达的Engram storage,使其他rank可读取该数据。按构造时的 with_grad 与 zero_copy 区分行为:

  • 推理(with_grad=False,zero_copy=False):将 storage 数据拷贝到内部host pinned共享内存段;group=None 且未显式指定容量时,内部按 storage.nbytes() 向上2MB对齐。当 storage 为FP8量化类型时,须同时传入SF量化表 sf。
  • 推理(with_grad=False,zero_copy=True):原地注册 storage 主机内存,注册或映射失败直接报错,不隐式回退到拷贝。当 storage 为FP8量化类型时,须同时传入SF量化表 sf。
  • 训练(with_grad=True):将 storage 的锁页内存直接映射为Engram storage(零拷贝,无数据搬运),storage 的原地更新对后续 engram_fetch 可见。当 storage 为FP8量化类型时,须同时传入SF量化表 sf。

写入完成后,内部都会获取通信上下文tensor、本地storage地址和rank数等信息,供后续 engram_fetch 使用。

推理模式内存说明:Engram storage的内存形态由 zero_copy 参数决定。zero_copy=False 时,使用内部host pinned共享内存段,即通过 aclrtMallocHost 分配的页锁定(pinned)主机内存,经 aclrtHostRegisterV2 映射后获得设备可访问地址,storage 数据拷贝写入其中,其大小由构造函数的 num_cpu_bytes 参数指定;zero_copy=True 时,不经过内部拷贝,直接将调用方提供的 storage 主机内存经 aclrtHostRegisterV2 注册并映射到设备地址,即调用方内存原地成为本rank的Engram storage,注册或映射失败直接报错,不隐式回退到拷贝路径,注册后 storage 的原地更新对后续 engram_fetch 可见,且在本ElasticBuffer生命周期内必须保持存活且地址不变。两种方式的内存均既可被本卡NPU直接访问,也可被远端rank的NPU通过URMA读取,从而实现跨rank的零拷贝数据共享。 训练模式内存映射:storage 的锁页主机内存经 aclrtHostRegisterV2 注册并映射到设备地址,再注册到HCCL通信域供远端rank访问。要求:storage 必须为锁页内存(如 pin_memory() 或 torch.empty(..., pin_memory=True) 分配);普通(非锁页)CPU内存在当前驱动的主机注册路径下不受支持,会在首次调用时报 aclrtHostGetDevicePointer 失败;storage 在本ElasticBuffer生命周期内必须保持存活且地址不变。重复调用本接口须传入同一 storage(可作为表原地更新后的跨rank同步点),传入其他地址会报错。

计算公式:

推理模式(zero_copy=False)通过memcpy_s将storage的数据按字节拷贝到内部host pinned共享内存段起始位置:

HostPinnedBuf[0:storage.nbytes()]←storage.data()HostPinnedBuf[0 : storage.nbytes()] \leftarrow storage.data()

推理模式(zero_copy=True)无拷贝,调用方主机内存经主机注册映射后直接作为本rank的Engram表:

EngramTable[rank_id]≡storageEngramTable[rank\_id] \equiv storage

训练模式无拷贝,storage 的锁页内存经主机注册映射后直接作为本rank的Engram表:

EngramTable[rank_id]≡storageEngramTable[rank\_id] \equiv storage

分布式模式写入前后各执行一次 Barrier;group=None local模式没有通信域,不执行 Barrier:

Barrier→write(storage)→BarrierBarrier \rightarrow write(storage) \rightarrow Barrier

其中 storage.nbytes() = num_entries × hidden × dtype_size,zero_copy=False 时须满足 storage.nbytes() ≤ num_cpu_bytes。

函数原型:

ElasticBuffer.engram_write(storage, sf=None, *, zero_copy=None) -> None

输入参数:

  • storage (Tensor):必选参数,待写入的CPU tensor,shape为 (num_entries, hidden),表示有 num_entries 个条目,每个条目维度为 hidden。要求2维、连续、hidden必须大于0,数据类型支持 bfloat16、float16、float32(不带SF时)、float8_e4m3fn、float8_e5m2(带SF时)。
  • sf (Optional[Tensor]):可选参数,FP8量化的缩放因子(Scale Factor)表,仅当 storage 为 float8_e4m3fn 或 float8_e5m2 时传入(此时为必选)。要求2维张量,shape为 (行数, num_sf_packs),列数 num_sf_packs = ceil(hidden / group_size),其中 group_size 为MX量化的分组大小(每分组一个SF),即对每个条目的 hidden 个元素按分组数向上取整,须满足 0 < num_sf_packs ≤ hidden。行数按模式区分:训练模式为本rank的分片SF表,有 num_entries_per_rank 行,且为CPU锁页(pinned)张量;推理模式为全量SF表,有 num_entries_per_rank × rank_size 行,且为NPU张量。数据类型支持 float32、float8_e8m0,数据格式为 NDND。
  • zero_copy (Optional[bool]):keyword-only参数。未传时按模式取默认值:推理为 False,训练为 True。推理时 False 表示拷贝到内部host pinned window,True 表示原地注册调用方内存,失败直接抛错;训练时始终原地注册pinned storage,显式传 False 会直接报错。

输出说明:无返回值。推理模式 zero_copy=False 时,数据拷贝写入内部host pinned共享内存段;推理模式 zero_copy=True 时,storage 调用方内存被原地注册为Engram storage(无数据搬运);训练模式 storage 锁页内存被注册为Engram storage。

engram_fetch

功能:根据输入的全局索引,从对应rank抓取Engram数据。推理和训练的行为由构造时的 with_grad 决定:

  • 推理(with_grad=False):通过URMA one-sided read从远端rank的Engram storage抓取数据,可读取远端 engram_write 写入内部host pinned共享内存段的数据,也可读取远端以 zero_copy=True 原地注册的调用方内存,两种注册方式对抓取侧透明。接口采用异步设计:调用后立即返回一个callable,执行该callable时阻塞等待URMA传输完成并返回结果tensor。engram_write 传入过 sf 时,callable额外返回每token对应的SF数据 fetched_sf,即返回 (fetched, fetched_sf)。
  • 训练(with_grad=True):通过all-to-all通信从远端rank抓取数据(桶排序 → a2a交换indices → 本地gather → a2a交换data → 还原),返回一个callable,执行该callable时等待传输完成并返回 (fetched, fetch_ctx) 二元组,其中 fetch_ctx 为save-for-backward上下文 EngramFetchCtx。engram_write 传入过 sf 时,callable额外返回每token对应的SF数据 fetched_sf,即返回 (fetched, fetched_sf, fetch_ctx);SF数据与hidden数据同行存放、随token一起交换,反向无SF梯度。

计算公式:

每个全局索引按如下方式映射到目标rank和本地条目索引:

rank_id=⌊global_idx/num_entries⌋rank\_id = \lfloor global\_idx / num\_entries \rfloor

local_idx=global_idx mod num_entrieslocal\_idx = global\_idx \bmod num\_entries

fetched[i]=EngramTable[rank_id][local_idx]fetched[i] = EngramTable[rank\_id][local\_idx]

其中各变量含义如下:

  • global_idxglobal\_idx:输入索引张量 indices 的元素值,取值范围 [0,world_size×num_entries)[0, world\_size \times num\_entries)。
  • num_entriesnum\_entries:engram_write 时各rank写入的条目数,即 storage.size(0)。
  • world_sizeworld\_size:通信域中的rank总数。
  • rank_idrank\_id:global_idxglobal\_idx 映射到的目标rank编号,取值范围 [0,world_size)[0, world\_size)。当 rank_idrank\_id 为本rank时,数据直接从本地的Engram storage(host pinned共享内存段或原地注册的调用方内存)读取;当 rank_idrank\_id 为远端rank时,通过URMA跨卡读取。
  • local_idxlocal\_idx:目标rank内的本地条目索引,取值范围 [0,num_entries)[0, num\_entries)。
  • EngramTable[rank_id]EngramTable[rank\_id]:目标rank通过 engram_write 提供的Engram表数据(推理模式位于host pinned共享内存段或 zero_copy=True 原地注册的调用方内存,训练模式为直接映射的上层锁页表内存),shape为 (num_entries, hidden), EngramTable[rank_id][local_idx]EngramTable[rank\_id][local\_idx] 表示其中第 local_idxlocal\_idx 个条目。
  • fetched[i]fetched[i]:输出张量中第 ii 个token对应的Engram数据,i∈[0,num_tokens)i \in [0, num\_tokens),num_tokensnum\_tokens 为 indices 的长度。

训练(with_grad=True)的索引映射与推理一致(见上述 rank_idrank\_id、local_idxlocal\_idx 公式),区别在于通过all-to-all通信完成跨rank数据抓取,并保存反向上下文 EngramFetchCtx。前向过程为:

  1. 桶排序:按 rank_idi=⌊indices[i]/num_entries⌋rank\_id_i = \lfloor indices[i] / num\_entries \rfloor 对 indices 分桶,记录桶排列序 permperm 与每rank发送量 send_countssend\_counts:

    send_counts[r]=∣{ i∣rank_idi=r }∣,r∈[0,world_size)send\_counts[r] = |\{\,i \mid rank\_id_i = r\,\}|, \quad r \in [0, world\_size)

  2. a2a交换indices:各rank将排序后的indices(全局索引)发送到目标rank,接收其他rank请求的全局索引,得到 recv_local_entryrecv\_local\_entry(均为映射到本rank的全局索引,即 global_idx / num_entries == rank_id)、recv_countsrecv\_counts,接收总量 num_recv=∑r=0world_size−1recv_counts[r]num\_recv = \sum_{r=0}^{world\_size-1} recv\_counts[r]。

  3. 本地gather:将 recv_local_entryrecv\_local\_entry 中的全局索引按 local_idx=recv_local_entry[j] mod num_entrieslocal\_idx = recv\_local\_entry[j] \bmod num\_entries 转换后,从本地 EngramTable[rank_id]EngramTable[rank\_id] 读取:

    local_data[j]=EngramTable[rank_id][recv_local_entry[j] mod num_entries],j∈[0,num_recv)local\_data[j] = EngramTable[rank\_id][recv\_local\_entry[j] \bmod num\_entries], \quad j \in [0, num\_recv)

    启用SF量化时,SF行按同一 local_idxlocal\_idx 从本rank SF表读取,与hidden数据同行存放(行宽 rowStride=hidden_bytes+sf_bytesrowStride = hidden\_bytes + sf\_bytes)。

  4. a2a交换data:将 local_datalocal\_data(含SF行,每行 rowStriderowStride 字节)沿原请求路径送回,得到 recv_data[i]recv\_data[i],i∈[0,num_tokens)i \in [0, num\_tokens)。

  5. 还原:按 permperm 重排回原始token顺序:

    fetched[perm[i]]=recv_data[i],i∈[0,num_tokens)fetched[perm[i]] = recv\_data[i], \quad i \in [0, num\_tokens)

  6. 保存反向上下文 fetch_ctxfetch\_ctx(即 EngramFetchCtx),包含 permperm、send_countssend\_counts、recv_countsrecv\_counts、recv_local_entryrecv\_local\_entry、num_recvnum\_recv 五个字段,供反向 engram_fetch_grad 使用。

函数原型:

ElasticBuffer.engram_fetch(indices) -> Callable

输入参数:

  • indices (Tensor):必选参数,查询索引的NPU tensor,shape为 (num_tokens,),表示要抓取的条目全局索引(训练场景各卡len(indices)保持一致,推理场景可以不一致)。数据类型支持 int32,数据格式为 NDND。元素取值范围需在 [0, world_size × num_entries),若某一位置的元素取值超过了该范围,则返回值中该位置对应的数据为0。

输出说明:

  • wait_callable (Callable):返回一个callable,调用时根据模式返回不同结果。

推理调用 wait_callable() 返回:

  • fetched (Tensor):NPU tensor,shape为 (num_tokens, hidden),数据类型与 engram_write 的 storage.dtype 相同,数据格式为 NDND。
  • fetched_sf (Tensor):可选返回,启用SF量化时返回。NPU tensor,shape为 (num_tokens, num_sf_packs),数据类型与 engram_write 的 sf.dtype 相同,数据格式为 NDND。

训练调用 wait_callable() 返回:

  • fetched (Tensor):NPU tensor,shape为 (num_tokens, hidden),数据类型与 storage.dtype 相同,数据格式为 NDND。
  • fetched_sf (Tensor):可选返回,启用SF量化时返回,规格同推理。
  • fetch_ctx (EngramFetchCtx):save-for-backward上下文,包含反向所需的5个通信元数据tensor(详见 EngramFetchCtx)。需原样传递给 engram_fetch_grad。

engram_fetch_grad

功能:训练反向接口,需与训练模式的 engram_fetch 配套使用。根据前向保存的 EngramFetchCtx,将 grad_fetched 沿前向路径反向交换并按local entry稀疏累加,产出稀疏梯度用于优化器更新。

计算公式:

反向沿前向路径逆序执行,fetch_ctxfetch\_ctx 各字段(permperm、send_countssend\_counts、recv_countsrecv\_counts、recv_local_entryrecv\_local\_entry、num_recvnum\_recv)均来自前向 engram_fetch 训练模式返回的 EngramFetchCtx。依次为:

  1. Unsort:按 permperm 将 grad_fetchedgrad\_fetched 重排回桶排序顺序:

    grad_sorted[i]=grad_fetched[perm[i]],i∈[0,num_tokens)grad\_sorted[i] = grad\_fetched[perm[i]], \quad i \in [0, num\_tokens)

  2. 反向a2a交换:将 grad_sortedgrad\_sorted 通过a2a反向交换(send_countssend\_counts 为send量,recv_countsrecv\_counts 为recv量),各rank收到对应 recv_local_entryrecv\_local\_entry 的梯度:

    grad_recv[j]↔recv_local_entry[j],j∈[0,num_recv)grad\_recv[j] \leftrightarrow recv\_local\_entry[j], \quad j \in [0, num\_recv)

  3. Unique:对 recv_local_entryrecv\_local\_entry 按 local_idx=recv_local_entry[j] mod num_entrieslocal\_idx = recv\_local\_entry[j] \bmod num\_entries 转换后去重,得到本rank local entry索引集合:

    unique_local_entry=unique({ recv_local_entry[j] mod num_entries∣j∈[0,num_recv) })unique\_local\_entry = \text{unique}(\{\,recv\_local\_entry[j] \bmod num\_entries \mid j \in [0, num\_recv)\,\})

  4. ScatterAdd:对每个unique entry,按FP32累加所有映射到该entry的梯度后转回输出dtype:

grad_unique[k]=Castdtype ⁣(∑j∈[0,num_recv)recv_local_entry[j]modnum_entries=unique_local_entry[k]Castfp32(grad_recv[j]))grad\_unique[k] = \text{Cast}_{dtype}\!\left(\sum_{\substack{j \in [0,num\_recv) \\ recv\_local\_entry[j] \bmod num\_entries = unique\_local\_entry[k]}} \text{Cast}_{fp32}(grad\_recv[j])\right)

其中 KK 为去重后的local entry数量(运行时决定,输出前 KK 行有效),num_tokensnum\_tokens 为 indices 的长度,num_entriesnum\_entries 为 engram_write 时各rank写入的条目数。grad_unique 与 unique_local_entry 可直接用于优化器稀疏更新。

函数原型:

ElasticBuffer.engram_fetch_grad(grad_fetched, fetch_ctx) -> (Tensor, Tensor)

输入参数:

  • grad_fetched (Tensor):必选参数,前向 fetched 的梯度,NPU tensor,shape为 (num_tokens, hidden),数据类型支持 bfloat16、float16、float32,数据格式为 NDND。
  • fetch_ctx (EngramFetchCtx):必选参数,前向 engram_fetch 训练模式返回的上下文对象,包含 perm、send_counts、recv_counts、recv_local_entry、num_recv 五个字段。

输出说明:

  • grad_unique (Tensor):NPU tensor,shape为 (K, hidden),数据类型与 grad_fetched 相同(内部按FP32累加后转回输出dtype),数据格式为 NDND。其中 K 为去重后的local entry数量(运行时决定),前 K 行有效。
  • unique_local_entry (Tensor):NPU tensor,shape为 (K,),数据类型为 int32,数据格式为 NDND。表示 grad_unique 每行对应的local entry索引。

barrier

功能:跨卡同步。

函数原型:

ElasticBuffer.barrier(use_comm_stream=True, with_cpu_sync=False) -> None

输入参数:

  • use_comm_stream (bool):可选参数,表示是否使用专用通信stream执行barrier。默认值为 True,使用专用通信stream,barrier前后通过event同步计算流与通信流;设为 False 时使用当前计算stream。
  • with_cpu_sync (bool):可选参数,表示是否在barrier前后同步设备。默认值为 False。设为 True 时,在barrier前后各调用一次 aclrtSynchronizeDevice,确保设备侧操作完成。

输出说明:无返回值。

get_engram_storage_size_hint(静态方法)

功能:计算Engram存储所需的CPU buffer大小。

计算公式:

dtype_size = elementSize(dtype)              # 如bfloat16=2, float16=2, float32=4
hidden_size_bytes = hidden × dtype_size
num_bytes_per_entry = Align32(hidden_size_bytes)
num_cpu_bytes = Align2MB(num_bytes_per_entry × num_entries)

其中 AlignX(value) = ((value + X - 1) / X) × X,/ 表示整除。num_bytes_per_entry 按32字节对齐,最终结果按2兆字节对齐。

函数原型:

ElasticBuffer.get_engram_storage_size_hint(
    num_entries, hidden, dtype=torch.bfloat16
) -> int

输入参数:

  • num_entries (int):必选参数,Engram storage的条目数,必须非负。
  • hidden (int):必选参数,每个条目的隐藏层维度,必须大于0。
  • dtype (torch.dtype):可选参数,数据类型,默认为 torch.bfloat16。仅在此处用于按dtype计算字节数。

输出说明:

  • num_cpu_bytes (int):CPU buffer大小(MB),用于engram_write的本地存储区(仅推理模式使用),已按2MB对齐。

dispatch

功能:需与 combine 配套使用,完成MoE的Expert Parallelism(EP)并行部署下的token dispatch。该接口根据每个token的topK专家索引,将token数据通过EP域的alltoallv通信分发到对应的专家卡上。

  • 支持cached模式,即第二次dispatch时可复用第一次的handle,跳过slot分配阶段,实现更低延迟。
  • 支持指定 num_max_tokens_per_rank 控制接收buffer大小上限。

计算公式:

alltoall_x_out=alltoallv(x)alltoall\_x\_out = alltoallv(x)

dst_buffer_slot_idx=SlotAssignment(topk_idx)dst\_buffer\_slot\_idx = SlotAssignment(topk\_idx)

recv_src_metadata=MetadataAssignment(alltoall_x_out,topk_idx)recv\_src\_metadata = MetadataAssignment(alltoall\_x\_out, topk\_idx)

函数原型:

ElasticBuffer.dispatch(
    x,
    *,
    topk_idx=None,
    topk_weights=None,
    handle=None,
    num_experts=None,
    num_max_tokens_per_rank=None,
    expert_alignment=None,
    do_cpu_sync=None,
    async_with_compute_stream=False,
) -> (Tensor | Tuple[Tensor, Tensor], Tensor | None, Tensor | None, EPHandle) | object

输入参数:

  • x (Tensor 或 Tuple[Tensor, Tensor]):必选参数,表示计算使用的token数据,需根据 topk_idx 来发送给其他卡。当传入tuple时,第一个Tensor为token数据,第二个Tensor为scales。token要求为2 维张量,shape为 (BS, H),数据类型支持 bfloat16、float16、float8_e5m2、float8_e4m3fn,数据格式为 NDND。scales要求为2 维张量,shape为 (BS, H1),数据类型支持float32或float8_e8m0,数据格式为 NDND,只在token为float8_e5m2、float8_e4m3fn数据类型时传入。
  • *:其之前的变量是位置相关的;之后的变量是可选参数,需要使用键值对赋值,不赋值会使用默认值。
  • topk_idx (Tensor):可选参数,表示每个token的topK个专家索引,决定每个token要发给哪些专家。要求为2 维张量,shape为 (BS, K),数据类型支持 int32,数据格式为 NDND。张量里value取值范围为 [0, num_experts)。非cached模式下为必选参数,cached模式下必须为 None。
  • topk_weights (Tensor):可选参数,表示每个token对应的topK专家权重。要求为2 维张量,shape为 (BS, K),数据类型支持 float32,数据格式为 NDND。非cached模式下为可选参数,cached模式下必须为 None。
  • handle (EPHandle):可选参数,表示上一次dispatch返回的handle对象,用于cached模式。传入handle时,topk_idx 和 topk_weights 必须为 None,do_cpu_sync 必须为 False。默认为 None,即非cached模式。
  • num_experts (int):可选参数,MoE专家总数量。取值范围 [2, 2048],且满足 num_experts % ep_world_size = 0。非cached模式下为必选参数;cached模式下使用 handle 中的值,传入参数被忽略。
  • num_max_tokens_per_rank (int):可选参数,表示每张卡上的最大token数量上限,传入时覆盖ElasticBuffer初始化的值。默认使用初始化时传入的值。cached模式下使用 handle 中的值,传入参数被忽略。
  • expert_alignment (int):可选参数,表示专家对齐数。当前仅支持取值1;cached模式使用 handle 中的值。
  • do_cpu_sync (bool):可选参数,表示是否进行CPU同步等待。非cached模式默认为 True,cached模式下不能为 True。
  • async_with_compute_stream (bool):可选参数,表示是否启用异步调用,默认为 False。设为 True 时返回event对象,可在执行独立计算后调用 event.current_stream_wait() 获取dispatch结果。

输出说明:

  • async_with_compute_stream=False:接口直接返回最终结果。
  • async_with_compute_stream=True:主阶段提交后,接口返回 event (object),用于管理本次异步调用。调用 event.current_stream_wait() 获取最终结果。

两种方式的最终结果内容、顺序和类型一致,各项说明如下:

  • recv_x (Tensor 或 Tuple[Tensor, Tensor]):表示本卡收到的token数据。Tensor shape为 (A, H),数据类型与 x 一致,数据格式为 NDND。经专家网络处理后,作为 combine 的 x 输入。当 x 输入包含scales时,输出为 (recv_x, recv_scales)。

  • recv_topk_idx (None):当前版本始终为 None,预留参数。

  • recv_topk_weights (Tensor | None):表示本卡收到的topK权重。仅当输入 topk_weights 不为 None 时返回,否则为 None。要求为1 维张量,shape为 (A,),数据类型为 float32,数据格式为 NDND,作为 combine 的 topk_weights 输入。

  • handle (EPHandle):表示dispatch阶段生成的handle对象,包含slot索引、元数据等信息,需传递给 combine 使用。handle的属性如下:

    • dst_buffer_slot_idx (Tensor):发送侧索引,dtype为 int32。
    • recv_src_metadata (Tensor):接收元数据,shape为 (A_alloc, 5),dtype为 int32;仅前 sum(num_recv_tokens_per_expert) 行有效。
    • recv_rank_offsets (Tensor):各源EP rank对应metadata行数的排他前缀和,shape为 (ep_world_size + 1,),dtype为 int32;rank r 的metadata区间为 [recv_rank_offsets[r], recv_rank_offsets[r + 1]),最后一个元素等于有效metadata行数。它是下述 packed buffer 尾部的视图,cached模式复用其内容,不再是独立算子输入/输出。
    • recv_metadata_buffer (Tensor):连续一维 int32 backing tensor,基址要求512字节对齐。前 A_alloc * 5 个元素保留五列语义;offsets从 align_up(A_alloc * 5 * 4, 512) 字节处开始。总字节数为 align_up(A_alloc * 5 * 4, 512) + align_up((ep_world_size + 1) * 4, 512)。两段padding不参与计算或精度比较,内容未定义。recv_src_metadata 和 recv_rank_offsets 必须保持为此buffer的视图。

    底层Dispatch Epilogue、cached输入和Combine仅传完整packed tensor,不能传五列子视图后越过其shape访问尾部;偏移使用分配容量 A_alloc,而非有效行数。cached输入输出使用相同容量。旧的两tensor句柄需显式打包或重新dispatch,不能混用旧算子包与新wheel;复制到其他设备时先复制完整buffer,再按容量重建视图。请成套重新编译安装算子和wheel(包含 moe_ep_metadata_layout.h),并更新JIT缓存。

    • num_recv_tokens_per_rank (Tensor):各卡接收token数量,shape为 (ep_world_size,),dtype为 int32。
    • num_recv_tokens_per_expert (Tensor):每个本地专家接收的token数量,shape为 (num_local_experts,),dtype为 int64。
    • num_experts (int):专家总数量。
    • expert_alignment (int):专家对齐数。
    • num_max_tokens_per_rank (int):每张卡最大token数量上限。
    • topk_idx (Tensor):原始topK索引。

combine

功能:需与 dispatch 配套使用,相当于按dispatch算子收集数据的路径原路返回。该接口将专家处理后的token数据根据dispatch阶段记录的元数据信息,通过逆向路由和纯累加聚合,将token数据组合还原为原始序列顺序。

  • 当前版本仅支持纯累加模式。
  • 当前版本不支持bias参数。

计算公式:

combined_xi=∑k=0K−1xslot(i,k)combined\_x_i = \sum_{k=0}^{K-1} x_{slot(i,k)}

函数原型:

ElasticBuffer.combine(
    x, handle, *, topk_weights=None, bias=None, async_with_compute_stream=False
) -> (Tensor, Tensor?) | object

输入参数:

  • x (Tensor):必选参数,表示经过专家计算后的token数据,即 dispatch 输出的 recv_x 经过专家网络处理后的结果。要求为2 维张量,shape为 (A, H),数据类型支持 bfloat16、float16,数据格式为 NDND。
  • handle (EPHandle):必选参数,表示 dispatch 返回的handle对象,包含slot索引、接收元数据等信息。handle的属性参见 dispatch 输出说明。
  • *:其之前的变量是位置相关的;之后的变量是可选参数,需要使用键值对赋值,不赋值会使用默认值。
  • topk_weights (Tensor):可选参数,用于训练反向场景,表示专家权重的梯度,要求为1 维张量,shape为 (A,),数据类型支持 float32,数据格式为 NDND,传入时按dispatch 输入的 topk_idx 顺序输出combined_topk_weights。若不提供,输出 combined_topk_weights 为 None。
  • bias (Tensor 或 Tuple[Tensor, Tensor]):可选参数,当前版本不支持bias,传入 None 即可。预留支持单个bias张量或 bias_0、bias_1 双张量模式。
  • async_with_compute_stream (bool):可选参数,表示是否启用异步调用,默认为 False。设为 True 时返回event对象,可在执行独立计算后调用 event.current_stream_wait() 获取combine结果。

输出说明:

  • async_with_compute_stream=False:接口直接返回最终结果。
  • async_with_compute_stream=True:主阶段提交后,接口返回 event (object),用于管理本次异步调用。调用 event.current_stream_wait() 获取最终结果。

两种方式的最终结果内容、顺序和类型一致,各项说明如下:

  • combined_x (Tensor):表示combine后的token数据,还原为原始序列顺序。要求为2 维张量,shape为 (BS, H),数据类型与 x 一致(bfloat16 或 float16),数据格式为 NDND,不支持非连续的Tensor。
  • combined_topk_weights (Tensor | None):表示combine后的专家权重梯度。当 topk_weights 输入不为 None 时,要求为2 维张量,shape为 (BS, K),数据类型为 float32,数据格式为 NDND;当 topk_weights 输入为 None 时,返回 None。

get_moe_ep_ccl_buffer_size(静态方法)

功能:返回默认的CCL通信buffer大小(单位:MB)。当前dispatch和combine所需的通信buffer无需再通过 HCCL_BUFFSIZE 环境变量手动配置,无需调用该接口。

函数原型:

ElasticBuffer.get_moe_ep_ccl_buffer_size(world_size, num_max_tokens_per_rank, hidden, num_experts, topk) -> int

输入参数:

  • world_size (int):必选参数,表示EP通信域的大小(即参与EP通信的卡数)。取值范围 [2, 1024]。
  • num_max_tokens_per_rank (int):必选参数,表示每张卡上的最大token数量上限。
  • hidden (int):必选参数,表示hidden size隐藏层大小。取值范围 (0, 8192]。
  • num_experts (int):必选参数,MoE专家总数量,取值范围 [2, 2048],且满足 num_experts % ep_world_size = 0。
  • topk (int):必选参数,表示选取topK个专家,取值范围 [1, 32]。

输出说明:

  • ccl_buffer_size (int):默认的CCL通信buffer大小,固定返回200,单位为MB。当前通信buffer已由ElasticBuffer内部按算子参数自动计算并申请,该值目前无参考意义。

destroy

功能:释放ElasticBuffer实例持有的资源,包括Dispatch/Combine通信上下文。注意:Engram通信的host pinned内存(含推理模式自建的host pinned内存、训练模式下调用方零拷贝存储的注册映射)在创建时已注册进HCCL引擎上下文且无反注册接口,destroy后该部分内存由进程级共享池按通信域保留、随进程退出统一释放,destroy不会释放该部分内存(调用方的存储内存本体始终不会被释放)。同通信域销毁后重建ElasticBuffer时直接复用共享池内存,复用约束:自建buffer重建容量不得超过首建值;外部零拷贝buffer重建时地址与大小必须与首建注册一致,否则接口报错,此时需更换新的通信域。训练模式下HCCL默认通信buffer由框架管理,无需手动释放。当构造时 explicitly_destroy=False(默认)时,实例被垃圾回收时会自动调用本方法;当 explicitly_destroy=True 时,需要由调用方显式调用。

输入参数:无参数。

输出说明:无返回值,实例资源释放完成。

约束说明

  • 参数对齐约束:

    • num_cpu_bytes 必须为2MB对齐(即能被 2 × 1024 × 1024 整除)。
    • hidden 必须大于0。
    • get_engram_storage_size_hint 返回值自动满足2MB对齐。
  • Engram维度约束:

    • storage 必须为2 维张量。
    • indices 必须为1 维张量。
  • Engram dtype约束:

    • storage.dtype 仅支持 bfloat16、float16、float32(不带SF时)、float8_e4m3fn、float8_e5m2(带SF时)。
    • indices.dtype 必须为 int32。
  • Engram SF量化约束:

    • sf 与 storage.dtype 必须配套:storage 为 float8_e4m3fn/float8_e5m2 时必须传入 sf;storage 为 bfloat16/float16/float32 时不得传入 sf。
    • sf 必须为2维张量,sf.dtype 仅支持 float32、float8_e8m0。
    • 训练模式:sf shape为 (storage.size(0), num_sf_packs),列数 num_sf_packs = ceil(hidden / group_size),group_size 为MX量化的分组大小,且须满足 0 < num_sf_packs ≤ hidden;sf 必须为CPU锁页内存(与 storage 同为直接映射,零拷贝);sf 在ElasticBuffer生命周期内必须保持保活且地址不变。
    • 推理模式:sf shape为 (world_size × num_entries, num_sf_packs)(全量SF表,每个条目一组SF),为NPU张量,按全局索引寻址;local模式(group=None)下 world_size=1,行数即为 num_entries。
    • engram_fetch_grad 不产生SF梯度:fetched_sf 视为不可导张量,反向仅对hidden数据回传梯度。
  • Engram设备约束:

    • storage 必须在CPU上。
    • indices 必须在NPU上。
  • Engram调用顺序约束:

  • full-vocab local约束:

    • group=None 仅支持推理,with_grad=True、MoE参数和 barrier 均会被拒绝。
    • 调用方应在创建实例前调用 torch.npu.set_device(local_rank),并在首次 engram_write、后续 engram_fetch 与 destroy 期间保持当前NPU device不变;local运行时资源绑定首次 engram_write 时的当前NPU device。
    • storage 为完整全局词表,indices 为全局行号,num_entries_per_rank 等于 storage.size(0)。
    • zero_copy=True 时Python实例保存 storage 引用;mmap/SharedMemory视图的底层owner仍必须由调用方保留到所有fetch完成且 destroy() 成功。
    • 多进程共享同一词表推荐 /dev/shm、mmap 或 SharedMemory;不要把 pin_memory() 的私有副本当作跨进程共享方案。
    • indices 必须全部落在有效全局索引范围内;越界或负数索引属于调用方错误,输出行为未定义。
  • Engram推理模式约束:

    • slice模式(group 非 None,跨rank分布式推理)中,仅支持创建offload内存通过URMA通信,通信暂不支持通过PCIE方式访问offload内存,仅支持通过UB访问。
    • local模式(group=None,full-vocab local推理)中,offload内存为全量Engram表,不经过分布式通信。
  • Engram训练模式约束:

    • with_grad=True 时,num_max_tokens_per_rank 必须为正整数。
    • with_grad=True 时,engram_fetch 返回的 fetch_ctx 为局部变量,多次fetch不会覆盖(每次调用返回独立的ctx)。
    • engram_fetch_grad 的 grad_fetched shape 必须与前向 fetched 一致。
    • 训练模式下,通信buffer使用HCCL默认buffer(大小受 HCCL_BUFFSIZE 环境变量控制,默认200MB),由框架管理,无需手动申请或释放。
    • 训练模式下,engram_write 直接映射 storage 锁页内存(零拷贝):storage 必须为锁页内存(pin_memory() 分配),普通(非锁页)CPU内存不受支持;storage 必须非空,且在ElasticBuffer生命周期内保持存活、地址不变;重复调用须传入同一 storage。
  • Engram数值约束:

    • num_cpu_bytes、num_entries必须非负。
    • hidden 必须大于0。
    • zero_copy=False 时(数据写入内部host pinned共享内存段),须满足 storage.nbytes() ≤ num_cpu_bytes。storage.nbytes() 表示tensor实际占用的字节数,即 num_entries × hidden × dtype_size(其中 dtype_size 为单个元素的字节大小,如 bfloat16 为2字节、float32 为4字节)。
    • 全局条目总数须满足 world_size × num_entries < 2^31(int32 最大值),保证indices索引不溢出。
    • group=None 时须满足 num_entries < 2^31。
  • Engram netlayer约束:

    • netlayer 仅作用于Engram建链选层(engram_write 触发的链路探测与channel创建);Dispatch/Combine路径不使用该参数。
    • netlayer 必须为 "auto" 或非负整数字符串;且必须存在于HCCL netlayer列表中,否则建链失败。
    • 选层规则:"auto" 自netlayer 0起逐层尝试与对端卡建链;数字串仅在该分层内建链,该层所有对端都必须可达,指定分层的分层编号不存在,或该分层内任一对端无可达链路时,建链失败。
  • Dispatch/Combine配套约束:

    • dispatch 和 combine 必须配套使用。
    • 调用接口过程中使用的 num_experts、num_max_tokens_per_rank 参数取值所有卡需保持一致,且 dispatch 和 combine 对应参数也需保持一致。
    • comm_alg 在构造ElasticBuffer实例时确定,同一EP通信域中的所有rank必须使用相同取值;同一实例的dispatch、dispatch epilogue、combine和combine epilogue使用同一种通信算法。
    • comm_alg="auto" 时,组网中的FullMesh端口和Clos端口都会使用。
    • comm_alg="clos_only" 时只使用Clos端口、不使用FullMesh端口。在clos_only下,不支持UBG(UB_RTP)协议链路。
    • 当前版本不支持bias参数,bias 必须传入 None。
    • cached模式下,topk_idx 和 topk_weights 必须为 None,do_cpu_sync 必须为 False;非cached模式下,topk_idx 为必选参数,topk_weights 为可选参数。
  • Dispatch/Combine异步调用约束:

    • 同一通信组的各rank需要保持相同的dispatch/combine调用顺序。
    • 启用异步调用时,每次dispatch/combine都需要配套调用其返回event的 event.current_stream_wait() 方法。
  • Dispatch/Combine Shape变量说明:

    • A:表示本卡接收的最大token数量,A = ep_world_size * num_max_tokens_per_rank * MIN(K, num_local_experts)。
    • H:表示hidden size隐藏层大小。取值范围为 (0, 8192]。
    • BS:表示batch sequence size,即本卡的token数量。
    • K:表示选取topK个专家,取值范围为 1 ≤ K ≤ min(32, num_experts)。
    • num_local_experts:表示本卡专家数量,num_local_experts = num_experts / ep_world_size,其中 num_experts 取值范围为 [2, 2048] 且须被 ep_world_size 整除,即满足 0 < num_local_experts * ep_world_size ≤ 2048。
  • HCCL通信域缓存区大小:

    • dispatch 和 combine 所需的CCL通信buffer由ElasticBuffer内部自动计算并按需申请,无需配置 HCCL_BUFFSIZE 环境变量。
    • Engram训练模式(with_grad=True)的a2a收发仍使用HCCL默认通信buffer,HCCL_BUFFSIZE 环境变量仅对该路径生效(不配置时默认200MB)。
  • 通信域约束:

    • Engram通信域 world_size 范围 [2, 1024],支持多卡分布式场景。
    • 一个模型中的 dispatch 和 combine 算子仅支持相同EP通信域,且该通信域中不允许有其他算子。
  • 特殊场景处理:

    • 支持 num_entries = 0。
    • 支持 num_tokens = 0。
    • 二进制一致:engram_write和engram_fetch全程纯数据搬运,输出与源必须逐字节相等,无任何容差。

调用示例

Engram单算子模式调用(多卡分布式)

import os
import torch
import torch_npu
import torch.distributed as dist
import torch.multiprocessing as mp
from torch.multiprocessing import Process, Manager
from cann_ops_transformer import ElasticBuffer

num_entries = 10000
hidden = 4096
dtype = torch.bfloat16
world_size = 2


def set_device(rank):
    torch_npu.npu.set_device(rank)
    print(f"current device set: {torch_npu.npu.current_device()}")


def init_hccl_comm(rank, world_size):
    print(f"[INFO] device_{rank} create HCCL communication link")
    master_ip = "127.0.0.1"
    dist.init_process_group(
        backend="hccl",
        rank=rank,
        world_size=world_size,
        init_method=f"tcp://{master_ip}:50001",
    )
    print(f"device_{rank} init_process_group success")

    group = dist.new_group(backend="hccl", ranks=list(range(world_size)))
    return group


def run_elastic_buffer(queue, rank, world_size, storage, indices):
    print(f"{os.getpid()=}{rank=}")
    set_device(rank)
    group = init_hccl_comm(rank, world_size)

    num_cpu_bytes = ElasticBuffer.get_engram_storage_size_hint(
        num_entries, hidden, dtype
    )
    print(f"[INFO] device_{rank} num_cpu_bytes={num_cpu_bytes}")

    buffer = ElasticBuffer(
        group,
        num_cpu_bytes=num_cpu_bytes,
        explicitly_destroy=True,
        netlayer="auto",
    )

    print(f"[INFO] device_{rank} run engram_write")
    buffer.engram_write(storage)
    # SF量化(可选):storage 为 fp8 时须同时传入缩放因子表(NPU张量,全量SF表):
    #   num_sf_packs = (hidden + 31) // 32  # MX量化group_size=32,即ceil(hidden/group_size)
    #   sf = torch.rand(num_entries * world_size, num_sf_packs, dtype=torch.float32, device="npu")
    #   buffer.engram_write(storage_fp8, sf)
    #   fetched, fetched_sf = buffer.engram_fetch(indices_npu)()

    print(f"[INFO] device_{rank} run engram_fetch")
    indices_npu = indices.npu()
    wait_callable = buffer.engram_fetch(indices_npu)
    fetched = wait_callable()

    torch.npu.synchronize()
    print(f"[INFO] device_{rank} fetched shape: {fetched.shape}")
    buffer.destroy()
    dist.destroy_process_group()

    queue.put([rank, fetched.cpu()])


if __name__ == "__main__":
    storage = torch.randn(num_entries, hidden, dtype=dtype)
    indices = torch.randint(
        0,
        num_entries * world_size,
        (1000,),
        dtype=torch.int32,
    )

    manager = Manager()
    result_queue = manager.Queue()
    mp.set_start_method("forkserver", force=True)

    proc_list = []
    for rank in range(world_size):
        p = Process(
            target=run_elastic_buffer,
            args=(result_queue, rank, world_size, storage.clone(), indices.clone()),
        )
        p.start()
        proc_list.append(p)

    results = [None] * world_size
    for _ in range(world_size):
        rank_id, fetched = result_queue.get()
        results[rank_id] = fetched
        print(f"[INFO] rank_{rank_id} result collected")

    for p in proc_list:
        p.join()

    if all(result is not None for result in results):
        print("All ranks finished successfully")
        for rank, result in enumerate(results):
            print(f"Rank {rank} fetched shape: {result.shape}")
    else:
        print("[ERROR] Task failed. Please check the detailed error logs.")
        exit(1)

Engram训练模式调用(多卡分布式)

import os
import torch
import torch_npu
import torch.distributed as dist
from torch.multiprocessing import Process
from cann_ops_transformer import ElasticBuffer

num_entries = 4
hidden = 128
dtype = torch.bfloat16
world_size = 2
num_tokens = 6


def set_device(rank):
    torch_npu.npu.set_device(rank)


def init_hccl_comm(rank, world_size):
    dist.init_process_group(
        backend="hccl",
        rank=rank,
        world_size=world_size,
        init_method=f"tcp://127.0.0.1:50003",
    )
    return dist.new_group(backend="hccl", ranks=list(range(world_size)))


def train_worker(rank):
    set_device(rank)
    group = init_hccl_comm(rank, world_size)
    device = f"npu:{rank}"

    # ==================== 生成 embedding 和 indices ====================
    torch.manual_seed(42 + rank)
    storage = torch.randn(num_entries, hidden, dtype=dtype, pin_memory=True)
    total_entries = num_entries * world_size

    torch.manual_seed(100 + rank)
    indices = torch.randint(0, total_entries, (num_tokens,), dtype=torch.int32)

    # ==================== 创建 ElasticBuffer(with_grad=True)====================
    num_cpu_bytes = ElasticBuffer.get_engram_storage_size_hint(
        num_entries, hidden, dtype
    )
    buffer = ElasticBuffer(
        group=group,
        num_cpu_bytes=num_cpu_bytes,
        num_max_tokens_per_rank=num_tokens,
        with_grad=True,
        explicitly_destroy=True,
        netlayer="auto",
    )

    # ==================== 写入 storage ====================
    buffer.engram_write(storage)
    # SF量化(可选):storage 为 fp8 时须同时传入缩放因子表(本rank表,需锁页):
    #   num_sf_packs = (hidden + 31) // 32  # MX量化group_size=32,即ceil(hidden/group_size)
    #   sf = torch.rand(num_entries, num_sf_packs, dtype=torch.float32).pin_memory()
    #   buffer.engram_write(storage_fp8, sf)
    #   fetched, fetched_sf, fetch_ctx = buffer.engram_fetch(indices_npu)()
    # fetched_sf 无反向梯度,反向仍只需传 grad_fetched 与 fetch_ctx
    dist.barrier()
    torch.npu.synchronize()

    # ==================== 训练前向 ====================
    indices_npu = indices.to(device)
    fetched, fetch_ctx = buffer.engram_fetch(indices_npu)()
    print(f"[rank {rank}] forward: fetched shape={fetched.shape}")

    # ==================== 训练反向 ====================
    # 假设 grad_fetched 来自 loss.backward()
    grad_fetched = fetched.clone()
    grad_unique, unique_local_entry = buffer.engram_fetch_grad(grad_fetched, fetch_ctx)
    print(f"[rank {rank}] backward: grad_unique shape={grad_unique.shape}, dtype={grad_unique.dtype}")
    print(f"[rank {rank}] backward: unique_local_entry={unique_local_entry.cpu().tolist()}")

    # ==================== 优化器更新(稀疏) ====================
    # storage[unique_local_entry] -= lr * grad_unique
    # 注意: grad_unique 与 grad_fetched 同 dtype, 需类型转换后更新 storage

    # ==================== 清理 ====================
    dist.barrier()
    torch.npu.synchronize()
    buffer.destroy()
    dist.destroy_process_group()


if __name__ == "__main__":
    torch.multiprocessing.set_start_method("forkserver", force=True)
    proc_list = []
    for rank in range(world_size):
        proc = Process(target=train_worker, args=(rank,))
        proc.start()
        proc_list.append(proc)
    for proc in proc_list:
        proc.join()
    print("All processes finished.")

Dispatch/Combine单算子模式调用(多卡分布式)

import os
import torch
import torch_npu
import torch.distributed as dist
from torch.multiprocessing import Process
from cann_ops_transformer import ElasticBuffer

master_ip = "127.0.0.1"
world_size = 2
num_experts = world_size * 4
num_max_tokens_per_rank = 128
hidden = 4096
top_k = 4


def run_dispatch_combine(rank):
    torch_npu.npu.set_device(rank)
    dist.init_process_group(
        backend="hccl",
        rank=rank,
        world_size=world_size,
        init_method=f"tcp://{master_ip}:50002",
    )

    group = dist.new_group(backend="hccl")
    buffer = ElasticBuffer(
        group,
        num_max_tokens_per_rank=num_max_tokens_per_rank,
        hidden=hidden,
        num_topk=top_k,
        explicitly_destroy=True,
    )

    num_tokens = 64
    x = torch.randn(
        num_tokens,
        hidden,
        dtype=torch.bfloat16,
        device=f"npu:{rank}",
    )
    topk_idx = torch.randint(
        0,
        num_experts,
        (num_tokens, top_k),
        dtype=torch.int32,
        device=f"npu:{rank}",
    )
    topk_weights = torch.rand(
        num_tokens,
        top_k,
        dtype=torch.float32,
        device=f"npu:{rank}",
    )

    a = torch.randn((1024, 1024), dtype=torch.float16, device=x.device)
    b = torch.randn_like(a)
    c = torch.empty_like(a)

    dispatch_event = buffer.dispatch(
        x,
        topk_idx=topk_idx,
        topk_weights=topk_weights,
        num_experts=num_experts,
        do_cpu_sync=False,
        async_with_compute_stream=True,
    )
    # 执行独立计算
    torch.mm(a, b, out=c)
    recv_x, _, recv_topk_weights, handle = dispatch_event.current_stream_wait()

    expert_output = recv_x
    combine_event = buffer.combine(
        expert_output,
        handle,
        topk_weights=recv_topk_weights,
        async_with_compute_stream=True,
    )
    # 执行独立计算
    torch.mm(a, b, out=c)
    combined_x, combined_topk_weights = combine_event.current_stream_wait()

    torch.npu.synchronize()
    print(f"[rank {rank}] combined_x shape={combined_x.shape}, expected ({num_tokens}, {hidden})")
    assert combined_x.shape == (num_tokens, hidden)
    print(f"[rank {rank}] dispatch_combine PASS")

    buffer.destroy()
    dist.destroy_process_group()


if __name__ == "__main__":
    os.environ["HCCL_WHITELIST_DISABLE"] = "1"

    processes = []
    for rank in range(world_size):
        p = Process(target=run_dispatch_combine, args=(rank,))
        p.start()
        processes.append(p)

    for p in processes:
        p.join()

    print("All processes finished.")