An open source framework that provides a simple, universal API for building distributed applications. Ray is packaged with RLlib, a scalable reinforcement learning library, and Tune, a scalable hyperparameter tuning library.

Project README

.. image:: https://github.com/ray-project/ray/raw/master/doc/source/images/ray_header_logo.png

.. image:: https://readthedocs.org/projects/ray/badge/?version=master :target: http://docs.ray.io/en/master/?badge=master

.. image:: https://img.shields.io/badge/Ray-Join%20Slack-blue :target: https://forms.gle/9TSdDYUgxYs8SA9e8

.. image:: https://img.shields.io/badge/Discuss-Ask%20Questions-blue :target: https://discuss.ray.io/

.. image:: https://img.shields.io/twitter/follow/raydistributed.svg?style=social&logo=twitter :target: https://twitter.com/raydistributed


Ray provides a simple, universal API for building distributed applications.

Ray is packaged with the following libraries for accelerating machine learning workloads:

  • Tune_: Scalable Hyperparameter Tuning
  • RLlib_: Scalable Reinforcement Learning
  • RaySGD <https://docs.ray.io/en/master/raysgd/raysgd.html>__: Distributed Training Wrappers
  • Datasets_: Flexible Distributed Data Loading (beta)

As well as libraries for taking ML and distributed apps to production:

  • Serve_: Scalable and Programmable Serving
  • Workflows_: Fast, Durable Application Flows (alpha)

There are also many community integrations <https://docs.ray.io/en/master/ray-libraries.html>_ with Ray, including Dask, MARS, Modin, Horovod, Hugging Face, Scikit-learn, and others. Check out the full list of Ray distributed libraries here <https://docs.ray.io/en/master/ray-libraries.html>_.

Install Ray with: pip install ray. For nightly wheels, see the Installation page <https://docs.ray.io/en/master/installation.html>__.

.. _Modin: https://github.com/modin-project/modin .. _Hugging Face: https://huggingface.co/transformers/main_classes/trainer.html#transformers.Trainer.hyperparameter_search .. _MARS: https://docs.ray.io/en/latest/data/mars-on-ray.html .. _Dask: https://docs.ray.io/en/latest/data/dask-on-ray.html .. _Horovod: https://horovod.readthedocs.io/en/stable/ray_include.html .. _Scikit-learn: joblib.html .. _Serve: https://docs.ray.io/en/master/serve/index.html .. _Datasets: https://docs.ray.io/en/master/data/dataset.html .. _Workflows: https://docs.ray.io/en/master/workflows/concepts.html

Quick Start

Execute Python functions in parallel.

.. code-block:: python

import ray

def f(x):
    return x * x

futures = [f.remote(i) for i in range(4)]

To use Ray's actor model:

.. code-block:: python

import ray

class Counter(object):
    def __init__(self):
        self.n = 0

    def increment(self):
        self.n += 1

    def read(self):
        return self.n

counters = [Counter.remote() for i in range(4)]
[c.increment.remote() for c in counters]
futures = [c.read.remote() for c in counters]

Ray programs can run on a single machine, and can also seamlessly scale to large clusters. To execute the above Ray script in the cloud, just download this configuration file <https://github.com/ray-project/ray/blob/master/python/ray/autoscaler/aws/example-full.yaml>__, and run:

ray submit [CLUSTER.YAML] example.py --start

Read more about launching clusters <https://docs.ray.io/en/master/cluster/index.html>_.

Tune Quick Start

.. image:: https://github.com/ray-project/ray/raw/master/doc/source/images/tune-wide.png

Tune_ is a library for hyperparameter tuning at any scale.

  • Launch a multi-node distributed hyperparameter sweep in less than 10 lines of code.
  • Supports any deep learning framework, including PyTorch, PyTorch Lightning <https://github.com/williamFalcon/pytorch-lightning>_, TensorFlow, and Keras.
  • Visualize results with TensorBoard <https://www.tensorflow.org/tensorboard>__.
  • Choose among scalable SOTA algorithms such as Population Based Training (PBT), Vizier's Median Stopping Rule, HyperBand/ASHA_.
  • Tune integrates with many optimization libraries such as Facebook Ax <http://ax.dev>, HyperOpt <https://github.com/hyperopt/hyperopt>, and Bayesian Optimization <https://github.com/fmfn/BayesianOptimization>_ and enables you to scale them transparently.

To run this example, you will need to install the following:

.. code-block:: bash

$ pip install "ray[tune]"

This example runs a parallel grid search to optimize an example objective function.

.. code-block:: python

from ray import tune

def objective(step, alpha, beta):
    return (0.1 + alpha * step / 100)**(-1) + beta * 0.1

def training_function(config):
    # Hyperparameters
    alpha, beta = config["alpha"], config["beta"]
    for step in range(10):
        # Iterative training function - can be any arbitrary training procedure.
        intermediate_score = objective(step, alpha, beta)
        # Feed the score back back to Tune.

