Update README: torchrun usage guide, verified training results

- Rewrite known issues as usage notes with torchrun/PET_* explanation
- Add trainer.command to TrainJob options table
- Update checklist with 2-node 16-GPU training verification

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
selee 2026-02-10 16:38:32 +09:00
parent 7cd7c1af7e
commit 965b87ced3
1 changed files with 21 additions and 6 deletions

View File

@ -213,6 +213,7 @@ Volcano 스케줄러를 Kubeflow TrainJob과 연동하여 gang scheduling, queue
|------|------|
| `runtimeRef.name` | 사용할 ClusterTrainingRuntime 이름 |
| `trainer.image` | 학습 컨테이너 이미지 |
| `trainer.command` | 학습 스크립트 실행 명령 (torchrun 사용 — 아래 주의사항 참고) |
| `trainer.numNodes` | 학습에 사용할 노드 수 (Runtime 기본값 override) |
| `trainer.numProcPerNode` | 노드당 프로세스 수 (`"auto"`면 GPU 수만큼 자동) |
| `trainer.resourcesPerNode` | 노드당 리소스 (Runtime 기본값 override) |
@ -271,18 +272,32 @@ kubectl get pods -l trainer.kubeflow.org/trainjob-name=<trainjob-name> \
- [x] Kubeflow Trainer CRD 생성됨 (trainjobs, trainingruntimes 등)
- [x] ClusterTrainingRuntime 목록 확인 (deepspeed-distributed, torch-distributed 등 6개)
- [x] Training Queue 생성됨
- [x] 테스트 TrainJob 제출 시 PodGroup 자동 생성 확인
- [x] 테스트 TrainJob Pod가 Volcano 스케줄러로 스케줄링됨
- [x] 테스트 TrainJob 제출 시 PodGroup 자동 생성 확인 (minMember=2, Running)
- [x] 테스트 TrainJob Pod가 서로 다른 GPU 노드에 배치됨
- [x] 2노드 16GPU 분산학습 정상 동작 확인 (VGG11 + CIFAR10 + NCCL)
---
## 알려진 이슈
## 주의사항
### Runtime에 `command`를 설정하면 torchrun이 주입되지 않음
### torchrun 사용 및 Runtime/TrainJob command 분리
Kubeflow Trainer torch runtime은 컨테이너에 `command`가 없을 때 자동으로 torchrun을 주입하여 `RANK`, `LOCAL_RANK`, `WORLD_SIZE` 등 환경변수를 설정합니다. Runtime에서 `command`를 직접 지정하면 torchrun 주입이 우회됩니다.
Kubeflow Trainer torch runtime은 Runtime에 `command`가 없을 때 `PET_*` 환경변수(NNODES, NPROC_PER_NODE, MASTER_ADDR, MASTER_PORT, NODE_RANK)를 자동 주입합니다. 이를 위해 replicatedJob에 `trainer.kubeflow.org/trainjob-ancestor-step: trainer` 라벨이 필수입니다.
따라서 **Runtime에는 `command`를 넣지 않고**, TrainJob의 `trainer.command`에서 학습 스크립트를 지정해야 합니다.
학습 스크립트 실행 구조:
- **Runtime**: `command` 없음 — Trainer controller가 `PET_*` 환경변수를 주입
- **TrainJob**: `trainer.command``torchrun`으로 스크립트 지정 — torchrun이 `PET_*` 환경변수를 읽어 분산 학습 설정
```yaml
# TrainJob 예시
spec:
trainer:
command:
- torchrun
- /workspace/scripts/train_nccl.py
```
> `python`으로 직접 실행하면 `PET_*` 환경변수가 무시되어 `RANK`, `WORLD_SIZE` 등이 설정되지 않습니다.
### JAX ClusterTrainingRuntime 미지원