---

name: train-tune description: "Use Ray Train and Ray Tune for distributed training, checkpointing, hyperparameter tuning, resources, and result analysis." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Ray Train And Tune

Use this sub-skill when the task mentions ray.train, ScalingConfig, RunConfig, CheckpointConfig, train.report, ray.tune.Tuner, TuneConfig, tune.report, search spaces, schedulers, with_resources, ResultGrid, max_concurrent_trials, or storage_path.

Fast Routing

• Use Ray Train when the main problem is distributed training orchestration: training workers, scaling configs, checkpoints, fault tolerance, persistent storage, and training callbacks.
• Use Ray Tune when the main problem is experiment execution or hyperparameter tuning: trainables, search spaces, schedulers/search algorithms, per-trial resources, concurrency, output folders, and best-result analysis.
• Use Train and Tune together by letting Tune launch trials and letting each trial create a Train trainer or training driver; cap max_concurrent_trials so inner Train workers can acquire resources.
• Route Ray Data input pipeline construction to ../data-pipelines/SKILL.md, Ray Core placement/resource semantics to ../core-runtime/SKILL.md, trained artifact serving to ../serve-deployments/SKILL.md, and RLlib AlgorithmConfig work to ../rllib-workloads/SKILL.md.

Minimal Tune Pattern

from ray import tune


def objective(config):
    score = (config["width"] - 3) ** 2
    tune.report({"loss": score})

results = tune.Tuner(
    tune.with_resources(objective, {"cpu": 1, "gpu": 0}),
    param_space={"width": tune.grid_search([2, 3, 4])},
    tune_config=tune.TuneConfig(metric="loss", mode="min"),
    run_config=tune.RunConfig(name="small_sweep", storage_path="./ray_results"),
).fit()
print(results.get_best_result().config)

Read Next

• Read references/api-reference.md for verified signatures and how Train/Tune objects relate.
• Read references/workflows.md for checkpoint/storage recipes, Tune sweeps, scheduler/resource examples, ResultGrid analysis, and Train+Tune integration.
• Read references/troubleshooting.md for missing extras, storage mistakes, metric/mode mismatches, resource deadlocks, GPU visibility, checkpoint/report misuse, and output locations.
• Run python scripts/tune_train_smoke.py --help for a safe helper. Add --run-tune only when starting a tiny local Ray Tune run is acceptable.

Installation Notes

• Prefer narrow extras: ray[train] for Train workloads and ray[tune] for Tune workloads. Add framework extras or packages only for the selected trainer/search algorithm.
• Python support for this Ray family is >=3.10.
• Avoid recommending ray[all] by default; it can install unnecessary dependencies for unrelated Ray libraries.