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。前向过程为:
-
桶排序:按 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)
-
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]。 -
本地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)。
-
a2a交换data:将 local_datalocal\_data(含SF行,每行 rowStriderowStride 字节)沿原请求路径送回,得到 recv_data[i]recv\_data[i],i∈[0,num_tokens)i \in [0, num\_tokens)。
-
还原:按 permperm 重排回原始token顺序:
fetched[perm[i]]=recv_data[i],i∈[0,num_tokens)fetched[perm[i]] = recv\_data[i], \quad i \in [0, num\_tokens)
-
保存反向上下文 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。依次为:
-
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)
-
反向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)
-
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)\,\})
-
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;rankr的metadata区间为[recv_rank_offsets[r], recv_rank_offsets[r + 1]),最后一个元素等于有效metadata行数。它是下述 packed buffer 尾部的视图,cached模式复用其内容,不再是独立算子输入/输出。 - recv_metadata_buffer (
Tensor):连续一维int32backing 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索引。
- dst_buffer_slot_idx (
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。- 训练模式:
sfshape为(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生命周期内必须保持保活且地址不变。 - 推理模式:
sfshape为(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调用顺序约束:
- 必须先调用 engram_write 至少一次,才能调用 engram_fetch。
- 同一ElasticBuffer实例上不允许并发 engram_fetch(需等待上次fetch的callable执行完成)。
- 训练模式下,必须先调用 engram_fetch(训练模式)获取
fetch_ctx,才能调用 engram_fetch_grad。
-
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表,不经过分布式通信。
- slice模式(
-
Engram训练模式约束:
with_grad=True时,num_max_tokens_per_rank必须为正整数。with_grad=True时,engram_fetch 返回的fetch_ctx为局部变量,多次fetch不会覆盖(每次调用返回独立的ctx)。- engram_fetch_grad 的
grad_fetchedshape 必须与前向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通信域缓存区大小:
-
通信域约束:
-
特殊场景处理:
- 支持
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.")