背景

本文档梳理 HyperParallel、PyTorch（torch.distributed）与 TorchTitan 三层并行栈的用户接口对标关系，便于迁移、文档补齐与 API 规划。

• PyTorch：分布式原语库（DTensor、FSDP2、TP、PP、DCP、collectives）
• TorchTitan：基于 PyTorch 的 LLM 训练框架（Trainer、ModelSpec、组件化）
• HyperParallel：昇腾亲和的并行原语 + 部分对标 Titan 的训练框架

分析基于源码：hyper-parallel/hyper_parallel、pytorch/torch/distributed、torchtitan/torchtitan

---

全局定位

维度	PyTorch	TorchTitan	HyperParallel
定位	分布式原语库	PyTorch 上的 LLM 训练框架	昇腾并行原语 + 训练框架
训练入口	无	Trainer + tyro	BaseTrainer + YAML
模型注册	无	ModelSpec + model_registry	ModelSpec + register_spec
并行编排	用户自行组合	TP→CP→AC→FSDP→PP	同 Titan 思路
独有优势	collective/FSDP/PP 调度最全	组件化、模型生态、spmd_types	昇腾/NPU、EP/MoE、swap、SAPP、LlamaFactory

---

1. DTensor / 设备 Mesh

📎 细粒度对比（逐类、逐接口）： #2 DTensor / DeviceMesh 对标 PyTorch：差距梳理与补齐路线图 · #5 HSDP / FSDP 对标 PyTorch：差距梳理与补齐路线图

接口名	Hyper	PyTorch	TorchTitan	功能描述
DTensor	hyper_parallel / core.dtensor	torch.distributed.tensor	使用 PyTorch	分布式张量抽象
Layout	core.dtensor.layout	—	—（SpmdLayout）	Hyper 自有 layout 抽象
DeviceMesh / init_device_mesh	core.dtensor	torch.distributed.device_mesh	使用 PyTorch	多维设备拓扑
get_current_mesh	hyper_parallel	—	—	当前活跃 mesh
distribute_module / distribute_tensor	core.dtensor	torch.distributed.tensor	使用 PyTorch	模块/张量 DTensor 化
Shard / Replicate / Partial	placement_types	torch.distributed.tensor	使用 PyTorch	Placement 类型
init_parameters / init_empty_weights / init_on_device	hyper_parallel	—	—	分片初始化工具链
SkipDTensorDispatch	hyper_parallel	—	—	梯度 hook 绕过 dispatch

模块小结： PyTorch 提供标准 DTensor；Titan 复用 PyTorch 并引入 SpmdLayout；Hyper 增加 Layout 与分片初始化，支持 MindSpore 双栈。

---

2. HSDP / FSDP

接口名	Hyper	PyTorch	TorchTitan	功能描述
fully_shard	core.fully_shard	torch.distributed.fsdp	distributed.fsdp	FSDP2 参数切分
HSDPModule	hyper_parallel	FSDPModule	使用 PyTorch	FSDP 模块封装
hsdp_sync_stream	hyper_parallel	—	—	梯度同步流
MixedPrecisionPolicy / OffloadPolicy	core.fully_shard.utils	torch.distributed.fsdp	使用 PyTorch	混合精度/offload 策略
FullyShardedDataParallel（FSDP1）	—	torch.distributed.fsdp	使用 PyTorch	FSDP 旧版
apply_fsdp_to_decoder	—	—	distributed.fsdp	Decoder 级 FSDP 应用

模块小结： 三方围绕 FSDP2 收敛；Hyper 命名 HSDPModule，Titan 提供训练编排封装，PyTorch 含 FSDP1 全量 API。

---

3. 张量并行 TP

接口名	Hyper	PyTorch	TorchTitan	功能描述
parallelize_module	core.tensor_parallel	tensor.parallel	使用 PyTorch	声明式 TP
ColwiseParallel / RowwiseParallel / SequenceParallel	hyper_parallel	tensor.parallel	使用 PyTorch	TP 策略类
NoParallel	hyper_parallel	—	—	显式不切分
PrepareModuleInput/Output	hyper_parallel	tensor.parallel	使用 PyTorch	边界 layout 重分布
loss_parallel	core.tensor_parallel	tensor.parallel.loss	components.loss	分布式 CE
shard_module / DFunction	core.shard	—	—	Hyper 底层扩展

模块小结： TP 是 Hyper 与 PyTorch 对齐度最高的模块；Titan 在 parallelize_* 内调用 PyTorch TP。

---

4. 流水线 PP

接口名	Hyper	PyTorch	TorchTitan	功能描述
PipelineStage	core.pipeline_parallel	pipelining	使用 PyTorch	Stage 封装
Schedule1F1B / GPipe / Interleaved1F1B	core.pipeline_parallel	pipelining	使用 PyTorch	基础调度
ScheduleMPipeTranspose	core.pipeline_parallel.mpipe	—	—	MPipe Transpose
ScheduleZeroBubble / DualPipeV	—	pipelining	使用 PyTorch	高级调度
pipeline_llm	—	—	distributed.pipeline_parallel	自动切分 LLM
CommComputeOverlap	core.pipeline_parallel	—	—	B/F 通算掩盖

模块小结： 基础 PP 共享 PyTorch；Titan 强在自动切分；Hyper 独有 MPipe 与通算掩盖。

---

5. 上下文并行 CP

接口名	Hyper	PyTorch	TorchTitan	功能描述
ContextParallel / AsyncContextParallel	core.context_parallel	—	—	类式 CP
DSA 系列（8 类）	core.context_parallel	—	—	DSA 专用 CP
context_parallel（函数式）	—	tensor.experimental	使用 PyTorch	函数式 CP
apply_cp_to_forward	—	—	distributed.context_parallel	attention CP 包装

