MindFormers 移植：MindSpore → PyTorch

总体目标：将 MindFormers 整套大模型套件从 MindSpore 迁移到纯 PyTorch，使其在没有 MindSpore 的环境下独立运行，面向 Ascend NPU（torch_npu），并向下兼容 CUDA / CPU；最终覆盖预训练 / 微调 / 评测 / 推理全流程与主干模型全家族。

当前进度：以 DeepSeek-V3 的单卡 PyNative（动态图）预训练闭环作为第一个落地里程碑，已跑通并作为整套移植的基座（后端收口层、映射规范、版本容错方案在此沉淀，后续模型与场景复用）。

设计约束：单卡 = 多卡的 world_size==1 特例。所有分布式抽象（DTensor / DeviceMesh / 集合通信）保留，规模设为 1，向多卡与并行放大时本层代码尽量零改动。

详细设计取舍见 deepseek3_pytorch_migration_思路.md；里程碑完成报告见 pytorch_migration_deepseek3_single_card.md。

---

目录

• 移植路线图
• 快速开始
• 已完成的部分
• 未完成的部分
• MindSpore → PyTorch 映射速查

---

移植路线图

整套移植按"先打通一条最小闭环，再横向铺开、纵向加深"推进。所有阶段都服务于同一目标——去 MindSpore 依赖、全面 PyTorch 化。

阶段	目标	状态
M0 · 基座	后端收口层 _backend、MindSpore→PyTorch 映射规范、torch 版本容错方案	✅ 已完成
M1 · 首个闭环	DeepSeek-V3 单卡 PyNative 预训练闭环（合成数据）跑通	✅ 已完成
M2 · 真实训练	真实数据管线 torch 化 + 多卡 / 并行真机实跑	⬜ 进行中/未完成
M3 · 全流程	微调（PEFT/LoRA）、评测、推理 pipeline 全部 PyTorch 化	⬜ 未开始
M4 · 全模型	横向推广到 qwen3 / glm4 / telechat3 等 Mcore 全家族	⬜ 未开始
M5 · 收尾	图模式路径取舍、数值对齐、权重转换/续训兼容、文档与 CI	⬜ 未开始

当前处于 M1 完成、M2 进行中。下文"已完成 / 未完成"均围绕上述路线图展开。

---

快速开始

环境要求

组件	说明
Python	3.9 ~ 3.11
PyTorch	≥ 2.4（已在 2.4.0 / 2.10 / 2.12 上验证 import；DTensor / FSDP2 已做版本容错）
torch_npu	仅 Ascend NPU 需要；CUDA / CPU 不需要
不需要 MindSpore	pynative 路径已完全去 MindSpore 依赖

启动训练（msrun 的等价替换）

入口是 mindformers/run_pynative.py（不是 run_mindformer.py——后者顶层会 import 图模式组件，无 MindSpore 时 import 阶段即失败）。

cd mindformers

# ① 单卡 · 最简（无需任何多进程拉起器，init_process_group 自动补默认环境变量）
MF_DEVICE_TYPE=npu python run_pynative.py \
    --config configs/deepseek3/pretrain_deepseek3_single_card.yaml

# ② 单卡 · 用 torchrun（对应 msrun --worker_num=1；torchrun 负责设 RANK/WORLD_SIZE/LOCAL_RANK）
MF_DEVICE_TYPE=npu torchrun --nproc_per_node=1 run_pynative.py \
    --config configs/deepseek3/pretrain_deepseek3_single_card.yaml

# ③ 本地 CPU 冒烟（无 NPU/GPU 时验证逻辑闭环）
KMP_DUPLICATE_LIB_OK=TRUE MF_DEVICE_TYPE=cpu PYTHONPATH=$(pwd) \
    python run_pynative.py \
    --config configs/deepseek3/pretrain_deepseek3_single_card.yaml --device_type cpu

设备切换：--device_type npu|cuda|cpu 或环境变量 MF_DEVICE_TYPE（npu→hccl、cuda→nccl、cpu→gloo）。 ⚠️ MF_DEVICE_TYPE 必须在 import 之前生效（run_pynative.py 已在 import trainer 前设置好，直接传 --device_type 即可）。

命令行对照

MindSpore（旧）	PyTorch（新）
msrun --worker_num=1 ... run_mindformer.py --config x.yaml	torchrun --nproc_per_node=1 run_pynative.py --config x.yaml
python run_mindformer.py --config x.yaml（单进程）	python run_pynative.py --config x.yaml

验证

# 直接建模闭环（不经 YAML，最小前反向）
python tests/pt/test_deepseek3_single_card.py

本地 CPU（torch 2.12）已双路验证 EXIT 0：① 上述直接建模闭环；② run_pynative.py 端到端跑满 10 步并保存 checkpoint。

---

已完成的部分

对应路线图 M0（基座）+ M1（首个闭环）。所有改动集中在 pynative 路径 + 其 import 链拖入的共享基础设施——这些是整套移植复用的底座。

新增文件（可复用基座）

文件	作用	复用价值
mindformers/run_pynative.py	纯 PyTorch 训练入口，替代 run_mindformer.py	后续所有模型共用
mindformers/mindformers/pynative/_backend.py	后端收口层：MF_DEVICE_TYPE 选设备/通信后端，统一封装 torch.distributed 集合通信、进程组引导、device mesh、版本容错 rms_norm	全局唯一后端切换点，M2~M4 直接复用
mindformers/mindformers/pynative/dtensor_compat.py	DTensor 版本容错解析（torch.distributed.tensor → 回退 _tensor）	全模型共用
mindformers/configs/deepseek3/pretrain_deepseek3_single_card.yaml	最小单卡配置（hidden 256 / 4 层 / 8 专家 / vocab 1024，合成数据）	新模型配置模板
mindformers/tests/pt/test_deepseek3_single_card.py	直接建模闭环验证	测试范式模板

