Ray, from first principles
A linearized course through Learning Ray: start with the Core runtime, then build upward into RLlib, Tune, Data, Train, Serve, clusters, platform handoffs, and ecosystem choices.
Why this series
Ray can feel like a bag of unrelated APIs until you see the common thread: tasks, actors, objects, resources, and failure boundaries. This course keeps that thread visible. Each lesson asks what problem the layer solves, what it hides, and what trade-off remains yours.
Book and API note
The source book is from 2023. The syllabus follows the public Learning Ray outline, but the lessons are original companion notes and the wording reflects current Ray docs where helpful. In particular, the old AIR umbrella is treated as an ML-platform handoff pattern across Ray Data, Train, Tune, Serve, and checkpoints.
Coverage map
| Book chapter | Lesson coverage | Teaching focus |
|---|---|---|
| Chapter 1 | Lessons 00-01 | Ray motivation, layers, design principles, and library map. |
| Chapter 2 | Lessons 02-05 | Core API, runtime components, tasks, actors, objects, scheduling, and MapReduce. |
| Chapter 3 | Lessons 06 and 14 | First distributed app through a reinforcement-learning simulation, plus the tooling/debugging lens needed to inspect it. |
| Chapter 4 | Lesson 07 | RLlib environment, rollout, multi-agent, offline, and curriculum concepts. |
| Chapter 5 | Lesson 08 | Tune, trials, search spaces, schedulers, and checkpoints. |
| Chapter 6 | Lesson 09 | Ray Data datasets, blocks, transformations, streaming execution, pandas/Dask/Spark-style interop, and ML handoffs. |
| Chapter 7 | Lesson 10 | Ray Train, distributed training jobs, scaling, data, checkpoints, and Tune integration. |
| Chapter 8 | Lesson 11 | Ray Serve, online inference, deployments, batching, and model composition. |
| Chapter 9 | Lessons 12 and 14 | Ray clusters, KubeRay, cluster launcher, cloud deployment, autoscaling, and operational signals. |
| Chapter 10 | Lessons 13-14 | AIR concepts reframed as ML-platform handoffs, memory/failure behavior, and checkpoint boundaries. |
| Chapter 11 | Lessons 15-16 | Ecosystem, integrations, alternatives, and capstone platform design. |
Part I - Core mental model
00
Orientation - Ray as distributed Python
A linear map of the whole series: tasks, actors, objects, ML libraries, clusters, and the trade-offs that make Ray powerful without making it magic.
01
Why Ray Exists
The problem Ray attacks: Python is pleasant locally, but most real ML and simulation workloads eventually need distributed execution.
02
Tasks, Objects, and Futures
The first real Ray program: remote functions return object references, and object references let a dependency graph run asynchronously.
03
Actors, State, and Services
When a function is not enough: actors let Ray keep state near the worker that owns it.
04
Runtime, Scheduling, and the Object Store
The invisible machinery: head node metadata, worker processes, local object stores, resources, locality, and what happens when bytes move.
05
Distributed Patterns: Map, Shuffle, Reduce
The simple MapReduce example is not toy material. It is the shape behind many Ray Data, Tune, and training pipelines.
Part II - Applications and libraries
06
Your First Distributed Application
A reinforcement-learning maze is useful because it separates environment simulation, policy evaluation, learning, and coordination.
07
RLlib: Scalable Reinforcement Learning
RLlib packages the rollout-worker, learner, policy, evaluation, multi-agent, and offline-data machinery you just built by hand.
08
Ray Tune: Experiments and Hyperparameter Search
Tune is not just random search on more machines. It is a control plane for trials, resources, schedulers, checkpoints, and early stopping.
09
Ray Data: Blocks, Streaming Execution, and ML Dataflow
Ray Data gives the rest of the Ray ML stack a common way to load, transform, repartition, stream, and hand data to batch inference or training.
10
Ray Train: Distributed Training
Ray Train wraps the recurring shape of distributed ML: workers, data shards, framework launch, checkpoints, metrics, and scale-out.
11
Ray Serve: Online Inference
Serve turns Ray actors into scalable deployments with HTTP ingress, handles, batching, composition, and independent autoscaling.
Part III - Cluster and platform layer
12
Ray Clusters, KubeRay, and Autoscaling
The moment a local Ray app outgrows one machine, the real system becomes head pods, worker groups, resources, networking, logs, and autoscaling policy.
13
The ML Platform Bridge
The book's Ray AIR chapter is best read today as a platform lesson: compose Data, Train, Tune, Serve, checkpoints, and offline batch inference around one runtime.
14
Debugging, Observability, and Failure Semantics
A distributed Ray app needs a failure model: what retries, what is idempotent, what state can be rebuilt, and what metrics explain the slowdown.
15
Ecosystem, Integrations, and Alternatives
Ray is strongest when you know what it should replace, what it should integrate with, and what it should leave alone.
16
Capstone: Design a Ray ML Platform
Put the series together: one pipeline that ingests data, tunes and trains models, serves them online, and runs on a cluster without hiding the hard trade-offs.
How to read it
- Read 00-05 linearly. They establish the mental model: task graph, actors, object store, resources, and shuffle.
- Then choose the library path. RLlib, Tune, Data, Train, and Serve can be read independently once Core is clear.
- Finish with 12-16 before production. Clusters, platform handoffs, debugging, ecosystem boundaries, and the capstone are where toy examples become operational systems.