ray

Ray

Library-reference skill for production, open-source Ray — 26 rules across 6 categories covering the path from training to serving. Ray's API surface churned hard through the 2.x line (Train V2 became the default, Serve removed parameters and handle classes outright, Ray Data reversed a deprecation), so a model fluent in the older corpus produces code that warns, errors, or silently means something else. Each rule names the wrong default it corrects; there is no rule for things a capable model already gets right.

Scope is classic-ML Ray on self-hosted/KubeRay clusters. LLM serving and batch inference (ray.serve.llm, ray.data.llm) are the sibling ray-llm skill.

Pinned to ray 2.57.0 (Python ≥ 3.10). API claims were verified against the unpacked 2.57.0 wheel; classic-ML examples were exercised on a live local Ray 2.57.0 runtime.

When to Apply

• Writing or reviewing distributed training code — TorchTrainer, ScalingConfig, checkpointing, fault tolerance
• Building data pipelines with Ray Data — reads, map_batches, GPU inference pools, training ingest
• Running hyperparameter sweeps with Ray Tune, especially combined with Ray Train
• Writing or reviewing Ray Serve deployments — scaling, handles, composition, production config
• Using Ray Core primitives directly — tasks, actors, object store, retries
• Standing up or reviewing production Ray infrastructure — KubeRay CRDs, job submission, fault tolerance, observability

Rule Categories

#	Category	Prefix	Covers
1	Ray Train	train-	Train V2 as the default (deprecated config fields), ray.train.report over ray.air session, config imports and elastic scaling, the prepare_model/prepare_data_loader wrappers
2	Ray Serve	serve-	max_ongoing_requests (old name removed), current autoscaling fields, DeploymentResponse handles, serve.run/build/deploy lifecycle, replica placement options
3	Ray Data	data-	compute= strategies (the concurrency reversal), override_num_blocks, streaming execution replacing pipelines, torch ingest, zero-copy read-only batches
4	Ray Core	core-	The classic anti-patterns' non-obvious residue, retry/restart defaults, object store & /dev/shm sizing, ray.util.state
5	Ray Tune	tune-	Tuner as canonical (with tune.run's true status), ray.tune.RunConfig imports, the driver-function Train integration
6	Production & Clusters	prod-	KubeRay CRD choice, Jobs API submission, GCS fault tolerance with Redis, baked images vs runtime_env, Prometheus/Grafana wiring

Quick Reference

1. Ray Train

• train-v2-default-changed-semantics — V2 is the default since 2.51; sync_config/verbose/fail_fast are gone
• train-report-not-air-session — ray.train.report(metrics, checkpoint=); ray.air is a legacy shim
• train-configs-from-ray-train-elastic — V2 config imports, elastic num_workers=(min, max), case-sensitive resource keys
• train-prepare-model-and-loader — without prepare_model/prepare_data_loader, N workers train N unsynchronized copies

2. Ray Serve

• serve-max-ongoing-requests — max_concurrent_queries is removed; max_ongoing_requests (default 5) + max_queued_requests
• serve-autoscaling-current-fields — target_ongoing_requests, *_factor fields, num_replicas="auto", scale-to-zero
• serve-deployment-response-handles — DeploymentResponse.result()/await, never ray.get; composition via .bind()
• serve-run-build-deploy — serve.run + serve build/deploy; Deployment.deploy() era is removed
• serve-placement-controls — max_replicas_per_node, per-replica placement groups, gang scheduling, request routers

3. Ray Data

• data-compute-not-concurrency — concurrency= is deprecated (again); compute=ActorPoolStrategy/TaskPoolStrategy
• data-override-num-blocks — parallelism is deprecated in read APIs
• data-streaming-replaced-pipelines — DatasetPipeline/window/repeat removed; execution streams on consumption
• data-iter-torch-batches-not-to-torch — to_torch is gone; iter_torch_batches and Train dataset shards
• data-zero-copy-read-only-batches — batches are read-only views by default; set an explicit batch_size

4. Ray Core

• core-classic-traps-residue — the non-obvious residue of the classic anti-patterns: ray.wait draining, closure/global copies, few-ms task floor
• core-retries-system-failures-only — retry_exceptions is opt-in; actors don't restart by default
• core-object-store-sizing — 30% default, /dev/shm in containers, spilling to local disk
• core-state-api-not-ray-state — ray.state is gone; ray.util.state is the introspection API

5. Ray Tune

• tune-tuner-canonical — Tuner is the API; tune.run is legacy but not removed
• tune-runconfig-from-ray-tune — Tuner takes ray.tune.RunConfig, not ray.train's or ray.air's
• tune-driver-function-not-trainer — Trainer-inside-Tuner is deprecated; use a driver function + with_resources

6. Production & Clusters

• prod-kuberay-crd-choice — RayCluster vs RayJob (shutdownAfterJobFinishes defaults false) vs RayService
• prod-jobs-api-not-head-driver — ray job submit for long-lived clusters; Ray Client is a dev tool
• prod-gcs-ft-redis — head-crash survival for RayService needs external Redis GCS
• prod-baked-images-not-runtime-env — images carry prod dependencies; runtime_env (now incl. uv, image_uri) is for iteration
• prod-metrics-wiring — the dashboard needs external Prometheus/Grafana to show time series

How to Use

Read a reference file when its decision comes up. Each rule names the wrong default it corrects, then shows the canonical way (with an incorrect/correct contrast only where the wrong way is a real trap).

• Section definitions — category structure
• Rule template — for adding new rules
• AGENTS.md — auto-built table of contents across all rules

Related Skills

• ray-llm — the sibling rule pack for LLM serving (ray.serve.llm) and batch inference (ray.data.llm) on Ray
• mlflow-3 — experiment tracking and model registry; pairs with Ray Train for the tracking side of the MLOps cycle

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and source references