一、目标与背景

📎 姊妹专项： #5 HSDP / FSDP 对标 PyTorch：差距梳理与补齐路线图

本 Issue 目标： 在保持 Hyper 现有架构不变的前提下，完善 DTensor / DeviceMesh 基础能力，使其在语义与 API 上尽可能对齐 PyTorch torch.distributed.tensor + device_mesh，降低 PyTorch 生态迁移成本。

上级文档： 本 Issue 是 HyperParallel / PyTorch / TorchTitan 用户接口对标 在 DTensor 模块的子专项，聚焦「基础分布式张量层」的差距分析与补齐计划。

分析依据（源码）：

侧	路径
PyTorch	torch/distributed/{tensor,device_mesh}
HyperParallel	hyper_parallel/core/dtensor、core/shard/_op_dispatch.py

一致性图例（附录中使用）： ✅ 一致 · ⚠️ 部分一致 · ❌ 仅一侧有 · 🔶 Hyper 扩展

---

二、范围与架构约束

2.1 模块范围

本 Issue 覆盖以下子模块的对标与补齐：

子模块	PyTorch	Hyper
Placement	tensor/placement_types.py	core/dtensor/placement_types.py
Layout	—（DTensorSpec）	core/dtensor/layout.py
DeviceMesh	distributed/device_mesh.py	core/dtensor/device_mesh.py
DTensor	tensor/_api.py	core/dtensor/dtensor.py
重分布	tensor/_redistribute.py	core/dtensor/tensor_redistribution.py
Op 分发	tensor/_dispatch.py + _ops/	core/shard/_op_dispatch.py
RNG	tensor/_random.py	core/dtensor/random.py

2.2 架构约束（补齐前提）

以下设计保持不变，补齐工作在此基础上演进：

• DTensor 继承 DTensorBase（平台包装类），不改为 torch.Tensor 子类
• Layout 作为 Hyper 核心抽象（alias / tensor_map），不移除
• 算子通过 YAML + 注册式 _op_dispatch 分发，不改为 PyTorch 式全量 __torch_dispatch__

2.3 与 PyTorch 的三条结构性差异

理解以下差异，是阅读后文差距与路线图的前提：

1. 元数据模型：PyTorch 用 DeviceMesh + placements；Hyper 额外有 Layout（MindSpore 风格 alias / tensor_map）。
2. 算子覆盖：PyTorch DTensor 即 Tensor，绝大多数 aten 自动 sharding；Hyper 依赖注册表，未覆盖 op 走 full-gather 回退。
3. 分布语义：PyTorch distribute_tensor 含 scatter/broadcast；Hyper 当前仅本地 slice（P0 首要补齐项）。

---

三、对标结论（速览）

3.1 已对齐的能力（可直接复用思路）

能力	说明
init_device_mesh + mesh["dp"] 子 mesh	用法高度一致；Hyper 额外支持 rank_list / init_backend
DTensor.from_local + Shard / Replicate / Partial	核心 API 对齐；Hyper 额外支持 alias 字符串
redistribute / full_tensor（同步路径）	接口一致；Hyper 缺 grad_placements / async_op
distribute_module + partition_fn	高度一致；Hyper 额外支持 MindSpore Cell
manual_seed + OffsetBasedRNGTracker	分布式 RNG 语义对齐
get_current_mesh 上下文	与 PyTorch _mesh_resources 对齐

3.2 Hyper 独有能力（保留，不作为补齐对象）

• Layout 别名切分（"dp", "None"）
• init_parameters / init_empty_weights / init_on_device 分片初始化链
• SkipDTensorDispatch、reduce_partial() 显式 API
• 昇腾轴查询：get_device_num_along_axis、get_comm_group_by_axis 等

3.3 按场景一致性总表

用户场景	一致性	说明
init_device_mesh + 子 mesh 切分	✅	注意 rank_list 差异
from_local + Placement	✅	Hyper 支持 alias
parallelize 中 distribute_tensor	⚠️	Hyper 无通信，行为不等价
to_local / redistribute / full_tensor	⚠️	接口同名，autograd/async 选项缺失
任意 aten op 作用于 DTensor	❌	Hyper 仅已注册 op 高效
rank0 单份权重一次分片	❌	依赖 P0 补齐 src_data_rank
distribute_module	✅
分布式 randn 初始化	❌	依赖 P0 补齐
FSDP + StridedShard	⚠️	Hyper 内部有，未公开导出

