AReaL-MinT 딥다이브
— 매니지드 LLM 학습 API "Tinker"를 내 GPU 클러스터에 그대로 재현하기

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README 첫 문장은 이렇게 못박는다: "Open-source, self-hosted MinT training runtime on AReaL." 여기서 MinT는 LLM용 RL(강화학습) 학습 인프라로, "CPU 한 대짜리 스크립트가 데이터·손실함수·RL 환경을 정의하면, MinT이 그 계산을 GPU 클러스터에서 대신 실행"하는 게 핵심 아이디어다. 모델을 바꾸고 싶으면 문자열 하나(base_model="Qwen/Qwen3.6-27B")만 바꾸면 된다.

AReaL-MinT는 이 MinT과 똑같은 HTTP API를 노출하되, 내부적으로는 실제 GitHub 코드를 열어 보면 1,165줄짜리 FastAPI 앱(app.py)이 60개가 넘는 엔드포인트로 세션 생성·순전파·역전파·최적화 스텝·체크포인트·샘플링까지 전부 처리하고 있다. 학습 계산은 AReaL(중국 AI Lab 계열의 오픈소스 RL 학습 프레임워크, FSDP2 기반)에, 추론·샘플링은 SGLang(고성능 LLM 서빙 엔진)에 위임한다. 즉 "API 얼굴은 MinT, 몸통은 AReaL+SGLang"인 조합형 런타임이다.

2왜 주목받는가

"Tinker의 오픈소스 대안"이라는 포지셔닝 · Tinker 클라이언트 호환 · AReaL+SGLang 조합의 실전 검증.

AReaL-MinT가 공개 직후 TrendShift에 오른 이유는 세 가지 흐름이 겹치기 때문이다. 첫째, 2026년 들어 매니지드 파인튜닝 API(Tinker 등)가 "코드만 짜면 GPU를 신경 안 써도 된다"는 편의성으로 주목받으면서, 동시에 "그럼 이걸 오픈소스로 직접 돌릴 순 없나"라는 수요도 함께 커졌다. 둘째, RL 기반 파인튜닝(GRPO 등)이 SFT만으로는 못 잡는 추론 능력 향상의 표준 기법으로 자리잡았다. 셋째, AReaL과 SGLang이라는 각자 검증된 오픈소스 두 개를 하나의 서비스로 엮어 낸 통합형 접근 자체가 드물다.

Tinker(매니지드 API)와 무엇이 다른가

3기술 스택 전체 지도

control plane=FastAPI/uvicorn/pydantic, 학습=AReaL FSDP2/torch, 추론=SGLang+LoRA, 패키징=uv/pyproject.

pyproject.toml을 열어 보면 이 프로젝트가 세 겹의 레이어로 구성돼 있다는 게 바로 드러난다. ① 가벼운 기본 의존성(FastAPI 등, CPU만 있어도 설치됨), ② [gpu] 추가 의존성(swanlab 등 GPU 실습용 도구), ③ [system] 무거운 의존성(torch·AReaL·SGLang — 도커 베이스 이미지에서 상속받는 게 기본이라 명시적 설치는 선택). 이 분리 덕분에 "코드 구조만 읽어보고 싶다"면 무거운 GPU 스택 없이도 저장소를 열어 볼 수 있다.

4아키텍처 심화 분석

FastAPI control plane의 디스패치 · future 폴링 세만틱 · FSDP2/SGLang GPU 분할 · LoRA 핫리로드 · SFT/GRPO 데이터 흐름.

README가 제시하는 아키텍처 다이어그램은 이렇다. 이 절에서는 실제 소스 코드(router.py·future_store.py·backends/areal.py·backends/areal_inf.py)를 근거로 이 다이어그램 뒤에서 정확히 무슨 일이 벌어지는지 파헤친다.

① 진입점 — FastAPI가 요청을 받아 future로 즉시 응답한다

app.py의 모든 쓰기 엔드포인트(forward_backward·optim_step·asample 등)는 계산이 끝날 때까지 기다리지 않는다. 요청이 들어오면 _future(payload, **kwargs) 헬퍼가 future_store에 새 항목을 만들고 request_id만 즉시 반환한다. 실제 GPU 계산은 백그라운드에서 진행되고, 클라이언트는 /retrieve_future를 반복 호출(폴링)해 결과를 받는다. MinT SDK의 .result() 메서드가 이 폴링 루프를 클라이언트 쪽에서 감춰 준다.

// future_store.py의 핵심 상태 전이 (실제 코드 발췌)
retrieve(request_id):
  if payload is _PENDING:              // 아직 안 끝남
      raise PendingFutureError(queue_state, reason)
  if pending_polls > 0:                // 인위적 지연(테스트/큐 시뮬레이션용)
      pending_polls -= 1; raise PendingFutureError(...)
  if allow_try_again_once and not sent: // "한 번 더 물어보세요" 신호
      return {"type": "try_again", ...}
  if payload_size > metadata_only_threshold:  // 너무 크면 메타데이터만
      return {"status": "complete_metadata", "response_payload_size": ...}
  del self._items[request_id]          // 정상 조회 후 즉시 삭제(1회성)
  return payload

