<p align="center">
<img src="https://raw.githubusercontent.com/whitecircle/halo/HEAD/logo.png" height="100" alt="Halo logo: a white ring on black">
<h3 align="center">Halo</h3>
</p>
<p align="center">
모두를 위한 프론티어 연구소 훈련 (Frontier-Lab Training for Everyone)
</p>
<p align="center">
<a href="https://whitecircle.com/research/halo"><strong >블로그 게시물</strong></a> ·
<a href="https://whitecircle.com/halo/docs"><strong >문서(Docs)</strong></a> ·
<a href="examples/"><strong >예제(Examples)</strong></a> ·
<a href="https://whitecircle.com/halo/docs/performance"><strong >벤치마크(Benchmarks)</strong></a>
</p>
<br/>
Halo란 무엇인가 (What is Halo)
Halo는 [White Circle]에서 구축한 오픈 소스 프레임워크로, 대규모 언어 및 멀티모달 모델을 훈련하기 위해 사용됩니다. 이 프레임워크는 사전 학습(pre-training), SFT, 선호도 최적화(preference optimization), 완전 비동기 다중 턴 RL(multi-turn RL) 및 기타 기능을 지원합니다.
동일한 코드베이스는 하나의 GPU 또는 여러 노드에 걸쳐 실행될 수 있으며, EP, CP, TP, ETP, PP, FSDP2, 융합 커널(fused kernels), BF16 학습, 분산 롤아웃을 지원합니다.
Halo는 Hugging Face 모델을 직접 훈련합니다. 체크포인트는 여전히 from_pretrained로 로드되며, MoE 계열이 추가하는 EP 레이어는 GPT-OSS를 제외한 모든 계열에서 가족당 90줄 미만입니다 (GPT-OSS의 경우 168줄) (모델 통합 비용).
8× B300 환경에서, Halo 1.2.0은 packed 64k 및 128k 행에 대해 Qwen3.6-35B-A3B를 Megatron Bridge의 1.10–1.12배, TRL 1.17.1의 1.47배, NeMo AutoModel 0.7.0의 1.9–2.0배로 훈련했으며, Qwen3.5-122B-A10B를 TRL 대비 1.50배, NeMo 대비 1.7–1.9배로 훈련했습니다. 이는 64k 환경에서 밀집된(dense) Qwen3.5-9B에 대해 조정된 Megatron보다 11.5% 낮은 수치입니다 (벤치마크). 또한, Halo 1.1.0과 비교한 12가지 형태의 벤치마크에서는 1.11–2.07배 더 빠르게 작동합니다.
사전 및 사후 학습(Pre- & Post-Training) · EP / CP / TP / ETP / PP ·
다중 노드(Multi-Node) · 검증 가능하고 다중 턴 RL(Verifiable & Multi-Turn RL) · FA4 + Liger + Grouped GEMM · 완전 BF16
</br>
Halo를 사용하는 이유 (Why Halo)
-
Halo는 Hugging Face 모델을 직접 훈련합니다. 트레이너가 Hugging Face 또는 TRL 트레이너를 상속받으며, 체크포인트는 표준 SafeTensors로 유지되고, from_pretrained가 계속 작동합니다.
-
기존 모델에 병렬화가 추가되었습니다. EP는 MoE 블록을 감싸고(wraps), CP는 어텐션(attention)을 감싸며, TP/ETP는 가중치를 제자리에 분할합니다(shard weights in place). 모델의 별도의 분산 구현은 없습니다.
-
분산 스택은 PyTorch를 기반으로 구축되었습니다. FSDP2, DTensor, 그리고 DeviceMesh가 기본적인 요소를 제공하며, DeepEP는 전문가 병렬화(Expert Parallelism)의 모든-대-모든 통신(all-to-all communication)을 처리합니다.
-
각 병렬화 축은 자체 설정을 가집니다. EP, CP, TP, ETP, PP는 각각 별도로 구성됩니다. EP는 CP, TP 또는 ETP와 결합할 수 있으며, PP는 EP 또는 ETP와 결합할 수 있고, 그 외의 조합은 설정 시점에 거부됩니다.
-
훈련 방법들은 동일한 인프라를 공유합니다. 사전 훈련(Pre-training), SFT, 선호도 최적화(preference optimization), 증류(distillation), 그리고 RL은 동일한 병렬화 및 체크포인팅 코드를 사용하므로, 새로운 방법이 자체 분산 구현을 할 필요가 없습니다.
-
SFT를 통해 릴리스의 MTP 헤드를 훈련할 수 있습니다. 추측 디코딩(speculative decoding)을 위해 탑재되는 다중 토큰 예측 헤드(multi-token-prediction head)는 미세 조정(fine-tune)과 함께 또는 고정된 트렁크 위에서 훈련됩니다 (MTP heads).
-
성능 최적화가 통합되었습니다. Halo는 DeepEP V2, FlashAttention 4, Liger, Grouped GEMM, 패딩 없는(padding-free) 및 트리 패킹(tree packing), AdamWBF16 등을 포함하며, Blackwell, Hopper 및 구형 GPU를 위한 폴백 기능을 제공합니다.
-
RL은 비동기적이며, Transformers ↔ vLLM/SGLang 간의 명확한 분리가 이루어졌습니다. 다중 턴 환경 롤아웃(Multi-turn environment rollouts)은 vLLM 또는 SGLang 서버를 대상으로 Ray 액터로 실행되며, 트레이너는 네이티브 NCCL을 통해 업데이트된 가중치를 해당 서버들에 푸시합니다. 훈련 측면은 Megatron 백엔드나 veRL 의존성 없이 순수한 Transformers 형태를 유지합니다. Async GRPO with Environments를 참조하십시오.
</br>
최신 업데이트
<!-- 가장 최신 순서로 표시됩니다. 이 피드와 GitHub Releases가 Halo의 변경 로그입니다. -->
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
-
2026-11-07 — Halo 1.3.0rc1. 대규모 환경에서 더 빠른 강화학습 (RL)을 위한 릴리스 후보 버전입니다. 두 개의 8× B300 노드에서 Qwen3.5-35B-A3B를 사용한 동기식 GRPO(Generalized Reinforcement Policy Optimization)로, Miles v0.1.3의 0.176 대비 1k 응답 토큰당 스텝 시간이 0.137초입니다 (GRPO against Miles).
- 더 빠른 GRPO: 행(rows)이 토큰 예산 마이크로 배치에 패킹되며, 중요도 가중치(importance weights)는 손실 순전파(loss forward)에서 얻을 수 있고, 가중치 동기화(weight sync)는 서버 전체 그룹에 걸쳐 실행될 수 있습니다.
- RL의 새로운 기능: SGLang에서의 점수 중심화(score centering), Qwen3.5/3.6 MoE를 위한 FP8 가중치 롤아웃(rollouts), SGLang으로의 어댑터 전용 동기화, 그리고 GRPO 하에서의 GLM-5.3-Flash가 추가되었습니다.
- 확장성 (Scale): 여러 라이터에 걸쳐 스트라이프된(striped) 수집된 EP 저장소, 모델 로드 없이 가능한 어댑터 병합(adapter merges), 그리고 실행 중 몇 시간 후에 실패하던 설정을 위한 시작 검사 기능이 추가되었습니다.
-
2026-11-04 — Halo 1.2.0. 학습 단계가 기존의 모든 12가지 모양(shapes) 벤치마크 대비 1.11배에서 2.07배 빨라졌으며, GLM-5.3-Flash는 두 개의 새로운 커널을 통해 LoRA 처리량을 두 배 이상 증가시켰습니다. Halo는 또한 파이프라인 병렬성(pipeline parallelism)과 세 가지 모델 패밀리(benchmarks)를 추가로 확보했습니다.
- GLM-5.3-Flash: 새로운 어텐션(attention) 및 하이퍼 연결(hyper-connection) 커널이 추가되었습니다. EP8에서의 LoRA는 동일한 최대 메모리 사용량으로 이전보다 2.2–2.7배 빠르며, 두 대의 8-GPU 머신에서 수행하는 전체 파인튜닝은 최대 2.3배 빨라졌습니다.
- 파이프라인 병렬성 (Pipeline parallelism): SFT(Supervised Fine-Tuning), 선호도(preference), 오프라인 GRPO, 보상(reward), 분류 학습에 적용 가능하며, 각 단계 내부에 EP 또는 ETP가 포함됩니다 (docs).
- 새로운 모델: NVIDIA Nemotron 3.5 (Super VL 및 Lightning), Qwen3-Next, 그리고 실험적인 Qwen3.8-Flash-Next가 추가되어 총 열여덟 개의 MoE 패밀리를 지원합니다.
- SFT 기능: 공유 접두사(shared prefix)를 한 번 저장하는 트리 패킹(tree packing)과 MTP 헤드 훈련이 추가되었습니다.
- 업그레이드 참고 사항: 임포트 패키지는 이제
halo이며, 사용된 라이브러리는 transformers 5.20, TRL 1.14, vLLM 0.32, SGLang 0.5.22입니다. PaliGemma의 SFT 및 증류(distillation)는 이제 1.1.0에서 누락되었던 인과 마스크(causal mask)를 사용합니다.
-
2026-10-11 — Halo 1.1.0. 더 빠른 MoE(Mixture of Experts) 학습, 정확한 재개 기능, 그리고 더욱 안정적인 비동기 RL(Reinforcement Learning). 슬라이딩 윈도우 레이어에 통합된 MoE 커널과 FlexAttention을 사용하여 Gemma 4 26B-A4B는 두 개의 GPU에서 1.0.0 버전에 비해 1.67배 빨라졌으며, 원자적(atomic-free) 전문가 순열 기능은 EP8에서의 gpt-oss 속도를 최대 27% 향상시켰습니다. 체크포인트 및 재개 문제가 이제 조용히 지나가는 대신 실행을 중단시키며, 오프라인 GRPO는 컨텍스트 병렬성을 확보했습니다.
-
2026-08-20 — Halo 1.0.0. 첫 공개 릴리스: 네이티브 HuggingFace 모델(LLM 및 VLM)에 대한 EP / CP / TP / ETP 지원, 15개의 MoE 계열, vLLM 또는 SGLang 롤아웃을 사용한 다중 턴 RL 기반 사전 학습, FlashAttention-4, DeepEP V2, DeepGEMM, 그리고 AdamWBF16 옵티마이저를 포함합니다.
</br>
빠른 시작 (Quick start)
설치 (Installation)
Halo는 Blackwell 및 Hopper용 별도의 Docker 이미지로 제공되며, PyTorch, Flash Attention, DeepEP V2가 내장되어 있습니다. 계정 없이 익명으로 가져올 수 있습니다:
docker pull public.ecr.aws/whitecircle/halo:blackwell
...
버전 태그(:blackwell-1.3.0rc1, :hopper-1.3.0rc1)는 릴리스를 고정합니다. 이미지는 아키텍처별로 구성되어 있기 때문에 latest 태그는 없습니다. RL 추론용 이미지들은 이와 함께 게시됩니다 (:vllm-0.32.0, :sglang-0.5.22) 그리고 각각 :vllm-0.32.0-1.3.0rc1 및 :sglang-0.5.22-1.3.0rc1로 고정됩니다.
대신 로컬에서 빌드하려면:
호스트 Python 환경은 필요하지 않습니다. 이미지 세부 정보 및 빌드 옵션은 Installation를 참조하십시오.
학습 실행 시작 (Launch a training run)
halo launch는 학습 방법과 YAML 설정을 받습니다:
halo launch sft examples/sft/qwen3/qwen3-4b-ultrachat-lora.yaml
...
halo는 인수에 따라 python, torchrun, 또는 accelerate launch를 선택하며, --dry_run은 명령을 실행하는 대신 출력합니다. 설정 파일 이후에 위치하고 런처 자체의 옵션이 아닌 옵션들은 트레이너에게 전달되어 YAML 설정을 재정의합니다:
halo launch sft examples/sft/qwen3_5/qwen3.5-35b-a3b-ultrachat-ep.yaml \
-n 8 \
--expert_parallel_size=8 \
...
체크포인트(Checkpoint), 추론(inference), 데이터(data) 및 환경 유틸리티는 halo run을 사용합니다:
halo run merge-ep-shards --input_dir <ep-checkpoint-dir> --output_dir <merged-dir>
halo run quantize-to-lowp --input_dir <bf16-model-dir> --output_dir <nvfp4-out-dir> --format nvfp4
...
기반 스크립트는 직접 실행할 수도 있습니다:
python scripts/training/sft.py \
examples/sft/qwen3/qwen3-4b-ultrachat-lora.yaml
...
코딩 에이전트(Coding agents)
훈련 이미지는 저장소별 에이전트 스킬을 포함하여 배포합니다 (Claude Code와 Codex가 발견 가능; CLI를 이미지에 빌드하려면 --build-arg INSTALL_CLAUDE_CODE=1 추가). 이 스킬들은 작업 실행, 병렬 처리 설정 선택, 분산 실행 디버깅, 모델 추가, 체크포인트 관리, 데이터 준비, 처리량 최적화, RL 설정, 테스트 작성, 및 문서 최신 상태 유지에 사용됩니다.
</br>
문서화(Documentation)
사용자가 AI인지 여부에 따라 두 가지 버전의 문서를 제공합니다:
human-docs/: Halo 설치, 구성 및 실행을 위한 더 짧고 작업 중심의 가이드입니다.
agent-docs/: 코딩 에이전트를 위해 작성된 전체 기술 참고 자료로, 모델 통합, 병렬 처리, 최적화 내부 구조, 인프라 및 문제 해결 방법을 다룹니다.
전체 참고 자료는 사람이 사용하며 세부 정보를 알고 싶을 때도 완벽하게 읽기 쉽습니다.
사용자 가이드:
설치 ·
빠른 시작(Quickstart) ·
메서드 선택하기(Choosing a Method) ·
halo CLI ·
설정 파일 작성하기(Writing a Config) ·
데이터셋(Datasets) ·
훈련 메서드(Training Methods) ·
롤아웃 서버(Rollout Servers) ·
병렬 처리(Parallelism) ·
클러스터 및 다중 노드(Clusters & Multi-Node) ·
성능(Performance) ·
지원 매트릭스(Supported Matrix) ·
지원 모델(Supported Models) ·
모델 쿡북(Model Cookbooks) ·
모델 통합 비용(Model Integration Cost) ·
체크포인트 및 내보내기(Checkpoints & Export) ·
모니터링(Monitoring) ·
문제 해결(Troubleshooting) ·
환경 변수(Environment Variables) ·
AI 도구(AI Tooling) ·
기여하기(Contributing)
<br>
저장소 레이아웃 (Repository layout)
저장소의 지도:
| 경로 | 내용물 |
|---|
halo/ | 트레이너(Trainers), 병렬 처리(parallelism), 최적화 도구(optimizers), 커널(kernels), 콜레이터(collators), 그리고 콜백(callbacks) |
| ... | |
일반적인 실행 방식은 다음과 같습니다: examples/에서 설정 파일을 선택 → halo launch <메서드> <설정> (또는 Docker 이미지 내부에서 python scripts/training/<메서드>.py <설정>)입니다.
<br>
벤치마크 (Benchmarks)
달리 명시되지 않는 한 모든 행은 8× B300의 Blackwell 이미지를 사용하여 실행되었습니다. 속도는 따뜻한 커널 캐시 상태에서의 토큰/초(tokens/s)를 GPU당 기준으로 측정합니다. 신선한 Triton 캐시는 초기 단계에 비용이 발생하며 (Qwen3.5-35B-A3B의 첫 약 20회 실행은 안정화된 속도의 약 40% 수준입니다).
다른 프레임워크 대비 비교
문서를 격리하고 정확히 64k 또는 128k 토큰으로 채워진 행에 대해 UltraChat 200k 전체 파라미터 SFT(Supervised Fine-Tuning)를 수행했으며, 모든 프레임워크에서 동일한 행을 사용했습니다. 각 셀은 tok/s/GPU (최대 GiB)입니다; †는 다른 측정치보다 높은 값을 읽어내는 nvidia-smi 최대값입니다.
| Model, tokens per row | Halo 1.2.0 | Megatron Bridge | TRL 1.17.1 | NeMo AutoModel 0.7.0 |
|---|
| Qwen3.5-9B, 64k | 17,206 (54.3) | 19,431 (245.5†) | 14,735 (56.0) | 10,360 (99.3) |
| ... | | | | |
| Megatron Bridge는 Megatron Core 0.20.0을 포함하는 0.7.0 릴리스 후보 커밋입니다. 표 읽는 방법: | | | | |
- 최적화기(Optimizer) 체제가 다릅니다: Halo는 확률론적 반올림(stochastic rounding)을 사용하여 bf16 파라미터를 학습시키고, TRL과 NeMo는 bf16 Adam 상태를 사용한 bf16 파라미터, Megatron은 fp32 주 파라미터(122B의 경우 fp16 마스터)를 사용합니다.
- Megatron의 피크 값은 nvidia-smi 샘플이며, 나머지 값들은 torch 할당된 피크 값입니다. 이들을 직접 비교해서는 안 됩니다.
- 각 Halo 행은 선택된 설정에 대한 3회 실행의 중앙값(median)이며, 나머지 값들은 최고의 레이아웃을 사용한 단일 실행 결과입니다.
병렬 처리 레이아웃별 속도(Rate), 16k 및 4k 표, 그리고 다른 조건들: Throughput Benchmarks;
trl 측면의 비교: Halo vs stock TRL.
Miles 대비 GRPO