Star177
384
代码
代码
Issues71
Pull Requests139
Actions
项目讨论
Wiki
分析
Star177
384
已合并
docs: 按新目录结构重组 docs/zh #3175
犀牛创建于 18 天前
docs: 按新目录结构重组 docs/zh #3175
已合并
犀牛创建于 18 天前
从liuxi_/MindSpeed-MMdoc_reorg合入到Ascend/MindSpeed-MMmaster
共 102 个文件变更+347-345
M.agents/skills/mindspeed-mm-fsdp2-model-only-migration/SKILL.md+1-1
@@ -21,7 +21,7 @@ training.plugin
21 -> model(**batch_data, use_cache=False).loss21 -> model(**batch_data, use_cache=False).loss
22```22```
23 23 
24-迁移前先阅读 `docs/zh/features/fsdp2_developer_migration_guide.md`，理解插件式 FSDP2 的路线、入口、注册、YAML、权重加载和启动方式。24+迁移前先阅读 `docs/zh/guides/development/fsdp2_model_migration_guide.md`，理解插件式 FSDP2 的路线、入口、注册、YAML、权重加载和启动方式。
25 25 
26## 开始前：创建 Todo26## 开始前：创建 Todo
27 27 
MREADME.md+11-11
@@ -57,7 +57,7 @@ MindSpeed MM：面向大规模分布式训练的昇腾多模态大模型套件
57 57 
58# 目录结构58# 目录结构
59 59 
60-关键目录如下，详细目录介绍参见[目录介绍](docs/zh/dir_structure.md)60+关键目录如下，详细目录介绍参见[目录介绍](docs/zh/introduction/dir_structure.md)
61 61 
62```bash62```bash
63├─bridge # mbridge在线权重转换63├─bridge # mbridge在线权重转换
@@ -222,14 +222,14 @@ MindSpeed MM支持Atlas 800T A2等昇腾训练硬件形态，软件版本配套
222 222 
223---223---
224 224 
225-MindSpeed MM具体的安装请参考[安装指南](docs/zh/pytorch/install_guide.md)。225+MindSpeed MM具体的安装请参考[安装指南](docs/zh/guides/installation/install_guide.md)。
226-当前qwen3vl、wan2.2模型已支持一键安装，一键安装使用说明详见[一键安装使用说明](docs/zh/pytorch/install_guide.md)。226+当前qwen3vl、wan2.2模型已支持一键安装，一键安装使用说明详见[一键安装使用说明](docs/zh/guides/installation/install_guide.md)。
227 227 
228# 快速上手228# 快速上手
229 229 
230---230---
231 231 
232-MindSpeed MM将以Qwen2.5-VL-3B和Wan2.1-T2V-1.3B模型为例，引导开发者快速上手预置模型在昇腾NPU上的高效运行。具体的操作请参考[快速上手](./docs/zh/pytorch/quickstart.md)。232+MindSpeed MM将以Qwen2.5-VL-3B和Wan2.1-T2V-1.3B模型为例，引导开发者快速上手预置模型在昇腾NPU上的高效运行。具体的操作请参考[快速上手](./docs/zh/guides/practices/quickstart.md)。
233 233 
234# 特性/模型介绍234# 特性/模型介绍
235 235 
@@ -237,7 +237,7 @@ MindSpeed MM将以Qwen2.5-VL-3B和Wan2.1-T2V-1.3B模型为例，引导开发者
237 237 
238## 已支持特性概览238## 已支持特性概览
239 239 
240-| 模型 \ 特性 | [TP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/tensor-parallel.md) | [TP-SP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/sequence-parallel.md) | [VPP](docs/zh/features/virtual_pipeline_parallel.md) | [PP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/pipeline-parallel.md) | CP | [Distributed Optimizer](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/distributed-optimizer.md) | [Recomputation](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/recomputation.md) | [LoRA](./docs/zh/features/lora_finetune.md) | RL | [FSDP2](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/fsdp2.md) |240+| 模型 \ 特性 | [TP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/tensor-parallel.md) | [TP-SP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/sequence-parallel.md) | [VPP](docs/zh/features/parallel/virtual_pipeline_parallel.md) | [PP](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/pipeline-parallel.md) | CP | [Distributed Optimizer](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/distributed-optimizer.md) | [Recomputation](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/recomputation.md) | [LoRA](./docs/zh/features/training_mode/lora_finetune.md) | RL | [FSDP2](https://gitcode.com/Ascend/MindSpeed/blob/master/docs/zh/features/fsdp2.md) |
241|:--------------------:|:------:|:------:|:------:|:---------------------------------------------------------------------------------------:|:------:|:------:|:------:|:------:|:------:|:------:|241|:--------------------:|:------:|:------:|:------:|:---------------------------------------------------------------------------------------:|:------:|:------:|:------:|:------:|:------:|:------:|
242| Magistral-Small-2509 | | | | | | | ✔ | ✔ | | ✔ |242| Magistral-Small-2509 | | | | | | | ✔ | ✔ | | ✔ |
243| InternVL3.5-30B | | | | | | | ✔ | | | ✔ |243| InternVL3.5-30B | | | | | | | ✔ | | | ✔ |
@@ -284,7 +284,7 @@ MindSpeed MM将以Qwen2.5-VL-3B和Wan2.1-T2V-1.3B模型为例，引导开发者
284 284 
285## 配套版本与支持模型285## 配套版本与支持模型
286 286 
287-MindSpeed MM 预置了覆盖多模态生成、多模态理解等任务的丰富模型；各模型的参数规模、训练任务、推荐集群与认证状态，详见 **[MindSpeed MM 支持模型列表](docs/zh/pytorch/supported_models.md)**。287+MindSpeed MM 预置了覆盖多模态生成、多模态理解等任务的丰富模型；各模型的参数规模、训练任务、推荐集群与认证状态，详见 **[MindSpeed MM 支持模型列表](docs/zh/introduction/supported_models.md)**。
288 288 
289大语言模型（稠密模型、稀疏模型和状态空间模型）由 MindSpeed-LLM 专项维护，如需进行大语言模型训练，请访问 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM/blob/master/docs/zh/pytorch/models/supported_models.md) 获取详细使用说明。289大语言模型（稠密模型、稀疏模型和状态空间模型）由 MindSpeed-LLM 专项维护，如需进行大语言模型训练，请访问 [MindSpeed-LLM](https://gitcode.com/Ascend/MindSpeed-LLM/blob/master/docs/zh/pytorch/models/supported_models.md) 获取详细使用说明。
290 290 
@@ -314,7 +314,7 @@ MindSpeed MM 预置了覆盖多模态生成、多模态理解等任务的丰富
314 314 
315MindSpeed MM集成了昇腾profiling采集工具，以提供对模型运行情况的分析。该工具能够依照配置采集模型的算子、显存等关键信息，同时支持动静态两种采集方式，协助开发者分析模型瓶颈，并可根据实际场景需求选择使用。315MindSpeed MM集成了昇腾profiling采集工具，以提供对模型运行情况的分析。该工具能够依照配置采集模型的算子、显存等关键信息，同时支持动静态两种采集方式，协助开发者分析模型瓶颈，并可根据实际场景需求选择使用。
316 316 
317- 具体方法见 [README](./docs/zh/tools.md) 的profiling章节317+ 具体方法见 [README](./docs/zh/tools/tools.md) 的profiling章节
318 318 
319## MindStudio Insight性能分析工具319## MindStudio Insight性能分析工具
320 320 
@@ -327,19 +327,19 @@ MindStudio Insight提供了包括Timeline视图、通信分析、计算耗时等
327 327 
328MindSpeed MM支持提取视频和文本特征并保存328MindSpeed MM支持提取视频和文本特征并保存
329 329 
330- 具体方法见 [README](./docs/zh/tools.md) 的Sora类模型特征提取章节330+ 具体方法见 [README](./docs/zh/tools/tools.md) 的Sora类模型特征提取章节
331 331 
332## 内存快照提取332## 内存快照提取
333 333 
334MindSpeed MM集成了昇腾内存快照采集工具，以提供对模型运行情况的分析。334MindSpeed MM集成了昇腾内存快照采集工具，以提供对模型运行情况的分析。
335 335 
336- 具体方法见 [README](./docs/zh/tools.md) 的内存快照提取章节336+ 具体方法见 [README](./docs/zh/tools/tools.md) 的内存快照提取章节
337 337 
338## Tensorboard使用338## Tensorboard使用
339 339 
340MindSpeed MM支持Tensorboard的使用340MindSpeed MM支持Tensorboard的使用
341 341 
342- 具体方法见 [README](./docs/zh/tools.md) 的Tensorboard使用章节342+ 具体方法见 [README](./docs/zh/tools/tools.md) 的Tensorboard使用章节
343 343 
344# 版本维护344# 版本维护
345 345 
@@ -371,7 +371,7 @@ MindSpeed MM已发布版本维护策略：
371 371 
372---372---
373 373 
374-相关FAQ请参考链接：[FAQ](./docs/zh/FAQ.md)374+相关FAQ请参考链接：[FAQ](./docs/zh/guides/troubleshooting/FAQ.md)
375 375 
376# 相关资源376# 相关资源
377 377 
Mcheckpoint/vlm_model/config.py+3-3
@@ -59,13 +59,13 @@ class VppParallelConfig(BaseModel):
59 """权模型切分配置，包括tp的size，以及pp切分时vit和llm在pp域每张卡上切分的层数"""59 """权模型切分配置，包括tp的size，以及pp切分时vit和llm在pp域每张卡上切分的层数"""
60 60 
61 llm_pp_layers: List[List[NonNegativeInt]]61 llm_pp_layers: List[List[NonNegativeInt]]
62- """llm模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/virtual_pipeline_parallel.md"""62+ """llm模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/parallel/virtual_pipeline_parallel.md"""
63 63 
64 vit_pp_layers: List[List[NonNegativeInt]]64 vit_pp_layers: List[List[NonNegativeInt]]
65- """vit模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/virtual_pipeline_parallel.md"""65+ """vit模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/parallel/virtual_pipeline_parallel.md"""
66 66 
67 audio_pp_layers: Optional[List[List[NonNegativeInt]]] = None67 audio_pp_layers: Optional[List[List[NonNegativeInt]]] = None
68- """audio模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/virtual_pipeline_parallel.md"""68+ """audio模块pipeline parallel切分每张卡上切分几层, vpp切分配置参考docs/zh/features/parallel/virtual_pipeline_parallel.md"""
69 69 
70 tp_size: PositiveInt = 170 tp_size: PositiveInt = 1
71 """默认tensor parallel张量并行组，模型转换时不同的tp组要切分到不同的目录下"""71 """默认tensor parallel张量并行组，模型转换时不同的tp组要切分到不同的目录下"""
Mdocs/en/replace_ascend_path_guide.md+1-1
@@ -22,7 +22,7 @@ This guide provides the complete steps for batch path replacement using the `rep
22| File Type | Description | Typical Path Example |22| File Type | Description | Typical Path Example |
23|---------|------|-------------|23|---------|------|-------------|
24| Shell scripts (`.sh`) | Training/testing startup scripts | `examples/*/pretrain_*.sh`, `scripts/install.sh` |24| Shell scripts (`.sh`) | Training/testing startup scripts | `examples/*/pretrain_*.sh`, `scripts/install.sh` |
25-| Markdown documents (`.md`) | Installation guides, model usage instructions | `docs/zh/pytorch/install_guide.md`, `docker/OVERVIEW.md` |25+| Markdown documents (`.md`) | Installation guides, model usage instructions | `docs/zh/guides/installation/install_guide.md`, `docker/OVERVIEW.md` |
26| RST documents (`.rst`) | User guides | `UserGuide/quick_start/environment_setup.rst` |26| RST documents (`.rst`) | User guides | `UserGuide/quick_start/environment_setup.rst` |
27| Python files (`.py`) | Source code (if path references exist) | Source files of each module |27| Python files (`.py`) | Source code (if path references exist) | Source files of each module |
28| Dockerfile | Docker image build scripts | `docker/Dockerfile` |28| Dockerfile | Docker image build scripts | `docker/Dockerfile` |
Ddocs/zh/_menu.md+0-32
@@ -1,32 +0,0 @@
1-# MindSpeed MM
yaoyaoxu
yaoyaoxuyaoyaoxu18 天前
已过期

这块是删除了吗？

likedislike
犀牛
犀牛
18 天前 评论：
2- 
3-- [MindSpeed MM简介](../zh/introduction.md)
4-- [软件安装](pytorch/install_guide.md)
5-- [模型使用](pytorch/supported_models.md)
6-- [特性说明]()
7- - [特性列表](../zh/features/supported_features.md)
8- - [并行特性]()
9- - [FSDP2](./features/fsdp2.md)
10- - [序列并行]()
11- - [Unaligned Ulysses CP](./features/unaligned_ulysses_cp.md)
12- - [DiT Ring Attention](./features/dit_ring_attention.md)
13- - [DiT USP](./features/dit_usp.md)
14- - [异构并行](./features/hetero_parallel.md)
15- - [显存优化]()
16- - [Async Activation Offload](./features/async_activation_offload.md)
17- - [Online Data Rearrange](./features/online_data_rearrange.md)
18- - [优化特性]()
19- - [Chunk Loss](./features/chunkloss.md)
20- - [VLM Model Loss Calculate Type](./features/vlm_model_loss_calculate_type.md)
21- - [训练模式]()
22- - [LoRA微调（基于Megatron训练后端）](./features/lora_finetune.md)
23- - [LoRA微调（基于FSDP2训练后端）](./features/lora_finetune_fsdp2.md)
24- - [数据处理](./features/seqpack.md)
25- - [确定性计算](features/other/deterministic_computing.md)
26-- [模型迁移]()
27- - [迁移指南（基于FSDP2训练后端）](./features/fsdp2_qwen3vl_migration_practice.md)
28-- [模型性能调优](pytorch/performance_tuning.md)
29-- [开发工具]()
30- - [性能数据采集](tools.md)
31- - [权重转换](features/mm_convert.md)
32-- [FAQ](FAQ.md)
Rdocs/zh/features/async_preprocess_iterable_dataset.md→docs/zh/features/data/async_preprocess_iterable_dataset.md+0-0
文件重命名但无更改。
Rdocs/zh/features/building_data_for_VLModel.md→docs/zh/features/data/building_data_for_VLModel.md+1-1
@@ -4,7 +4,7 @@
4 4 
5## 1. 适用范围5## 1. 适用范围
6 6 
7-本文所述数据构造方式通用于仓库内大多数 VL 模型（如 [Qwen3.6](../../../examples/qwen3_6)、[Qwen3.5](../../../examples/qwen3_5)、[Qwen3VL](../../../examples/qwen3vl)、[GLM4.5V](../../../examples/glm4.5v)、[Kimi-K2.5](../../../examples/kimik2_5)、[Step3-VL](../../../examples/step3_vl) 等）。各模型若有特殊数据要求（如视频、音频等），以其 README 为准。7+本文所述数据构造方式通用于仓库内大多数 VL 模型（如 [Qwen3.6](../../../../examples/qwen3_6)、[Qwen3.5](../../../../examples/qwen3_5)、[Qwen3VL](../../../../examples/qwen3vl)、[GLM4.5V](../../../../examples/glm4.5v)、[Kimi-K2.5](../../../../examples/kimik2_5)、[Step3-VL](../../../../examples/step3_vl) 等）。各模型若有特殊数据要求（如视频、音频等），以其 README 为准。
8 8 
9<a id="real-data"></a>9<a id="real-data"></a>
10 10 
Rdocs/zh/features/multimodal_dataset.md→docs/zh/features/data/multimodal_dataset.md+0-0
文件重命名但无更改。
Rdocs/zh/features/preprocess_on_fly.md→docs/zh/features/data/preprocess_on_fly.md+0-0
文件重命名但无更改。
Rdocs/zh/features/seqpack.md→docs/zh/features/data/seqpack.md+0-0
文件重命名但无更改。
Mdocs/zh/features/feature_list.md+32-32
@@ -38,40 +38,40 @@
38 </tr></thead>38 </tr></thead>
39<tbody>39<tbody>
40 <tr>40 <tr>
41- <td class="tg-t1fb" rowspan="10">并行特性</td>41+ <td class="tg-t1fb" rowspan="9">并行特性</td>
42 <td class="tg-citn">FSDP2</td>42 <td class="tg-citn">FSDP2</td>
43- <td class="tg-i1fi"><a href="fsdp2.md">FSDP2</a></td>43+ <td class="tg-i1fi"><a href="parallel/fsdp2.md">FSDP2</a></td>
44 44 
45 </tr>45 </tr>
46 <tr>46 <tr>
47 <td class="tg-citn" rowspan="2">PP并行</td>47 <td class="tg-citn" rowspan="2">PP并行</td>
48- <td class="tg-i1fi"><a href="dynamic_dpcp.md">动态PP / Dynamic DPCP</a></td>48+ <td class="tg-i1fi"><a href="parallel/dynamic_dpcp.md">动态PP / Dynamic DPCP</a></td>
49 49 
50 </tr>50 </tr>
51 <tr>51 <tr>
52- <td class="tg-i1fi"><a href="virtual_pipeline_parallel.md">Virtual Pipeline Parallel</a></td>52+ <td class="tg-i1fi"><a href="parallel/virtual_pipeline_parallel.md">Virtual Pipeline Parallel</a></td>
53 53 
54 </tr>54 </tr>
55 <tr>55 <tr>
56 <td class="tg-citn" rowspan="4">序列并行</td>56 <td class="tg-citn" rowspan="4">序列并行</td>
57- <td class="tg-i1fi"><a href="unaligned_ulysses_cp.md">Unaligned Ulysses CP</a></td>57+ <td class="tg-i1fi"><a href="parallel/unaligned_ulysses_cp.md">Unaligned Ulysses CP</a></td>
58 58 
59 </tr>59 </tr>
60 <tr>60 <tr>
61- <td class="tg-i1fi"><a href="dit_ring_attention.md">DiT Ring Attention</a></td>61+ <td class="tg-i1fi"><a href="parallel/dit_ring_attention.md">DiT Ring Attention</a></td>
62 62 
63 </tr>63 </tr>
64 <tr>64 <tr>
65- <td class="tg-i1fi"><a href="dit_usp.md">DiT USP</a></td>65+ <td class="tg-i1fi"><a href="parallel/dit_usp.md">DiT USP</a></td>
66 66 
67 </tr>67 </tr>
68 <tr>68 <tr>
69- <td class="tg-i1fi"><a href="unaligned_sequence_parallel.md">Unaligned Sequence Parallel</a></td>69+ <td class="tg-i1fi"><a href="parallel/unaligned_sequence_parallel.md">Unaligned Sequence Parallel</a></td>
70 70 
71 </tr>71 </tr>
72 <tr>72 <tr>
73 <td class="tg-citn">异构并行</td>73 <td class="tg-citn">异构并行</td>
74- <td class="tg-i1fi"><a href="hetero_parallel.md">Hetero Parallel</a></td>74+ <td class="tg-i1fi"><a href="parallel/hetero_parallel.md">Hetero Parallel</a></td>
75 75 
76 </tr>76 </tr>
77 <tr>77 <tr>
@@ -82,90 +82,90 @@
82 <tr>82 <tr>
83 <td class="tg-t1fb" rowspan="7">显存优化</td>83 <td class="tg-t1fb" rowspan="7">显存优化</td>
84 <td class="tg-citn">Offload</td>84 <td class="tg-citn">Offload</td>
85- <td class="tg-i1fi"><a href="async_activation_offload.md">Async Activation Offload</a></td>85+ <td class="tg-i1fi"><a href="memory/async_activation_offload.md">Async Activation Offload</a></td>
86 86 
87 </tr>87 </tr>
88 <tr>88 <tr>
89 <td class="tg-citn" rowspan="3">张量交换</td>89 <td class="tg-citn" rowspan="3">张量交换</td>
90- <td class="tg-i1fi"><a href="swap_core.md">Swap Core（张量交换底座）</a></td>90+ <td class="tg-i1fi"><a href="memory/swap_core.md">Swap Core（张量交换底座）</a></td>
91 91 
92 </tr>92 </tr>
93 <tr>93 <tr>
94- <td class="tg-i1fi"><a href="op_replay.md">Op Replay</a></td>94+ <td class="tg-i1fi"><a href="optimization/op_replay.md">Op Replay</a></td>
95 95 
96 </tr>96 </tr>
97 <tr>97 <tr>
98- <td class="tg-i1fi"><a href="act_stash.md">Act Stash</a></td>98+ <td class="tg-i1fi"><a href="memory/act_stash.md">Act Stash</a></td>
99 99 
100 </tr>100 </tr>
101 <tr>101 <tr>
102 <td class="tg-citn" rowspan="2">负载均衡</td>102 <td class="tg-citn" rowspan="2">负载均衡</td>
103- <td class="tg-0ijx"><a href="online_data_rearrange.md">Online Data Rearrange</a></td>103+ <td class="tg-0ijx"><a href="memory/online_data_rearrange.md">Online Data Rearrange</a></td>
104 104 
105 </tr>105 </tr>
106 <tr>106 <tr>
107- <td class="tg-i1fi"><a href="encoder_dp_balance.md">Encoder DP Balance</a></td>107+ <td class="tg-i1fi"><a href="memory/encoder_dp_balance.md">Encoder DP Balance</a></td>
108 108 
109 </tr>109 </tr>
110 <tr>110 <tr>
111 <td class="tg-citn">Bucket Reordering</td>111 <td class="tg-citn">Bucket Reordering</td>
112- <td class="tg-i1fi"><a href="bucket_reordering.md">Bucket Reordering</a></td>112+ <td class="tg-i1fi"><a href="memory/bucket_reordering.md">Bucket Reordering</a></td>
113 113 
114 </tr>114 </tr>
115 <tr>115 <tr>
116 <td class="tg-t1fb" rowspan="7">优化特性</td>116 <td class="tg-t1fb" rowspan="7">优化特性</td>
117 <td class="tg-citn" rowspan="2">损失优化</td>117 <td class="tg-citn" rowspan="2">损失优化</td>
118- <td class="tg-i1fi"><a href="chunkloss.md">Chunk Loss</a></td>118+ <td class="tg-i1fi"><a href="optimization/chunkloss.md">Chunk Loss</a></td>
119 119 
120 </tr>120 </tr>
121 <tr>121 <tr>
122- <td class="tg-i1fi"><a href="vlm_model_loss_calculate_type.md">VLM Model Loss Calculate Type</a></td>122+ <td class="tg-i1fi"><a href="optimization/vlm_model_loss_calculate_type.md">VLM Model Loss Calculate Type</a></td>
123 123 
124 </tr>124 </tr>
125 <tr>125 <tr>
126 <td class="tg-citn" rowspan="2">性能优化</td>126 <td class="tg-citn" rowspan="2">性能优化</td>
127- <td class="tg-jajh"><a href="fpdt.md">FPDT</a></td>127+ <td class="tg-jajh"><a href="optimization/fpdt.md">FPDT</a></td>
128 128 
129 </tr>129 </tr>
130 <tr>130 <tr>
131- <td class="tg-jajh"><a href="grad_norm_overlap.md">Grad Norm Overlap</a></td>131+ <td class="tg-jajh"><a href="optimization/grad_norm_overlap.md">Grad Norm Overlap</a></td>
132 132 
133 </tr>133 </tr>
134 <tr>134 <tr>
135 <td class="tg-citn" rowspan="3">优化器</td>135 <td class="tg-citn" rowspan="3">优化器</td>
136- <td class="tg-jajh"><a href="dummy_optimizer.md">Dummy Optimizer</a></td>136+ <td class="tg-jajh"><a href="optimization/dummy_optimizer.md">Dummy Optimizer</a></td>
137 137 
138 </tr>138 </tr>
139 <tr>139 <tr>
140- <td class="tg-jajh"><a href="parameter_lr_wd_tuning.md">Parameter LR/WD Tuning</a></td>140+ <td class="tg-jajh"><a href="optimization/parameter_lr_wd_tuning.md">Parameter LR/WD Tuning</a></td>
141 141 
142 </tr>142 </tr>
143 <tr>143 <tr>
144- <td class="tg-jajh"><a href="fsdp2_muon_optimizer.md">FSDP2 Muon Optimizer</a></td>144+ <td class="tg-jajh"><a href="optimization/fsdp2_muon_optimizer.md">FSDP2 Muon Optimizer</a></td>
145 145 
146 </tr>146 </tr>
147 <tr>147 <tr>
148 <td class="tg-whwg" rowspan="5">训练模式</td>148 <td class="tg-whwg" rowspan="5">训练模式</td>
149 <td class="tg-citn">预训练</td>149 <td class="tg-citn">预训练</td>
150- <td class="tg-jajh"><a href="pretrain.md">Pretrain</a></td>150+ <td class="tg-jajh"><a href="training_mode/pretrain.md">Pretrain</a></td>
151 151 
152 </tr>152 </tr>
153 <tr>153 <tr>
154 <td class="tg-citn" rowspan="3">高效微调</td>154 <td class="tg-citn" rowspan="3">高效微调</td>
155- <td class="tg-jajh"><a href="lora_finetune.md">LoRA Finetune</a></td>155+ <td class="tg-jajh"><a href="training_mode/lora_finetune.md">LoRA Finetune</a></td>
156 156 
157 </tr>157 </tr>
158 <tr>158 <tr>
159- <td class="tg-jajh"><a href="lora_finetune_fsdp2.md">LoRA Finetune with FSDP2</a></td>159+ <td class="tg-jajh"><a href="training_mode/lora_finetune_fsdp2.md">LoRA Finetune with FSDP2</a></td>
160 160 
161 </tr>161 </tr>
162 <tr>162 <tr>
163- <td class="tg-jajh"><a href="agentic_sft.md">Agentic SFT</a></td>163+ <td class="tg-jajh"><a href="training_mode/agentic_sft.md">Agentic SFT</a></td>
164 164 
165 </tr>165 </tr>
166 <tr>166 <tr>
167 <td class="tg-citn">Layerwise Training</td>167 <td class="tg-citn">Layerwise Training</td>
168- <td class="tg-jajh"><a href="layerwise_disaggregated_training.md">Layerwise Disaggregated Training</a></td>168+ <td class="tg-jajh"><a href="training_mode/layerwise_disaggregated_training.md">Layerwise Disaggregated Training</a></td>
169 169 
170 </tr>170 </tr>
171 <tr>171 <tr>
@@ -177,18 +177,18 @@
177 <tr>177 <tr>
178 <td class="tg-whwg" rowspan="2">数据处理</td>178 <td class="tg-whwg" rowspan="2">数据处理</td>
179 <td class="tg-citn">数据集</td>179 <td class="tg-citn">数据集</td>
180- <td class="tg-jajh"><a href="multimodal_dataset.md">Multimodal Dataset</a></td>180+ <td class="tg-jajh"><a href="data/multimodal_dataset.md">Multimodal Dataset</a></td>
181 181 
182 </tr>182 </tr>
183 <tr>183 <tr>
184 <td class="tg-citn">SeqPack</td>184 <td class="tg-citn">SeqPack</td>
185- <td class="tg-jajh"><a href="seqpack.md">SeqPack</a></td>185+ <td class="tg-jajh"><a href="data/seqpack.md">SeqPack</a></td>
186 186 
187 </tr>187 </tr>
188 <tr>188 <tr>
189 <td class="tg-whwg" rowspan="2">模型转换</td>189 <td class="tg-whwg" rowspan="2">模型转换</td>
190 <td class="tg-citn">模型转换</td>190 <td class="tg-citn">模型转换</td>
191- <td class="tg-jajh"><a href="mm_convert.md">MM Convert</a></td>191+ <td class="tg-jajh"><a href="../tools/mm_convert.md">MM Convert</a></td>
192 192 
193 </tr>193 </tr>
194 <tr>194 <tr>
@@ -205,7 +205,7 @@
205 <tr>205 <tr>
206 <td class="tg-whwg">评估工具</td>206 <td class="tg-whwg">评估工具</td>
207 <td class="tg-citn">VBench</td>207 <td class="tg-citn">VBench</td>
208- <td class="tg-jajh"><a href="vbench-evaluate.md">VBench Evaluate</a></td>208+ <td class="tg-jajh"><a href="../tools/vbench-evaluate.md">VBench Evaluate</a></td>
209 209 
210 </tr>210 </tr>
211</tbody></table>211</tbody></table>
Rdocs/zh/features/act_stash.md→docs/zh/features/memory/act_stash.md+0-0
文件重命名但无更改。
Rdocs/zh/features/async_activation_offload.md→docs/zh/features/memory/async_activation_offload.md+0-0
文件重命名但无更改。
Rdocs/zh/features/bucket_reordering.md→docs/zh/features/memory/bucket_reordering.md+0-0
文件重命名但无更改。
Rdocs/zh/features/data_balance.md→docs/zh/features/memory/data_balance.md+1-1
@@ -41,7 +41,7 @@ flowchart TD
41 41 
42紫色为初始状态，蓝色为目标状态。通过数据映射路径与All2All通信，实现数据的重排布。42紫色为初始状态，蓝色为目标状态。通过数据映射路径与All2All通信，实现数据的重排布。
43 43 
44-![all2all](../../../sources/images/features/online-data-balance/all2all.png)44+![all2all](../../../../sources/images/features/online-data-balance/all2all.png)
45 45 
46## 3. 使用指南46## 3. 使用指南
47 47 
Rdocs/zh/features/encoder_dp_balance.md→docs/zh/features/memory/encoder_dp_balance.md+2-2
@@ -14,7 +14,7 @@
14 14 
15通过 Alltoall 通信实现 encoder 的负载均衡：将多 patch 的 DP rank 上的部分计算任务传递给少 patch 的 DP rank，使各卡的计算量趋于均衡。15通过 Alltoall 通信实现 encoder 的负载均衡：将多 patch 的 DP rank 上的部分计算任务传递给少 patch 的 DP rank，使各卡的计算量趋于均衡。
16 16 
17-![encoder数据负载均衡原理](../../../sources/images/encoder_dp_balance/encoder_dp_balance.png)17+![encoder数据负载均衡原理](../../../../sources/images/encoder_dp_balance/encoder_dp_balance.png)
18 18 
19**核心机制：**19**核心机制：**
20 20 
@@ -54,4 +54,4 @@ GPT_ARGS="
54 54 
551. 该特性当前为 beta 版本，仅支持 InternVL 模型551. 该特性当前为 beta 版本，仅支持 InternVL 模型
562. 启用后会增加少量通信开销，建议在确认存在负载不均衡问题时使用562. 启用后会增加少量通信开销，建议在确认存在负载不均衡问题时使用
57-3. 后续版本将支持更多模型，敬请关注 [特性列表](feature_list.md)57+3. 后续版本将支持更多模型，敬请关注 [特性列表](../feature_list.md)
Rdocs/zh/features/online_data_balance.md→docs/zh/features/memory/online_data_balance.md+1-1
@@ -43,7 +43,7 @@ flowchart TD
43 43 
44紫色为初始状态，蓝色为目标状态。通过数据映射路径与All2All通信，实现数据的重排布。44紫色为初始状态，蓝色为目标状态。通过数据映射路径与All2All通信，实现数据的重排布。
45 45 
46-<img src="../../../sources/images/features/online-data-balance/all2all.png" alt="all2all">46+<img src="../../../../sources/images/features/online-data-balance/all2all.png" alt="all2all">
47 47 
48## 3. 使用指南48## 3. 使用指南
49 49 
Rdocs/zh/features/online_data_rearrange.md→docs/zh/features/memory/online_data_rearrange.md+0-0
文件重命名但无更改。
Rdocs/zh/features/swap_core.md→docs/zh/features/memory/swap_core.md+2-2
@@ -124,7 +124,7 @@ flowchart LR
124 124 
125仅配置 `swap_plan` 不会生效：底座本身不产生显存收益，收益来自其上的租户——需至少开启一个（租户配置见各自文档）：125仅配置 `swap_plan` 不会生效：底座本身不产生显存收益，收益来自其上的租户——需至少开启一个（租户配置见各自文档）：
126 126 
127-- **Op Replay（算子重放）**：建立在重计算（checkpoint）机制之上的策略。在前向时把作用域内白名单算子的输出异步换出到DDR，重计算时按路由直接从DDR取回、跳过该算子的重算，从而只缓存少量昂贵算子的输出，用可控的HBM预算 + DDR带宽换取大部分重算开销的消除。详见 [Op Replay](op_replay.md)。127+- **Op Replay（算子重放）**：建立在重计算（checkpoint）机制之上的策略。在前向时把作用域内白名单算子的输出异步换出到DDR，重计算时按路由直接从DDR取回、跳过该算子的重算，从而只缓存少量昂贵算子的输出，用可控的HBM预算 + DDR带宽换取大部分重算开销的消除。详见 [Op Replay](../optimization/op_replay.md)。
128- **Act Stash（激活暂存）**：激活offload的 `saved_tensors_hooks` 实现。在前向时把模块内autograd保存的激活张量打包（pack）换出到共享缓存，反向时按需取回（unpack），是仓库已有逐层激活offload（legacy实现）的另一种形态。详见 [Act Stash](act_stash.md)。128- **Act Stash（激活暂存）**：激活offload的 `saved_tensors_hooks` 实现。在前向时把模块内autograd保存的激活张量打包（pack）换出到共享缓存，反向时按需取回（unpack），是仓库已有逐层激活offload（legacy实现）的另一种形态。详见 [Act Stash](act_stash.md)。
129 129 
130选型要点：130选型要点：
@@ -137,5 +137,5 @@ flowchart LR
137### 已知约束137### 已知约束
138 138 
139- **已验证范围**：qwen3_5 4B（FSDP2后端，Op Replay与Act Stash租户）e2e训练，截至2026-08。139- **已验证范围**：qwen3_5 4B（FSDP2后端，Op Replay与Act Stash租户）e2e训练，截至2026-08。
140-- **精度验证建议**：新配置（新租户、新scope、新白名单）上线前，用确定性模式做逐位对照——`training.use_deter_comp: true` + 固定种子 + 关数据shuffle，同配置开/关特性各跑若干步，逐iter loss与grad norm逐位一致才放行（见 [确定性计算](other/deterministic_computing.md)）。先确认基线本身逐位可复现：个别算子kernel非确定时，逐位差异并非本特性引入；`examples/qwen3_5/finetune_qwen3_5_4B.sh` 已验证逐位可复现。140+- **精度验证建议**：新配置（新租户、新scope、新白名单）上线前，用确定性模式做逐位对照——`training.use_deter_comp: true` + 固定种子 + 关数据shuffle，同配置开/关特性各跑若干步，逐iter loss与grad norm逐位一致才放行（见 [确定性计算](../other/deterministic_computing.md)）。先确认基线本身逐位可复现：个别算子kernel非确定时，逐位差异并非本特性引入；`examples/qwen3_5/finetune_qwen3_5_4B.sh` 已验证逐位可复现。
141- **多流场景**：① 跨流生产的张量须先汇流（事件同步到计算流）再被put——这是多流编程自身的纪律，与底座无关；② D2H拷出的排序锚定在 **put时刻**调用流上录制的事件：驱逐即使后来被无关上下文间接触发，拷出也只与put前的写入保序，驱逐侧无需额外关注；③ pop侧的落点分配与消费排序仍以调用时ambient为准，**反向有多流参与调度的场景不在已验证范围内**。此类问题表现为偶发错值、不报错；排查时用 `capacity_mb: 0` 确定性驱逐档做二分定位——错值消失即指向异步序问题。141- **多流场景**：① 跨流生产的张量须先汇流（事件同步到计算流）再被put——这是多流编程自身的纪律，与底座无关；② D2H拷出的排序锚定在 **put时刻**调用流上录制的事件：驱逐即使后来被无关上下文间接触发，拷出也只与put前的写入保序，驱逐侧无需额外关注；③ pop侧的落点分配与消费排序仍以调用时ambient为准，**反向有多流参与调度的场景不在已验证范围内**。此类问题表现为偶发错值、不报错；排查时用 `capacity_mb: 0` 确定性驱逐档做二分定位——错值消失即指向异步序问题。
Rdocs/zh/features/chunkloss.md→docs/zh/features/optimization/chunkloss.md+0-0
文件重命名但无更改。
Rdocs/zh/features/chunkmbs.md→docs/zh/features/optimization/chunkmbs.md+2-2
@@ -25,13 +25,13 @@ FSDP2
25 25 
26该方案具体的示意图如下26该方案具体的示意图如下
27 27 
28-<img src="../../../sources/images/chunkmbs.png" alt="chunkmbs" style="zoom:30%;" />28+<img src="../../../../sources/images/chunkmbs.png" alt="chunkmbs" style="zoom:30%;" />
29 29 
30在GBS相同的情况下，设置`micro_batch_size`为MBS，设置梯度累积步数（`gradient_accumulation_steps`）为`GBS/(DP*MBS)`，在每个梯度累积步都要进行每个block参数的unshard；但是开启该特性后，一种典型用法是设置`micro_batch_size`为`GBS/DP`（DP=1时即GBS），设置梯度累积为1，设置`chunkmbs_plan.chunk_mbs`为原来的MBS（即合并前每个micro_batch的大小），这样每次更新模型参数都只要对每个block进行一次参数unshard，大大节省了通信时间。在Qwen3.5 35B模型上实测整网收益5%左右。30在GBS相同的情况下，设置`micro_batch_size`为MBS，设置梯度累积步数（`gradient_accumulation_steps`）为`GBS/(DP*MBS)`，在每个梯度累积步都要进行每个block参数的unshard；但是开启该特性后，一种典型用法是设置`micro_batch_size`为`GBS/DP`（DP=1时即GBS），设置梯度累积为1，设置`chunkmbs_plan.chunk_mbs`为原来的MBS（即合并前每个micro_batch的大小），这样每次更新模型参数都只要对每个block进行一次参数unshard，大大节省了通信时间。在Qwen3.5 35B模型上实测整网收益5%左右。
31 31 
32## 使用方法32## 使用方法
33 33 
34-该方案需要与[异步激活卸载（Async Activation Offload）](./async_activation_offload.md)和重计算特性结合使用：开启了ChunkMBS的modules必须同时开启activation offload和recompute（约束见「注意事项」）。开启方式如下：34+该方案需要与[异步激活卸载（Async Activation Offload）](../memory/async_activation_offload.md)和重计算特性结合使用：开启了ChunkMBS的modules必须同时开启activation offload和recompute（约束见「注意事项」）。开启方式如下：
35 35 
36```yaml36```yaml
37features:37features:
Rdocs/zh/features/dummy_optimizer.md→docs/zh/features/optimization/dummy_optimizer.md+0-0
文件重命名但无更改。
Rdocs/zh/features/fpdt.md→docs/zh/features/optimization/fpdt.md+0-0
文件重命名但无更改。
Rdocs/zh/features/fsdp2_muon_optimizer.md→docs/zh/features/optimization/fsdp2_muon_optimizer.md+0-0
文件重命名但无更改。
Rdocs/zh/features/grad_norm_overlap.md→docs/zh/features/optimization/grad_norm_overlap.md+0-0
文件重命名但无更改。
Rdocs/zh/features/op_replay.md→docs/zh/features/optimization/op_replay.md+2-2
@@ -1,6 +1,6 @@
1# Op Replay（算子重放）1# Op Replay（算子重放）
2 2 
3-> Op Replay是 [Swap Core](swap_core.md) 底座之上的租户，与底座的交互只有 `put` / `pop` 两个接口；换入换出的物理行为由共享的 `swap_plan` 配置决定。底座的行为与约定见 [Swap Core](swap_core.md)，本文只描述Op Replay自身的配置与语义。3+> Op Replay是 [Swap Core](../memory/swap_core.md) 底座之上的租户，与底座的交互只有 `put` / `pop` 两个接口；换入换出的物理行为由共享的 `swap_plan` 配置决定。底座的行为与约定见 [Swap Core](../memory/swap_core.md)，本文只描述Op Replay自身的配置与语义。
4 4 
5## 适用后端5## 适用后端
6 6 
@@ -108,7 +108,7 @@ def my_op(x: torch.Tensor, ...) -> torch.Tensor:
108### 已知约束108### 已知约束
109 109 
110- **入口判定拦截的算子不进入缓存**：in-place（mutable schema）与view（返回输入别名）语义的算子按schema判定拒绝（应从 `cache_ops` 移除）；storage变更、元数据类与调用序不一致的算子（`detach` / `set_` / `resize_` / `prim.device` 等）由内置黑名单 `_OP_REPLAY_IGNORED_OPS` 按op名排除——调用序不一致的自定义算子会使FIFO路由对错op、静默错值，需自行确认两次执行的调用序一致。110- **入口判定拦截的算子不进入缓存**：in-place（mutable schema）与view（返回输入别名）语义的算子按schema判定拒绝（应从 `cache_ops` 移除）；storage变更、元数据类与调用序不一致的算子（`detach` / `set_` / `resize_` / `prim.device` 等）由内置黑名单 `_OP_REPLAY_IGNORED_OPS` 按op名排除——调用序不一致的自定义算子会使FIFO路由对错op、静默错值，需自行确认两次执行的调用序一致。
111-- **换出的算子输出禁止原地改写**：缓存输出从put到取回之间不得被任何原地写触碰（契约无运行时兜底，违反时静默产生错误梯度），契约详见 [Swap Core](swap_core.md) 使用约定。常见安全形态：残差的in-place落在非缓存张量上（`hidden.add_(attn_out)`）；危险形态：直接改写缓存输出（`out = mm(a, b); out.add_(bias)`）、共享workspace跨层复用（自定义算子schema未声明alias时入口判定拦不住）。补救：改函数式写法（`out = mm(a, b) + bias`）、把该算子移出 `cache_ops`、或缩小scope绕开此类模块。111+- **换出的算子输出禁止原地改写**：缓存输出从put到取回之间不得被任何原地写触碰（契约无运行时兜底，违反时静默产生错误梯度），契约详见 [Swap Core](../memory/swap_core.md) 使用约定。常见安全形态：残差的in-place落在非缓存张量上（`hidden.add_(attn_out)`）；危险形态：直接改写缓存输出（`out = mm(a, b); out.add_(bias)`）、共享workspace跨层复用（自定义算子schema未声明alias时入口判定拦不住）。补救：改函数式写法（`out = mm(a, b) + bias`）、把该算子移出 `cache_ops`、或缩小scope绕开此类模块。
112- **与嵌套重计算互斥**：启用Op Replay时，`recompute_plan.apply_modules` 若同时匹配某模块及其子孙模块（嵌套checkpoint），接线期直接报错；请移除重叠的匹配pattern。不启用Op Replay的普通嵌套重计算不受影响。112- **与嵌套重计算互斥**：启用Op Replay时，`recompute_plan.apply_modules` 若同时匹配某模块及其子孙模块（嵌套checkpoint），接线期直接报错；请移除重叠的匹配pattern。不启用Op Replay的普通嵌套重计算不受影响。
113- **scope优先级**：多个scope匹配同一模块时列表在前者生效（列表序 = 优先级）；嵌套scope（一个scope的区域落在另一个之内）内层优先。113- **scope优先级**：多个scope匹配同一模块时列表在前者生效（列表序 = 优先级）；嵌套scope（一个scope的区域落在另一个之内）内层优先。
114- **kwargs无关项**：缓存判定发生在算子分发层、按 `torch.ops` 名门控，与算子的具体传参形态（args/kwargs）无关。114- **kwargs无关项**：缓存判定发生在算子分发层、按 `torch.ops` 名门控，与算子的具体传参形态（args/kwargs）无关。
Rdocs/zh/features/parameter_lr_wd_tuning.md→docs/zh/features/optimization/parameter_lr_wd_tuning.md+0-0
文件重命名但无更改。
Rdocs/zh/features/qat_w8a16.md→docs/zh/features/optimization/qat_w8a16.md+0-0
文件重命名但无更改。
Rdocs/zh/features/quantization.md→docs/zh/features/optimization/quantization.md+0-0
文件重命名但无更改。
Rdocs/zh/features/vlm_model_loss_calculate_type.md→docs/zh/features/optimization/vlm_model_loss_calculate_type.md+3-3
@@ -22,7 +22,7 @@ FSDP2 + MCORE
22- **步骤2**：在梯度累积维度上求均值 22- **步骤2**：在梯度累积维度上求均值
23- **步骤3**：在数据并行（DP）域上求均值 23- **步骤3**：在数据并行（DP）域上求均值
24 24 
25-![默认方式](../../../sources/images/vlm_model_loss_calculate_type/default.png)25+![默认方式](../../../../sources/images/vlm_model_loss_calculate_type/default.png)
26 26 
27### 按样本粒度计算Loss（Calculate Per Sample Loss）27### 按样本粒度计算Loss（Calculate Per Sample Loss）
28 28 
@@ -33,7 +33,7 @@ FSDP2 + MCORE
33- **步骤3**：在梯度累积维度上求均值 33- **步骤3**：在梯度累积维度上求均值
34- **步骤4**：在数据并行（DP）域上求均值 34- **步骤4**：在数据并行（DP）域上求均值
35 35 
36-![按样本计算](../../../sources/images/vlm_model_loss_calculate_type/sample_level.png)36+![按样本计算](../../../../sources/images/vlm_model_loss_calculate_type/sample_level.png)
37 37 
38### 按Token粒度计算Loss（Calculate Per Token Loss）38### 按Token粒度计算Loss（Calculate Per Token Loss）
39 39 
@@ -42,7 +42,7 @@ FSDP2 + MCORE
42- 直接累加全局批次中所有有效token的交叉熵损失 42- 直接累加全局批次中所有有效token的交叉熵损失
43- 最终结果除以全局批次中的有效token总数 43- 最终结果除以全局批次中的有效token总数
44 44 
45-![按Token计算](../../../sources/images/vlm_model_loss_calculate_type/token_level.png)45+![按Token计算](../../../../sources/images/vlm_model_loss_calculate_type/token_level.png)
46 46 
47## 使用方法47## 使用方法
48 48 
Rdocs/zh/features/dit_ring_attention.md→docs/zh/features/parallel/dit_ring_attention.md+0-0
文件重命名但无更改。
Rdocs/zh/features/dit_usp.md→docs/zh/features/parallel/dit_usp.md+0-0
文件重命名但无更改。
Rdocs/zh/features/dynamic_dpcp.md→docs/zh/features/parallel/dynamic_dpcp.md+0-0
文件重命名但无更改。
Rdocs/zh/features/EP_balance.md→docs/zh/features/parallel/ep_balance.md+1-1
@@ -17,7 +17,7 @@
17- **调度决策层面** ：如下图所示，在每个专家并行（EP）Rank上预留少量冗余专家槽位作为弹性缓冲池。系统基于全局实时负载状态，采用贪心策略精准识别高负载Rank上的“热点专家”，并将其动态复制到低负载Rank的冗余槽位中。这一设计突破了传统静态专家映射的束缚，使原本积压在高负载Rank上的Token能够被迁移至低负载Rank处理，仅以极低的冗余开销即可快速实现全局负载均衡。17- **调度决策层面** ：如下图所示，在每个专家并行（EP）Rank上预留少量冗余专家槽位作为弹性缓冲池。系统基于全局实时负载状态，采用贪心策略精准识别高负载Rank上的“热点专家”，并将其动态复制到低负载Rank的冗余槽位中。这一设计突破了传统静态专家映射的束缚，使原本积压在高负载Rank上的Token能够被迁移至低负载Rank处理，仅以极低的冗余开销即可快速实现全局负载均衡。
18- **执行优化层面** ：为消除冗余专家引入的额外开销，在执行层面进行了针对性优化。一方面，利用`permute`和`unpermute`的反向计算过程，分别掩盖冗余专家参数同步与梯度聚合产生的通信延迟；另一方面，在CPU侧采用`Numba`即时编译技术加速负载重规划的求解过程，确保调度决策本身不会成为训练性能瓶颈。18- **执行优化层面** ：为消除冗余专家引入的额外开销，在执行层面进行了针对性优化。一方面，利用`permute`和`unpermute`的反向计算过程，分别掩盖冗余专家参数同步与梯度聚合产生的通信延迟；另一方面，在CPU侧采用`Numba`即时编译技术加速负载重规划的求解过程，确保调度决策本身不会成为训练性能瓶颈。
19 19 
20-<img src="../../../sources/images/ep_balance.png" alt="ep_balance" style="zoom:22%;" />20+<img src="../../../../sources/images/ep_balance.png" alt="ep_balance" style="zoom:22%;" />
21 21 
22## 使用方法22## 使用方法
23 23 
Rdocs/zh/features/fsdp2.md→docs/zh/features/parallel/fsdp2.md+2-2
@@ -39,7 +39,7 @@ torchrun $DISTRIBUTED_ARGS mindspeed_mm/fsdp/train/trainer.py \
39| `training` | 优化器、学习率、迭代步数、权重加载/保存等 |39| `training` | 优化器、学习率、迭代步数、权重加载/保存等 |
40| `tools` | profiling、内存分析等工具 |40| `tools` | profiling、内存分析等工具 |
41 41 
42-各配置段的字段含义，可参考示例配置 `examples/qwen3_5/qwen3_5_4B_config.yaml`，以及 [FSDP2 开发者迁移指南](fsdp2_developer_migration_guide.md)。42+各配置段的字段含义，可参考示例配置 `examples/qwen3_5/qwen3_5_4B_config.yaml`，以及 [FSDP2 开发者迁移指南](../../guides/development/fsdp2_model_migration_guide.md)。
43 43 
44### 权重转换44### 权重转换
45 45 
@@ -51,7 +51,7 @@ mm-convert GenericDCPConverter hf_to_dcp \
51 --dcp_dir ckpt/dcp_path/xxx51 --dcp_dir ckpt/dcp_path/xxx
52```52```
53 53 
54-训练后导出 HF 权重（`dcp_to_hf`）、完整参数说明，以及个别模型的专用转换器，详见[权重转换](mm_convert.md)。54+训练后导出 HF 权重（`dcp_to_hf`）、完整参数说明，以及个别模型的专用转换器，详见[权重转换](../../tools/mm_convert.md)。
55 55 
56### 注意事项56### 注意事项
57 57 
Rdocs/zh/features/fsdp2_principle.md→docs/zh/features/parallel/fsdp2_principle.md+3-3
@@ -10,7 +10,7 @@ PyTorch的完全分片数据并行（FSDP）旨在提供一个高性能的即时
10 10 
11基于上述局限性，FSDP2移除了FlatParameter，采用沿0维分片的DTensor表示分片参数，支持对单个参数的便捷操作、无需通信的分片状态字典，以及更简化的初始化流程；同时FSDP2实现了一种改进的内存管理系统，通过避免使用recordStream来降低并确定Device内存使用，且无需任何Host同步。11基于上述局限性，FSDP2移除了FlatParameter，采用沿0维分片的DTensor表示分片参数，支持对单个参数的便捷操作、无需通信的分片状态字典，以及更简化的初始化流程；同时FSDP2实现了一种改进的内存管理系统，通过避免使用recordStream来降低并确定Device内存使用，且无需任何Host同步。
12 12 
13-<div align="center"><img src="../../../sources/images/features/fsdp2/compare_fsdp1_fsdp2.png" width="70%"></div>13+<div align="center"><img src="../../../../sources/images/features/fsdp2/compare_fsdp1_fsdp2.png" width="70%"></div>
14 14 
15## 核心工作机制15## 核心工作机制
16 16 
@@ -23,7 +23,7 @@ PyTorch的完全分片数据并行（FSDP）旨在提供一个高性能的即时
23 23 
243. **自底向上的分组策略** ：在复杂模型中 `fully_shard` 应遵循自底向上的应用顺序，例如：应先对每个TransformerLayer层应用 `fully_shard` ，再应用于root模型243. **自底向上的分组策略** ：在复杂模型中 `fully_shard` 应遵循自底向上的应用顺序，例如：应先对每个TransformerLayer层应用 `fully_shard` ，再应用于root模型
25 25 
26-<div align="center"><img src="../../../sources/images/features/fsdp2/fsdp_workflow.png" width="70%"></div>26+<div align="center"><img src="../../../../sources/images/features/fsdp2/fsdp_workflow.png" width="70%"></div>
27 27 
28## 使用方式28## 使用方式
29 29 
@@ -57,7 +57,7 @@ export CUDA_DEVICE_MAX_CONNECTIONS=2
57- `--use-torch-fsdp2`：启用FSDP2训练模式57- `--use-torch-fsdp2`：启用FSDP2训练模式
58- `--fsdp2-config-path`：指定FSDP2配置文件路径58- `--fsdp2-config-path`：指定FSDP2配置文件路径
59 59 
60-其中，FSDP2配置文件中参数说明见：[FSDP2参数介绍](../reference/mcore-fsdp2_configuration.md)60+其中，FSDP2配置文件中参数说明见：[FSDP2参数介绍](../../reference/mcore-fsdp2_configuration.md)
61 61 
62### 大模型Meta初始化62### 大模型Meta初始化
63 63 
Rdocs/zh/features/hetero_parallel.md→docs/zh/features/parallel/hetero_parallel.md+1-1
@@ -7,7 +7,7 @@
7- 模型异构：不同编码器（vision/audio encoder）、骨干（LLM）的计算量、模型大小不同，带来存算不均衡问题，导致计算空泡。具体表现为`LLM bound`和`encoder bound`现象。7- 模型异构：不同编码器（vision/audio encoder）、骨干（LLM）的计算量、模型大小不同，带来存算不均衡问题，导致计算空泡。具体表现为`LLM bound`和`encoder bound`现象。
8- 数据异构：训练样本中不同模态数据（文本、语音、视觉）token数量差异大且动态变化（动态分辨率），从而导致不同编码器、骨干网络计算量差异，带来负载不均衡问题。具体有`Intra-microbatch`和`inter-microbatch`不均衡。8- 数据异构：训练样本中不同模态数据（文本、语音、视觉）token数量差异大且动态变化（动态分辨率），从而导致不同编码器、骨干网络计算量差异，带来负载不均衡问题。具体有`Intra-microbatch`和`inter-microbatch`不均衡。
9 9 
10-针对模型异构和数据异构，MindSpeed MM分别设计了hetero-parallel和[在线数据重排方案](./online_data_rearrange.md)。10+针对模型异构和数据异构，MindSpeed MM分别设计了hetero-parallel和[在线数据重排方案](../memory/online_data_rearrange.md)。
11 11 
12## hetero-parallel12## hetero-parallel
13 13 
Rdocs/zh/features/unaligned_sequence_parallel.md→docs/zh/features/parallel/unaligned_sequence_parallel.md+1-1
@@ -7,7 +7,7 @@ SP（Sequence Parallel）并行算法是一种针对长序列数据处理的并
7## 解决方案7## 解决方案
8 8 
9Sequence Parallel主要作用于TransformerLayer中的Dropout和LayerNorm模块，在序列维度对数据进行非均匀切分。9Sequence Parallel主要作用于TransformerLayer中的Dropout和LayerNorm模块，在序列维度对数据进行非均匀切分。
10-![alt text](../../../sources/images/sp.png)10+![alt text](../../../../sources/images/sp.png)
11 11 
12## 使用方法12## 使用方法
13 13 
Rdocs/zh/features/unaligned_ulysses_cp.md→docs/zh/features/parallel/unaligned_ulysses_cp.md+1-1
@@ -7,7 +7,7 @@ CP（Context Parallel）并行算法是一种针对长序列数据处理的并
7## 解决方案7## 解决方案
8 8 
9Ulysses CP算法基于All2All算子，对All2All算子的Input List与Output List根据序列长度进行非均匀切分，使能Ulysses算法。9Ulysses CP算法基于All2All算子，对All2All算子的Input List与Output List根据序列长度进行非均匀切分，使能Ulysses算法。
10-![alt text](../../../sources/images/ulysses.png)10+![alt text](../../../../sources/images/ulysses.png)
11 11 
12## 使用方法12## 使用方法
13 13 
Rdocs/zh/features/virtual_pipeline_parallel.md→docs/zh/features/parallel/virtual_pipeline_parallel.md+1-1
@@ -12,7 +12,7 @@ Pipedream流水线并行切分粒度过大，运行过程中仍然有许多空
12 12 
13在设备数量不变的情况下，分出更多的流水线阶段，以更多的通信量，换取空泡比率降低。13在设备数量不变的情况下，分出更多的流水线阶段，以更多的通信量，换取空泡比率降低。
14 14 
15-![alt text](../../../sources/images/virtual_pipeline_parallel/virtual_pipeline.png)15+![alt text](../../../../sources/images/virtual_pipeline_parallel/virtual_pipeline.png)
16 16 
17[原文链接](https://people.eecs.berkeley.edu/~matei/papers/2021/sc_megatron_lm.pdf)17[原文链接](https://people.eecs.berkeley.edu/~matei/papers/2021/sc_megatron_lm.pdf)
18 18 
Mdocs/zh/features/supported_features.md+12-12
@@ -42,29 +42,29 @@
42 <tr>42 <tr>
43 <td class="tg-t1fb" rowspan="6">并行特性</td>43 <td class="tg-t1fb" rowspan="6">并行特性</td>
44 <td class="tg-citn">FSDP2</td>44 <td class="tg-citn">FSDP2</td>
45- <td class="tg-i1fi"><a href="fsdp2.md">FSDP2</a></td>45+ <td class="tg-i1fi"><a href="parallel/fsdp2.md">FSDP2</a></td>
46 <td class="tg-fr9f">✓</td>46 <td class="tg-fr9f">✓</td>
47 <td class="tg-fr9f">×</td>47 <td class="tg-fr9f">×</td>
48 </tr>48 </tr>
49 <tr>49 <tr>
50 <td class="tg-citn" rowspan="3">序列并行</td>50 <td class="tg-citn" rowspan="3">序列并行</td>
51- <td class="tg-i1fi"><a href="unaligned_ulysses_cp.md">Unaligned Ulysses CP</a></td>51+ <td class="tg-i1fi"><a href="parallel/unaligned_ulysses_cp.md">Unaligned Ulysses CP</a></td>
52 <td class="tg-fr9f">✓</td>52 <td class="tg-fr9f">✓</td>
53 <td class="tg-fr9f">✓</td>53 <td class="tg-fr9f">✓</td>
54 </tr>54 </tr>
55 <tr>55 <tr>
56- <td class="tg-i1fi"><a href="dit_ring_attention.md">DiT Ring Attention</a></td>56+ <td class="tg-i1fi"><a href="parallel/dit_ring_attention.md">DiT Ring Attention</a></td>
57 <td class="tg-fr9f">×</td>57 <td class="tg-fr9f">×</td>
58 <td class="tg-fr9f">✓</td>58 <td class="tg-fr9f">✓</td>
59 </tr>59 </tr>
60 <tr>60 <tr>
61- <td class="tg-i1fi"><a href="dit_usp.md">DiT USP</a></td>61+ <td class="tg-i1fi"><a href="parallel/dit_usp.md">DiT USP</a></td>
62 <td class="tg-fr9f">×</td>62 <td class="tg-fr9f">×</td>
63 <td class="tg-fr9f">✓</td>63 <td class="tg-fr9f">✓</td>
64 </tr>64 </tr>
65 <tr>65 <tr>
66 <td class="tg-citn">异构并行</td>66 <td class="tg-citn">异构并行</td>
67- <td class="tg-i1fi"><a href="hetero_parallel.md">Hetero Parallel</a></td>67+ <td class="tg-i1fi"><a href="parallel/hetero_parallel.md">Hetero Parallel</a></td>
68 <td class="tg-fr9f">×</td>68 <td class="tg-fr9f">×</td>
69 <td class="tg-fr9f">✓</td>69 <td class="tg-fr9f">✓</td>
70 </tr>70 </tr>
@@ -77,43 +77,43 @@
77 <tr>77 <tr>
78 <td class="tg-t1fb" rowspan="2">显存优化</td>78 <td class="tg-t1fb" rowspan="2">显存优化</td>
79 <td class="tg-citn">Offload</td>79 <td class="tg-citn">Offload</td>
80- <td class="tg-i1fi"><a href="async_activation_offload.md">Async Activation Offload</a></td>80+ <td class="tg-i1fi"><a href="memory/async_activation_offload.md">Async Activation Offload</a></td>
81 <td class="tg-fr9f">✓</td>81 <td class="tg-fr9f">✓</td>
82 <td class="tg-fr9f">✓</td>82 <td class="tg-fr9f">✓</td>
83 </tr>83 </tr>
84 <tr>84 <tr>
85 <td class="tg-citn">负载均衡</td>85 <td class="tg-citn">负载均衡</td>
86- <td class="tg-i1fi"><a href="online_data_rearrange.md">Online Data Rearrange</a></td>86+ <td class="tg-i1fi"><a href="memory/online_data_rearrange.md">Online Data Rearrange</a></td>
87 <td class="tg-fr9f">×</td>87 <td class="tg-fr9f">×</td>
88 <td class="tg-fr9f">✓</td>88 <td class="tg-fr9f">✓</td>
89 </tr>89 </tr>
90 <tr>90 <tr>
91 <td class="tg-t1fb" rowspan="2">优化特性</td>91 <td class="tg-t1fb" rowspan="2">优化特性</td>
92 <td class="tg-citn" rowspan="2">loss优化</td>92 <td class="tg-citn" rowspan="2">loss优化</td>
93- <td class="tg-i1fi"><a href="chunkloss.md">Chunk Loss</a></td>93+ <td class="tg-i1fi"><a href="optimization/chunkloss.md">Chunk Loss</a></td>
94 <td class="tg-fr9f">✓</td>94 <td class="tg-fr9f">✓</td>
95 <td class="tg-fr9f">×</td>95 <td class="tg-fr9f">×</td>
96 </tr>96 </tr>
97 <tr>97 <tr>
98- <td class="tg-i1fi"><a href="vlm_model_loss_calculate_type.md">VLM Model Loss Calculate Type</a></td>98+ <td class="tg-i1fi"><a href="optimization/vlm_model_loss_calculate_type.md">VLM Model Loss Calculate Type</a></td>
99 <td class="tg-fr9f">✓</td>99 <td class="tg-fr9f">✓</td>
100 <td class="tg-fr9f">✓</td>100 <td class="tg-fr9f">✓</td>
101 </tr>101 </tr>
102 <tr>102 <tr>
103 <td class="tg-whwg" rowspan="4">训练模式</td>103 <td class="tg-whwg" rowspan="4">训练模式</td>
104 <td class="tg-citn" rowspan="2">高效微调</td>104 <td class="tg-citn" rowspan="2">高效微调</td>
105- <td class="tg-jajh"><a href="lora_finetune.md">LoRA微调（基于Mcore训练后端）</a></td>105+ <td class="tg-jajh"><a href="training_mode/lora_finetune.md">LoRA微调（基于Mcore训练后端）</a></td>
106 <td class="tg-fr9f">×</td>106 <td class="tg-fr9f">×</td>
107 <td class="tg-fr9f">✓</td>107 <td class="tg-fr9f">✓</td>
108 </tr>108 </tr>
109 <tr>109 <tr>
110- <td class="tg-jajh"><a href="lora_finetune_fsdp2.md">LoRA微调（基于FSDP后端）</a></td>110+ <td class="tg-jajh"><a href="training_mode/lora_finetune_fsdp2.md">LoRA微调（基于FSDP后端）</a></td>
111 <td class="tg-fr9f">✓</td>111 <td class="tg-fr9f">✓</td>
112 <td class="tg-fr9f">×</td>112 <td class="tg-fr9f">×</td>
113 </tr>113 </tr>
114 <tr>114 <tr>
115 <td class="tg-citn">数据处理</td>115 <td class="tg-citn">数据处理</td>
116- <td class="tg-jajh"><a href="seqpack.md">SeqPack</a></td>116+ <td class="tg-jajh"><a href="data/seqpack.md">SeqPack</a></td>
117 <td class="tg-fr9f">✓</td>117 <td class="tg-fr9f">✓</td>
118 <td class="tg-fr9f">×</td>118 <td class="tg-fr9f">×</td>
119 </tr>119 </tr>
Rdocs/zh/features/agentic_sft.md→docs/zh/features/training_mode/agentic_sft.md+0-0
文件重命名但无更改。
Rdocs/zh/features/layerwise_disaggregated_training.md→docs/zh/features/training_mode/layerwise_disaggregated_training.md+8-8
@@ -13,7 +13,7 @@
13 13 
14边云协同分布式训练是一种同时满足“本地微算力”和“数据不出园”的训练方案。该方案在常规PP并行的基础上，采用了新的模型切分方案：少量直接处理原始样本的模型块部署在企业本地（边侧）、大量仅需处理中间结果的模型块部署在运营商侧（云侧）。在此部署方案下，边侧仅需少量算力处理模型首尾层，且原始样本无需上传云端。14边云协同分布式训练是一种同时满足“本地微算力”和“数据不出园”的训练方案。该方案在常规PP并行的基础上，采用了新的模型切分方案：少量直接处理原始样本的模型块部署在企业本地（边侧）、大量仅需处理中间结果的模型块部署在运营商侧（云侧）。在此部署方案下，边侧仅需少量算力处理模型首尾层，且原始样本无需上传云端。
15 15 
16-![image](../../../sources/images/layerwise_disaggregated_training/layerwise_disaggregated_training.png)16+![image](../../../../sources/images/layerwise_disaggregated_training/layerwise_disaggregated_training.png)
17 17 
18边云协同分布式训练特性支持以下功能：18边云协同分布式训练特性支持以下功能：
19 19 
@@ -47,7 +47,7 @@
47- 步骤2：将两级逻辑流水合并，若两级流水的任务队列出现冲突，则优化任务执行顺序。47- 步骤2：将两级逻辑流水合并，若两级流水的任务队列出现冲突，则优化任务执行顺序。
48 48 
49案例：PP=3，mbn = 449案例：PP=3，mbn = 4
50-![image](../../../sources/images/layerwise_disaggregated_training/pipeline_chart.png)50+![image](../../../../sources/images/layerwise_disaggregated_training/pipeline_chart.png)
51 51 
52其中上图为步骤1生成的两级逻辑流水、下图为步骤2合并后的最终流水方案。步骤2合并边侧两级流水时出现了任务冲突，优化阶段时按FS-FE-BS-BE的执行顺序重排。优化的依据是此执行顺序可以增大可容忍边云通信时延：以样本3的前向传播通信为例，其通信时间可以由样本5的前向计算时间掩盖，提升了可容忍通信时延，从而在拉远收敛场景下减小算效损失。52其中上图为步骤1生成的两级逻辑流水、下图为步骤2合并后的最终流水方案。步骤2合并边侧两级流水时出现了任务冲突，优化阶段时按FS-FE-BS-BE的执行顺序重排。优化的依据是此执行顺序可以增大可容忍边云通信时延：以样本3的前向传播通信为例，其通信时间可以由样本5的前向计算时间掩盖，提升了可容忍通信时延，从而在拉远收敛场景下减小算效损失。
53 53 
@@ -73,11 +73,11 @@
73 73 
74案例：PP=2，TP=8，对称TP74案例：PP=2，TP=8，对称TP
75 75 
76-![image](../../../sources/images/layerwise_disaggregated_training/ldt_tp.png 'ldt_tp.png')76+![image](../../../../sources/images/layerwise_disaggregated_training/ldt_tp.png 'ldt_tp.png')
77 77 
78案例：PP=2，TP=4/TP=8，非对称TP78案例：PP=2，TP=4/TP=8，非对称TP
79 79 
80-![image](../../../sources/images/layerwise_disaggregated_training/ldt_vtp.png 'ldt_vtp.png')80+![image](../../../../sources/images/layerwise_disaggregated_training/ldt_vtp.png 'ldt_vtp.png')
81 81 
82效果：由于在进行P2P通信之前，megatron现有逻辑会提前在TP组内完成AR通信，因此仅通过单卡进行通信即可将完整的数据传递给下一级PP，以上P2P通信方式可保证非对称TP下跨流水线层级通信的正确性。82效果：由于在进行P2P通信之前，megatron现有逻辑会提前在TP组内完成AR通信，因此仅通过单卡进行通信即可将完整的数据传递给下一级PP，以上P2P通信方式可保证非对称TP下跨流水线层级通信的正确性。
83 83 
@@ -88,15 +88,15 @@
88 88 
89案例：PP=3, TP=8, DP=2，对称DP89案例：PP=3, TP=8, DP=2，对称DP
90 90 
91-![image](../../../sources/images/layerwise_disaggregated_training/ldt_dp.png 'ldt_dp.png')91+![image](../../../../sources/images/layerwise_disaggregated_training/ldt_dp.png 'ldt_dp.png')
92 92 
93案例：PP=3, TP=8, DP=1/DP=2，非对称DP93案例：PP=3, TP=8, DP=1/DP=2，非对称DP
94 94 
95-![image](../../../sources/images/layerwise_disaggregated_training/ldt_vdp.png 'ldt_vdp.png')95+![image](../../../../sources/images/layerwise_disaggregated_training/ldt_vdp.png 'ldt_vdp.png')
96 96 
97针对通讯组初始化的处理，复用现有Megatron生成rank组的逻辑，首先基于对称DP场景将边云分开进行rank组生成；再将边侧的rank组进行重计算合并；云侧的rank组整体偏移边侧卡数。97针对通讯组初始化的处理，复用现有Megatron生成rank组的逻辑，首先基于对称DP场景将边云分开进行rank组生成；再将边侧的rank组进行重计算合并；云侧的rank组整体偏移边侧卡数。
98 98 
99-![image](../../../sources/images/layerwise_disaggregated_training/ldt_vdp_gen_ranks.png 'ldt_vdp_gen_ranks.png')99+![image](../../../../sources/images/layerwise_disaggregated_training/ldt_vdp_gen_ranks.png 'ldt_vdp_gen_ranks.png')
100 100 
101针对边侧梯度的处理，megatron现有逻辑在时分复用处理多个DP域的数据计算梯度时，默认会累加梯度，相当于边侧默认对梯度已经做了AR操作，只需要在最后对累加的总梯度求平均即可。101针对边侧梯度的处理，megatron现有逻辑在时分复用处理多个DP域的数据计算梯度时，默认会累加梯度，相当于边侧默认对梯度已经做了AR操作，只需要在最后对累加的总梯度求平均即可。
102 102 
@@ -106,7 +106,7 @@
106 106 
107本文档以Qwen2.5VL-32B-Instruct模型为例（VIT隐藏层数32层，LLM隐藏层数64层）介绍边云特性使能方法，具体步骤如下：107本文档以Qwen2.5VL-32B-Instruct模型为例（VIT隐藏层数32层，LLM隐藏层数64层）介绍边云特性使能方法，具体步骤如下：
108 108 
109-1. 参考[MindSpeed MM安装指导](../pytorch/install_guide.md)，完成环境安装。109+1. 参考[MindSpeed MM安装指导](../../guides/installation/install_guide.md)，完成环境安装。
110 110 
1112. 从Hugging Face库下载对应的模型权重[Qwen2.5-VL-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-32B-Instruct)，放至./ckpt/hf_path路径下。1112. 从Hugging Face库下载对应的模型权重[Qwen2.5-VL-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-32B-Instruct)，放至./ckpt/hf_path路径下。
112 112 
Rdocs/zh/features/lora_finetune.md→docs/zh/features/training_mode/lora_finetune.md+1-1
@@ -11,7 +11,7 @@ $
11W' = W + A \cdot B11W' = W + A \cdot B
12$12$
13 13 
14-![alt text](../../../sources/images/lora_finetune/lora_model.png)14+![alt text](../../../../sources/images/lora_finetune/lora_model.png)
15 15 
16 其中，$W'$ 是更新后的权重，$W$ 是原始权重，$A$ 和 $B$ 是需要学习的低秩矩阵。16 其中，$W'$ 是更新后的权重，$W$ 是原始权重，$A$ 和 $B$ 是需要学习的低秩矩阵。
17 17 
Rdocs/zh/features/lora_finetune_fsdp2.md→docs/zh/features/training_mode/lora_finetune_fsdp2.md+0-0
文件重命名但无更改。
Rdocs/zh/features/pretrain.md→docs/zh/features/training_mode/pretrain.md+0-0
文件重命名但无更改。
Rdocs/zh/features/fsdp2_developer_migration_guide.md→docs/zh/guides/development/fsdp2_model_migration_guide.md+1-1
@@ -8,7 +8,7 @@ MindSpeed MM FSDP2 基于 PyTorch FSDP2 构建。MindSpeed MM 在此基础上补
8 8 
9## 1. 先识别 FSDP2 路线9## 1. 先识别 FSDP2 路线
10 10 
11-MindSpeed MM 仓内同时存在两套容易混淆的 FSDP2 使用方式。它们的训练入口、配置文件和模型/数据接入方式不同，迁移前必须先确定目标路线。本文档聚焦新版插件式 FSDP2；新增模型和新增数据集推荐优先接入这一路线。Megatron 桥接式 FSDP2 属于过渡形态，主要用于存量入口兼容，后续不再作为新特性迭代方向；旧路线请继续参考 `docs/zh/features/fsdp2.md` 和对应 `examples/*/fsdp2_config.yaml`。11+MindSpeed MM 仓内同时存在两套容易混淆的 FSDP2 使用方式。它们的训练入口、配置文件和模型/数据接入方式不同，迁移前必须先确定目标路线。本文档聚焦新版插件式 FSDP2；新增模型和新增数据集推荐优先接入这一路线。Megatron 桥接式 FSDP2 属于过渡形态，主要用于存量入口兼容，后续不再作为新特性迭代方向；旧路线请继续参考 `docs/zh/features/parallel/fsdp2.md` 和对应 `examples/*/fsdp2_config.yaml`。
12 12 
13| 项目 | 新版插件式 FSDP2（本文主线） | Megatron 桥接式 FSDP2（旧路线） |13| 项目 | 新版插件式 FSDP2（本文主线） | Megatron 桥接式 FSDP2（旧路线） |
14|---|---|---|14|---|---|---|
Rdocs/zh/pytorch/model_migration_dev_guide.md→docs/zh/guides/development/fsdp2_model_migration_guide_old.md+4-4
@@ -16,7 +16,7 @@ Last updated: 12/08/2025. Author: zs-derrick
16 16 
17下图是模型迁移的总体流程图介绍：17下图是模型迁移的总体流程图介绍：
18 18 
19-![migration](../../../sources/images/dev_guide/migration/migration.png)19+![migration](../../../../sources/images/dev_guide/migration/migration.png)
20 20 
21为系统性地完成上述适配工作，我们将模型迁移过程分解为四个关键流程：21为系统性地完成上述适配工作，我们将模型迁移过程分解为四个关键流程：
22 22 
@@ -63,7 +63,7 @@ MindSpeed-MM 训练逻辑整体沿用 Megatron 风格，各类模型统一使用
63 63 
64### 🔄 核心接口调用流程64### 🔄 核心接口调用流程
65 65 
66-![flowchart](../../../sources/images/dev_guide/migration/flowchart.png)66+![flowchart](../../../../sources/images/dev_guide/migration/flowchart.png)
67 67 
68## 模型迁移68## 模型迁移
69 69 
@@ -179,7 +179,7 @@ MindSpeed-MM 同时提供了一套优化的多模态数据集处理模块，包
179 179 
180### 🧩 模型结构迁移180### 🧩 模型结构迁移
181 181 
182-![model](../../../sources/images/dev_guide/migration/model.png)182+![model](../../../../sources/images/dev_guide/migration/model.png)
183 183 
184在 MindSpeed-MM 框架中，所有训练模型都通过标准化的入口函数进行构建和执行：`model_provider` 构造模型，`forward_step` 执行前向结果，`loss_func` 计算训练损失。184在 MindSpeed-MM 框架中，所有训练模型都通过标准化的入口函数进行构建和执行：`model_provider` 构造模型，`forward_step` 执行前向结果，`loss_func` 计算训练损失。
185 185 
@@ -415,7 +415,7 @@ offload_to_cpu: False
415 415 
416针对模型结构复杂或特殊场景的定制化需求，我们提供了灵活的自定义切分方案。用户可以通过调用 `FSDP2Mixin` 提供的 `fully_shard` 接口，实现完全按需设计的切分和优化策略，获得对模型分布式训练的精细化控制能力，从而有效应对各类复杂架构与高性能训练场景。下图显示了 FSDP2Mixin 类的核心组成，用户可以根据各自需求对其方法进行重写：416针对模型结构复杂或特殊场景的定制化需求，我们提供了灵活的自定义切分方案。用户可以通过调用 `FSDP2Mixin` 提供的 `fully_shard` 接口，实现完全按需设计的切分和优化策略，获得对模型分布式训练的精细化控制能力，从而有效应对各类复杂架构与高性能训练场景。下图显示了 FSDP2Mixin 类的核心组成，用户可以根据各自需求对其方法进行重写：
417 417 
418-![fsdp2](../../../sources/images/dev_guide/migration/fsdp2.png)418+![fsdp2](../../../../sources/images/dev_guide/migration/fsdp2.png)
419 419 
420**自定义 fully_shard 实现示例**420**自定义 fully_shard 实现示例**
421 421 
Rdocs/zh/pytorch/model-migration-guide.md→docs/zh/guides/development/mcore_model_migration_guide.md+1-1
@@ -70,7 +70,7 @@ sequenceDiagram
70 70 
71【模型开发时推荐使用配套的环境版本】71【模型开发时推荐使用配套的环境版本】
72 72 
73-请参考[安装指南](install_guide.md)，完成昇腾软件安装。73+请参考[安装指南](../installation/install_guide.md)，完成昇腾软件安装。
74 74 
75>[!NOTE]75>[!NOTE]
76>76>
Rdocs/zh/pytorch/model-migration.md→docs/zh/guides/development/model-migration.md+3-3
@@ -38,7 +38,7 @@ NVIDIA GPU采用CUDA（Compute Unified Device Architecture）的并行计算架
38## 模型迁移总体流程38## 模型迁移总体流程
39 39 
40通用模型迁移适配方法，可以分为四个阶段：迁移分析、模型迁移、精度调试与性能调优，总体流程如下图所示。40通用模型迁移适配方法，可以分为四个阶段：迁移分析、模型迁移、精度调试与性能调优，总体流程如下图所示。
41-![alt text](../../../sources/images/migration_guide/migration_process1.png)41+![alt text](../../../../sources/images/migration_guide/migration_process1.png)
42 42 
43## 迁移分析43## 迁移分析
44 44 
@@ -72,7 +72,7 @@ bitsandbytes已支持在昇腾上进行安装，具体可单击[Supported Backen
72 72 
73总体流程如下：73总体流程如下：
74 74 
75-![alt text](../../../sources/images/migration_guide/migration_process2.png)75+![alt text](../../../../sources/images/migration_guide/migration_process2.png)
76 76 
77## 精度调优77## 精度调优
78 78 
@@ -216,7 +216,7 @@ export CPU_AFFINITY_CONF=<mode>,npu<value1>:<value2>-<value3>
216 216 
2172. 权重转换(hf2mm)2172. 权重转换(hf2mm)
218 218 
219- MindSpeed MM修改了部分原始网络的结构名称，使用`mm-convert`工具对原始预训练权重进行转换。该工具实现了Hugging Face权重和MindSpeed MM权重的互相转换以及PP（Pipeline Parallel）权重的重切分。参考[权重转换工具](../features/mm_convert.md)219+ MindSpeed MM修改了部分原始网络的结构名称，使用`mm-convert`工具对原始预训练权重进行转换。该工具实现了Hugging Face权重和MindSpeed MM权重的互相转换以及PP（Pipeline Parallel）权重的重切分。参考[权重转换工具](../../tools/mm_convert.md)
220 220 
221 ```bash221 ```bash
222 # 7b222 # 7b
Rdocs/zh/pytorch/new_model_development.md→docs/zh/guides/development/new_model_development.md+2-2
@@ -8,7 +8,7 @@ Last updated: 12/08/2025. Author: cxiaolong
8 8 
9该流程主要包含环境搭建、数据集构建、模型构建、配置文件、训练入口、训练脚本、启动训练。9该流程主要包含环境搭建、数据集构建、模型构建、配置文件、训练入口、训练脚本、启动训练。
10 10 
11-![开发流程](../../../sources/images/dev_guide/new_model_dev/flow.png)11+![开发流程](../../../../sources/images/dev_guide/new_model_dev/flow.png)
12 12 
13## Step1: 环境搭建13## Step1: 环境搭建
14 14 
@@ -182,7 +182,7 @@ MindSpeed-MM 提供了丰富的 DataLoader 组件，调用入口为 `mindspeed_m
182 182 
183MindSpeed-MM 中提供了一个 SoRAModel 作为所有扩散视频生成模型的组合类，模型继承关系如下。SoRAModel 是一个组合类，可以实例化成 Wan、HunyuanVideo 等具体的模型，由 TextEncoder、PredictModel、DiffusionModel、AEModel 多个部件组成。183MindSpeed-MM 中提供了一个 SoRAModel 作为所有扩散视频生成模型的组合类，模型继承关系如下。SoRAModel 是一个组合类，可以实例化成 Wan、HunyuanVideo 等具体的模型，由 TextEncoder、PredictModel、DiffusionModel、AEModel 多个部件组成。
184 184 
185-![sora model](../../../sources/images/dev_guide/new_model_dev/sora_model.png)185+![sora model](../../../../sources/images/dev_guide/new_model_dev/sora_model.png)
186 186 
187本教程将新构建一个 `CustomModel` 用于表示自定义的视频生成模型的组合类，它由 `PredictModel(CustomDiT)`、`TextEncoder(UMT5)`、`AEModel(WanVideoVAE)`、`DiffusionModel(WanFlowMatchScheduler)` 四部分组成。187本教程将新构建一个 `CustomModel` 用于表示自定义的视频生成模型的组合类，它由 `PredictModel(CustomDiT)`、`TextEncoder(UMT5)`、`AEModel(WanVideoVAE)`、`DiffusionModel(WanFlowMatchScheduler)` 四部分组成。
188 188 
Rdocs/zh/pytorch/install_guide.md→docs/zh/guides/installation/install_guide.md+9-9
@@ -27,11 +27,11 @@
27 27 
28## 安装前准备28## 安装前准备
29 29 
30-请参见《版本说明》中的“[相关产品版本配套说明](../release_notes_mm.md#相关产品版本配套说明)”章节，下载安装对应的软件版本。30+请参见《版本说明》中的“[相关产品版本配套说明](../../release_notes_mm.md#相关产品版本配套说明)”章节，下载安装对应的软件版本。
31 31 
32> [!NOTE]32> [!NOTE]
33>33>
34-> 安装运行程序建议使用非root用户，且建议对安装程序的目录文件做好权限管控：文件夹权限设置为750，文件权限设置为640。可以通过设置umask控制安装后文件的权限，如设置umask为0027。更多安全相关内容请参见《[安全声明](../../../SECURITYNOTE.md)》中各组件关于“文件权限控制”的说明。34+> 安装运行程序建议使用非root用户，且建议对安装程序的目录文件做好权限管控：文件夹权限设置为750，文件权限设置为640。可以通过设置umask控制安装后文件的权限，如设置umask为0027。更多安全相关内容请参见《[安全声明](../../../../SECURITYNOTE.md)》中各组件关于“文件权限控制”的说明。
35 35 
36下载[固件与驱动](https://www.hiascend.com/hardware/firmware-drivers)，请根据系统和硬件产品型号选择对应版本的社区版本或商用版本的固件与驱动。36下载[固件与驱动](https://www.hiascend.com/hardware/firmware-drivers)，请根据系统和硬件产品型号选择对应版本的社区版本或商用版本的固件与驱动。
37参考如下命令安装：37参考如下命令安装：
@@ -52,22 +52,22 @@ chmod +x Ascend-hdk-<chip_type>-npu-firmware_<version>.run
52> - 使用镜像前，请先确认机器型号。最新镜像仅支持aarch64架构，可通过uname -a命令确认当前环境是否符合要求。52> - 使用镜像前，请先确认机器型号。最新镜像仅支持aarch64架构，可通过uname -a命令确认当前环境是否符合要求。
53> - 配套镜像已预装配套的CANN 9.1.0软件及TorchNPU 26.1.0插件，您可根据需要选用。53> - 配套镜像已预装配套的CANN 9.1.0软件及TorchNPU 26.1.0插件，您可根据需要选用。
54> - 若您当前环境与提供的镜像不兼容，请选择[方式二：源码安装](#方式二源码安装)。54> - 若您当前环境与提供的镜像不兼容，请选择[方式二：源码安装](#方式二源码安装)。
55-> - master分支后续会更新新的镜像，如果需要自定义构建镜像，请参见[镜像概述](../../../docker/OVERVIEW.zh.md)。55+> - master分支后续会更新新的镜像，如果需要自定义构建镜像，请参见[镜像概述](../../../../docker/OVERVIEW.zh.md)。
56 56 
571. 拉取镜像571. 拉取镜像
58 58 
59 当前可使用MindSpeed MM 26.1.0分支对应镜像，请按需[拉取镜像](https://www.hiascend.com/developer/ascendhub/detail/6857f6fc2cfa4a678710a7075426ee5e)。59 当前可使用MindSpeed MM 26.1.0分支对应镜像，请按需[拉取镜像](https://www.hiascend.com/developer/ascendhub/detail/6857f6fc2cfa4a678710a7075426ee5e)。
60 60 
61 <!-- npu="950" id1 -->61 <!-- npu="950" id1 -->
62- - <term>Ascend 950PR&950DT系列产品<</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-950-openeuler24.03-py3.1162+ - <term>Ascend 950PR&950DT系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-950-openeuler24.03-py3.11
63 63 
64- - <term>Ascend 950PR&950DT系列产品<</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-950-ubuntu22.04-py3.1164+ - <term>Ascend 950PR&950DT系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-950-ubuntu22.04-py3.11
65 <!-- end id1 -->65 <!-- end id1 -->
66 66 
67 <!-- npu="A3" id2 -->67 <!-- npu="A3" id2 -->
68 - <term>Atlas A3训练系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-a3-openeuler24.03-py3.1168 - <term>Atlas A3训练系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-a3-openeuler24.03-py3.11
69 69 
70- - <term>Atlas A3训练系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-950-ubuntu22.04-py3.1170+ - <term>Atlas A3训练系列产品</term>：v26.1.0-cann9.1.0-torch_npu2.7.1.post8-a3-ubuntu22.04-py3.11
71 <!-- end id2 -->71 <!-- end id2 -->
72 72
73 <!-- npu="910b" id3 -->73 <!-- npu="910b" id3 -->
@@ -136,7 +136,7 @@ chmod +x Ascend-hdk-<chip_type>-npu-firmware_<version>.run
136 mindspeed-mm:v26.1.0-cann9.1.0-torch_npu2.7.1.post8-a3-openeuler24.03-py3.11 bash136 mindspeed-mm:v26.1.0-cann9.1.0-torch_npu2.7.1.post8-a3-openeuler24.03-py3.11 bash
137 ```137 ```
138 138 
139- 具体参数配置说明可查看MindSpeed MM Docker镜像概述的[构建脚本参数说明](../../../docker/OVERVIEW.zh.md#构建脚本参数说明)139+ 具体参数配置说明可查看MindSpeed MM Docker镜像概述的[构建脚本参数说明](../../../../docker/OVERVIEW.zh.md#构建脚本参数说明)
140 140 
1413. 加载容器并确认环境状态1413. 加载容器并确认环境状态
142 142 
@@ -183,7 +183,7 @@ chmod +x Ascend-hdk-<chip_type>-npu-firmware_<version>.run
183 |参数名称|说明|是否必选|取值范围|183 |参数名称|说明|是否必选|取值范围|
184 |--|--|--|:-:|184 |--|--|--|:-:|
185 |-t, --torchversion|表示当前使用的torch版本|否|2.7.1或2.10.0|185 |-t, --torchversion|表示当前使用的torch版本|否|2.7.1或2.10.0|
186- |-m, --msid|表示当前基于源码安装的MindSpeed加速库的commit id|是|MindSpeed最新商用分支commit id|186+ |-m, --msid|表示当前基于源码安装的MindSpeed加速库的commit id|是|MindSpeed最新release版本commit id|
187 |-y, --yes|确认所有软件重新安装|否|-|187 |-y, --yes|确认所有软件重新安装|否|-|
188 |-n, --no|自动跳过第三方依赖库安装|否|-|188 |-n, --no|自动跳过第三方依赖库安装|否|-|
189 |-mt, --megatron|安装Megatron-LM|否|默认安装版本Megatron-LM 0.12.0|189 |-mt, --megatron|安装Megatron-LM|否|默认安装版本Megatron-LM 0.12.0|
@@ -267,7 +267,7 @@ chmod +x Ascend-hdk-<chip_type>-npu-firmware_<version>.run
267 cd ..267 cd ..
268 ```268 ```
269 269 
270- 6. 安装MindSpeed MM及其相关依赖，可通过[pyproject.toml](../../../pyproject.toml)配置第三方依赖清单。270+ 6. 安装MindSpeed MM及其相关依赖，可通过[pyproject.toml](../../../../pyproject.toml)配置第三方依赖清单。
271 271 
272 ```shell272 ```shell
273 pip install -e .273 pip install -e .
Rdocs/zh/replace_ascend_path_guide.md→docs/zh/guides/installation/replace_ascend_path_guide.md+1-1
@@ -22,7 +22,7 @@ MindSpeed MM 仓库中的部分安装文档使用了硬编码的 `/usr/local/Asc
22| 文件类型 | 说明 | 典型路径示例 |22| 文件类型 | 说明 | 典型路径示例 |
23|---------|------|-------------|23|---------|------|-------------|
24| Shell 脚本（`.sh`）| 训练/测试启动脚本 | `examples/*/pretrain_*.sh`、`scripts/install.sh` |24| Shell 脚本（`.sh`）| 训练/测试启动脚本 | `examples/*/pretrain_*.sh`、`scripts/install.sh` |
25-| Markdown 文档（`.md`）| 安装指南、模型使用说明 | `docs/zh/pytorch/install_guide.md`、`docker/OVERVIEW.md` |25+| Markdown 文档（`.md`）| 安装指南、模型使用说明 | `docs/zh/guides/installation/install_guide.md`、`docker/OVERVIEW.md` |
26| Python 文件（`.py`）| 源码（如有路径引用） | 各模块源文件 |26| Python 文件（`.py`）| 源码（如有路径引用） | 各模块源文件 |
27| Dockerfile | Docker 镜像构建脚本 | `docker/Dockerfile` |27| Dockerfile | Docker 镜像构建脚本 | `docker/Dockerfile` |
28 28 
Rdocs/zh/features/fsdp2_qwen3vl_migration_practice.md→docs/zh/guides/practices/fsdp2_qwen3vl_migration_practice.md+10-10
@@ -6,12 +6,12 @@
6 6 
7本文面向需要将新模型接入 FSDP2 后端的研究人员、工程师与开发者，要求读者：7本文面向需要将新模型接入 FSDP2 后端的研究人员、工程师与开发者，要求读者：
8 8 
9-- 已按 [安装指导](../pytorch/install_guide.md) 完成昇腾环境与 MindSpeed MM 的安装；9+- 已按 [安装指导](../installation/install_guide.md) 完成昇腾环境与 MindSpeed MM 的安装；
10- 具备 PyTorch 训练与模型开发调试的基础知识；10- 具备 PyTorch 训练与模型开发调试的基础知识；
11- 了解模型迁移、分布式训练及精度对齐的基本概念；11- 了解模型迁移、分布式训练及精度对齐的基本概念；
12- 待迁移的模型已能在源平台（如 GPU）正常训练，并保留了 loss 基线，作为迁移的起点与后续精度对齐的参照。12- 待迁移的模型已能在源平台（如 GPU）正常训练，并保留了 loss 基线，作为迁移的起点与后续精度对齐的参照。
13 13 
14-若仅需使用现成样例跑通 Qwen3-VL 微调、而非接入新模型，请参考 [Qwen3VL README](../../../examples/qwen3vl/README_v1.md)。14+若仅需使用现成样例跑通 Qwen3-VL 微调、而非接入新模型，请参考 [Qwen3VL README](../../../../examples/qwen3vl/README_v1.md)。
15 15 
16## 源模型与迁移目标16## 源模型与迁移目标
17 17 
@@ -31,7 +31,7 @@ Qwen3VLMoeForConditionalGeneration
31└── lm_head # 输出头31└── lm_head # 输出头
32```32```
33 33 
34-建议先梳理该模块树：后续的 FSDP 分片计划、冻结配置、重计算配置，填写的都是这些模块路径。样例 [`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`](../../../examples/qwen3vl/qwen3vl_30B_config_v1.yaml) 的 `parallel.fsdp_plan.apply_modules` 即按这些路径配置，可对照参考。34+建议先梳理该模块树：后续的 FSDP 分片计划、冻结配置、重计算配置，填写的都是这些模块路径。样例 [`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`](../../../../examples/qwen3vl/qwen3vl_30B_config_v1.yaml) 的 `parallel.fsdp_plan.apply_modules` 即按这些路径配置，可对照参考。
35 35 
36### 迁移目标：插件式 FSDP2 后端36### 迁移目标：插件式 FSDP2 后端
37 37 
@@ -256,7 +256,7 @@ mm-convert GenericDCPConverter hf_to_dcp \
256 --dcp_dir ckpt/Qwen3-VL-30B-A3B-Instruct-dcp256 --dcp_dir ckpt/Qwen3-VL-30B-A3B-Instruct-dcp
257```257```
258 258 
259-然后把 YAML 里 `training.load` 取消注释，填转换得到的 DCP 目录 `ckpt/Qwen3-VL-30B-A3B-Instruct-dcp`。转换工具的更多用法见 [权重转换](mm_convert.md)。259+然后把 YAML 里 `training.load` 取消注释，填转换得到的 DCP 目录 `ckpt/Qwen3-VL-30B-A3B-Instruct-dcp`。转换工具的更多用法见 [权重转换](../../tools/mm_convert.md)。
260 260 
261`plugin` 列表则把[模型接入](#模型接入)与[数据接入](#数据接入)的成果接进框架：启动时按顺序导入这两个目录，模型与数据集完成注册，`model_id`/`dataset_type` 才找得到对应实现。261`plugin` 列表则把[模型接入](#模型接入)与[数据接入](#数据接入)的成果接进框架：启动时按顺序导入这两个目录，模型与数据集完成注册，`model_id`/`dataset_type` 才找得到对应实现。
262 262 
@@ -301,7 +301,7 @@ torchrun $DISTRIBUTED_ARGS mindspeed_mm/fsdp/train/trainer.py \
301bash examples/qwen3vl/finetune_qwen3vl_30B_v1.sh301bash examples/qwen3vl/finetune_qwen3vl_30B_v1.sh
302```302```
303 303 
304-日志输出到 `logs/` 目录。权重下载、COCO 数据集准备等通用操作步骤本文不重复，按 [Qwen3VL README](../../../examples/qwen3vl/README_v1.md) 执行即可。304+日志输出到 `logs/` 目录。权重下载、COCO 数据集准备等通用操作步骤本文不重复，按 [Qwen3VL README](../../../../examples/qwen3vl/README_v1.md) 执行即可。
305 305 
306**如何确认训练成功启动**：启动后训练日志会按 `log_interval` 周期打印每个 iteration 的关键指标，形如：306**如何确认训练成功启动**：启动后训练日志会按 `log_interval` 周期打印每个 iteration 的关键指标，形如：
307 307 
@@ -310,13 +310,13 @@ iteration 1/10000 | consumed samples: 8 | elapsed time per iteration (ms): 6603.
310iteration 2/10000 | consumed samples: 16 | elapsed time per iteration (ms): 2231.6 | learning rate: 1.000000E-08 | global batch size: 8 | loss: 1.009848E+01 | grad norm: 49.063 |310iteration 2/10000 | consumed samples: 16 | elapsed time per iteration (ms): 2231.6 | learning rate: 1.000000E-08 | global batch size: 8 | loss: 1.009848E+01 | grad norm: 49.063 |
311```311```
312 312 
313-只要日志能持续按 iteration 打印、`loss` 在合理范围且随训练总体下降、`grad norm` 未出现 NaN/Inf，即说明已正常跑通（首个 iteration 通常较慢，因包含编译与初始化开销，属正常现象）。若启动报错或卡住，可查阅 [FAQ](../FAQ.md)。313+只要日志能持续按 iteration 打印、`loss` 在合理范围且随训练总体下降、`grad norm` 未出现 NaN/Inf，即说明已正常跑通（首个 iteration 通常较慢，因包含编译与初始化开销，属正常现象）。若启动报错或卡住，可查阅 [FAQ](../troubleshooting/FAQ.md)。
314 314 
315## 训练成功启动后315## 训练成功启动后
316 316 
317- **精度对齐**：迁移的模型跑通后，建议与源仓（GPU/参考框架）对齐精度。具体做法是开启确定性计算（`training.use_deter_comp: true`）、固定随机种子、关闭数据 shuffle，消除随机性后对比两边的 loss 曲线是否一致；317- **精度对齐**：迁移的模型跑通后，建议与源仓（GPU/参考框架）对齐精度。具体做法是开启确定性计算（`training.use_deter_comp: true`）、固定随机种子、关闭数据 shuffle，消除随机性后对比两边的 loss 曲线是否一致；
318-- **性能调优**：采集 Profiling、定位瓶颈、按需开启序列并行/预取/ChunkLoss 等，见 [性能调优](../pytorch/performance_tuning.md)；318+- **性能调优**：采集 Profiling、定位瓶颈、按需开启序列并行/预取/ChunkLoss 等，见 [性能调优](../tuning/performance_tuning.md)；
319-- **低成本微调**：显存预算有限时改用 [LoRA 微调（FSDP2）](./lora_finetune_fsdp2.md)；319+- **低成本微调**：显存预算有限时改用 [LoRA 微调（FSDP2）](../../features/training_mode/lora_finetune_fsdp2.md)；
320-- **导出权重**：训练产物为 DCP 格式，用 `mm-convert GenericDCPConverter dcp_to_hf` 转回 HF 格式，见 [权重转换](mm_convert.md)。320+- **导出权重**：训练产物为 DCP 格式，用 `mm-convert GenericDCPConverter dcp_to_hf` 转回 HF 格式，见 [权重转换](../../tools/mm_convert.md)。
321 321 
322-本文以 Qwen3-VL 为例走完了完整迁移流程；更完整的接口说明与各配置段字段定义，可查阅 [FSDP2 迁移指南](./fsdp2_developer_migration_guide.md)。322+本文以 Qwen3-VL 为例走完了完整迁移流程；更完整的接口说明与各配置段字段定义，可查阅 [FSDP2 迁移指南](../development/fsdp2_model_migration_guide.md)。
Rdocs/zh/pytorch/quickstart.md→docs/zh/guides/practices/quickstart.md+4-4
@@ -8,7 +8,7 @@ MindSpeed MM同时支持多模态生成和多模态理解模型，下面分别
8 8 
9### 环境准备9### 环境准备
10 10 
11-1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](install_guide.md)。11+1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](../installation/install_guide.md)。
122. 在`MindSpeed-MM`下创建以下目录用于存储日志、数据及权重文件。122. 在`MindSpeed-MM`下创建以下目录用于存储日志、数据及权重文件。
13 13 
14 ```bash14 ```bash
@@ -70,7 +70,7 @@ MindSpeed MM同时支持多模态生成和多模态理解模型，下面分别
70 |tp_size|TP并行数量，注意要和微调启动脚本中的配置一致|否|1|70 |tp_size|TP并行数量，注意要和微调启动脚本中的配置一致|否|1|
71 71 
72 > [!NOTE]72 > [!NOTE]
73- > 由于Qwen2_5_VL和Qwen2_VL在权重转换逻辑上保持一致，更多工具详情可参见[权重转换命令行工具](../features/mm_convert.md)。73+ > 由于Qwen2_5_VL和Qwen2_VL在权重转换逻辑上保持一致，更多工具详情可参见[权重转换命令行工具](../../tools/mm_convert.md)。
74 74 
75### 数据预处理75### 数据预处理
76 76 
@@ -261,7 +261,7 @@ LOAD_PATH="ckpt/mm_path/Qwen2.5-VL-3B-Instruct"
261 261 
262### 环境准备262### 环境准备
263 263 
264-1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](install_guide.md)。264+1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](../installation/install_guide.md)。
265 265 
2662. 安装其它依赖：2662. 安装其它依赖：
267 267 
@@ -569,4 +569,4 @@ mm-convert WanConverter mm_to_hf \
569 569 
570多模态理解模型更多细节请参考《[Qwen2_5_VL 使用指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/examples/qwen2.5vl/README.md)》。570多模态理解模型更多细节请参考《[Qwen2_5_VL 使用指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/examples/qwen2.5vl/README.md)》。
571 571 
572-多模态生成模型更多细节请参考《[Wan2.2 使用指南](../../../examples/wan2.2/README.md)》。572+多模态生成模型更多细节请参考《[Wan2.2 使用指南](../../../../examples/wan2.2/README.md)》。
Rdocs/zh/pytorch/quickstart_fsdp2.md→docs/zh/guides/practices/quickstart_fsdp2.md+2-2
@@ -11,7 +11,7 @@ Qwen3-VL模型采用Pytorch原生FSDP2（Fully Sharded Data Parallel 2）框架,
11 11 
12## 环境准备12## 环境准备
13 13 
14-1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](install_guide.md)。14+1. 基于PyTorch框架和Python3.12完成模型训练环境的安装，具体请参见[MindSpeed MM安装指导](../installation/install_guide.md)。
152. 在`MindSpeed-MM`下创建以下目录用于存储日志、数据及权重文件。152. 在`MindSpeed-MM`下创建以下目录用于存储日志、数据及权重文件。
16 16 
17 ```bash17 ```bash
@@ -199,4 +199,4 @@ mm-convert GenericDCPConverter dcp_to_hf \
199 199 
200> 完整参数以 `mm-convert GenericDCPConverter dcp_to_hf -h` 为准。200> 完整参数以 `mm-convert GenericDCPConverter dcp_to_hf -h` 为准。
201 201 
202-如只想低成本微调，可改用 LoRA（可参考 [LoRA 微调（FSDP2）](../features/lora_finetune_fsdp2.md)）。202+如只想低成本微调，可改用 LoRA（可参考 [LoRA 微调（FSDP2）](../../features/training_mode/lora_finetune_fsdp2.md)）。
Rdocs/zh/FAQ.md→docs/zh/guides/troubleshooting/FAQ.md+9-9
@@ -2,23 +2,23 @@
2 2 
3| 序号 | 问题简述 | 影响 | 当前方案 | 后续计划 | 相关链接 |3| 序号 | 问题简述 | 影响 | 当前方案 | 后续计划 | 相关链接 |
4|:------:|:------:|:------:|:------:|:------:|:------:|4|:------:|:------:|:------:|:------:|:------:|:------:|
5-| 1 | CANN 版本不匹配导致训练报错 | 训练无法启动或出现算子报错 | 确保驱动固件、CANN Toolkit/Kernels/NNAL、PyTorch、TorchNPU 版本严格配套，参考 [版本配套说明](./release_notes_mm.md#相关产品版本配套说明) | 持续更新版本配套表 | [安装说明](./pytorch/install_guide.md) |5+| 1 | CANN 版本不匹配导致训练报错 | 训练无法启动或出现算子报错 | 确保驱动固件、CANN Toolkit/Kernels/NNAL、PyTorch、TorchNPU 版本严格配套，参考 [版本配套说明](../../release_notes_mm.md#相关产品版本配套说明) | 持续更新版本配套表 | [安装说明](../installation/install_guide.md) |
6-| 2 | `ModuleNotFoundError: No module named 'acl'` | 无法导入昇腾相关模块 | 检查是否已执行 `source /usr/local/Ascend/ascend-toolkit/set_env.sh`，建议写入 `~/.bashrc` | - | [安装说明](./pytorch/install_guide.md) |6+| 2 | `ModuleNotFoundError: No module named 'acl'` | 无法导入昇腾相关模块 | 检查是否已执行 `source /usr/local/Ascend/ascend-toolkit/set_env.sh`，建议写入 `~/.bashrc` | - | [安装说明](../installation/install_guide.md) |
7-| 3 | CANN nnal 包安装顺序错误导致 `libatb.so` 找不到 | 推理或训练时报动态库缺失错误 | nnal 包必须在 `source /usr/local/Ascend/ascend-toolkit/set_env.sh` 之后安装，否则找不到依赖路径 | - | [安装说明](./pytorch/install_guide.md) |7+| 3 | CANN nnal 包安装顺序错误导致 `libatb.so` 找不到 | 推理或训练时报动态库缺失错误 | nnal 包必须在 `source /usr/local/Ascend/ascend-toolkit/set_env.sh` 之后安装，否则找不到依赖路径 | - | [安装说明](../installation/install_guide.md) |
8| 4 | 多机多卡启动时脚本卡死无报错 | 无法启动分布式训练 | 确保已安装 `pdsh`，否则多机多卡启动脚本会卡死。可通过 `apt install pdsh` 或 `yum install pdsh` 安装 | - | - |8| 4 | 多机多卡启动时脚本卡死无报错 | 无法启动分布式训练 | 确保已安装 `pdsh`，否则多机多卡启动脚本会卡死。可通过 `apt install pdsh` 或 `yum install pdsh` 安装 | - | - |
9-| 5 | HuggingFace 权重无法直接用于训练 | 训练启动失败 | HuggingFace 权重格式（safetensors/bin）不能直接用于 Megatron 架构训练，需使用 `mm-convert` 工具转换为 MindSpeed-MM 格式 | - | [权重转换](./features/mm_convert.md) |9+| 5 | HuggingFace 权重无法直接用于训练 | 训练启动失败 | HuggingFace 权重格式（safetensors/bin）不能直接用于 Megatron 架构训练，需使用 `mm-convert` 工具转换为 MindSpeed-MM 格式 | - | [权重转换](../../tools/mm_convert.md) |
10-| 6 | 权重转换时 TP/PP 参数与训练不一致 | 训练加载权重失败 | 权重转换时的 `tp_size`、`pp_size` 及 `llm_pp_layers`/`vit_pp_layers` 必须与训练脚本中的并行配置保持一致 | - | [权重转换](./features/mm_convert.md) |10+| 6 | 权重转换时 TP/PP 参数与训练不一致 | 训练加载权重失败 | 权重转换时的 `tp_size`、`pp_size` 及 `llm_pp_layers`/`vit_pp_layers` 必须与训练脚本中的并行配置保持一致 | - | [权重转换](../../tools/mm_convert.md) |
11| 7 | `tp_size` 超过 `num_key_value_heads` 导致报错 | 张量并行切分失败 | TP 并行度（`tp_size`）不能超过模型配置中的 `num_key_value_heads`，否则 KV 头无法均分到各卡 | - | - |11| 7 | `tp_size` 超过 `num_key_value_heads` 导致报错 | 张量并行切分失败 | TP 并行度（`tp_size`）不能超过模型配置中的 `num_key_value_heads`，否则 KV 头无法均分到各卡 | - | - |
12-| 8 | 训练完成后权重文件数量与原始 HF 模型不一致 | 用户疑惑权重是否完整 | 训练生成的是 Megatron-Core (mcore) 格式权重，经 mg2hf 转换后得到标准 HF 格式。文件数量因切分策略不同而变化，但参数完整，需重新生成 `model.safetensors.index.json` | - | [权重转换](./features/mm_convert.md) |12+| 8 | 训练完成后权重文件数量与原始 HF 模型不一致 | 用户疑惑权重是否完整 | 训练生成的是 Megatron-Core (mcore) 格式权重，经 mg2hf 转换后得到标准 HF 格式。文件数量因切分策略不同而变化，但参数完整，需重新生成 `model.safetensors.index.json` | - | [权重转换](../../tools/mm_convert.md) |
13-| 9 | NPU 显存不足（OOM） | 训练中断 | 可采取以下措施：1. 减小 `micro-batch-size`（最低至1）；2. 增大 TP/PP 并行度（TP×PP≤NPU 数量）；3. 减小 `seq-length`；4. 开启重计算（`--recompute-granularity full --recompute-method block --recompute-num-layers`）；5. 使用 ChunkLoss 降低显存峰值 | - | [ChunkLoss](./features/chunkloss.md) |13+| 9 | NPU 显存不足（OOM） | 训练中断 | 可采取以下措施：1. 减小 `micro-batch-size`（最低至1）；2. 增大 TP/PP 并行度（TP×PP≤NPU 数量）；3. 减小 `seq-length`；4. 开启重计算（`--recompute-granularity full --recompute-method block --recompute-num-layers`）；5. 使用 ChunkLoss 降低显存峰值 | - | [ChunkLoss](../../features/optimization/chunkloss.md) |
14| 10 | LLM PP 切分为 0 层时出现 `learning_rate=None` assertion 报错 | 训练启动后立即崩溃 | PP 切分配置中 LLM 部分不能出现 0 层的 stage，例如 `llm=[0,8,10,10]` 会导致该问题，需调整为 `llm=[1,7,10,10]` 等确保每个 stage 均有 LLM 层 | 优化学习率加载逻辑以支持 0 层 stage | - |14| 10 | LLM PP 切分为 0 层时出现 `learning_rate=None` assertion 报错 | 训练启动后立即崩溃 | PP 切分配置中 LLM 部分不能出现 0 层的 stage，例如 `llm=[0,8,10,10]` 会导致该问题，需调整为 `llm=[1,7,10,10]` 等确保每个 stage 均有 LLM 层 | 优化学习率加载逻辑以支持 0 层 stage | - |
15| 11 | 数据预处理超时或同步报错 | 大数据集训练无法启动 | 可增大超时参数 `--distributed-timeout-minutes`；对于超大数据集（百万级以上），建议分批预处理或使用更高性能存储 | 优化数据预处理并行效率 | - |15| 11 | 数据预处理超时或同步报错 | 大数据集训练无法启动 | 可增大超时参数 `--distributed-timeout-minutes`；对于超大数据集（百万级以上），建议分批预处理或使用更高性能存储 | 优化数据预处理并行效率 | - |
16| 12 | 网卡名称错误导致通信超时 | 多机训练无法启动 | 使用 `ifconfig` 检查网卡名称，设置对应环境变量：`export HCCL_SOCKET_IFNAME=<网卡名>`、`export TP_SOCKET_IFNAME=<网卡名>`、`export GLOO_SOCKET_IFNAME=<网卡名>` | - | - |16| 12 | 网卡名称错误导致通信超时 | 多机训练无法启动 | 使用 `ifconfig` 检查网卡名称，设置对应环境变量：`export HCCL_SOCKET_IFNAME=<网卡名>`、`export TP_SOCKET_IFNAME=<网卡名>`、`export GLOO_SOCKET_IFNAME=<网卡名>` | - | - |
17| 13 | 保存 checkpoint 时超时报错 | 训练完成后保存权重失败 | 确保磁盘 IO 带宽正常，单个节点最大约60GB文件需在36分钟内保存完成；也可忽略该报错，不影响已保存的权重 | - | - |17| 13 | 保存 checkpoint 时超时报错 | 训练完成后保存权重失败 | 确保磁盘 IO 带宽正常，单个节点最大约60GB文件需在36分钟内保存完成；也可忽略该报错，不影响已保存的权重 | - | - |
18| 14 | 复制脚本后出现 `syntax error near unexpected token` | 脚本无法执行 | 从 Windows 复制脚本到 Linux 时换行符不匹配，执行 `dos2unix xxx.sh` 或在 vim 中设置 `:set ff=unix` | - | - |18| 14 | 复制脚本后出现 `syntax error near unexpected token` | 脚本无法执行 | 从 Windows 复制脚本到 Linux 时换行符不匹配，执行 `dos2unix xxx.sh` 或在 vim 中设置 `:set ff=unix` | - | - |
19| 15 | 不同 CANN 版本环境变量冲突 | 多版本环境下训练异常 | 不同版本的 CANN 包建议使用 Docker 隔离，避免环境变量互相干扰 | - | - |19| 15 | 不同 CANN 版本环境变量冲突 | 多版本环境下训练异常 | 不同版本的 CANN 包建议使用 Docker 隔离，避免环境变量互相干扰 | - | - |
20-| 16 | 多模态模型训练中快慢卡负载不均衡 | 训练效率低下 | 使用多模态异构 PP 切分，将视觉编码器、音频编码器和 LLM 分别配置不同的 PP 层数分布，避免某些卡负载过重 | - | [异构并行](./features/hetero_parallel.md) |20+| 16 | 多模态模型训练中快慢卡负载不均衡 | 训练效率低下 | 使用多模态异构 PP 切分，将视觉编码器、音频编码器和 LLM 分别配置不同的 PP 层数分布，避免某些卡负载过重 | - | [异构并行](../../features/parallel/hetero_parallel.md) |
21| 17 | 训练 loss 不收敛 | 模型效果差 | 检查：1. 数据质量和清洗逻辑；2. 学习率和 warmup 策略；3. 是否使用预训练权重初始化；4. 数据路径和图片路径是否正确 | - | - |21| 17 | 训练 loss 不收敛 | 模型效果差 | 检查：1. 数据质量和清洗逻辑；2. 学习率和 warmup 策略；3. 是否使用预训练权重初始化；4. 数据路径和图片路径是否正确 | - | - |
22| 18 | 推荐的关键环境变量配置 | 影响训练性能和稳定性 | 建议配置：`export ASCEND_GLOBAL_LOG_LEVEL=1`、`export TASK_QUEUE_ENABLE=2`、`export CPU_AFFINITY_CONF=2`、`export HCCL_CONNECT_TIMEOUT=600`、`export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True` | - | - |22| 18 | 推荐的关键环境变量配置 | 影响训练性能和稳定性 | 建议配置：`export ASCEND_GLOBAL_LOG_LEVEL=1`、`export TASK_QUEUE_ENABLE=2`、`export CPU_AFFINITY_CONF=2`、`export HCCL_CONNECT_TIMEOUT=600`、`export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True` | - | - |
23-| 19 | Megatron-LM 版本与 MindSpeed-MM 不匹配 | 安装或运行报错 | MindSpeed-MM 需要配套版本的 Megatron-LM，请参考 [安装说明](./pytorch/install_guide.md) 中指定的 commit 或 tag 进行 checkout | - | [安装说明](./pytorch/install_guide.md) |23+| 19 | Megatron-LM 版本与 MindSpeed-MM 不匹配 | 安装或运行报错 | MindSpeed-MM 需要配套版本的 Megatron-LM，请参考 [安装说明](../installation/install_guide.md) 中指定的 commit 或 tag 进行 checkout | - | [安装说明](../installation/install_guide.md) |
24| 20 | Docker 镜像中缺少模型特定依赖 | 模型训练报错 | Docker 镜像仅预装 torch、TorchNPU 和 decord 基础依赖，需根据目标模型的 README 在 base 环境中手动安装额外依赖 | - | - |24| 20 | Docker 镜像中缺少模型特定依赖 | 模型训练报错 | Docker 镜像仅预装 torch、TorchNPU 和 decord 基础依赖，需根据目标模型的 README 在 base 环境中手动安装额外依赖 | - | - |
Rdocs/zh/troubleshooting.md→docs/zh/guides/troubleshooting/troubleshooting.md+8-8
@@ -37,7 +37,7 @@
37 cat /usr/local/Ascend/cann/version.info37 cat /usr/local/Ascend/cann/version.info
38 ```38 ```
39 39 
40-2. 对照 [版本配套说明](release_notes_mm.md#相关产品版本配套说明) 确认版本是否配套40+2. 对照 [版本配套说明](../../release_notes_mm.md#相关产品版本配套说明) 确认版本是否配套
413. 检查 TorchNPU 版本是否与 CANN 版本匹配：413. 检查 TorchNPU 版本是否与 CANN 版本匹配：
42 42 
43 ```bash43 ```bash
@@ -122,7 +122,7 @@
122 --recompute-granularity full --recompute-method block --recompute-num-layers <层数>122 --recompute-granularity full --recompute-method block --recompute-num-layers <层数>
123 ```123 ```
124 124 
125-5. 使用 ChunkLoss 降低显存峰值（参考 [ChunkLoss](features/chunkloss.md)）125+5. 使用 ChunkLoss 降低显存峰值（参考 [ChunkLoss](../../features/optimization/chunkloss.md)）
1266. 使用分布式优化器 `--use-distributed-optimizer`1266. 使用分布式优化器 `--use-distributed-optimizer`
127 127 
128### LLM PP 切分为 0 层报错128### LLM PP 切分为 0 层报错
@@ -203,10 +203,10 @@
203 203 
204**排查步骤**：204**排查步骤**：
205 205 
206-1. 使用 profiling 工具分析各卡计算时间（参考 [工具使用](tools.md)）206+1. 使用 profiling 工具分析各卡计算时间（参考 [工具使用](../../tools/tools.md)）
2072. 检查是否启用了异构并行配置2072. 检查是否启用了异构并行配置
208-3. 考虑使用多模态异构 PP 切分（参考 [异构并行](features/hetero_parallel.md)）208+3. 考虑使用多模态异构 PP 切分（参考 [异构并行](../../features/parallel/hetero_parallel.md)）
209-4. 考虑启用 encoder 数据负载均衡（参考 [Encoder数据负载均衡](features/encoder_dp_balance.md)）209+4. 考虑启用 encoder 数据负载均衡（参考 [Encoder数据负载均衡](../../features/memory/encoder_dp_balance.md)）
210 210 
211---211---
212 212 
@@ -218,7 +218,7 @@
218 218 
219**排查步骤**：219**排查步骤**：
220 220 
221-1. 确认已使用 `mm-convert` 工具转换权重（参考 [权重转换](features/mm_convert.md)）221+1. 确认已使用 `mm-convert` 工具转换权重（参考 [权重转换](../../tools/mm_convert.md)）
2222. 检查转换时的并行配置与训练脚本是否一致：2222. 检查转换时的并行配置与训练脚本是否一致：
223 - `tp_size`223 - `tp_size`
224 - `pp_size`224 - `pp_size`
@@ -248,7 +248,7 @@
248 248 
2491. Docker 镜像仅预装 torch、TorchNPU 和 decord 基础依赖2491. Docker 镜像仅预装 torch、TorchNPU 和 decord 基础依赖
2502. 根据目标模型的 README 在 base 环境中手动安装额外依赖2502. 根据目标模型的 README 在 base 环境中手动安装额外依赖
251-3. 参考 [Docker 使用](../../docker/OVERVIEW.zh.md)251+3. 参考 [Docker 使用](../../../../docker/OVERVIEW.zh.md)
252 252 
253### CANN 版本冲突253### CANN 版本冲突
254 254 
@@ -313,4 +313,4 @@ export ASCEND_SLOG_PRINT_TO_STDOUT=1 # 日志直接打印到终端
313 313 
314### 使用 Profiling 工具314### 使用 Profiling 工具
315 315 
316-详细使用方法请参考 [工具使用](tools.md#profiling采集工具)。316+详细使用方法请参考 [工具使用](../../tools/tools.md#profiling采集工具)。
Rdocs/zh/pytorch/memory_tuning.md→docs/zh/guides/tuning/memory_tuning.md+2-2
@@ -156,7 +156,7 @@ dump执行完成后，会在输出目录生成 `snapshot_` 开头的 `pickle`
156 156 
157#### FSDP157#### FSDP
158 158 
159-套件支持FSDP2特性，可以参考 [FSDP2使用说明](../features/fsdp2.md) 使用FSDP2。159+套件支持FSDP2特性，可以参考 [FSDP2使用说明](../../features/parallel/fsdp2.md) 使用FSDP2。
160启用此特性，默认情况下可以对静态显存做完全切分。160启用此特性，默认情况下可以对静态显存做完全切分。
161 161 
162### 静态显存调优162### 静态显存调优
@@ -220,7 +220,7 @@ MM内置的模型如qwen2.5VL、OpenSoraPlan1.3支持开启模型切分，详情
220在生成模型的DiT、理解模型的decoder等主干transformer模型前反向计算阶段，激活值中间结果的保存是一个常见的瓶颈。220在生成模型的DiT、理解模型的decoder等主干transformer模型前反向计算阶段，激活值中间结果的保存是一个常见的瓶颈。
221激活值重计算可以仅保存少量保存点，并在反向计算时从保存点再次计算出中间变量用于反向计算，避免了保存大部分中间结果到反向，可以大幅降低激活值。221激活值重计算可以仅保存少量保存点，并在反向计算时从保存点再次计算出中间变量用于反向计算，避免了保存大部分中间结果到反向，可以大幅降低激活值。
222 222 
223-对于FSDP2模型，重计算在yaml中配置生效，使用方法参考 [FSDP2使用说明](../features/fsdp2.md) 使用223+对于FSDP2模型，重计算在yaml中配置生效，使用方法参考 [FSDP2使用说明](../../features/parallel/fsdp2.md) 使用
224 224 
225> - `recompute_modules`225> - `recompute_modules`
226> : - 描述：配置激活值重计算，以计算换内存226> : - 描述：配置激活值重计算，以计算换内存
Rdocs/zh/pytorch/performance_tuning.md→docs/zh/guides/tuning/performance_tuning.md+12-12
@@ -22,7 +22,7 @@
22MindSpeed-MM提供了Profiling采集工具，支持静态采集和动态采集两种模式，用于采集模型训练过程中的性能数据。两个训练后端的配置入口不同：22MindSpeed-MM提供了Profiling采集工具，支持静态采集和动态采集两种模式，用于采集模型训练过程中的性能数据。两个训练后端的配置入口不同：
23 23 
24- **FSDP2后端**：在训练YAML的`tools`段配置，`tools.profile`用于性能数据采集（`enable`、`profile_type`、`ranks`等字段），`tools.memory_profile`用于显存快照采集（`enable`、`start_step`、`end_step`、`save_path`等字段），可参考各FSDP2模型样例YAML（如`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`）中的`tools`段。24- **FSDP2后端**：在训练YAML的`tools`段配置，`tools.profile`用于性能数据采集（`enable`、`profile_type`、`ranks`等字段），`tools.memory_profile`用于显存快照采集（`enable`、`start_step`、`end_step`、`save_path`等字段），可参考各FSDP2模型样例YAML（如`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`）中的`tools`段。
25-- **MCORE（Megatron）后端**：通过`mindspeed_mm/tools/tools.json`配置采集开关与参数，详细使用方法请参考[Profiling采集工具](../tools.md#profiling采集工具)；25+- **MCORE（Megatron）后端**：通过`mindspeed_mm/tools/tools.json`配置采集开关与参数，详细使用方法请参考[Profiling采集工具](../../tools/tools.md#profiling采集工具)；
26 26 
27采集profiling时，建议同时记录以下关键上下文信息，便于后续分析：27采集profiling时，建议同时记录以下关键上下文信息，便于后续分析：
28 28 
@@ -84,7 +84,7 @@ MFU（Model FLOPs Utilization，模型算力利用率）是指训练过程中实
84 84 
85## 性能调优方法85## 性能调优方法
86 86 
87-MindSpeed-MM提供了多种性能调优特性，可根据实际场景选择合适的策略。各特性的详细使用方法请参考[特性目录](../features/feature_list.md)中的对应文档。部分特性与训练后端绑定，使用前请先确认当前所用后端。87+MindSpeed-MM提供了多种性能调优特性，可根据实际场景选择合适的策略。各特性的详细使用方法请参考[特性目录](../../features/feature_list.md)中的对应文档。部分特性与训练后端绑定，使用前请先确认当前所用后端。
88 88 
89### 两后端通用特性89### 两后端通用特性
90 90 
@@ -92,11 +92,11 @@ MindSpeed-MM提供了多种性能调优特性，可根据实际场景选择合
92 92 
93#### 异步激活值卸载93#### 异步激活值卸载
94 94 
95-将激活值卸载至Host侧，利用异步机制使拷贝被计算掩盖，降低峰值显存，详见[异步激活值卸载](../features/async_activation_offload.md)95+将激活值卸载至Host侧，利用异步机制使拷贝被计算掩盖，降低峰值显存，详见[异步激活值卸载](../../features/memory/async_activation_offload.md)
96 96 
97#### ChunkLoss97#### ChunkLoss
98 98 
99-对序列维度分块计算loss，避免同时保留整个序列的logits，降低显存峰值，详见[ChunkLoss](../features/chunkloss.md)99+对序列维度分块计算loss，避免同时保留整个序列的logits，降低显存峰值，详见[ChunkLoss](../../features/optimization/chunkloss.md)
100 100 
101#### 重计算101#### 重计算
102 102 
@@ -133,8 +133,8 @@ Python的垃圾回收（GC）机制可能导致训练性能抖动。当观察到
133 133 
134显存是训练吞吐的关键约束，释放显存可以增大数据规模（MBS或序列长度），从而实现更好的通算掩盖。以下方法均可用于降低显存峰值。134显存是训练吞吐的关键约束，释放显存可以增大数据规模（MBS或序列长度），从而实现更好的通算掩盖。以下方法均可用于降低显存峰值。
135 135 
136-- **ChunkMBS**：结合重计算与异步激活卸载，对Batch维度进行细粒度切分（Chunk），使得一次参数Unshard后可以完成多个micro-chunk的前反向计算，减少通信次数、提升通算掩盖效果。在Qwen3.5 35B模型上实测整网收益约5%。详见[ChunkMBS](../features/chunkmbs.md)。使用ChunkMBS需同时开启重计算和异步激活值卸载，且`apply_modules`需被前两者覆盖。136+- **ChunkMBS**：结合重计算与异步激活卸载，对Batch维度进行细粒度切分（Chunk），使得一次参数Unshard后可以完成多个micro-chunk的前反向计算，减少通信次数、提升通算掩盖效果。在Qwen3.5 35B模型上实测整网收益约5%。详见[ChunkMBS](../../features/optimization/chunkmbs.md)。使用ChunkMBS需同时开启重计算和异步激活值卸载，且`apply_modules`需被前两者覆盖。
137-- **async_activation_offload（异步激活值卸载）**：FSDP2通过`enable_activation_offload`开启，原理与详情见[异步激活值卸载](../features/async_activation_offload.md)。137+- **async_activation_offload（异步激活值卸载）**：FSDP2通过`enable_activation_offload`开启，原理与详情见[异步激活值卸载](../../features/memory/async_activation_offload.md)。
138 138 
139#### Host内存优化139#### Host内存优化
140 140 
@@ -142,7 +142,7 @@ Python的垃圾回收（GC）机制可能导致训练性能抖动。当观察到
142 142 
143#### 通信与计算重叠143#### 通信与计算重叠
144 144 
145-- **序列并行**：Ulysses上下文并行，通过训练YAML的`parallel.ulysses_parallel_size`配置，原理见[Unaligned Ulysses CP](../features/unaligned_ulysses_cp.md)145+- **序列并行**：Ulysses上下文并行，通过训练YAML的`parallel.ulysses_parallel_size`配置，原理见[Unaligned Ulysses CP](../../features/parallel/unaligned_ulysses_cp.md)
146- **Prefetch配置**：通过提前发起参数AllGather实现通信与计算重叠，由`num_to_forward_prefetch`（前向预取层数，默认0）和`num_to_backward_prefetch`（反向预取层数，默认1）控制（均定义于`mindspeed_mm/fsdp/params/parallel_args.py`）。两点需注意：146- **Prefetch配置**：通过提前发起参数AllGather实现通信与计算重叠，由`num_to_forward_prefetch`（前向预取层数，默认0）和`num_to_backward_prefetch`（反向预取层数，默认1）控制（均定义于`mindspeed_mm/fsdp/params/parallel_args.py`）。两点需注意：
147 - 开启EP（Expert Parallelism）场景下，前向预取的AllGather可能与EP域的All2All抢占带宽，应检查预取层数是否合理。147 - 开启EP（Expert Parallelism）场景下，前向预取的AllGather可能与EP域的All2All抢占带宽，应检查预取层数是否合理。
148 - 预取顺序由`fsdp_plan.apply_modules`的配置顺序决定，**必须与模型前向执行顺序一致**，否则会预取错层、掩盖失效。148 - 预取顺序由`fsdp_plan.apply_modules`的配置顺序决定，**必须与模型前向执行顺序一致**，否则会预取错层、掩盖失效。
@@ -150,12 +150,12 @@ Python的垃圾回收（GC）机制可能导致训练性能抖动。当观察到
150 150 
151#### 其他优化151#### 其他优化
152 152 
153-- **重计算（recompute）**：通过`recompute`参数开启、`recompute_plan.apply_modules`指定重计算的模块（使用模块路径匹配，支持精确路径、通配符和正则表达式，可精确到实例级别）。详见[FSDP2迁移指南](../features/fsdp2_developer_migration_guide.md)。153+- **重计算（recompute）**：通过`recompute`参数开启、`recompute_plan.apply_modules`指定重计算的模块（使用模块路径匹配，支持精确路径、通配符和正则表达式，可精确到实例级别）。详见[FSDP2迁移指南](../development/fsdp2_model_migration_guide.md)。
154-- **fully_shard切分粒度优化**：默认情况下FSDP2对每个Block单独做fully_shard，产生多次小参数通信。对于参数量较大的子模块（如MoE experts），可以通过`parallel.fsdp_plan.apply_modules`指定其单独切分，减少通信算子调用次数。详见[FSDP2迁移指南](../features/fsdp2_developer_migration_guide.md)。154+- **fully_shard切分粒度优化**：默认情况下FSDP2对每个Block单独做fully_shard，产生多次小参数通信。对于参数量较大的子模块（如MoE experts），可以通过`parallel.fsdp_plan.apply_modules`指定其单独切分，减少通信算子调用次数。详见[FSDP2迁移指南](../development/fsdp2_model_migration_guide.md)。
155- **Cast优化**：模型中可能存在不必要的精度转换（Cast）操作，主要涉及：(1) RMSNorm内部已使用fp32高精度实现，外部无需额外转fp32；(2) MoE routing（Unpermute）TorchNPU插件已修复相关bug，输入已支持output为bf16、routing_weight为fp32的组合，无需额外Cast。在Qwen3.5 MoE模型上，消融RMSNorm + Unpermute处的Cast约有5%性能收益；消融RMSNorm + Unpermute + RMSNormGated处的Cast约有10%性能收益。收益视模型结构而定，修改前应验证精度对齐。155- **Cast优化**：模型中可能存在不必要的精度转换（Cast）操作，主要涉及：(1) RMSNorm内部已使用fp32高精度实现，外部无需额外转fp32；(2) MoE routing（Unpermute）TorchNPU插件已修复相关bug，输入已支持output为bf16、routing_weight为fp32的组合，无需额外Cast。在Qwen3.5 MoE模型上，消融RMSNorm + Unpermute处的Cast约有5%性能收益；消融RMSNorm + Unpermute + RMSNormGated处的Cast约有10%性能收益。收益视模型结构而定，修改前应验证精度对齐。
156 156 
157### MCORE（Megatron）后端特性157### MCORE（Megatron）后端特性
158 158 
159-- **异构并行**：支持不同维度的并行策略组合，详见[异构并行](../features/hetero_parallel.md)159+- **异构并行**：支持不同维度的并行策略组合，详见[异构并行](../../features/parallel/hetero_parallel.md)
160-- **序列并行**：通过切分序列维度降低单卡计算量，支持Ulysses、RingAttention、USP等算法，详见[DiT USP](../features/dit_usp.md)和[DiT Ring Attention](../features/dit_ring_attention.md)160+- **序列并行**：通过切分序列维度降低单卡计算量，支持Ulysses、RingAttention、USP等算法，详见[DiT USP](../../features/parallel/dit_usp.md)和[DiT Ring Attention](../../features/parallel/dit_ring_attention.md)
161-- **融合算子与通信隐藏**：rms_norm/swiglu/flash attention等融合算子与Megatron权重更新通信隐藏，详见[迁移调优指南](./model-migration.md#性能调优)161+- **融合算子与通信隐藏**：rms_norm/swiglu/flash attention等融合算子与Megatron权重更新通信隐藏，详见[迁移调优指南](../development/model-migration.md#性能调优)
Mdocs/zh/index.md+12-12
@@ -12,29 +12,29 @@ MindSpeed-MM是面向大规模分布式训练的昇腾多模态大模型套件
12:caption: QuickStart:12:caption: QuickStart:
13:maxdepth: 113:maxdepth: 1
14 14 
15-pytorch/install_guide15+guides/installation/install_guide
16-快速实践16+introduction/quick_practice
17```17```
18 18 
19```{toctree}19```{toctree}
20:caption: 开发指南:20:caption: 开发指南:
21:maxdepth: 121:maxdepth: 1
22 22 
23-introduction23+introduction/overview
24-pytorch/model_migration_dev_guide24+guides/development/fsdp2_model_migration_guide_old
25-pytorch/new_model_development25+guides/development/new_model_development
26```26```
27 27 
28```{toctree}28```{toctree}
29:caption: 特性文档:29:caption: 特性文档:
30:maxdepth: 130:maxdepth: 1
31 31 
32-features/特性总览32+introduction/feature_overview
33-features/fsdp2_principle33+features/parallel/fsdp2_principle
34features/parallel/hetero-parallel34features/parallel/hetero-parallel
35features/parallel/sequence_parallel35features/parallel/sequence_parallel
36-features/async_activation_offload36+features/memory/async_activation_offload
37-features/online_data_balance37+features/memory/online_data_balance
38features/parallel/tensor_parallel38features/parallel/tensor_parallel
39```39```
40 40 
@@ -55,13 +55,13 @@ reference/environment_variables
55:caption: 调优指南:55:caption: 调优指南:
56:maxdepth: 156:maxdepth: 1
57 57 
58-pytorch/memory_tuning58+guides/tuning/memory_tuning
59-pytorch/performance_tuning59+guides/tuning/performance_tuning
60```60```
61 61 
62```{toctree}62```{toctree}
63:caption: FAQ:63:caption: FAQ:
64:maxdepth: 164:maxdepth: 1
65 65 
66-FAQ66+guides/troubleshooting/FAQ
67```67```
Adocs/zh/introduction/_menu.md+32-0
@@ -0,0 +1,32 @@
1+# MindSpeed MM
2+ 
3+- [MindSpeed MM简介](overview.md)
4+- [软件安装](../guides/installation/install_guide.md)
5+- [模型使用](supported_models.md)
6+- [特性说明]()
7+ - [特性列表](../features/supported_features.md)
8+ - [并行特性]()
9+ - [FSDP2](../features/parallel/fsdp2.md)
10+ - [序列并行]()
11+ - [Unaligned Ulysses CP](../features/parallel/unaligned_ulysses_cp.md)
12+ - [DiT Ring Attention](../features/parallel/dit_ring_attention.md)
13+ - [DiT USP](../features/parallel/dit_usp.md)
14+ - [异构并行](../features/parallel/hetero_parallel.md)
15+ - [显存优化]()
16+ - [Async Activation Offload](../features/memory/async_activation_offload.md)
17+ - [Online Data Rearrange](../features/memory/online_data_rearrange.md)
18+ - [优化特性]()
19+ - [Chunk Loss](../features/optimization/chunkloss.md)
20+ - [VLM Model Loss Calculate Type](../features/optimization/vlm_model_loss_calculate_type.md)
21+ - [训练模式]()
22+ - [LoRA微调（基于Megatron训练后端）](../features/training_mode/lora_finetune.md)
23+ - [LoRA微调（基于FSDP2训练后端）](../features/training_mode/lora_finetune_fsdp2.md)
24+ - [数据处理](../features/data/seqpack.md)
25+ - [确定性计算](../features/other/deterministic_computing.md)
26+- [模型迁移]()
27+ - [迁移指南（基于FSDP2训练后端）](../guides/practices/fsdp2_qwen3vl_migration_practice.md)
28+- [模型性能调优](../guides/tuning/performance_tuning.md)
29+- [开发工具]()
30+ - [性能数据采集](../tools/tools.md)
31+ - [权重转换](../tools/mm_convert.md)
32+- [FAQ](../guides/troubleshooting/FAQ.md)
Rdocs/zh/dir_structure.md→docs/zh/introduction/dir_structure.md+5-2
@@ -12,8 +12,12 @@
12├─docs # 项目文档目录12├─docs # 项目文档目录
13│ ├─en13│ ├─en
14│ └─zh # 中文文档目录14│ └─zh # 中文文档目录
15+│ ├─introduction # 简介、目录结构、支持的模型
16+│ ├─guides # 安装、实践、开发、调优、问题定位指南
15│ ├─features # 特性说明文档17│ ├─features # 特性说明文档
16-│ └─pytorch # pytorch后端迁移文档18+│ ├─reference # 配置与参数说明
19+│ ├─tools # 工具类文档
20+│ └─mindspore # MindSpore后端文档
17├─examples # 所有模型运行脚本和README目录21├─examples # 所有模型运行脚本和README目录
18│ ├─<model_name> # 某个模型的脚本 22│ ├─<model_name> # 某个模型的脚本
19│ │ ├─xxx.sh # 启动脚本23│ │ ├─xxx.sh # 启动脚本
@@ -52,7 +56,6 @@
52├─tests # 测试代码目录56├─tests # 测试代码目录
53│ ├─st # 系统测试用例57│ ├─st # 系统测试用例
54│ └─ut # 单元测试用例58│ └─ut # 单元测试用例
55-├─UserGuide # 用户指南目录
56└─verl_plugin # verl适配目录59└─verl_plugin # verl适配目录
57 ├─verl_npu # verl适配代码60 ├─verl_npu # verl适配代码
58 ├─README.md # verl适配说明文档61 ├─README.md # verl适配说明文档
Rdocs/zh/features/特性总览.md→docs/zh/introduction/feature_overview.md+0-0
文件重命名但无更改。
Rdocs/zh/introduction.md→docs/zh/introduction/overview.md+7-7
@@ -17,7 +17,7 @@ MindSpeed MM架构关系如图所示
17 17 
18图1 MindSpeed MM架构图18图1 MindSpeed MM架构图
19 19 
20-![alt text](../../sources/images/architecture_mindspeed_mm.png)20+![alt text](../../../sources/images/architecture_mindspeed_mm.png)
21 21 
22## 功能特性22## 功能特性
23 23 
@@ -29,14 +29,14 @@ MindSpeed MM 组件组成有预置模型、套件功能、多模态优化特性
29 29 
30 多模态加速特性：包括多维高效并行算法（DP/PP/TP/CP/EP/FSDP2）、通算掩盖(Computation-Communication Overlap)、多模态负载均衡、动态显存管理（重计算、分级存储）、长序列优化等，确保训练效率最大化。30 多模态加速特性：包括多维高效并行算法（DP/PP/TP/CP/EP/FSDP2）、通算掩盖(Computation-Communication Overlap)、多模态负载均衡、动态显存管理（重计算、分级存储）、长序列优化等，确保训练效率最大化。
31 31 
32-## MindSpeed MM 双后端支持32+## MindSpeed MM双后端支持
33 33 
34-MindSpeed MM 支持两类训练后端：基于 PyTorch FSDP2 的 FSDP2 后端，以及基于 MindSpeed Core（即 Megatron-LM 内核）的 Megatron 后端。新增模型推荐使用 FSDP2 后端。34+MindSpeed MM支持两类训练后端：基于PyTorch FSDP2的FSDP2后端，以及基于MindSpeed Core（即Megatron-LM内核）的Megatron后端。新增模型推荐使用FSDP2后端。
35 35 
36-### FSDP2 后端36+### FSDP2后端
37 37 
38-MindSpeed MM FSDP2 后端基于 PyTorch FSDP2 构建，在此基础上补充了面向昇腾平台的并行状态管理、模型注册、数据注册、DCP 检查点、重计算、LoRA、专家并行和多模态数据处理能力。该后端以独立的训练入口和一份 YAML 配置运行，不依赖 Megatron 命令行参数，已应用于包括 Wan2.2、Qwen3VL 在内的多个开源多模态模型训练任务。38+MindSpeed MM FSDP2后端基于PyTorch FSDP2构建，在此基础上补充了面向昇腾平台的并行状态管理、模型注册、数据注册、DCP检查点、重计算、LoRA、专家并行和多模态数据处理能力。该后端以独立的训练入口和一份YAML配置运行，不依赖Megatron命令行参数，已应用于包括Wan2.2、Qwen3VL在内的多个开源多模态模型训练任务。
39 39 
40-### Megatron 后端40+### Megatron后端
41 41 
42-Megatron 后端采用 PTD（Pipeline, Tensor, Data）并行方案，支持异构并行、序列并行（Ulysses、RingAttention、USP）、融合算子与 Megatron 权重更新通信隐藏等特性。该后端复用 Megatron 训练入口，训练脚本需要编写 `GPT_ARGS`、`MM_ARGS`、`OUTPUT_ARGS` 等参数以通过 Megatron 的参数校验。42+Megatron后端采用PTD（Pipeline, Tensor, Data）并行方案，支持异构并行、序列并行（Ulysses、RingAttention、USP）、融合算子与Megatron权重更新通信隐藏等特性。该后端复用Megatron训练入口，训练脚本需要编写`GPT_ARGS`、`MM_ARGS`、`OUTPUT_ARGS`等参数以通过Megatron的参数校验。
Rdocs/zh/快速实践.md→docs/zh/introduction/quick_practice.md+1-1
@@ -3,5 +3,5 @@
3```{toctree}3```{toctree}
4:maxdepth: 24:maxdepth: 2
5 5 
6-features/fsdp2_qwen3vl_migration_practice6+../guides/practices/fsdp2_qwen3vl_migration_practice
7```7```
Rdocs/zh/pytorch/supported_models.md→docs/zh/introduction/supported_models.md+11-11
@@ -116,7 +116,7 @@
116 <td> BF16 </td>116 <td> BF16 </td>
117 </tr>117 </tr>
118 <tr>118 <tr>
119- <td rowspan="2"><a href="../../../examples/diffusers/sd3">SD3.5</a></td>119+ <td rowspan="2"><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/sd3">SD3.5</a></td>
120 <td><a href="https://github.com/huggingface/diffusers/tree/5f724735437d91ed05304da478f3b2022fe3f6fb"> 8.1B </a></td>120 <td><a href="https://github.com/huggingface/diffusers/tree/5f724735437d91ed05304da478f3b2022fe3f6fb"> 8.1B </a></td>
121 <td> 全参微调 </td>121 <td> 全参微调 </td>
122 <td> 1x8 </td>122 <td> 1x8 </td>
@@ -129,42 +129,42 @@
129 <td> FP16 </td>129 <td> FP16 </td>
130 </tr>130 </tr>
131 <tr>131 <tr>
132- <td><a href="../../../examples/diffusers/flux">Flux</a></td>132+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/flux">Flux</a></td>
133 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">12B</a></td>133 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">12B</a></td>
134 <td> 全参微调 </td>134 <td> 全参微调 </td>
135 <td> 1x8 </td>135 <td> 1x8 </td>
136 <td> BF16 </td>136 <td> BF16 </td>
137 </tr>137 </tr>
138 <tr>138 <tr>
139- <td><a href="../../../examples/diffusers/flux2">Flux2-T2I</a></td>139+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/flux2">Flux2-T2I</a></td>
140 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">32B</a></td>140 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">32B</a></td>
141 <td> 全参微调 </td>141 <td> 全参微调 </td>
142 <td> 1x8 </td>142 <td> 1x8 </td>
143 <td> BF16 </td>143 <td> BF16 </td>
144 </tr>144 </tr>
145 <tr>145 <tr>
146- <td><a href="../../../examples/diffusers/flux2">Flux2-I2I</a></td>146+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/flux2">Flux2-I2I</a></td>
147 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">32B</a></td>147 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">32B</a></td>
148 <td> 全参微调 </td>148 <td> 全参微调 </td>
149 <td> 1x8 </td>149 <td> 1x8 </td>
150 <td> BF16 </td>150 <td> BF16 </td>
151 </tr>151 </tr>
152 <tr>152 <tr>
153- <td><a href="../../../examples/diffusers/flux-kontext">Flux-Kontext</a></td>153+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/flux-kontext">Flux-Kontext</a></td>
154 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">12B</a></td>154 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">12B</a></td>
155 <td> 全参微调 </td>155 <td> 全参微调 </td>
156 <td> 1x8 </td>156 <td> 1x8 </td>
157 <td> BF16 </td>157 <td> BF16 </td>
158 </tr>158 </tr>
159 <tr>159 <tr>
160- <td><a href="../../../examples/diffusers/qwen_image">Qwen-Image</a></td>160+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffusers/qwen_image">Qwen-Image</a></td>
161 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">27B</a></td>161 <td><a href="https://github.com/huggingface/diffusers/blob/main/examples/dreambooth">27B</a></td>
162 <td> LoRA微调 </td>162 <td> LoRA微调 </td>
163 <td> 1x8 </td>163 <td> 1x8 </td>
164 <td> BF16 </td>164 <td> BF16 </td>
165 </tr>165 </tr>
166 <tr>166 <tr>
167- <td><a href="../../../examples/diffsynth/qwen_image_edit">Qwen-Image-Edit</a></td>167+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/diffsynth/qwen_image_edit">Qwen-Image-Edit</a></td>
168 <td><a href="https://github.com/modelscope/Diffsynth-Studio/tree/main/examples/qwen_image">27B</a></td>168 <td><a href="https://github.com/modelscope/Diffsynth-Studio/tree/main/examples/qwen_image">27B</a></td>
169 <td> LoRA微调 </td>169 <td> LoRA微调 </td>
170 <td> 1x8 </td>170 <td> 1x8 </td>
@@ -181,14 +181,14 @@
181 <td> BF16 </td>181 <td> BF16 </td>
182 </tr>182 </tr>
183 <tr>183 <tr>
184- <td><a href="../../../examples/internvl3.5">InternVL 3.5</a></td>184+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/internvl3.5">InternVL 3.5</a></td>
185 <td><a href="https://huggingface.co/OpenGVLab/InternVL3_5-30B-A3B-Instruct">30B</a></td>185 <td><a href="https://huggingface.co/OpenGVLab/InternVL3_5-30B-A3B-Instruct">30B</a></td>
186 <td> 微调 </td>186 <td> 微调 </td>
187 <td> 1x8 (A3) </td>187 <td> 1x8 (A3) </td>
188 <td> BF16 </td>188 <td> BF16 </td>
189 </tr>189 </tr>
190 <tr>190 <tr>
191- <td rowspan="4"><a href="../../../examples/qwen2.5vl">Qwen2.5-VL</a></td>191+ <td rowspan="4"><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/qwen2.5vl">Qwen2.5-VL</a></td>
192 <td><a href="https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct">3B</a></td>192 <td><a href="https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct">3B</a></td>
193 <td> 微调 </td>193 <td> 微调 </td>
194 <td> 1x8 </td>194 <td> 1x8 </td>
@@ -251,7 +251,7 @@
251 <td> BF16 </td>251 <td> BF16 </td>
252 </tr>252 </tr>
253 <tr>253 <tr>
254- <td><a href="../../../examples/qwen2.5omni">Qwen2.5-Omni</a></td>254+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/qwen2.5omni">Qwen2.5-Omni</a></td>
255 <td><a href="https://huggingface.co/Qwen/Qwen2.5-Omni-7B">7B</a></td>255 <td><a href="https://huggingface.co/Qwen/Qwen2.5-Omni-7B">7B</a></td>
256 <td> 微调 </td>256 <td> 微调 </td>
257 <td> 1x8 </td>257 <td> 1x8 </td>
@@ -265,7 +265,7 @@
265 <td> BF16 </td>265 <td> BF16 </td>
266 </tr>266 </tr>
267 <tr>267 <tr>
268- <td><a href="../../../examples/magistral-2509">Magistral-Small-2509</a></td>268+ <td><a href="https://gitcode.com/Ascend/MindSpeed-MM/tree/26.1.0/examples/magistral-2509">Magistral-Small-2509</a></td>
269 <td><a href="https://huggingface.co/mistralai/Magistral-Small-2509">24B</a></td>269 <td><a href="https://huggingface.co/mistralai/Magistral-Small-2509">24B</a></td>
270 <td> 微调 </td>270 <td> 微调 </td>
271 <td> 1x8 </td>271 <td> 1x8 </td>
Mdocs/zh/release_notes_mm.md+3-3
@@ -186,9 +186,9 @@
186 186 
187|文档名称|内容简介|更新说明|187|文档名称|内容简介|更新说明|
188|--|--|--|188|--|--|--|
189-|《[MindSpeed MM安装指导](../zh/pytorch/install_guide.md)》|指导用户如何在NPU上基于PyTorch完成MindSpeed MM的安装，内容涵盖硬件与操作系统兼容性说明、驱动固件及CANN基础软件安装，以及基于PyTorch框架下的完整安装流程，帮助用户快速搭建多模态模型训练环境。|-|189+|《[MindSpeed MM安装指导](guides/installation/install_guide.md)》|指导用户如何在NPU上基于PyTorch完成MindSpeed MM的安装，内容涵盖硬件与操作系统兼容性说明、驱动固件及CANN基础软件安装，以及基于PyTorch框架下的完整安装流程，帮助用户快速搭建多模态模型训练环境。|-|
190-|《[MindSpeed MM快速入门（基于Megatron训练后端）](../zh/pytorch/quickstart.md)》|以Wan2.1和Qwen2.5-VL为例，指导开发者基于Megatron训练后端完成微调任务，帮助用户快速上手多模态模型训练。|-|190+|《[MindSpeed MM快速入门（基于Megatron训练后端）](guides/practices/quickstart.md)》|以Wan2.1和Qwen2.5-VL为例，指导开发者基于Megatron训练后端完成微调任务，帮助用户快速上手多模态模型训练。|-|
191-|《[MindSpeed MM快速入门（基于FSDP2训练后端）](../zh/pytorch/quickstart_fsdp2.md)》|以Qwen3-VL-30B，指导开发者基于FSDP2训练后端完成微调任务，帮助用户快速上手多模态模型训练。|-|191+|《[MindSpeed MM快速入门（基于FSDP2训练后端）](guides/practices/quickstart_fsdp2.md)》|以Qwen3-VL-30B，指导开发者基于FSDP2训练后端完成微调任务，帮助用户快速上手多模态模型训练。|-|
192 192 
193## 病毒扫描及漏洞修补列表193## 病毒扫描及漏洞修补列表
194 194 
Rdocs/zh/features/mm_convert.md→docs/zh/tools/mm_convert.md+0-0
文件重命名但无更改。
Rdocs/zh/features/multimodal_host_performance_analysis.md→docs/zh/tools/multimodal_host_performance_analysis.md+0-0
文件重命名但无更改。
Rdocs/zh/tools.md→docs/zh/tools/tools.md+8-8
@@ -4,7 +4,7 @@
4 4 
5### Profiling采集工具5### Profiling采集工具
6 6 
7-套件集成了昇腾[profiling采集工具](../../mindspeed_mm/tools/profiler.py)，以提供对模型运行情况的分析。内置模型均已适配，只需修改[tools.json](../../mindspeed_mm/tools/tools.json)文件即可生效。7+套件集成了昇腾[profiling采集工具](../../../mindspeed_mm/tools/profiler.py)，以提供对模型运行情况的分析。内置模型均已适配，只需修改[tools.json](../../../mindspeed_mm/tools/tools.json)文件即可生效。
8 8 
9+ 若新增模型，请先适配如下设置：9+ 若新增模型，请先适配如下设置：
10 10 
@@ -123,9 +123,9 @@ python mindspeed_mm/tools/profiler.py --mm-tool mindspeed_mm/tools/tools.json --
123 123 
124### Sora类模型特征提取124### Sora类模型特征提取
125 125 
126-[feature_extraction](../../mindspeed_mm/tools/feature_extraction)目录下工具可用于提取视频和文本特征并保存，目前支持单batch静态数据集特征提取。126+[feature_extraction](../../../mindspeed_mm/tools/feature_extraction)目录下工具可用于提取视频和文本特征并保存，目前支持单batch静态数据集特征提取。
127 127 
128-1. 按需修改视频、文本特征和数据存储路径的相关配置[tools.json](../../mindspeed_mm/tools/tools.json)文件。128+1. 按需修改视频、文本特征和数据存储路径的相关配置[tools.json](../../../mindspeed_mm/tools/tools.json)文件。
129 129 
130 ```bash130 ```bash
131 --extract_video_feature # 是否提取视频特征131 --extract_video_feature # 是否提取视频特征
@@ -133,20 +133,20 @@ python mindspeed_mm/tools/profiler.py --mm-tool mindspeed_mm/tools/tools.json --
133 --save_path # 特征数据存储路径133 --save_path # 特征数据存储路径
134 ```134 ```
135 135 
136-2. 使用前按需修改[feature_extraction.sh](../../examples/wan2.1/feature_extract/feature_extraction.sh)文件中对应模型数据集和配置文件（VAE、T5）路径。136+2. 使用前按需修改[feature_extraction.sh](../../../examples/wan2.1/feature_extract/feature_extraction.sh)文件中对应模型数据集和配置文件（VAE、T5）路径。
137 137 
138 ```bash138 ```bash
139 --MM_DATA # 数据配置文件路径(.json)139 --MM_DATA # 数据配置文件路径(.json)
140 --MM_MODEL # 模型配置文件路径(.json)140 --MM_MODEL # 模型配置文件路径(.json)
141 ```141 ```
142 142 
143-3. 配置完成后，调用[feature_extraction.sh](../../examples/wan2.1/feature_extract/feature_extraction.sh)即可提取数据特征。143+3. 配置完成后，调用[feature_extraction.sh](../../../examples/wan2.1/feature_extract/feature_extraction.sh)即可提取数据特征。
144 144 
145### 内存快照提取145### 内存快照提取
146 146 
147-套件集成了昇腾[内存快照采集工具](../../mindspeed_mm/tools/mem_profiler.py)，以提供对模型运行情况的分析。内置模型均已适配，只需修改[tools.json](../../mindspeed_mm/tools/tools.json)文件即可生效。147+套件集成了昇腾[内存快照采集工具](../../../mindspeed_mm/tools/mem_profiler.py)，以提供对模型运行情况的分析。内置模型均已适配，只需修改[tools.json](../../../mindspeed_mm/tools/tools.json)文件即可生效。
148 148 
149-+ 对复用[训练流程](../../mindspeed_mm/training.py)的模型，同样仅需修改配置。支持的配置项如下。149++ 对复用[训练流程](../../../mindspeed_mm/training.py)的模型，同样仅需修改配置。支持的配置项如下。
150 150 
151```json5151```json5
152{152{
@@ -321,7 +321,7 @@ python mindspeed_mm/fsdp/tools/profiler.py \
321 321 
322### 内存快照采集322### 内存快照采集
323 323 
324-FSDP2 后端使用独立的[内存快照采集工具](../../mindspeed_mm/fsdp/tools/memory_profiler.py)，通过模型训练 YAML 文件中的 tools.memory_profile 配置。324+FSDP2 后端使用独立的[内存快照采集工具](../../../mindspeed_mm/fsdp/tools/memory_profiler.py)，通过模型训练 YAML 文件中的 tools.memory_profile 配置。
325 325 
3261. 在模型训练 YAML 文件中配置 `tools.memory_profile`，例如：3261. 在模型训练 YAML 文件中配置 `tools.memory_profile`，例如：
327 327 
Rdocs/zh/features/vbench-evaluate.md→docs/zh/tools/vbench-evaluate.md+0-0
文件重命名但无更改。
Mexamples/cosyvoice3/README.md+1-1
@@ -43,7 +43,7 @@ commit_id=1822c5c
43 43 
44【模型开发时推荐使用配套的环境版本】44【模型开发时推荐使用配套的环境版本】
45 45 
46-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。46+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
47 47 
48### 2. 环境搭建48### 2. 环境搭建
49 49 
Mexamples/dancegrpo/README.md+2-2
@@ -39,7 +39,7 @@ commit_id=2149f36f22db601f9dbf70472fea11576f62a0f6
39 39 
40【模型开发时推荐使用配套的环境版本】40【模型开发时推荐使用配套的环境版本】
41 41 
42-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)42+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)
43 43 
44<a id="jump1.1"></a>44<a id="jump1.1"></a>
45 45 
@@ -62,7 +62,7 @@ cd ..
62 62 
63### 2. 环境搭建63### 2. 环境搭建
64 64 
65-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)创建Python环境并安装 torch 和 TorchNPU。65+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)创建Python环境并安装 torch 和 TorchNPU。
66 66 
67```bash67```bash
68conda activate test68conda activate test
Mexamples/funasr/README.md+1-1
@@ -44,7 +44,7 @@ commit_id=42b6d3b
44 44 
45【模型开发时推荐使用配套的环境版本】45【模型开发时推荐使用配套的环境版本】
46 46 
47-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。47+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
48 48 
49### 2. 环境搭建49### 2. 环境搭建
50 50 
Mexamples/glm4.5v/README.md+4-4
@@ -46,7 +46,7 @@ commit_id=8cb5963
46 46 
47【模型开发时推荐使用配套的环境版本】47【模型开发时推荐使用配套的环境版本】
48 48 
49-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。49+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
50 50 
51<a id="jump1.2"></a>51<a id="jump1.2"></a>
52 52 
@@ -115,8 +115,8 @@ mm-convert ExpertMergeDcpConverter hf_to_dcp --hf_dir "ckpt/hf_path/GLM-4.5V" --
115 115 
116## 数据集准备及处理116## 数据集准备及处理
117 117 
118-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。118+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
119-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。119+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
120 120 
121## 微调121## 微调
122 122 
@@ -260,7 +260,7 @@ WORLD_SIZE=$(($NPUS_PER_NODE * $NNODES))
260### 3. 启动微调260### 3. 启动微调
261 261 
262启动微调训练任务需要确认loss计算方式。262启动微调训练任务需要确认loss计算方式。
263-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)263+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
264 264 
265```shell265```shell
266bash examples/glm4.5v/model_106B.sh266bash examples/glm4.5v/model_106B.sh
Mexamples/glm5.3_flash/README.md+5-5
@@ -52,7 +52,7 @@ url=https://huggingface.co/zai-org/GLM-5.3-Flash-BF16/tree/main
52 52 
53【模型开发时推荐使用配套的环境版本】53【模型开发时推荐使用配套的环境版本】
54 54 
55-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。55+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
56 56 
57推荐环境版本如下：57推荐环境版本如下：
58 58 
@@ -164,8 +164,8 @@ pip list | grep fla
164 164 
165## 数据集准备及处理165## 数据集准备及处理
166 166 
167-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。167+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
168-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。168+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
169 169 
170## 训练170## 训练
171 171 
@@ -254,11 +254,11 @@ training:
254- 重计算254- 重计算
255 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭。255 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭。
256 - 开启后可以节省显存占用256 - 开启后可以节省显存占用
257-- [chunkloss](../../docs/zh/features/chunkloss.md)257+- [chunkloss](../../docs/zh/features/optimization/chunkloss.md)
258 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭258 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭
259 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。259 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。
260 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用260 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用
261-- [async activation offload](../../docs/zh/features/async_activation_offload.md)261+- [async activation offload](../../docs/zh/features/memory/async_activation_offload.md)
262 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭262 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭
263 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。263 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。
264 264 
Mexamples/hunyuanvideo_1.5/README.md+1-1
@@ -51,7 +51,7 @@ commit_id=bf576ef1d5ddc643cf814b1dff4f4dcc9a7581c7
51 51 
52【模型开发时推荐使用配套的环境版本】52【模型开发时推荐使用配套的环境版本】
53 53 
54-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)54+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)
55 55 
56### 1. 仓库拉取56### 1. 仓库拉取
57 57 
Mexamples/kimi_k3/README.md+8-8
@@ -55,7 +55,7 @@ url=https://huggingface.co/moonshotai/Kimi-K3/tree/main
55 55 
56【模型开发时推荐使用配套的环境版本】56【模型开发时推荐使用配套的环境版本】
57 57 
58-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。58+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
59 59 
60<a id="jump1.2"></a>60<a id="jump1.2"></a>
61 61 
@@ -206,8 +206,8 @@ pip install -e . --no-build-isolation --no-deps
206 206 
207## 数据集准备及处理207## 数据集准备及处理
208 208 
209-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。209+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
210-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。210+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
211 211 
212## 训练212## 训练
213 213 
@@ -278,8 +278,8 @@ NODE_RANK: 当前节点序号
278| `skip_kda_recompute` | `model` | 跳过linear attention层KDA重计算 | 选择性重计算，需同时使能重计算和`enable_activation_offload` |278| `skip_kda_recompute` | `model` | 跳过linear attention层KDA重计算 | 选择性重计算，需同时使能重计算和`enable_activation_offload` |
279| `recompute` | `features` | 重计算开关 | 开启后可以节省显存占用 |279| `recompute` | `features` | 重计算开关 | 开启后可以节省显存占用 |
280| `enable_activation_offload` | `features` | 激活值异步卸载到Host侧内存开关 | 开启后降低Device显存占用，`apply_modules`指定需要开启该特性的module |280| `enable_activation_offload` | `features` | 激活值异步卸载到Host侧内存开关 | 开启后降低Device显存占用，`apply_modules`指定需要开启该特性的module |
281-| `enable_chunk_loss` | `features` | chunkloss特性开关 | 需与`chunkloss_plan`关联使用，开启后大幅降低loss计算时的显存尖刺，详细说明请参考[chunkloss文档](../../docs/zh/features/chunkloss.md) |281+| `enable_chunk_loss` | `features` | chunkloss特性开关 | 需与`chunkloss_plan`关联使用，开启后大幅降低loss计算时的显存尖刺，详细说明请参考[chunkloss文档](../../docs/zh/features/optimization/chunkloss.md) |
282-| `enable_chunk_mbs` | `features` | 是否开启chunkmbs特性 | 需与`chunkmbs_plan`关联使用，开启后将MicroBatch维度切分为多个微块依次计算，可压缩激活显存峰值并提升训练吞吐，详细说明请参考[chunkmbs文档](../../docs/zh/features/chunkmbs.md) |282+| `enable_chunk_mbs` | `features` | 是否开启chunkmbs特性 | 需与`chunkmbs_plan`关联使用，开启后将MicroBatch维度切分为多个微块依次计算，可压缩激活显存峰值并提升训练吞吐，详细说明请参考[chunkmbs文档](../../docs/zh/features/optimization/chunkmbs.md) |
283 283 
284【数据目录配置】284【数据目录配置】
285 285 
@@ -307,14 +307,14 @@ NODE_RANK: 当前节点序号
307- 重计算307- 重计算
308 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭。308 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭。
309 - 开启后可以节省显存占用309 - 开启后可以节省显存占用
310-- [chunkloss](../../docs/zh/features/chunkloss.md)310+- [chunkloss](../../docs/zh/features/optimization/chunkloss.md)
311 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭311 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭
312 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。312 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。
313 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用313 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用
314-- [async activation offload](../../docs/zh/features/async_activation_offload.md)314+- [async activation offload](../../docs/zh/features/memory/async_activation_offload.md)
315 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭315 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭
316 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。316 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。
317-- [chunkmbs](../../docs/zh/features/chunkmbs.md)317+- [chunkmbs](../../docs/zh/features/optimization/chunkmbs.md)
318 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭318 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭
319 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`319 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`
320 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。320 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。
Mexamples/kimik2_5/README.md+4-4
@@ -63,7 +63,7 @@ commit_id=74797c9
63 63 
64【模型开发时推荐使用配套的环境版本】64【模型开发时推荐使用配套的环境版本】
65 65 
66-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。66+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
67 67 
68<a id="jump1.2"></a>68<a id="jump1.2"></a>
69 69 
@@ -81,8 +81,8 @@ bash scripts/install.sh --msbranch master && pip install tiktoken==0.12.0
81 81 
82## 数据集准备及处理82## 数据集准备及处理
83 83 
84-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。84+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
85-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。85+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
86 86 
87## 训练87## 训练
88 88 
@@ -151,7 +151,7 @@ NODE_RANK: 当前节点序号
151| `enable_preload` | `data->dataloader_param` | 数据预加载开关 | 开启后数据加载与计算重叠，减少训练等待时间 |151| `enable_preload` | `data->dataloader_param` | 数据预加载开关 | 开启后数据加载与计算重叠，减少训练等待时间 |
152| `enable_activation_offload` | `features` | 激活值卸载到Host侧内存开关 | 开启后降低Device显存占用，`apply_modules`指定需要开启该特性的module |152| `enable_activation_offload` | `features` | 激活值卸载到Host侧内存开关 | 开启后降低Device显存占用，`apply_modules`指定需要开启该特性的module |
153| `enable_chunk_mbs` | `features` | 是否开启chunkmbs特性 | 需与`chunkmbs_plan`关联使用，开启后将MicroBatch维度切分为多个微块依次计算，可压缩激活显存峰值并提升训练吞吐 |153| `enable_chunk_mbs` | `features` | 是否开启chunkmbs特性 | 需与`chunkmbs_plan`关联使用，开启后将MicroBatch维度切分为多个微块依次计算，可压缩激活显存峰值并提升训练吞吐 |
154-| `chunkmbs_plan` | `features` | chunkmbs切分策略配置 | 仅在`enable_chunk_mbs`启用时生效，包含`chunk_mbs`、`batch_dim`、`chunk_arg_indexs`、`chunk_kwarg_names`等子字段，详细说明请参考[chunkmbs文档](../../docs/zh/features/chunkmbs.md) |154+| `chunkmbs_plan` | `features` | chunkmbs切分策略配置 | 仅在`enable_chunk_mbs`启用时生效，包含`chunk_mbs`、`batch_dim`、`chunk_arg_indexs`、`chunk_kwarg_names`等子字段，详细说明请参考[chunkmbs文档](../../docs/zh/features/optimization/chunkmbs.md) |
155 155 
156<a id="jump3.3"></a>156<a id="jump3.3"></a>
157 157 
Mexamples/ltx2/README.md+1-1
@@ -68,7 +68,7 @@ commit_id=28c3c73fe557666c3de176e1e50a5220152ccfca
68 68 
69【模型开发时推荐使用配套的环境版本】69【模型开发时推荐使用配套的环境版本】
70 70 
71-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。71+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
72 72 
73<a id="jump1.2"></a>73<a id="jump1.2"></a>
74 74 
Mexamples/ltx2_3/README.md+1-1
@@ -78,7 +78,7 @@ MM 训练阶段从 LTX-2.3 检查点中加载 embedding connector；Gemma 目录
78 78 
79【模型开发时推荐使用配套的环境版本】79【模型开发时推荐使用配套的环境版本】
80 80 
81-请参考 [MindSpeed-MM 安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾驱动、CANN、PyTorch、`torch_npu` 和 MindSpeed 的安装。建议使用 Python 3.10；`torch`、`torch_npu`、CANN 版本需相互匹配。81+请参考 [MindSpeed-MM 安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾驱动、CANN、PyTorch、`torch_npu` 和 MindSpeed 的安装。建议使用 Python 3.10；`torch`、`torch_npu`、CANN 版本需相互匹配。
82 82 
83```bash83```bash
84conda activate <your_conda_env>84conda activate <your_conda_env>
Mexamples/magihuman/README.md+7-7
@@ -60,7 +60,7 @@ hf download GAIR/daVinci-MagiHuman \
60 60 
61### 1. 环境准备61### 1. 环境准备
62 62 
63-请先按 [安装指导](../../docs/zh/pytorch/install_guide.md) 完成 CANN、PyTorch、torch-npu 和63+请先按 [安装指导](../../docs/zh/guides/installation/install_guide.md) 完成 CANN、PyTorch、torch-npu 和
64MindSpeed MM 的安装，配套版本以该文档为准。64MindSpeed MM 的安装，配套版本以该文档为准。
65 65 
66在 MindSpeed MM 仓库根目录安装当前代码：66在 MindSpeed MM 仓库根目录安装当前代码：
@@ -241,7 +241,7 @@ bash examples/magihuman/finetune_magihuman_t2av.sh
241 241 
242训练日志能够持续输出 iteration，并且 loss、grad norm 未出现 NaN/Inf，即说明 forward、242训练日志能够持续输出 iteration，并且 loss、grad norm 未出现 NaN/Inf，即说明 forward、
243backward 和 optimizer step 已接通。首个 iteration 通常包含初始化和编译开销，耗时可能明显243backward 和 optimizer step 已接通。首个 iteration 通常包含初始化和编译开销，耗时可能明显
244-高于后续迭代。启动失败或训练卡住时，可查阅 [FAQ](../../docs/zh/FAQ.md)。244+高于后续迭代。启动失败或训练卡住时，可查阅 [FAQ](../../docs/zh/guides/troubleshooting/FAQ.md)。
245 245 
246在 8 卡 Ascend 910B3 上按上述配置训练，输入取 video 3840、audio 126、text 640 token246在 8 卡 Ascend 910B3 上按上述配置训练，输入取 video 3840、audio 126、text 640 token
247（packed 长度 4606），5000 step 稳态 step time 中位数 4634.8 ms，单卡 71.7 TFLOP/s，峰值显存247（packed 长度 4606），5000 step 稳态 step time 中位数 4634.8 ms，单卡 71.7 TFLOP/s，峰值显存
@@ -259,17 +259,17 @@ RMSNorm 使用 `npu_rms_norm`，fp32 下最大误差约 1e-6。连续半区 gate
259 259 
260| 特性 | 是否支持 | 说明 |260| 特性 | 是否支持 | 说明 |
261| --- | --- | --- |261| --- | --- | --- |
262-| [FSDP2](../../docs/zh/features/fsdp2.md) | 是 | 分片粒度 `dit.block.layers.{*}`，`param_dtype: bf16`、`reduce_dtype: fp32` |262+| [FSDP2](../../docs/zh/features/parallel/fsdp2.md) | 是 | 分片粒度 `dit.block.layers.{*}`，`param_dtype: bf16`、`reduce_dtype: fp32` |
263| 全参数微调 | 是 | text-to-audio-video，单流打包序列 |263| 全参数微调 | 是 | text-to-audio-video，单流打包序列 |
264| 重计算 | 是 | `features.recompute` 配合 `recompute_plan` |264| 重计算 | 是 | `features.recompute` 配合 `recompute_plan` |
265| 序列打包 | 是 | dataset 的 `collate_fn` 沿 token 轴拼接，`cu_seqlens` 驱动 varlen attention |265| 序列打包 | 是 | dataset 的 `collate_fn` 沿 token 轴拼接，`cu_seqlens` 驱动 varlen attention |
266| NPU 融合算子 | 是 | attention、RoPE、RMSNorm，默认开启 |266| NPU 融合算子 | 是 | attention、RoPE、RMSNorm，默认开启 |
267| 权重加载与导出 | 是 | DCP 保存与续训、HF 权重在线加载、导出回上游 HF 格式 |267| 权重加载与导出 | 是 | DCP 保存与续训、HF 权重在线加载、导出回上游 HF 格式 |
268-| [Ulysses CP](../../docs/zh/features/unaligned_ulysses_cp.md) | 是 | 开启后 DP 同比减小，需用梯度累积补回 global batch |268+| [Ulysses CP](../../docs/zh/features/parallel/unaligned_ulysses_cp.md) | 是 | 开启后 DP 同比减小，需用梯度累积补回 global batch |
269-| [LoRA 微调](../../docs/zh/features/lora_finetune_fsdp2.md) | 否 | — |269+| [LoRA 微调](../../docs/zh/features/training_mode/lora_finetune_fsdp2.md) | 否 | — |
270| 张量并行、Ring Attention | 否 | 相关配置项保持为 `1` |270| 张量并行、Ring Attention | 否 | 相关配置项保持为 `1` |
271-| [Chunk Loss](../../docs/zh/features/chunkloss.md) | 否 | — |271+| [Chunk Loss](../../docs/zh/features/optimization/chunkloss.md) | 否 | — |
272-| [Async Activation Offload](../../docs/zh/features/async_activation_offload.md) | 是 | 作用于 `dit.block.layers.{*}`；8 卡 100 步开关对照 loss/grad norm 逐位一致，每步卸载约 838 MiB，吞吐下降约 3% |272+| [Async Activation Offload](../../docs/zh/features/memory/async_activation_offload.md) | 是 | 作用于 `dit.block.layers.{*}`；8 卡 100 步开关对照 loss/grad norm 逐位一致，每步卸载约 838 MiB，吞吐下降约 3% |
273 273 
274## 权重布局与转换274## 权重布局与转换
275 275 
Mexamples/mcore/qwen3_5/README.md+3-3
@@ -46,7 +46,7 @@ commit_id=fc91372
46 46 
47【模型开发时推荐使用配套的环境版本】47【模型开发时推荐使用配套的环境版本】
48 48 
49-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。49+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
50 50 
51<a id="jump1.2"></a>51<a id="jump1.2"></a>
52 52 
@@ -130,8 +130,8 @@ pip list | grep fla_npu
130 130 
131## 数据集准备及处理131## 数据集准备及处理
132 132 
133-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。133+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
134-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../../docs/zh/features/building_data_for_VLModel.md#mock-data)。134+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
135 135 
136## 微调136## 微调
137 137 
Mexamples/mimov2_5/README.md+1-1
@@ -44,7 +44,7 @@ commit_id=13b5e3f
44 44 
45【模型开发时推荐使用配套的环境版本】45【模型开发时推荐使用配套的环境版本】
46 46 
47-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。47+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/tree/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
48 48 
49<a id="jump1.2"></a>49<a id="jump1.2"></a>
50 50 
Mexamples/minimax_h3/README.md+2-3
@@ -14,10 +14,9 @@
14 - [配置文件](#配置文件)14 - [配置文件](#配置文件)
15 - [启动训练](#启动训练)15 - [启动训练](#启动训练)
16 - [正式训练配置](#正式训练配置)16 - [正式训练配置](#正式训练配置)
17-- [开发与测试](#开发与测试)
18- - [跨后端 BF16 反向精度注意事项](#跨后端-bf16-反向精度注意事项)
19- [环境变量声明](#环境变量声明)17- [环境变量声明](#环境变量声明)
20- [注意事项](#注意事项)18- [注意事项](#注意事项)
19+ - [GPU\NPU BF16 反向精度注意事项](#gpunpu-bf16-反向精度注意事项)
21 20 
22## 版本说明21## 版本说明
23 22 
@@ -47,7 +46,7 @@ Video VAE 和 Audio VAE 的在线训练。训练数据需要先通过 DiffSynth-
47 46 
48## 环境安装47## 环境安装
49 48 
50-请先按照 [MindSpeed-MM 安装指南](../../docs/zh/pytorch/install_guide.md) 安装匹配版本的 Ascend Driver、CANN、PyTorch 和 torch-npu。49+请先按照 [MindSpeed-MM 安装指南](../../docs/zh/guides/installation/install_guide.md) 安装匹配版本的 Ascend Driver、CANN、PyTorch 和 torch-npu。
51 50 
52```bash51```bash
53git clone https://gitcode.com/Ascend/MindSpeed-MM.git52git clone https://gitcode.com/Ascend/MindSpeed-MM.git
Mexamples/minimax_m3_vl/README.md+4-4
@@ -47,7 +47,7 @@ transformers_version=v5.12.0
47 47 
48【模型开发时推荐使用配套的环境版本】48【模型开发时推荐使用配套的环境版本】
49 49 
50-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。50+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
51 51 
52推荐使用 Python 3.10、PyTorch 2.7.1、torch_npu 2.7.1 和 Transformers 5.12.0。52推荐使用 Python 3.10、PyTorch 2.7.1、torch_npu 2.7.1 和 Transformers 5.12.0。
53 53 
@@ -133,7 +133,7 @@ training:
133 133 
134## 数据集准备及处理134## 数据集准备及处理
135 135 
136-- 使用真实数据集训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)。136+- 使用真实数据集训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)。
137- 图片和视频分别使用 `<image>` 和 `<video>` 占位符，并与 `images`、`videos` 字段一一对应；相对路径以 `dataset_dir` 为根目录解析。137- 图片和视频分别使用 `<image>` 和 `<video>` 占位符，并与 `images`、`videos` 字段一一对应；相对路径以 `dataset_dir` 为根目录解析。
138 138 
139## 微调139## 微调
@@ -184,8 +184,8 @@ parallel:
184【性能优化配置】184【性能优化配置】
185 185 
186- 重计算：通过 `features.recompute` 开启，作用范围由 `features.recompute_plan.apply_modules` 指定。186- 重计算：通过 `features.recompute` 开启，作用范围由 `features.recompute_plan.apply_modules` 指定。
187-- [Chunk Loss](../../docs/zh/features/chunkloss.md)：通过 `features.enable_chunk_loss` 开启，降低长序列 LM Head loss 的显存峰值。187+- [Chunk Loss](../../docs/zh/features/optimization/chunkloss.md)：通过 `features.enable_chunk_loss` 开启，降低长序列 LM Head loss 的显存峰值。
188-- [Activation Offload](../../docs/zh/features/async_activation_offload.md)：通过 `features.enable_activation_offload` 开启，将 checkpoint 激活异步卸载到 Host。188+- [Activation Offload](../../docs/zh/features/memory/async_activation_offload.md)：通过 `features.enable_activation_offload` 开启，将 checkpoint 激活异步卸载到 Host。
189- Op Replay：在非重入式重计算中缓存指定算子的前向输出，减少反向阶段的重复计算。189- Op Replay：在非重入式重计算中缓存指定算子的前向输出，减少反向阶段的重复计算。
190 190 
1918K 优化配置 `minimax_m3_vl_fsdp2_perf_8card.yaml` 只缓存 `npu.npu_fusion_attention.default`，并设置 `capacity_mb: 256`。不要直接在整个 `self_attn` scope 中加入 `aten.matmul.default`，因为 M3 Sparse Indexer 的 FP32 score 张量随序列长度平方增长，会引入较大的 Host/Device 传输开销。1918K 优化配置 `minimax_m3_vl_fsdp2_perf_8card.yaml` 只缓存 `npu.npu_fusion_attention.default`，并设置 `capacity_mb: 256`。不要直接在整个 `self_attn` scope 中加入 `aten.matmul.default`，因为 M3 Sparse Indexer 的 FP32 score 张量随序列长度平方增长，会引入较大的 Host/Device 传输开销。
Mexamples/moss_tts/README.md+1-1
@@ -49,7 +49,7 @@ commit_id=fd7dac7
49 49 
50【模型开发时推荐使用配套的环境版本】50【模型开发时推荐使用配套的环境版本】
51 51 
52-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。52+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
53 53 
54<a id="jump1.2"></a>54<a id="jump1.2"></a>
55 55 
Mexamples/qwen3_5/README.md+10-10
@@ -54,20 +54,20 @@ Latest: 2026.8.24: 为适配 CANN9.1.0 和 torch 2.10.0，将 Triton-Ascend
54 54 
55【模型开发时推荐使用配套的环境版本】55【模型开发时推荐使用配套的环境版本】
56 56 
57-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)，完成 CANN 相关配置（驱动、固件及 Toolkit 工具包）。57+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)，完成 CANN 相关配置（驱动、固件及 Toolkit 工具包）。
58 58 
59<a id="jump1.2"></a>59<a id="jump1.2"></a>
60 60 
61### 2. 环境搭建61### 2. 环境搭建
62 62 
63-拉取MindSpeed MM代码仓，并进入代码仓根目录(若需要使用低版本的python，可参考[安装指南](../../docs/zh/pytorch/install_guide.md)的拉取方法)：63+拉取MindSpeed MM代码仓，并进入代码仓根目录(若需要使用低版本的python，可参考[安装指南](../../docs/zh/guides/installation/install_guide.md)的拉取方法)：
64 64 
65```bash65```bash
66git clone https://gitcode.com/Ascend/MindSpeed-MM.git66git clone https://gitcode.com/Ascend/MindSpeed-MM.git
67cd MindSpeed-MM67cd MindSpeed-MM
68```68```
69 69 
70-若存在自由指定依赖等手动安装需求，可以参考[安装指南](../../docs/zh/pytorch/install_guide.md)中的手动安装流程（注：Qwen3.5不需要安装该流程中的Megatron-LM库）70+若存在自由指定依赖等手动安装需求，可以参考[安装指南](../../docs/zh/guides/installation/install_guide.md)中的手动安装流程（注：Qwen3.5不需要安装该流程中的Megatron-LM库）
71 71 
72执行如下指令一键安装：72执行如下指令一键安装：
73 73 
@@ -239,8 +239,8 @@ mm-convert Qwen35Converter dcp_to_hf \
239 239 
240## 数据集准备及处理240## 数据集准备及处理
241 241 
242-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。242+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
243-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。243+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
244 244 
245## 微调245## 微调
246 246 
@@ -298,14 +298,14 @@ mm-convert Qwen35Converter dcp_to_hf \
298- 重计算298- 重计算
299 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。299 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。
300 - 开启后可以节省显存占用300 - 开启后可以节省显存占用
301-- [chunkloss](../../docs/zh/features/chunkloss.md)301+- [chunkloss](../../docs/zh/features/optimization/chunkloss.md)
302 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭302 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭
303 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。303 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。
304 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用304 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用
305-- [async activation offload](../../docs/zh/features/async_activation_offload.md)305+- [async activation offload](../../docs/zh/features/memory/async_activation_offload.md)
306 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭306 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭
307 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。307 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。
308-- [chunkmbs](../../docs/zh/features/chunkmbs.md)308+- [chunkmbs](../../docs/zh/features/optimization/chunkmbs.md)
309 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭309 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭
310 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`310 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`
311 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。311 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。
@@ -385,7 +385,7 @@ NNODES: 一共几个节点
385 385 
386### 3. 启动微调386### 3. 启动微调
387 387 
388-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)388+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
389可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。389可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。
390 390 
391```shell391```shell
@@ -398,7 +398,7 @@ bash examples/qwen3_5/finetune_qwen3_5_xxB.sh
398 398 
399将 `training.lora.enable` 设为 `true`，并按需配置其余参数，使用与全量微调相同的启动脚本进行LoRA微调。399将 `training.lora.enable` 设为 `true`，并按需配置其余参数，使用与全量微调相同的启动脚本进行LoRA微调。
400 400 
401-更详细的 LoRA 配置与参数说明见 [LoRA 微调特性文档](../../docs/zh/features/lora_finetune_fsdp2.md)。401+更详细的 LoRA 配置与参数说明见 [LoRA 微调特性文档](../../docs/zh/features/training_mode/lora_finetune_fsdp2.md)。
402 402 
403【并行策略调整建议】403【并行策略调整建议】
404 404 
Mexamples/qwen3_6/README.md+10-10
@@ -55,20 +55,20 @@ Latest: 2026.9.16: 为适配 CANN9.1.0 和 torch 2.10.0，将 Triton-Ascend
55 55 
56【模型开发时推荐使用配套的环境版本】56【模型开发时推荐使用配套的环境版本】
57 57 
58-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)，完成 CANN 相关配置（驱动、固件及 Toolkit 工具包）。58+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)，完成 CANN 相关配置（驱动、固件及 Toolkit 工具包）。
59 59 
60<a id="jump1.2"></a>60<a id="jump1.2"></a>
61 61 
62### 2. 环境搭建62### 2. 环境搭建
63 63 
64-拉取MindSpeed MM代码仓，并进入代码仓根目录(若需要使用低版本的python，可参考[安装指南](../../docs/zh/pytorch/install_guide.md)的拉取方法)：64+拉取MindSpeed MM代码仓，并进入代码仓根目录(若需要使用低版本的python，可参考[安装指南](../../docs/zh/guides/installation/install_guide.md)的拉取方法)：
65 65 
66```bash66```bash
67git clone https://gitcode.com/Ascend/MindSpeed-MM.git67git clone https://gitcode.com/Ascend/MindSpeed-MM.git
68cd MindSpeed-MM68cd MindSpeed-MM
69```69```
70 70 
71-若存在自由指定依赖等手动安装需求，可以参考[安装指南](../../docs/zh/pytorch/install_guide.md)中的手动安装流程（注：Qwen3.6不需要安装该流程中的Megatron-LM库）71+若存在自由指定依赖等手动安装需求，可以参考[安装指南](../../docs/zh/guides/installation/install_guide.md)中的手动安装流程（注：Qwen3.6不需要安装该流程中的Megatron-LM库）
72 72 
73执行如下指令一键安装：73执行如下指令一键安装：
74 74 
@@ -240,8 +240,8 @@ mm-convert Qwen35Converter dcp_to_hf \
240 240 
241## 数据集准备及处理241## 数据集准备及处理
242 242 
243-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。243+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
244-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。244+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
245 245 
246### Agentical Trace（OpenAI 格式）数据集246### Agentical Trace（OpenAI 格式）数据集
247 247 
@@ -416,14 +416,14 @@ dataset:
416- 重计算416- 重计算
417 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。417 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。
418 - 开启后可以节省显存占用418 - 开启后可以节省显存占用
419-- [chunkloss](../../docs/zh/features/chunkloss.md)419+- [chunkloss](../../docs/zh/features/optimization/chunkloss.md)
420 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭420 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭
421 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。421 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。
422 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用422 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用
423-- [async activation offload](../../docs/zh/features/async_activation_offload.md)423+- [async activation offload](../../docs/zh/features/memory/async_activation_offload.md)
424 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭424 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭
425 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。425 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。
426-- [chunkmbs](../../docs/zh/features/chunkmbs.md)426+- [chunkmbs](../../docs/zh/features/optimization/chunkmbs.md)
427 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭427 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭
428 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`428 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`
429 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。429 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。
@@ -467,7 +467,7 @@ NNODES: 一共几个节点
467 467 
468### 3. 启动微调468### 3. 启动微调
469 469 
470-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)470+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
471可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。471可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。
472 472 
473```shell473```shell
@@ -480,7 +480,7 @@ bash examples/qwen3_6/finetune_qwen3_6_35B.sh
480 480 
481将 `training.lora.enable` 设为 `true`，并按需配置其余参数，使用与全量微调相同的启动脚本进行LoRA微调。481将 `training.lora.enable` 设为 `true`，并按需配置其余参数，使用与全量微调相同的启动脚本进行LoRA微调。
482 482 
483-更详细的 LoRA 配置与参数说明见 [LoRA 微调特性文档](../../docs/zh/features/lora_finetune_fsdp2.md)。483+更详细的 LoRA 配置与参数说明见 [LoRA 微调特性文档](../../docs/zh/features/training_mode/lora_finetune_fsdp2.md)。
484 484 
485【并行策略调整建议】485【并行策略调整建议】
486 486 
Mexamples/qwen3_8/README.md+7-7
@@ -53,7 +53,7 @@ git checkout v5.2.0
53- [CANN](https://www.hiascend.com/cann/download?versionId=767&ids=d803%2Ch0501%2Ch0601%2Ch0701)（推荐使用离线安装方式）53- [CANN](https://www.hiascend.com/cann/download?versionId=767&ids=d803%2Ch0501%2Ch0601%2Ch0701)（推荐使用离线安装方式）
54- [TorchNPU](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download?versionId=174&ids=89dda9ba9de741349efa03687a487678%2C96%2C109%2C1%2C6%2C177%2C)54- [TorchNPU](https://www.hiascend.com/developer/software/ai-frameworks/pytorch/download?versionId=174&ids=89dda9ba9de741349efa03687a487678%2C96%2C109%2C1%2C6%2C177%2C)
55 55 
56-仍有疑问可以参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)56+仍有疑问可以参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)
57 57 
58<a id="jump1.2"></a>58<a id="jump1.2"></a>
59 59 
@@ -215,8 +215,8 @@ mm-convert Qwen35Converter dcp_to_hf \
215 215 
216## 数据集准备及处理216## 数据集准备及处理
217 217 
218-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。218+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
219-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。219+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
220 220 
221## 微调221## 微调
222 222 
@@ -266,14 +266,14 @@ mm-convert Qwen35Converter dcp_to_hf \
266- 重计算266- 重计算
267 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。267 - 在`features.recompute`配置，`true`表示开启，`false`表示关闭，默认开启。
268 - 开启后可以节省显存占用268 - 开启后可以节省显存占用
269-- [chunkloss](../../docs/zh/features/chunkloss.md)269+- [chunkloss](../../docs/zh/features/optimization/chunkloss.md)
270 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭270 - 在`features.enable_chunk_loss`配置，`true`表示开启，`false`表示关闭
271 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。271 - `features.chunkloss_plan.chunk_size`表示计算loss的时候在seq维度切分成大小为`chunk_size`的小块进行计算。
272 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用272 - 开启后可以大幅降低loss计算时的显存尖刺，节省整体显存占用
273-- [async activation offload](../../docs/zh/features/async_activation_offload.md)273+- [async activation offload](../../docs/zh/features/memory/async_activation_offload.md)
274 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭274 - 在`features.enable_activation_offload`配置，`true`表示开启，`false`表示关闭
275 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。275 - 开启后可以异步将重计算入口的激活值offload至host侧，在开启了重计算的场景下可以进一步节省显存。
276-- [chunkmbs](../../docs/zh/features/chunkmbs.md)276+- [chunkmbs](../../docs/zh/features/optimization/chunkmbs.md)
277 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭277 - 在`features.enable_chunk_mbs`配置，`true`表示开启，`false`表示关闭
278 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`278 - `features.chunkmbs_plan.chunk_mbs`表示切分以后单次计算的`micro_batch_size`
279 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。279 - 开启该特性时需要同时使能重计算和async activation offload特性，可以增加FSDP2单次unshard对应的计算密度，提高整网吞吐。
@@ -317,7 +317,7 @@ NNODES: 一共几个节点
317 317 
318### 3. 启动微调318### 3. 启动微调
319 319 
320-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)320+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
321可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。321可在`xxx_config.yaml`的`model`参数中配置上述文档中的`loss_type`。
322 322 
323```shell323```shell
Mexamples/qwen3_asr/README.md+1-1
@@ -53,7 +53,7 @@
53 53 
54【模型开发时推荐使用配套的环境版本】54【模型开发时推荐使用配套的环境版本】
55 55 
56-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。56+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
57 57 
58<a id="jump1.2"></a>58<a id="jump1.2"></a>
59 59 
Mexamples/qwen3omni/README.md+3-3
@@ -49,7 +49,7 @@ commit_id=7a833d1
49 49 
50【模型开发时推荐使用配套的环境版本】50【模型开发时推荐使用配套的环境版本】
51 51 
52-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。52+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
53 53 
54<a id="jump1.2"></a>54<a id="jump1.2"></a>
55 55 
@@ -365,7 +365,7 @@ CP=4
365使用activation_offload可以将重计算过程中产生的checkpoint点的激活值移动到host，反向异步从host传输到device，降低device激活显存占用，配置方式为在`model.json`中将`activation_offload`字段设置为true。365使用activation_offload可以将重计算过程中产生的checkpoint点的激活值移动到host，反向异步从host传输到device，降低device激活显存占用，配置方式为在`model.json`中将`activation_offload`字段设置为true。
366 366 
367【chunkloss 配置】367【chunkloss 配置】
368-参考[chunk loss文档](../../docs/zh/features/chunkloss.md)368+参考[chunk loss文档](../../docs/zh/features/optimization/chunkloss.md)
369 369 
370【模型保存加载及日志信息配置】370【模型保存加载及日志信息配置】
371 371 
@@ -444,7 +444,7 @@ WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))
444### 3. 启动微调444### 3. 启动微调
445 445 
446以Qwen3-Omni为例，启动微调训练任务。446以Qwen3-Omni为例，启动微调训练任务。
447-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)447+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
448 448 
449```shell449```shell
450cd MindSpeed-MM/450cd MindSpeed-MM/
Mexamples/qwen3omni/README_v1.md+2-2
@@ -48,7 +48,7 @@ commit_id=7a833d1
48 48 
49【模型开发时推荐使用配套的环境版本】49【模型开发时推荐使用配套的环境版本】
50 50 
51-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。51+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
52 52 
53<a id="jump1.2"></a>53<a id="jump1.2"></a>
54 54 
@@ -267,7 +267,7 @@ data->dataset_param->basic_parameters->dataset
267 267 
268【chunkloss 配置】268【chunkloss 配置】
269 269 
270-参考[chunk loss文档](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/features/chunkloss.md)270+参考[chunk loss文档](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/features/optimization/chunkloss.md)
271将`xxx_config_v1.yaml`中`enable_chunk_loss`字段设置为true，chunk_size表示每个子序列的最大长度（即每个 chunk 所包含的 token 数量）271将`xxx_config_v1.yaml`中`enable_chunk_loss`字段设置为true，chunk_size表示每个子序列的最大长度（即每个 chunk 所包含的 token 数量）
272 272 
273```yaml273```yaml
Mexamples/qwen3tts/README.md+1-1
@@ -47,7 +47,7 @@ commit_id=022e286
47 47 
48【模型开发时推荐使用配套的环境版本】48【模型开发时推荐使用配套的环境版本】
49 49 
50-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。50+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
51 51 
52<a id="jump1.2"></a>52<a id="jump1.2"></a>
53 53 
Mexamples/qwen3vl/README.md+8-8
@@ -46,7 +46,7 @@ commit_id=c0dbe09
46 46 
47【模型开发时推荐使用配套的环境版本】47【模型开发时推荐使用配套的环境版本】
48 48 
49-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。49+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
50 50 
51<a id="jump1.2"></a>51<a id="jump1.2"></a>
52 52 
@@ -104,8 +104,8 @@ mm-convert Qwen3VLConverter hf_to_dcp \
104 104 
105## 数据集准备及处理105## 数据集准备及处理
106 106 
107-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。107+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
108-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。108+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
109 109 
110## 微调110## 微调
111 111 
@@ -222,11 +222,11 @@ gpt_args:
222 222 
223【FSDP2 offload_to_cpu配置】223【FSDP2 offload_to_cpu配置】
224在fsdp2_config.yaml配置offload_to_cpu为True, 可以将参数，梯度和优化器状态卸载到CPU内存，进一步降低显存。但同时训练速度相对会变慢，在显存足够的情况下不建议开启。224在fsdp2_config.yaml配置offload_to_cpu为True, 可以将参数，梯度和优化器状态卸载到CPU内存，进一步降低显存。但同时训练速度相对会变慢，在显存足够的情况下不建议开启。
225-功能描述请详见：docs/zh/features/fsdp2.md。225+功能描述请详见：docs/zh/features/parallel/fsdp2.md。
226开启该功能时，同时需要在`qwen3vl_full_sft_xxB.yaml`文件中`gpt_args`配置项里配置`distributed_backend: npu:hccl,cpu:gloo`，以开启双通信后端。226开启该功能时，同时需要在`qwen3vl_full_sft_xxB.yaml`文件中`gpt_args`配置项里配置`distributed_backend: npu:hccl,cpu:gloo`，以开启双通信后端。
227 227 
228【chunkloss 配置】228【chunkloss 配置】
229-参考[chunk loss文档](../../docs/zh/features/chunkloss.md)229+参考[chunk loss文档](../../docs/zh/features/optimization/chunkloss.md)
230 230 
231【负载均衡损失配置】231【负载均衡损失配置】
232支持自定义moe模型中专家负载均衡的aux_loss的系数，在`qwen3vl_full_sft_xxB.yaml`中的`router_aux_loss_coef`，默认为0.0，即不计算该损失。232支持自定义moe模型中专家负载均衡的aux_loss的系数，在`qwen3vl_full_sft_xxB.yaml`中的`router_aux_loss_coef`，默认为0.0，即不计算该损失。
@@ -273,7 +273,7 @@ WORLD_SIZE=$(($NPUS_PER_NODE * $NNODES))
273 273 
274【LoRA微调（可选）】274【LoRA微调（可选）】
275 275 
276-LoRA为框架通用能力，当前已支持30B模型的语言模块LoRA微调，参数介绍请参考[LoRA特性文档](../../docs/zh/features/lora_finetune.md)。276+LoRA为框架通用能力，当前已支持30B模型的语言模块LoRA微调，参数介绍请参考[LoRA特性文档](../../docs/zh/features/training_mode/lora_finetune.md)。
277 277 
278LoRA微调场景下，需要先对原始权重完成以下权重转换278LoRA微调场景下，需要先对原始权重完成以下权重转换
279 279 
@@ -326,7 +326,7 @@ bash examples/qwen3vl/finetune_lora_qwen3vl_30B.sh
326### 3. 启动微调326### 3. 启动微调
327 327 
328以Qwen3VL-xxB为例，启动微调训练任务。328以Qwen3VL-xxB为例，启动微调训练任务。
329-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)329+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)
330通过修改`qwen3vl_full_sft_xxB.yaml`文件中的`loss_type`字段可以在不同的loss计算方式中切换。330通过修改`qwen3vl_full_sft_xxB.yaml`文件中的`loss_type`字段可以在不同的loss计算方式中切换。
331 331 
332```shell332```shell
@@ -335,7 +335,7 @@ bash examples/qwen3vl/finetune_qwen3vl_xxB.sh
335 335 
336**优化特性：**336**优化特性：**
337 337 
338-- ChunkLoss：可以参考文档[ChunkLoss](../../docs/zh/features/chunkloss.md)开启该特性优化长序列时的显存占用。338+- ChunkLoss：可以参考文档[ChunkLoss](../../docs/zh/features/optimization/chunkloss.md)开启该特性优化长序列时的显存占用。
339 339 
340---340---
341 341 
Mexamples/qwen3vl/README_v1.md+4-4
@@ -45,7 +45,7 @@ commit_id=c0dbe09
45 45 
46【模型开发时推荐使用配套的环境版本】46【模型开发时推荐使用配套的环境版本】
47 47 
48-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。48+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
49 49 
50<a id="jump1.2"></a>50<a id="jump1.2"></a>
51 51 
@@ -129,8 +129,8 @@ mm-convert GenericDCPConverter hf_to_dcp \
129 129 
130## 数据集准备及处理130## 数据集准备及处理
131 131 
132-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。132+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
133-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。133+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
134 134 
135## 微调135## 微调
136 136 
@@ -198,7 +198,7 @@ NNODES: 一共几个节点
198 198 
199### 3. 启动微调199### 3. 启动微调
200 200 
201-loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，根据`FSDP2后端`选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/vlm_model_loss_calculate_type.md)，在`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`配置`loss_type`参数，可以设置成default（默认）、per_sample_loss、per_token_loss这3个值。201+loss计算方式差异会对训练效果造成不同的影响，在启动训练任务之前，请查看关于loss计算的文档，根据`FSDP2后端`选择合适的loss计算方式[vlm_model_loss_calculate_type.md](../../docs/zh/features/optimization/vlm_model_loss_calculate_type.md)，在`examples/qwen3vl/qwen3vl_30B_config_v1.yaml`配置`loss_type`参数，可以设置成default（默认）、per_sample_loss、per_token_loss这3个值。
202 202 
203在代码仓根目录（MindSpeed-MM）下执行以下命令启动微调任务：203在代码仓根目录（MindSpeed-MM）下执行以下命令启动微调任务：
204 204 
Mexamples/self_forcing/README.md+1-1
@@ -36,7 +36,7 @@
36 36 
37【模型开发时推荐使用配套的环境版本】37【模型开发时推荐使用配套的环境版本】
38 38 
39-昇腾基础软件安装请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)39+昇腾基础软件安装请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)
40 40 
411. 在工作目录执行下列命令411. 在工作目录执行下列命令
42 42 
Mexamples/step3_vl/README.md+3-3
@@ -42,7 +42,7 @@ url=https://huggingface.co/stepfun-ai/Step3-VL-10B
42 42 
43【模型开发时推荐使用配套的环境版本】43【模型开发时推荐使用配套的环境版本】
44 44 
45-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)，完成昇腾软件安装。45+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)，完成昇腾软件安装。
46 46 
47### 2. 环境搭建47### 2. 环境搭建
48 48 
@@ -95,8 +95,8 @@ model-*.safetensors
95 95 
96## 数据集准备及处理96## 数据集准备及处理
97 97 
98-- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。98+- 使用**真实数据集**训练：参考[针对VL模型的数据构造 · 使用真实数据集](../../docs/zh/features/data/building_data_for_VLModel.md#real-data)（下载COCO2017 → 下载LLaVA-Instruct-150K标注 → 运行转换脚本生成`mllm_format_llava_instruct_data.json`）。
99-- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/building_data_for_VLModel.md#mock-data)。99+- 使用**虚构数据**做功能/性能测试：参考[针对VL模型的数据构造 · 使用虚构数据](../../docs/zh/features/data/building_data_for_VLModel.md#mock-data)。
100 100 
101## 微调101## 微调
102 102 
Mexamples/vace/README.md+2-2
@@ -68,7 +68,7 @@ commit_id=8332ece
68 68 
69【模型开发时推荐使用配套的环境版本】69【模型开发时推荐使用配套的环境版本】
70 70 
71-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)71+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)
72 72 
73### 仓库拉取73### 仓库拉取
74 74 
@@ -83,7 +83,7 @@ cd ../MindSpeed-MM
83 83 
84### 环境搭建84### 环境搭建
85 85 
86-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)创建Python环境并安装 torch、TorchNPU。86+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)创建Python环境并安装 torch、TorchNPU。
87 87 
88```bash88```bash
89conda activate test89conda activate test
Mexamples/wan2.1/README.md+6-6
@@ -77,7 +77,7 @@ commit_id=f8d4a1e
77 77 
78【模型开发时推荐使用配套的环境版本】78【模型开发时推荐使用配套的环境版本】
79 79 
80-请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/pytorch/install_guide.md)80+请参考[安装指南](https://gitcode.com/Ascend/MindSpeed-MM/blob/master/docs/zh/guides/installation/install_guide.md)
81 81 
82### 仓库拉取82### 仓库拉取
83 83 
@@ -92,7 +92,7 @@ cd ../MindSpeed-MM
92 92 
93### 环境搭建93### 环境搭建
94 94 
95-请参考[安装指南](../../docs/zh/pytorch/install_guide.md)创建Python环境并安装 torch、TorchNPU。95+请参考[安装指南](../../docs/zh/guides/installation/install_guide.md)创建Python环境并安装 torch、TorchNPU。
96 96 
97```bash97```bash
98conda activate test98conda activate test
@@ -317,11 +317,11 @@ bash examples/wan2.1/feature_extract/feature_extraction.sh
317 317 
318 - 默认使能方式为Ulysses序列并行。318 - 默认使能方式为Ulysses序列并行。
319 319 
320- - DiT-RingAttention：DiT RingAttention序列并行请[参考文档](../../docs/zh/features/dit_ring_attention.md)320+ - DiT-RingAttention：DiT RingAttention序列并行请[参考文档](../../docs/zh/features/parallel/dit_ring_attention.md)
321 321 
322- - DiT-USP: DiT USP混合序列并行（Ulysses + RingAttention）请[参考文档](../../docs/zh/features/dit_usp.md)322+ - DiT-USP: DiT USP混合序列并行（Ulysses + RingAttention）请[参考文档](../../docs/zh/features/parallel/dit_usp.md)
323 323 
324- - FPDT(Fully Pipelined Distributed Transformer): Ulysses Offload 并行请[参考文档](../../docs/zh/features/fpdt.md)324+ - FPDT(Fully Pipelined Distributed Transformer): Ulysses Offload 并行请[参考文档](../../docs/zh/features/optimization/fpdt.md)
325 325 
326 - 注：wan2.1使用full attention，对应general，即`--attention-mask-type general`。326 - 注：wan2.1使用full attention，对应general，即`--attention-mask-type general`。
327 327 
@@ -461,7 +461,7 @@ mm-convert WanConverter merge_lora_to_base \
461 461 
462### 环境准备462### 环境准备
463 463 
464-1. 参考docs/zh/features/vbench-evaluate.md中的环境安装指导完成vbench及依赖三方件的安装464+1. 参考docs/zh/tools/vbench-evaluate.md中的环境安装指导完成vbench及依赖三方件的安装
4652. 将VBench的 [t2v json](https://github.com/Vchitect/VBench/blob/master/vbench/VBench_full_info.json) 下载到MM代码根路径"./vbench/VBench_full_info.json"4652. 将VBench的 [t2v json](https://github.com/Vchitect/VBench/blob/master/vbench/VBench_full_info.json) 下载到MM代码根路径"./vbench/VBench_full_info.json"
466 466 
467### 生成视频样本467### 生成视频样本
Mexamples/wan2.2/README.md+3-3