3.4 迁移三原则

1. 勿将 Hyper distribute_tensor 等同 PyTorch 同名函数——当前无 scatter/broadcast。
2. 勿假设任意 PyTorch 算子对 Hyper DTensor 高效可用——未注册 op 会 full-gather。
3. 依赖 grad_placements / async_op 的代码需改写——补齐前按 P1 路线图规划。

---

四、能力差距（PyTorch 可达 · Hyper 未达）

在架构约束下，以下差距需通过功能补齐弥合；❌ 不支持 · ⚠️ 有替代但不等价。

4.1 阻塞级差距（对应 P0）

差距	PyTorch	Hyper	影响
distribute_tensor(src_data_rank)	scatter/broadcast	❌ 仅本地 slice	单 rank 加载权重、parallelize 入口
核心 aten op dispatch 覆盖	全量自动	⚠️ 注册表 + full-gather 回退	自定义算子、训练 silently 变慢
from_local(run_check=True)	✅	❌	分片错误难发现
rand / randn 工厂	✅	❌	分布式参数初始化
顶层 API 导出	distribute_tensor、工厂函数	⚠️ 有实现未导出	用户误用、文档不一致

4.2 高级并行差距（对应 P1）

差距	PyTorch	Hyper	影响
to_local / full_tensor(grad_placements)	✅	❌	CP、layout 变化后的梯度
redistribute(async_op=True)	✅ AsyncCollectiveTensor	❌ 全同步	通信-计算重叠
StridedShard 公开 API	✅	⚠️ 内部有	FSDP+TP 用户声明
Partial 归约类型	含 product/bitwise	⚠️ 集合更小	特殊归约场景
redistribute / full_tensor autograd	完整	⚠️ 不完整	可微分 gather/scatter
distribute_module + 单源分布	贯通	⚠️ 依赖 P0#1	模块级初始化

4.3 完备性与性能差距（对应 P2）

差距	PyTorch	Hyper
redistribute(forward_dtype, backward_dtype)	✅	❌
init_device_mesh(backend_override=)	✅ 公开	❌ 仅内部
Op fallback 可观测 / strict 模式	可 debug	❌ silent 退化
DCP / checkpoint 元数据互操作	DTensor 内置	⚠️ 独立模块
logspace + 工厂签名对齐	✅	⚠️ 部分缺失

4.4 明确不在本 Issue 补齐范围

项	原因
DTensor 继承 torch.Tensor	需推翻 DTensorBase 架构
XLA / torch_xla	文档已声明不支持
torch.compile / PT2 协议	需单独立项，非本模块短期目标
_MaskPartial、SymInt mesh	长尾 / compile 依赖

---

五、补齐路线图（P0 → P1 → P2）

原则： 不改架构，在 DTensorBase + Layout + 注册式 dispatch 上增量补齐。

5.1 优先级总览

优先级	目标	项数
P0	阻塞迁移 / 训练正确性	5
P1	高级并行与 autograd	6
P2	性能、API 完备、可维护性	5

5.2 P0 — 必须补

#	任务	现状	补齐方向	工作量
1	distribute_tensor 通信语义	仅本地 slice	Shard scatter / Replicate broadcast；src_data_rank=None 可跳过	中
2	核心 aten op dispatch 覆盖	full-gather 回退	LLM 热路径 op 分批注册；未覆盖告警	大
3	顶层 API 导出	未进 __all__	导出 distribute_tensor、ones/zeros/empty/full + 文档	小
4	from_local(run_check=True)	无校验	all-gather / meta 比对	小～中
5	rand / randn 工厂	框架已有	对接 RNG tracker + local shape 计算	中

5.3 P1 — 应补

#	任务	现状	补齐方向	工作量
6	grad_placements	无	autograd.Function 包装 to_local / full_tensor	中
7	异步 redistribute	全同步	对接 AsyncCollectiveTensor	中～大
8	StridedShard 公开	内部有	加入 __all__ + FSDP+TP 测试	小～中
9	Partial 归约对齐	集合偏小	product/prod 别名；avg 语义一致	小
10	可微分 redistribute	不完整	与 #6 联动完善 autograd 边界	中
11	distribute_module 贯通	依赖 #1	单 rank 广播参数验证	小

