feat: incorporate multi-device training scripts and README

README.md

@@ -11,6 +11,7 @@
 ```bash
 docker run -it --rm \
   --gpus all \
+  --network=host \
   --ipc=host \
   --shm-size=64g \
   -v /apps/yi:/apps/yi \
@@ -23,6 +24,8 @@ docker run -it --rm \
 
 说明：拉取该镜像需要先登录对应的私有 Docker Registry，相关 credentials 需自行准备。
 
+多机多卡训练时建议每台机器都用同名镜像和同名容器启动，并保持容器内代码、数据、checkpoint 路径一致。`--network=host` 用于避免 Docker bridge/NAT 影响 `torchrun` rendezvous 和 NCCL 跨机通信。
+
 ### 0.2 Megatron-LM submodule
 
 `Megatron-LM` 作为 git submodule 放在仓库根目录，用于实际的模型训练与推理。
@@ -162,6 +165,100 @@ python scripts/convert_phase_to_megatron.py \
 2. 训练的超参数如何设置
 3. 模型结构如何定义
 
+### 4.3 多机 32 卡训练速查
+
+完整说明见：
+
+- `scripts/kaiyuan2b-training/MULTINODE_TRAINING.md`
+
+当前多机训练目标是 g0033-g0036 四台机器，每台 8 张 H200，总计 32 张 GPU。脚本仍使用 Megatron-LM + `torchrun`，默认并行方式是数据并行：
+
+```bash
+--tensor-model-parallel-size 1
+--pipeline-model-parallel-size 1
+```
+
+四机训练时，`torchrun` 的核心参数是：
+
+```text
+--nproc_per_node 8
+--nnodes 4
+--node_rank 0/1/2/3
+--master_addr <g0033 address>
+--master_port 6000
+```
+
+`training_smoke_qwen3_1p7b.sh` 和 `training_smoke_gpt2.sh` 已支持通过环境变量覆盖这些参数：
+
+```bash
+NPROC_PER_NODE=8
+NNODES=4
+NODE_RANK=0
+MASTER_ADDR=10.20.32.33
+MASTER_PORT=6000
+```
+
+从 g0033 编排四机训练时使用：
+
+```bash
+cd /ssd1/yi/pretrain_kaiyuan2b/scripts/kaiyuan2b-training
+
+CONTAINER_NAME=megatron-ngc25-training \
+MASTER_ADDR=10.20.32.33 \
+NCCL_DEBUG=INFO \
+NCCL_SOCKET_IFNAME=eth00,eth01,eth02,eth03,eth04,eth05,eth06,eth07 \
+GLOO_SOCKET_IFNAME=bond1.1032 \
+bash start_multinode_training.sh gpt_smoke smoke smoke_32gpu
+```
+
+停止四机任务：
+
+```bash
+CONTAINER_NAME=megatron-ngc25-training \
+bash stop_multinode_training.sh smoke_32gpu
+```
+
+如果不使用 Docker 容器执行训练，可以不设置 `CONTAINER_NAME`。设置后，脚本会在每台机器上通过 `docker exec <CONTAINER_NAME>` 进入容器启动训练。
+
+四台机器上的容器建议这样启动，路径按实际部署调整：
+
+```bash
+docker run -dit \
+  --gpus all \
+  --network=host \
+  --ipc=host \
+  --shm-size=64g \
+  -v /ssd1/yi:/ssd1/yi \
+  -w /ssd1/yi/pretrain_kaiyuan2b \
+  --name megatron-ngc25-training \
+  base-mirror.tencentcloudcr.com/mode-optimization/megatron-env:ngc25.10 \
+  bash
+```
+
+多机训练前需要确认：
+
+- 四台机器都能访问同一套代码、tokenizer、训练数据路径。
+- 四台机器都已导入同一个 Docker image。
+- 容器网络模式是 `host`。
+- g0033 能通过 ssh 访问 g0034-g0036。
+- `MASTER_ADDR:MASTER_PORT` 能从其他节点访问。
+- NCCL 使用正确网卡，例如 `eth00-eth07`。
+
+ZeRO/分布式优化器通过 `ZERO_STAGE` 控制：
+
+```bash
+ZERO_STAGE=0  # 默认，不启用 distributed optimizer
+ZERO_STAGE=1  # --use-distributed-optimizer --data-parallel-sharding-strategy optim
+ZERO_STAGE=2  # --use-distributed-optimizer --data-parallel-sharding-strategy optim_grads
+```
+
+建议验证顺序：
+
+1. 单机 `gpt_smoke`
+2. 四机 `gpt_smoke`
+3. 四机 `qwen3_1p7b` + `ZERO_STAGE=0`
+4. 对比 `ZERO_STAGE=1/2` 的吞吐和显存
+
 ## 5. 模型说明
 
 ### 5.1 `gpt_smoke`