Ray Essential Curriculum

이 커리큘럼이 세우는 핵심 전제 — **한 대의 노트북에서 `ray.init()` 한 번이 곧 완전한 Ray 클러스터**입니다. GCS·raylet·오브젝트 스토어·대시보드가 모두 한 노드에 공존하고, 그 위로 Task/Actor 워커들이 작업을 분산 처리하며, Ray Data block(= 샤드)들이 데이터를 분할해 흘려보냅니다. 같은 코드가 노트북에서도 클러스터에서도 그대로 돈다는 원리가 7단계 전체의 뼈대입니다.

소개

Ray는 UC Berkeley RISELab에서 시작해 현재 Anyscale이 운영하는 오픈소스 분산 컴퓨팅 프레임워크입니다. 파이썬만으로 분산 실행·데이터 파이프라인·분산 학습·하이퍼파라미터 최적화·모델 서빙을 하나의 추상화 위에서 다룹니다. 이 시리즈의 특징은 — 분산 시스템 지식 없이도 @ray.remote 한 줄로 병렬화가 된다는 점을, 한 대의 노트북(로컬)에서 손으로 체득한다는 것입니다.

이 커리큘럼은 Ray-Essential 시리즈의 마스터 로드맵입니다. 한 대의 노트북(로컬) 을 기준으로, Ray가 지원하는 기능별 활용 전략을 손으로 체득하도록 설계했습니다. 각 항목을 정복할 때마다 체크박스를 채워 나가는 도장깨기 방식으로 진행 상황을 추적합니다.

선수 지식: Python 중급 문법과 동시성 기초. Concurrency Essential 시리즈가 세운 프로세스·스레드·GIL·멀티프로세싱 지식을 재사용합니다 — Ray는 바로 그 동시성 개념들을 분산 수준으로 일반화하기 때문입니다. 파이썬 GIL의 원리는 Python GIL 포스트에서 다뤘습니다.

학습 흐름

7단계는 아래 순서대로 진행하는 것을 권장합니다. 핵심(Core: Task/Actor)으로 Ray의 뼈대를 다진 뒤, 기능별 활용(Data·Tune·Train·Serve)으로 라이브러리를 정복하고, 통합(AIR + concurrency 종합 + Job 간 동시성)으로 마무리하는 흐름입니다.

flowchart TD
    Start([학습 시작]) --> S1

    subgraph CORE["핵심 · Ray Core"]
        S1["1단계<br/>Task · ObjectRef · raylet/Worker"]
        S2["2단계<br/>Actor · Actor Pool · in-process 동시성"]
    end

    subgraph FEAT["기능별 활용 · 로컬 실전"]
        S3["3단계<br/>Ray Data — block/샤드 파이프라인"]
        S4["4단계<br/>Ray Tune — 하이퍼파라미터 탐색"]
        S5["5단계<br/>Ray Train — 분산 학습 & 데이터 샤딩"]
        S6["6단계<br/>Ray Serve — 로컬 모델 서빙"]
    end

    subgraph INT["통합 · AIR와 확장"]
        S7["7단계<br/>통합 파이프라인 · Job 간 동시성"]
    end

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
    S7 --> Done([시리즈 완주 🎉])

학습 진행 현황

완료한 항목에는 상세 포스트 링크가 연결되어 있습니다. 학습이 진행될 때마다 체크박스와 진행률을 갱신합니다.

현재 완료한 항목: 21개
전체 항목: 21개
진행률: 100%

1단계: Ray 핵심 모델 & 로컬 설치 — Task · ObjectRef · raylet/Worker

Ray를 이해하는 출발점은 한 대의 노트북이 곧 하나의 분산 클러스터라는 사실입니다. 설치, ray.init(), 대시보드, 그리고 raylet(스케줄러)과 Worker(실행 프로세스)의 구분(Task는 워커 풀 공유, Actor는 워커 독점)을 잡습니다. 자세한 내용은 Stage 1 포스트에서 다룹니다.

로컬 설치와 기동: pip install "ray[default]", ray.init(num_cpus), 대시보드(:8265), ray stop/status — [상세]
Task와 ObjectRef: @ray.remote, ray.get/put/wait, GIL 초월 CPU 병렬화 — [상세]
raylet vs Worker & 오브젝트 스토어: 스케줄러와 실행 프로세스 구분, 메모리/디스크 스필(spill), OMP_NUM_THREADS 폭주 방지 — [상세]

2단계: 상태와 동시성 — Actor · Actor Pool · in-process concurrency

Ray의 상태를 가진 분산 객체 모델입니다. Counter 액터부터 async/threaded 액터와 max_concurrency(Job 내부 동시성의 핵심), 그리고 고정 워커 풀인 ActorPool을 실습합니다. 자세한 내용은 Stage 2 포스트에서 다룹니다.

Actor의 생명주기: @ray.remote 클래스, 전용 워커, 메서드 직렬화 — [상세]
in-process 동시성: threaded vs async 액터(구분법: async def 존재), max_concurrency, await obj_ref — [상세]
Actor Pool: ray.util.ActorPool(map/map_unordered), 상태 격리 워커 처리 — [상세]

3단계: 로컬 데이터 파이프라인 & 샤딩 — Ray Data

대용량 데이터 전처리를 분산 파이프라인으로 처리합니다. “DB shard = Ray Data block” 멘탈 모델을 세우고, 병렬도(= block 수)를 제어하는 방법을 익힙니다. 자세한 내용은 Stage 3 포스트에서 다룹니다.