就地改造（MindSpore → PyTorch）

• 算子层 pynative/layers/*：linear / layer_norm / activation / dropout / flash_attention（→ SDPA）/ mask_generate / identity_op / mc2
• Transformer 层 pynative/transformers/*：attention / multi_latent_attention(MLA) / mlp / transformer_layer / transformer_block / multi_token_prediction(MTP) / hyper_connection
• MoE pynative/transformers/moe/*：router（histc→bincount）/ moe_layer / moe_utils / experts（npu_grouped_matmul + 纯 torch 分段兜底）/ shared_experts
• 模型主干 pynative/base_models/gpt/*：gpt_model（expert_bias in-place zero_）/ parallelize（FSDP2 guard、meta device）
• 训练编排 pynative/trainer/*：trainer（torch autograd、loss.backward(gradient=sense)、_mf_name 参数名旁挂）/ utils（合成数据 DataLoader）
• 优化器 / Loss / LR：pynative/optimizer/adamw.py（继承 torch.optim.Optimizer）、loss/loss.py、core/lr/lr_schedule.py（ConstantWarmUpLR 纯 Python 化）
• 分布式兼容 pynative/distributed/*：parallel_dims / fsdp（FSDPModule 三级 guard）
• 共享基础设施（约 50+ 文件）：parallel_core/transformer_config.py、parallel_core/utils/init_method.py、models/utils.py、models/configuration_utils.py、models/deepseek3/*、mindformers/__init__.py、tools/*、generation/text_generator.py 等——纯 torch 化或用 if _HAS_MINDSPORE: guard 起图模式专用导入

沉淀的通用规范（供后续阶段直接套用）

• Parameter.name 只读 → 旁挂 p._mf_name，读取处 getattr(p,"name",None) or getattr(p,"_mf_name",None)
• torch 版本兼容统一套路：公共 API → 私有 API → None/手写，三级兜底（DTensor、FSDPModule、F.rms_norm）
• 单卡无 launcher 裸跑：_backend.init_process_group() 自动补齐 RANK/WORLD_SIZE/LOCAL_RANK/MASTER_ADDR/MASTER_PORT

---

未完成的部分

对应路线图 M2~M5。均是"完成整套 MindFormers 移植"必须补齐的环节，按优先级排列。

M2 · 真实训练（进行中，P0）

• 真实数据管线 torch 化：Megatron 混合数据 / MindDataset → torch.utils.data.DataLoader，替换当前合成数据（RandomDataset）。
• 多卡 / 并行真机实跑：torchrun --nproc_per_node=N 在 Ascend 验证 FSDP2 + DTensor + 集合通信在 world_size>1 下正确（抽象已按 world_size==1 保留，尚未真机实测）。
• Muon 优化器收尾（P1）：仍按 param.name 做 fnmatch，需比照 AdamW 改 _mf_name。
• MTP 开启验证（P1）：num_nextn_predict_layers>0（当前最小配置为 0），逻辑已迁移待验证。
• 数值对齐（P1）：与 MindSpore 基线做逐层前向 / 梯度 parity。

M3 · 全流程 PyTorch 化（未开始）

• 微调 / PEFT：pynative/pet/*（LoRA 等）端到端验证。
• 评测：eval 任务链路去 MindSpore。
• 推理 pipeline：generation/ + pipeline/ 生成流程 PyTorch 化。

M4 · 全模型推广（未开始）

• 复用 _backend 收口层与映射规范，横向迁移 qwen3 / qwen3_moe / glm4 / glm4_moe / telechat3 等 Mcore 全家族。
• Legacy 架构（mindformers/models/<model>/ 非 pynative）视需要迁移。

M5 · 收尾（未开始）

• 图模式（GRAPH_MODE）路径取舍：pynative 改造就地修改了共享基础设施，图模式路径未同步验证——决定是彻底移除还是并行维护。
• run_mindformer.py 入口：仍是 MindSpore 图模式入口，最终替换或废弃。
• 权重转换 / 续训兼容：分布式权重切分 / 重排（reshard / sharded_tensor）在 torch 下实现。
• 文档与 CI：CI 从 ASCEND_HOME_PATH + MindSpore 依赖切到 torch_npu；补齐用户文档。

---

MindSpore → PyTorch 映射速查

MindSpore	PyTorch
nn.Cell / construct	torch.nn.Module / forward
mindspore.mint.* / ops.*	torch.*
ops.cast(x,dt) / x.astype(dt)	x.to(dt)
mstype.float32	torch.float32
Parameter(...,name=)	torch.nn.Parameter(...) + 旁挂 _mf_name
mint.distributed.*	torch.distributed.*（经 _backend）
hyper_parallel.DTensor/DeviceMesh	torch.distributed.tensor.* / device_mesh.*（版本容错）
FlashAttentionScore	F.scaled_dot_product_attention
grouped_matmul（图算子）	torch_npu.npu_grouped_matmul + 纯 torch 分段兜底
手动 sense 反传	loss.backward(gradient=sense)
msrun	torchrun / 裸 python（单卡）

---

仓库布局：本工作区含 mindformers/（本移植目标）与 mindspore/（框架本体，本移植旨在移除其运行时依赖）。详见根目录 CLAUDE.md。