② 라우팅 — BackendRouter가 세션을 백엔드에 붙들어 맨다

router.py의 BackendRouter는 백엔드 레지스트리(학습용 1개 + 추론용 1개, backend_id로 식별)와 세션 테이블(session_id → TrainingSessionRecord)을 관리한다. SDK가 create_lora_training_client()를 호출하면 open_training_session(spec)이 실행되어 AReaL 백엔드에 PPOTrainer 인스턴스가 하나 생성되고, 이후 그 session_id로 들어오는 모든 forward·forward_backward·save_checkpoint 호출이 같은 트레이너로 디스패치된다. GRPO의 롤아웃(샘플링) 세션도 마찬가지로 rollout_session_id → (inference_backend_id, training_session_id) 매핑을 유지해, "이 롤아웃이 어느 학습 세션의 정책을 쓰는지"를 추적한다.

흥미로운 디스패치 로직은 _rollout_train_op()에 있다. 클라이언트가 보낸 loss_fn 문자열("ppo"·"grpo"·"reverse_kl" 등)을 검사해 TrainOp.FORWARD_BACKWARD_PPO 또는 TrainOp.FORWARD_BACKWARD_REVERSE_KL로 매핑한다 — 즉 SDK 코드에서 loss_fn="importance_sampling" 또는 "ppo"라고만 지정하면, 서버가 알아서 올바른 학습 연산으로 라우팅한다.

③ 학습 백엔드 — AReaL의 FSDP2 엔진을 감싼 어댑터

ArealTrainingBackend(backends/areal.py)는 세션을 열 때 YAML 설정(examples/qwen3_6_27b.yaml)을 읽어 AReaL의 PPOTrainer를 구성한다. 실제 설정 파일을 보면 actor.backend: "fsdp:d4p1t1"(데이터 병렬 4, 파이프라인 1, 텐서 1 — GPU 4장에 데이터만 쪼갬)와 rollout.backend: "sglang:d1p1t4"(데이터 1, 텐서 4 — GPU 4장으로 하나의 모델을 텐서 병렬 서빙)로 4+4 GPU 분할이 코드 레벨에서 확정돼 있다. actor.use_lora: true·lora_rank: 16이 기본값이라, 27B 모델 전체가 아니라 LoRA 어댑터만 학습하는 게 기본 동작이다.

학습 데이터는 MintTrainingAdapter(backends/mint_training.py)가 SDK의 Datum 페이로드(model_input 토큰 + loss_fn_inputs의 target_tokens/weights/logprobs/advantages)를 AReaL이 이해하는 텐서 배치로 변환한다. GRPO에서 SDK가 이미 계산해 보낸 advantage 값이 있으면 그대로 쓰고(raw_advantages), 없으면 AReaL의 compute_advantages가 새로 계산하도록 흘려보낸다 — 보상함수·advantage 계산은 클라이언트(사용자 스크립트) 책임, 그 이후 PPO/GRPO 손실 계산과 그래디언트는 서버(AReaL) 책임이라는 경계가 명확하다.

④ 추론 백엔드 & 가중치 동기화 — 두 갈래 경로가 공존한다

README는 "SGLang inference + LoRA hot-reload"라고 짧게 설명하지만, 실제 areal_inf.py의 클래스 docstring을 보면 더 정교하다. AReaL v2의 기본 경로는 awex(NCCL in-place 가중치 전송)로, 학습 GPU에서 추론 GPU로 전체 가중치를 직접 복사해 LoRA 스왑 없이도 최신 가중치를 유지한다. 반면 MinT SDK 특유의 "이름 붙은 스냅샷 샘플러"(save_weights_and_get_sampling_client(name=...)) 요청이 오면, _save_lora_to_hf로 LoRA 어댑터를 HuggingFace 포맷으로 디스크에 저장하고, SGLang의 /load_lora_adapter API로 그 어댑터를 즉시 로드시킨다. 이때 Megatron/VLM 체크포인트의 파라미터 이름(model.language_model.*)과 SGLang이 기대하는 이름(model.*)이 달라, _rename_lora_keys_for_sglang()이 safetensors 파일을 열어 키 이름을 직접 재작성하는 실전적인 호환성 코드까지 들어 있다.

⑤ SFT 데이터 흐름 — forward_backward → optim_step

⑥ GRPO 데이터 흐름 — 샘플링 → 보상 → advantage → 2단계 학습