analysis = tune.run(
        "alpha": tune.grid_search([0.001, 0.01, 0.1]),
        "beta": tune.choice([1, 2, 3])

print("Best config: ", analysis.get_best_config(metric="mean_loss", mode="min"))

# Get a dataframe for analyzing trial results.
df = analysis.results_df

If TensorBoard is installed, automatically visualize all trial results:

.. code-block:: bash

tensorboard --logdir ~/ray_results

.. _Tune: https://docs.ray.io/en/master/tune.html .. _Population Based Training (PBT): https://docs.ray.io/en/master/tune-schedulers.html#population-based-training-pbt .. _Vizier's Median Stopping Rule: https://docs.ray.io/en/master/tune-schedulers.html#median-stopping-rule .. _HyperBand/ASHA: https://docs.ray.io/en/master/tune-schedulers.html#asynchronous-hyperband

RLlib Quick Start

.. image:: https://github.com/ray-project/ray/raw/master/doc/source/images/rllib-wide.jpg

RLlib_ is an open-source library for reinforcement learning built on top of Ray that offers both high scalability and a unified API for a variety of applications.

.. code-block:: bash

pip install tensorflow # or tensorflow-gpu pip install "ray[rllib]"

.. code-block:: python

import gym
from gym.spaces import Discrete, Box
from ray import tune

class SimpleCorridor(gym.Env):
    def __init__(self, config):
        self.end_pos = config["corridor_length"]
        self.cur_pos = 0
        self.action_space = Discrete(2)
        self.observation_space = Box(0.0, self.end_pos, shape=(1, ))

    def reset(self):
        self.cur_pos = 0
        return [self.cur_pos]

    def step(self, action):
        if action == 0 and self.cur_pos > 0:
            self.cur_pos -= 1
        elif action == 1:
            self.cur_pos += 1
        done = self.cur_pos >= self.end_pos
        return [self.cur_pos], 1 if done else 0, done, {}

        "env": SimpleCorridor,
        "num_workers": 4,
        "env_config": {"corridor_length": 5}})

.. _RLlib: https://docs.ray.io/en/master/rllib.html

Ray Serve Quick Start

.. image:: https://raw.githubusercontent.com/ray-project/ray/master/doc/source/serve/logo.svg :width: 400

Ray Serve_ is a scalable model-serving library built on Ray. It is:

  • Framework Agnostic: Use the same toolkit to serve everything from deep learning models built with frameworks like PyTorch or Tensorflow & Keras to Scikit-Learn models or arbitrary business logic.
  • Python First: Configure your model serving declaratively in pure Python, without needing YAMLs or JSON configs.
  • Performance Oriented: Turn on batching, pipelining, and GPU acceleration to increase the throughput of your model.
  • Composition Native: Allow you to create "model pipelines" by composing multiple models together to drive a single prediction.
  • Horizontally Scalable: Serve can linearly scale as you add more machines. Enable your ML-powered service to handle growing traffic.

To run this example, you will need to install the following:

.. code-block:: bash

$ pip install scikit-learn
$ pip install "ray[serve]"

This example runs serves a scikit-learn gradient boosting classifier.

.. code-block:: python

import pickle
import requests

from sklearn.datasets import load_iris
from sklearn.ensemble import GradientBoostingClassifier

from ray import serve


# Train model.
iris_dataset = load_iris()
model = GradientBoostingClassifier()
model.fit(iris_dataset["data"], iris_dataset["target"])

class BoostingModel:
    def __init__(self, model):
        self.model = model
        self.label_list = iris_dataset["target_names"].tolist()

    async def __call__(self, request):
        payload = await request.json()["vector"]
        print(f"Received flask request with data {payload}")

        prediction = self.model.predict([payload])[0]
        human_name = self.label_list[prediction]
        return {"result": human_name}

# Deploy model.

# Query it!
sample_request_input = {"vector": [1.2, 1.0, 1.1, 0.9]}
response = requests.get("http://localhost:8000/iris", json=sample_request_input)
# Result:
# {
#  "result": "versicolor"
# }

.. _Ray Serve: https://docs.ray.io/en/master/serve/index.html

More Information

  • Documentation_
  • Tutorial_
  • Blog_
  • Ray 1.0 Architecture whitepaper_ (new)
  • Ray Design Patterns_ (new)
  • RLlib paper_
  • RLlib flow paper_
  • Tune paper_

Older documents:

  • Ray paper_
  • Ray HotOS paper_

.. _Documentation: http://docs.ray.io/en/master/index.html .. _Tutorial: https://github.com/ray-project/tutorial .. _Blog: https://medium.com/distributed-computing-with-ray .. _Ray 1.0 Architecture whitepaper: https://docs.google.com/document/d/1lAy0Owi-vPz2jEqBSaHNQcy2IBSDEHyXNOQZlGuj93c/preview .. _Ray Design Patterns: https://docs.google.com/document/d/167rnnDFIVRhHhK4mznEIemOtj63IOhtIPvSYaPgI4Fg/edit .. _Ray paper: https://arxiv.org/abs/1712.05889 .. _Ray HotOS paper: https://arxiv.org/abs/1703.03924 .. _RLlib paper: https://arxiv.org/abs/1712.09381 .. _RLlib flow paper: https://arxiv.org/abs/2011.12719 .. _Tune paper: https://arxiv.org/abs/1807.05118

Getting Involved

  • Forum_: For discussions about development, questions about usage, and feature requests.
  • GitHub Issues_: For reporting bugs.
  • Twitter_: Follow updates on Twitter.
  • Slack_: Join our Slack channel.
  • Meetup Group_: Join our meetup group.
  • StackOverflow_: For questions about how to use Ray.

.. _Forum: https://discuss.ray.io/ .. _GitHub Issues: https://github.com/ray-project/ray/issues .. _StackOverflow: https://stackoverflow.com/questions/tagged/ray .. _Meetup Group: https://www.meetup.com/Bay-Area-Ray-Meetup/ .. _Twitter: https://twitter.com/raydistributed .. _Slack: https://forms.gle/9TSdDYUgxYs8SA9e8

Open Source Agenda is not affiliated with "Ray" Project. README Source: ray-project/ray