Need help with academy?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

anyscale
286 Stars 115 Forks Apache License 2.0 381 Commits 16 Opened issues

Description

Ray tutorials from Anyscale

Services available

!
?

Need anything else?

Contributors list

Anyscale Academy - Tutorials on Ray and Ray-based Libraries

© 2018-2021, Anyscale. All Rights Reserved

Welcome to the Anyscale Academy tutorials on Ray, the system for scaling your applications from a laptop to a cluster.

This README tells you how to set up the tutorials, decide which content is best for your interests, and find videos of previous Academy live events.

Tips:

  1. Anyscale is developing a free, hosted version of these tutorials. Contact us for more information.
  2. Please report any issues or suggestions:
  3. If you are attending a live tutorial event, please follow the setup instructions provided in advance. It will take too long to do these instructions during the event.
  4. For troubleshooting help, see the Troubleshooting, Tips, and Tricks notebook.

Dependencies

For a few of the examples here, you may need to add some additional dependencies:

  • nodejs
  • holoviews
  • bokeh

Join Us at Ray Summit 2021!

Join us for the free Ray Summit 2021 virtual conference on June 22-24, 2021. We have an amazing lineup of luminar keynote speakers and breakout sessions on the Ray ecosystem, third-party Ray libraries, and applications of Ray in the real world.

Ray Summit 2021

For information about other online events, see anyscale.com/events.

Videos of Previous Live Sessions

To see videos of live sessions covering most of this material, see the Anyscale Academy page or visit the Anyscale YouTube! channel.

Tutorial Setup

Read the appropriate setup section that follows, then jump to Launching the Tutorials.

Setup for Anyscale Academy Hosted Sessions

There is nothing you need to setup, as the hosted environment will provide everything.

However, consider cloning or downloading a release of the tutorial notebooks and supporting software from the Academy repo, so you have a local copy of everything.

Tip: If you modify any notebooks during the hosted session, make sure you download them to save those changes.

Setup for a Local Machine

Note: Ray support for Windows is new. See these release notes for details.

Follow these instructions to use the tutorials. Note that some commands can take a while to finish.

Clone the Academy GitHub repo or download the latest release.

Now install the dependencies using either Anaconda or

pip
in your Python environment. We recommend using Anaconda.

Which Python Version?

Python 3.7 is recommended. While Ray supports Python 3.6, there are known problem using locales in that version and these tutorials. Specifically, the following code throws an error:

import locale
locale.setlocale(locale.LC_ALL, locale.getlocale())

This tutorial doesn't manipulate locales explicitly, but you may run into problems with your default locale.

While Ray supports Python 3.8, some dependencies used in

RLlib
(the Ray reinforcement library) are not yet supported for 3.8, at the time of this writing.

Using Anaconda

If you need to install Anaconda, follow the instructions here. If you already have Anaconda installed, consider running

conda upgrade --all
.

Run the following commands in the root directory of this project. First, use

conda
to install the other dependencies, including Ray. Then activate the newly-created environment, named
anyscale-academy
. Finally, run the provided
tools/fix-jupyter.sh
script to install a graphing library extension in Jupyter Lab and perform other tasks.
conda env create -f environment.yml
conda activate anyscale-academy
tools/fix-jupyter.sh

If you are using Windows, see the Fixing Jupyter Lab on Windows below for an alternative to using

tools/fix-jupyter.sh
.

Note that Python 3.7 is used. Ignore the similar-looking

environment-docker.yml
file. It is used to build Docker images.

You can delete the environment later with the following command:

conda env remove --name anyscale-academy

Using Pip

If you don't use Anaconda, you'll have to install these prerequisites first:

  • Python 3.7:
    • See notes above about problems with 3.6 and 3.8. Don't use 3.8, but 3.6 may work for you.
    • The version of Python that comes with your operating system is probably too old. Try
      python --version
      to see what you have.
    • Installation instructions are at python.org.
  • Pip: A recent version - consider upgrading if it's not the latest version.
  • Node.js: Required for some of the Jupyter Lab graphics extensions we use.
    • Installation instructions are here.
  • SWIG: Required for building dependencies.
    • Use the package manager of your system (e.g.
      apt
      on Ubuntu,
      brew
      on MacOS) to install, or download here.

Next, run the following commands in the root directory of this project to complete the setup. First, run the

pip
command to install the rest of the libraries required for these tutorials, including Ray. Then, run the provided script to install a graphing library extension in Jupyter Lab and perform other tasks.
pip install -r requirements.txt
tools/fix-jupyter.sh

If you are using Windows, see the Fixing Jupyter Lab on Windows below for an alternative to using

tools/fix-jupyter.sh
.

Fixing Jupyter Lab on Windows

The

tools/fix-jupyter.sh
shell script runs the following commands. If you are using Windows, run them yourself as shown here.

First, see if the following

pyviz
extension is installed:
jupyter labextension check --installed "@pyviz/jupyterlab_pyviz"

If not, run this command:

jupyter labextension install "@pyviz/jupyterlab_pyviz"

Finally, run these commands:

jupyter labextension update --all
jupyter lab build
jupyter labextension list

Final Installation Notes

If you use Jupyter a lot, consider installing Kite on your machine and the Jupter Lab plugin for Kite. Installation and usage instructions are here.

When you have finished working through the tutorials, run the script

tools/cleanup.sh
, which prints temporary files, checkpoint directories, etc. that were created during the lessons. You might want to remove these as they can add up to 100s of MBs.

Note: A Windows version of this script is TBD.

Launching the Tutorials

The previous steps installed Jupyter Lab, the notebook-based environment we'll use for all the lessons. To start run the following command in the project root directory:

jupyter lab

It should automatically open a browser window with the lab environment, but if not, the console output will show the URL you should use.

Tip: If you get an error that

jupyter
can't be found and you are using the Anaconda setup, make sure you activated the
anyscale-academy
environment, as shown above.

Which Tutorials Are Right for Me?

Here is a recommended reading list, based on your interests:

| You Are... | Best Tutorials | | :--------- | :------------- | | A developer who is new to Ray | First, Ray Crash Course, then Advanced Ray | | A developer who is experienced with Ray | Advanced Ray (alpha release) | | A developer or data scientist interested in Reinforcement Learning | Ray RLlib | | A developer or data scientist interested in Hyperparameter Tuning | Ray Tune | | A developer or data scientist interested in accelerated model training with PyTorch |See the Ray SGD lesson in the Ray Tune tutorial | | A developer or data scientist interested in model serving | Ray Serve | | A DevOps engineer interested in managing Ray clusters | Ray Cluster Launcher (forthcoming) |

See the Overview notebook for detailed, up-to-date descriptions for each tutorial and the lessons it contains.

Troubleshooting and Further Information

See the Troubleshooting, Tips, and Tricks notebook.

For details on the Ray API and the ML libraries, see the Ray Docs. For other information, see ray.io, including the Ray blog.

Ray started at U.C. Berkeley RISELab. It is now developed in artisanal, small batches at Anyscale.

Building Docker Images

NOTE: At this time, the Docker images only run on the Anyscale platform!!

Use the script

tools/make-docker-images.sh
to create two Docker images,
academy-base
and
academy-all
. Use the
--help
option to see the arguments and environment variables it uses. For example, to use a tagged GitHub release of the Academy code,
v1.2.3
:
$ tools/make-docker-image.sh v2.0.0-RC1 --docker-tag 2.0.0.1 --docker-tag latest

Using the Academy repo tagged release

v2.0.0-RC1
, this command creates two Docker images, each of which is has two "virtual" copies tagged
2.0.0.1
and
latest
. (The copies are identical, so no extra space is actually used. You specify as many as you want.) They are also uploaded to Anyscale's Docker Hub. If you omit the
--docker-tag
argument, the Git tag is used as the image tag, with the
v
removed.

One image is

anyscale/academy-base
, which has everything except the tutorials themselves. It has the required Anaconda environment setup and configured Jupyter Lab environment, etc. The
base
image takes a while to build, but it should only need rebuilding for each new Ray release. The Docker file used is
docker/Dockerfile-academy-base
. Note that a Conda environment is created in this build using
./environment-docker.yml
.

The second image is

anyscale/academy-all
, which is built upon
academy-base
. It has the tutorial materials and builds very quickly compared to
base
. The Docker file used is
docker/Dockerfile-academy-all
.

Use

all
or no arguments (the
make
targets) to build both images and push them to Docker Hub. You must run
docker login --username ...
before building the
*-upload
targets described next.

Here are the "interesting" targets you might specify to fine tune what's done:

| Target | Purpose | | :-------------- | :------ | |

all
| Build both images and upload them to Docker Hub (default target). | |
docker-images
| Build both images, but don't upload them. | |
docker-upload
| Upload both images. Assumes they are already built. | |
academy-base
| Build and upload the
base
image. | |
academy-all
| Build and upload the
all
image. |

There are other options you can try to customize what happens. Use the

--help
flag to find out.

NOTES:

  1. When building releases, use
    latest
    in the list of
    DOCKER_TAGS
    . The
    academy-live-events
    repo uses this image tag by default for creating sessions!
  2. The
    make
    rules are nontrival. Pass
    -n
    to print out the expansions of them if you are unfamiliar with
    make
    syntax or just want to see what commands would be executed.
  3. If the Docker build errors out with code 137, first try cleaning old images and containers (
    docker ps -a; docker rm ...
    and
    docker images; docker rmi ...
    ). Next try restarting Docker. What's most likely to work is to increase the memory allocated to the Docker process. On MacOS, use the Preferences to do this. If that doesn't work, try increasing the swap and disk image sizes.

WARNING: It took over a week for me to successfully create the first versions of these Docker images. JupyterLab configurations, in particular, are very fragile with regards to some of the animated graphics in Ray Crash Course. So, only modify the builds with great caution and test everything carefully!! Also, note that

environment-docker.yml
hard-codes Python 3.7.7. Using 3.7 causes runtime failures in the Anyscale platform!!!

Ray Summit 2021

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.