GRPO의 핵심은 가치함수(value critic) 네트워크가 따로 없다는 점이다. PPO는 보통 "이 상태가 얼마나 좋은가"를 별도로 추정하는 크리틱 모델을 학습시켜야 하지만, GRPO는 같은 프롬프트에 대해 여러 응답을 뽑아(그룹) 그 그룹 내부의 평균·표준편차만으로 advantage를 정규화한다. 크리틱 모델 학습·저장·서빙이 통째로 사라지므로 인프라가 단순해진다 — qwen3_6_27b.yaml의 reward_norm: {mean_level: group, std_level: group} 설정이 이를 그대로 반영한다.

5디렉토리 구조 해부

src/·examples/·scripts/·docs/·tests/ 실제 내용 기반.

6학습 포인트 (기술별)

이 저장소에서 실제로 무엇을 배울 수 있는가 + 각 주제 실습 아이디어.

7하드웨어 / 시스템 요구사항

공식 요구사항 + 현실적인 개인 대안.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — GPU 없이도 시작할 수 있는 개념 실습부터, 실제 배선을 뜯어보는 심화 과제까지.

과제 1 · fake 백엔드로 control plane 뼈대 체험 난이도 ★☆☆☆☆

GPU 없이도 가장 먼저 할 수 있는 실습이다. 저장소를 클론해 기본 의존성만 설치(pip install -e '.[dev]')한 뒤, areal-mint serve --training-backend fake로 서버를 띄운다. 그 다음 curl이나 httpx로 /healthz·/api/v1/server_info를 호출해 응답 구조를 확인하고, /create_session으로 가짜 세션을 열어 future_store의 폴링 흐름을 직접 눈으로 관찰한다.

# 로컬 실행 (GPU 불필요, fake 백엔드)
git clone https://github.com/areal-project/AReaL-MinT.git
cd AReaL-MinT
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]' --no-deps
pip install fastapi pydantic uvicorn colorlog tenacity aiohttp aiofiles httpx requests flask

areal-mint serve --training-backend fake --port 8000
# 다른 터미널에서:
curl http://localhost:8000/healthz
curl http://localhost:8000/api/v1/server_info

과제 2 · future_store 단위 테스트 읽고 확장하기 난이도 ★★☆☆☆

tests/test_future_store.py를 열어 어떤 시나리오(정상 완료·TTL 만료·pending_polls·metadata_only)를 테스트하는지 파악한 뒤, "결과가 3번 폴링 후에야 준비되는" 새로운 시나리오를 직접 추가해 테스트를 통과시킨다. pytest tests/test_future_store.py -v로 검증.

과제 3 · SFT Datum을 손으로 만들어 API로 전송 난이도 ★★★☆☆

docs/guide.md의 build_sft_datum 함수를 참고해, 토크나이저 없이도 정수 토큰 ID 리스트를 직접 만들어 fake 백엔드의 /forward_backward 엔드포인트에 POST 요청을 보내 본다. weights 배열이 prompt 구간은 0, completion 구간은 1이 되는 걸 직접 손으로 구성해 보면 "SFT loss mask"의 의미가 체화된다.

과제 4 · 미니 GRPO advantage 계산기 만들기 난이도 ★★★☆☆

examples/smoke_helpers.py의 compute_group_advantages 함수를 참고하지 않고 직접 구현해 본다. 보상 리스트를 입력받아 (reward - group_mean) / group_std를 반환하는 순수 함수를 작성하고, 표준편차가 0일 때(모든 응답이 똑같은 보상을 받았을 때) 어떻게 나눗셈 오류를 막을지도 함께 고민해 본다.

// 직접 구현해 볼 시그니처
def compute_group_advantages(rewards: list[float]) -> list[float]:
    # TODO: 그룹 평균·표준편차로 정규화
    # 힌트: std가 0에 가까우면 1.0으로 클램프해 0-division 방지
    ...

assert compute_group_advantages([1.0, 1.0, 1.0, 1.0]) == [0.0, 0.0, 0.0, 0.0]
print(compute_group_advantages([0.9, 0.1, 0.5, 0.3]))

과제 5 · (GPU 보유자용) smoke_e2e.sh 전체 파이프라인 실행 난이도 ★★★★★

8×GPU 클라우드 인스턴스에 접근할 수 있다면, README의 Quick Start를 그대로 따라 mintctl start 27b로 서버를 띄우고 bash examples/smoke_e2e.sh를 실행해 SFT → GRPO → RL 수렴까지 이어지는 전체 파이프라인을 직접 관찰한다. mintctl logs -f로 실시간 로그를 보며, 4절에서 설명한 future 폴링·LoRA 핫로드가 실제 로그 라인으로 어떻게 나타나는지 확인해 보는 것이 목표.

9관련 기술 심화 학습 로드맵

RL 기초 → PPO/GRPO → 분산학습 → 추론 최적화 — 6주 계획.

10핵심 키워드 사전

이 문서와 저장소에 나온 주요 용어 정리.

11참고 링크

공식 저장소 · 관련 프로젝트 · 논문.