模块小结： 接口风格不同（Hyper 类式 vs PyTorch 函数式）；Hyper 偏 DSA/NPU，Titan 偏 Flex/SDPA 集成。

---

6. 专家并行 EP / MoE

接口名	Hyper	PyTorch	TorchTitan	功能描述
ExpertParallel / ExpertTensorParallel	core.expert_parallel	—	—	EP 策略
MoE / GroupedExperts / Router	platform.torch.common	—	models.common.moe	MoE 构建块
mega_moe / mega_moe_grad	core.multicore	—	—	昇腾多核 MoE 算子
minimal_async_ep	—	—	distributed.minimal_async_ep	Titan 轻量 EP

模块小结： PyTorch 无独立 EP 模块；Hyper EP 最完整；Titan 偏模型内嵌 MoE。

---

7. 进程组 / 通信

接口名	Hyper	PyTorch	TorchTitan	功能描述
init_process_group 等	collectives.cc	torch.distributed	distributed.utils	进程组管理子集
all_reduce / broadcast 等	—（直接用 torch）	torch.distributed	使用 PyTorch	集合通信全集
DistributedDataParallel	—	torch.nn.parallel	—	经典 DDP

模块小结： Hyper 不重封装 collective；训练主路径走 FSDP 而非 DDP。

---

8. 激活检查点

接口名	Hyper	PyTorch	TorchTitan	功能描述
checkpoint / checkpoint_wrapper	core.activation_checkpoint	torch.utils.checkpoint 等	distributed.activation_checkpoint	激活重计算
swap / SwapManager	core.activation_checkpoint	—	—	激活 swap 到 CPU
SelectiveAC / MemoryBudgetAC	—	—	distributed.activation_checkpoint	选择性 AC 配置

模块小结： Hyper 独有完整 swap 体系；Titan selective AC 配置更成熟。

---

9. 分布式检查点 DCP

接口名	Hyper	PyTorch	TorchTitan	功能描述
save / async_save / load	core.distributed_checkpoint	torch.distributed.checkpoint	CheckpointManager	DCP 核心 API
ReshardHandler / layout I/O	core.distributed_checkpoint	—	—	Hyper 扩展
offline_transform.*	offline_transform	—	—	HF ↔ DCP 转换
HuggingFaceStorageReader/Writer	—	torch.distributed.checkpoint	使用 PyTorch	HF 存储后端

---

10. 训练框架

接口名	Hyper	PyTorch	TorchTitan	功能描述
ParallelDims	trainer.parallel_dims	—	torchtitan.distributed	并行维度校验（Hyper 移植自 Titan）
BaseTrainer / LLMTrainer / VLTrainer	trainer	—	torchtitan.trainer.Trainer	训练骨架
HyperTrainerConfig / parse_args	trainer.config	—	ConfigManager + tyro	配置解析
ModelSpec / register_spec	models.spec	—	protocols.model_spec	模型注册
Module / ShardingConfig	dmodule	—	protocols	声明式模块与切分

模块小结： Hyper 框架层明显对标 TorchTitan；Titan 组件更全（Metrics/Tokenizer/Quantization/RL），Hyper 用 YAML + Callback。

---

11. 仅 PyTorch 有（Hyper/Titan 未封装）

• DDP、ZeroRedundancyOptimizer
• FSDP1 全套、register_fsdp_forward_method、share_comm_ctx
• 全量 collectives / P2P / RPC / Elastic / torchrun
• PP 高级调度（ZeroBubble、DualPipeV）、Pipe IR
• tensor.experimental CP、implicit_replication、register_sharding
• CommDebugMode、ShardedTensor 遗留 API

---

12. 仅 TorchTitan 有（Hyper 无）

• ConfigManager / OverrideConfig / tyro CLI
• MetricsProcessor、ParallelAwareDataloader、HuggingFaceTokenizer
• FlexAttention / VarlenAttention
• 量化（Float8/MXFP8）、LoRAConverter
• ForgeEngine、experiments.rl、TorchFT
• spmd_types / SpmdLayout 体系
• 更广模型：llama3、qwen3、gpt_oss、deepseek_v3、flux

---

13. 仅 HyperParallel 有

• get_platform（PyTorch/MindSpore 双栈）
• Layout、shard_module、DFunction、DSA-CP 八类
• EP 全套、mega_moe、扩展 symmetric memory
• swap 体系、SAPP 自动并行、hyper-offload
• integration.llamafactory、Muon / get_hyper_optimizer
• ScheduleMPipeTranspose、CommComputeOverlap
• NPU 实验算子（custom_ops.experimental）

---

14. 迁移速查

从…到 Hyper	对照模块
PyTorch 原语	core.dtensor、core.tensor_parallel、core.fully_shard、core.pipeline_parallel、collectives、core.distributed_checkpoint
TorchTitan 框架	trainer、dmodule、models.spec、models.*、trainer.parallel_dims

Titan 接口	Hyper 对应
ParallelDims	trainer.ParallelDims
ModelSpec	models.spec.ModelSpec
Module / ShardingConfig	dmodule
parallelize_qwen3_5	models.qwen3_5.parallelize_qwen3_5
Trainer	BaseTrainer / LLMTrainer
LRSchedulersContainer	core.optimizer.LRSchedulersContainer

---

建议后续动作

1. 将本文档沉淀为 docs/api/framework_comparison.md 并链接到 API Reference 索引
2. 对「Hyper 有但未顶层导出」的接口（如 distribute_tensor、loss_parallel）评估是否加入 hyper_parallel.__all__
3. 标注与 Titan 对标的接口在 docstring 中增加 @see torchtitan... 引用

---

本 Issue 由接口梳理自动生成，欢迎补充遗漏接口或修正对标关系。

---

同步自上游 mindspore/hyper-parallel#262