5.4 P2 — 建议补

#	任务	补齐方向	工作量
12	redistribute dtype cast	forward_dtype / backward_dtype	中
13	backend_override 公开	暴露至 init_device_mesh	小
14	Op fallback 策略	strict 模式 + fallback 计数	小～中
15	checkpoint 元数据桥接	Layout/placements 序列化 adapter	中～大
16	logspace + 工厂签名	API 完备	小

5.5 里程碑

M1（迁移可用）  P0 #1 #3 #4 #5
M2（训练稳定）  P0 #2 热路径 op + P1 #8 #9
M3（高级并行）  P1 #6 #7 #10 #11
M4（性能完备）  P2 #12～#16

5.6 执行优先级结论

1. distribute_tensor 通信 + op dispatch 覆盖 — 不改架构下收益最大。
2. grad_placements + 异步 redistribute — 解锁 CP / FSDP 高级场景。
3. P2 项 — M3 后并行推进，提升性能与 API 完备性。

---

附录 A：逐类逐接口对照

详细技术参考；日常决策优先看第三～五章。

A.1 Placement 类型

Placement（基类）

接口/成员	PyTorch	Hyper	一致性	功能描述
基类	C++ Placement + Python 包装	纯 Python	⚠️	排布策略抽象
is_shard / is_replicate / is_partial	C++ 侧	✅	✅	类型查询
__eq__ / __hash__	子类实现	子类实现	⚠️	可哈希比较

Shard / StridedShard / Replicate / Partial

类型	一致性	要点
Shard(dim)	✅	切分逻辑 Hyper 在 Layout/redistribution 中
StridedShard / _StridedShard	⚠️	语义一致；Hyper 未顶层导出
Replicate	✅
Partial(reduce_op)	⚠️	Hyper reduce 类型更少；无 _MaskPartial

A.2 Layout（🔶 Hyper 独有）

能力	PyTorch	Hyper
Layout + alias ("dp","None")	❌	✅
placement_to_tensor_map	❌	✅
to_dict() / MindSpore 互操作	❌	✅

A.3 DeviceMesh

类别	高度一致	Hyper 独有	PyTorch 独有
工厂/上下文	init_device_mesh、get_current_mesh、__enter__	rank_list、init_backend、轴查询 API	backend_override（公开）、SymInt coordinate
子 mesh	__getitem__、flatten、concatenate		mesh 属性（Tensor 形式）

A.4 DTensor 类

类别	接口	一致性
构造	from_local	⚠️ Hyper 无 run_check / grad_placements
分布	distribute_tensor	⚠️ Hyper 无通信
转换	to_local / redistribute / full_tensor	⚠️ Hyper 缺 async / grad 选项
形状	shape / local_shape / size	✅
就地	copy_ / zero_ / fill_	⚠️ Hyper 显式实现
PyTorch 独有	__tensor_flatten__、DCP 元数据、compile 协议	❌
Hyper 独有	layout 属性、SkipDTensorDispatch、alias placements	🔶

A.5 模块级函数

函数	一致性	要点
distribute_module	✅	Hyper 支持 MindSpore；不支持 XLA
ones/zeros/empty/full	⚠️	Hyper 有实现未导出
rand/randn/logspace	❌	Hyper 缺失
init_parameters 等	🔶	Hyper 独有

A.6 RNG 与工具

接口	一致性
manual_seed / OffsetBasedRNGTracker / fork_rng	✅
compute_local_shape_and_global_offset	✅
visualize_sharding / try_find_mesh_from_args	❌ Hyper 无

A.7 与 TorchTitan 的关系

• TorchTitan 不重新定义 DTensor，直接使用 PyTorch API；声明式切分用 SpmdLayout，非 Hyper Layout。
• Hyper 在 ParallelDims / mesh 测试中有 TorchTitan 兼容用例，但 DTensor 层仍走 Hyper Layout 路径。

---

父 Issue：HyperParallel / PyTorch / TorchTitan 用户接口对标 · 姊妹专项：HSDP / FSDP 子专项