Ray Data 기초: from_pandas/read_parquet/read_sql, map/map_batches(Task/Pool 전략), to_pandas() — [상세]
block과 샤딩: repartition(n), split(n)/split_at_indices/streaming_split, 병렬도 제어 — [상세]
batch 변환 실전: map_batches(numpy/pandas), ActorPoolStrategy, compute 인자(deprecated concurrency 대체) — [상세]

4단계: 하이퍼파라미터 자동화 — Ray Tune

머신러닝 모델 튜닝을 “노트북 코어 수만큼 병렬”로 탐색합니다. 그리드/로그 유니폼 탐색, ASHA 조기 종료, 코어 오버서브스크라이빙을 실습합니다. 자세한 내용은 Stage 4 포스트에서 다룹니다.

Tuner 기본: tune.Tuner + grid_search/loguniform/choice, tune.report — [상세]
조기 종료와 탐색: ASHA/HyperBand, Optuna 등 검색 알고리즘 — [상세]
로컬 리소스 제어: with_resources, max_concurrent_trials, 코어 오버서브스크라이빙 — [상세]

5단계: 분산 학습 — Ray Train & 데이터 샤딩

PyTorch 모델을 노트북에서 N개 워커로 분산 학습합니다. 각 워커가 데이터의 서로 다른 “샤드”를 받는 원리(get_dataset_shard/DistributedSampler)가 핵심입니다. 자세한 내용은 Stage 5 포스트에서 다룹니다.

TorchTrainer 기본: ScalingConfig(num_workers), prepare_model/prepare_data_loader — [상세]
데이터 샤딩: get_dataset_shard(), DistributedSampler, 전역 배치 = 워커배치 × world_size — [상세]
체크포인트와 복원: RunConfig/CheckpointConfig, 로컬 경로 저장, Train V2(RAY_TRAIN_V2_ENABLED) 주의 — [상세]

6단계: 로컬 모델 서빙 — Ray Serve (동시성/스케일)

학습한 모델을 로컬에서 즉시 HTTP 엔드포인트로 배포합니다. Serve는 공식적으로 local first — 배포 전 로컬 테스트를 장려합니다. 자세한 내용은 Stage 6 포스트에서 다룹니다.

Deployment 기본: @serve.deployment, serve.run(app, route_prefix="/"), localhost:8000 — [상세]
구성과 인그레스: deployment graph, FastAPI ingress, HF 파이프라인 — [상세]
로컬 스케일/동시성: num_replicas, 리퀘스트 배칭, max_concurrent_queries 주의점 — [상세]

7단계: 실전 통합 — AIR 파이프라인 & Job 간 동시성

배운 모든 것을 하나의 조립 스크립트로 통합합니다. Data → Train → Tune → Serve를 잇는 엔드투엔드 ML 파이프라인(AIR) 을 로컬에서 구동하고, concurrency 처리(워커 풀 · Job 내부/간 동시성)를 종합합니다. 자세한 내용은 Stage 7 포스트에서 다룹니다.

AIR 통합: ray.data 전처리 → TorchTrainer → Tuner → 체크포인트 → Serve HTTP 최종 호출 — [상세]
concurrency 종합: 워커 풀(액터 풀), map_batches, ray.wait 스트리밍, async 액터 — [상세]
Job 간 동시성 & 확장: ray job submit으로 여러 잡 클러스터 공유, --num-cpus/--memory 상한, KubeRay 전망(선택) — [상세]

핵심 포인트

한 노드 = 전체 클러스터: ray.init() 한 번이 곧 완전한 Ray 클러스터입니다. 클러스터 모델을 처음부터 로컬에서 가르치면, 나중에 KubeRay로 올라가도 코드가 그대로입니다.
worker와 shard를 정확히 구분하세요: Worker = Task/Actor 코드가 도는 프로세스(Task는 워커 풀 공유, Actor는 독점). Ray에서 “shard”는 부품이 아니라 데이터를 독립 워커에 분할 배치하는 행위(Ray Data block, Train 데이터 샤드, split(n)).
Job 내부 vs Job 간 동시성을 구분하세요: Job 내부 는 태스크/액터/max_concurrency(스레드·이벤트 루프)로, Job 간 은 별도 ray job submit이 클러스터를 공유하고 --num-cpus/--memory로 제한합니다.
GIL을 재사용하세요: Python GIL은 이 시리즈의 파이썬 면의 토대입니다. Ray가 GIL을 어떻게 프로세스 수준으로 우회하고, threaded 액터가 왜 GIL에 묶이는지가 1·2단계의 핵심 대비입니다.

결론

Ray는 개념을 아는 것보다 손으로 익히는 분산 컴퓨팅 프레임워크입니다. 이 커리큘럼을 나침반 삼아 한 대의 노트북에서 Task/Actor로 시작해, Data·Tune·Train·Serve의 기능별 활용 전략, 그리고 AIR 통합 파이프라인까지 7단계로 도장을 깨며 체화해 보세요. 완료할 때마다 체크박스를 채워 나가는 도장깨기로 진행 상황을 시각적으로 확인할 수 있습니다.

시리즈 전체 글

Ray Essential Curriculum — 이 로드맵 (1단계~7단계 개괄)
Stage 1 · Ray 기본과 로컬 설치 — Task · ObjectRef · raylet/Worker
Stage 2 · Actor와 동시성 — Actor · Actor Pool · in-process concurrency
Stage 3 · Ray Data 파이프라인 — block/샤딩 · batch 변환
Stage 4 · Ray Tune 튜닝 — 하이퍼파라미터 탐색 · 조기 종료
Stage 5 · Ray Train 분산 학습 — 분산 학습 · 데이터 샤딩
Stage 6 · Ray Serve 서빙 — 로컬 모델 서빙 · 스케일
Stage 7 · 실전 통합 — AIR 파이프라인 · Job 간 동시성

소개