wassname/ray
1
0
Fork 0
mirror of https://github.com/wassname/ray.git synced 2026-09-10 12:38:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

[api] Initial API deprecations for Ray 1.0 (#10325)

Browse Source
This commit is contained in:
Eric Liang
2020-08-28 15:03:50 -07:00
committed by GitHub
parent 9c25ca6f5e
commit 519354a39a
75 changed files with 223 additions and 2414 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/actors.rst
+1 -1
View File
@@ -72,7 +72,7 @@ Resources with Actors
You can specify that an actor requires CPUs or GPUs in the decorator. While Ray has built-in support for CPUs and GPUs, Ray can also handle custom resources.
When using GPUs, Ray will automatically set the environment variable ``CUDA_VISIBLE_DEVICES`` for the actor after instantiated. The actor will have access to a list of the IDs of the GPUs
that it is allowed to use via ``ray.get_gpu_ids(as_str=True)``. This is a list of strings,
that it is allowed to use via ``ray.get_gpu_ids()``. This is a list of strings,
like ``[]``, or ``['1']``, or ``['2', '5', '6']``. Under some circumstances, the IDs of GPUs could be given as UUID strings instead of indices (see the `CUDA programming guide <https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#env-vars>`__).
.. code-block:: python
doc/source/configure.rst
+1 -45
View File
@@ -159,7 +159,7 @@ To add authentication via the Python API, start Ray using:
.. code-block:: python
ray.init(redis_password="password")
ray.init(_redis_password="password")
To add authentication via the CLI or to connect to an existing Ray instance with
password-protected Redis ports:
@@ -182,48 +182,4 @@ to localhost when the ray is started using ``ray.init``.
See the `Redis security documentation <https://redis.io/topics/security>`__
for more information.
Using the Object Store with Huge Pages
--------------------------------------
Plasma is a high-performance shared memory object store originally developed in
Ray and now being developed in `Apache Arrow`_. See the `relevant
documentation`_.
On Linux, it is possible to increase the write throughput of the Plasma object
store by using huge pages. You first need to create a file system and activate
huge pages as follows.
.. code-block:: shell
sudo mkdir -p /mnt/hugepages
gid=`id -g`
uid=`id -u`
sudo mount -t hugetlbfs -o uid=$uid -o gid=$gid none /mnt/hugepages
sudo bash -c "echo $gid > /proc/sys/vm/hugetlb_shm_group"
# This typically corresponds to 20000 2MB pages (about 40GB), but this
# depends on the platform.
sudo bash -c "echo 20000 > /proc/sys/vm/nr_hugepages"
**Note:** Once you create the huge pages, they will take up memory which will
never be freed unless you remove the huge pages. If you run into memory issues,
that may be the issue.
You need root access to create the file system, but not for running the object
store.
You can then start Ray with huge pages on a single machine as follows.
.. code-block:: python
ray.init(huge_pages=True, plasma_directory="/mnt/hugepages")
In the cluster case, you can do it by passing ``--huge-pages`` and
``--plasma-directory=/mnt/hugepages`` into ``ray start`` on any machines where
huge pages should be enabled.
See the relevant `Arrow documentation for huge pages`_.
.. _`Apache Arrow`: https://arrow.apache.org/
.. _`relevant documentation`: https://arrow.apache.org/docs/python/plasma.html#the-plasma-in-memory-object-store
.. _`Arrow documentation for huge pages`: https://arrow.apache.org/docs/python/plasma.html#using-plasma-with-huge-pages
doc/source/index.rst
-1
View File
@@ -206,7 +206,6 @@ Academic Papers
joblib.rst
iter.rst
pandas_on_ray.rst
projects.rst
.. toctree::
:hidden:
doc/source/package-ref.rst
+4 -45
View File
@@ -74,12 +74,12 @@ ray.get_resource_ids
.. autofunction:: ray.get_resource_ids
.. _ray-get_webui_url-ref:
.. _ray-get_dashboard_url-ref:
ray.get_webui_url
~~~~~~~~~~~~~~~~~
ray.get_dashboard_url
~~~~~~~~~~~~~~~~~~~~~
.. autofunction:: ray.get_webui_url
.. autofunction:: ray.get_dashboard_url
.. _ray-shutdown-ref:
@@ -88,21 +88,6 @@ ray.shutdown
.. autofunction:: ray.shutdown
.. _ray-register_custom_serializer-ref:
ray.register_custom_serializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autofunction:: ray.register_custom_serializer
.. _ray-profile-ref:
ray.profile
~~~~~~~~~~~
.. autofunction:: ray.profile
.. _ray-method-ref:
ray.method
@@ -123,13 +108,6 @@ ray.nodes
.. autofunction:: ray.nodes
.. _ray-objects-ref:
ray.objects
~~~~~~~~~~~
.. autofunction:: ray.objects
.. _ray-timeline-ref:
ray.timeline
@@ -137,13 +115,6 @@ ray.timeline
.. autofunction:: ray.timeline
.. _ray-object_transfer_timeline-ref:
ray.object_transfer_timeline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autofunction:: ray.object_transfer_timeline
.. _ray-cluster_resources-ref:
ray.cluster_resources
@@ -221,24 +192,12 @@ The Ray Command Line API
:prog: ray stack
:show-nested:
.. _ray-stat-doc:
.. click:: ray.scripts.scripts:statistics
:prog: ray statistics
:show-nested:
.. _ray-memory-doc:
.. click:: ray.scripts.scripts:memory
:prog: ray memory
:show-nested:
.. _ray-globalgc-doc:
.. click:: ray.scripts.scripts:globalgc
:prog: ray globalgc
:show-nested:
.. _ray-timeline-doc:
.. click:: ray.scripts.scripts:timeline
doc/source/projects.rst
-189
View File
@@ -1,189 +0,0 @@
Ray Projects (Experimental)
===========================
Ray projects make it easy to package a Ray application so it can be
rerun later in the same environment. They allow for the sharing and
reliable reuse of existing code.
Quick start (CLI)
-----------------
.. code-block:: bash
# Creates a project in the current directory. It will create a
# project.yaml defining the code and environment and a cluster.yaml
# describing the cluster configuration. Both will be created in the
# ray-project subdirectory of the current directory.
$ ray project create <project-name>
# Create a new session from the given project. Launch a cluster and run
# the command, which must be specified in the project.yaml file. If no
# command is specified, the "default" command in ray-project/project.yaml
# will be used. Alternatively, use --shell to run a raw shell command.
$ ray session start <command-name> [arguments] [--shell]
# Open a console for the given session.
$ ray session attach
# Stop the given session and terminate all of its worker nodes.
$ ray session stop
Examples
--------
See `the readme <https://github.com/ray-project/ray/blob/master/python/ray/projects/examples/README.md>`__
for instructions on how to run these examples:
- `Open Tacotron <https://github.com/ray-project/ray/blob/master/python/ray/projects/examples/open-tacotron/ray-project/project.yaml>`__:
A TensorFlow implementation of Google's Tacotron speech synthesis with pre-trained model (unofficial)
- `PyTorch Transformers <https://github.com/ray-project/ray/blob/master/python/ray/projects/examples/pytorch-transformers/ray-project/project.yaml>`__:
A library of state-of-the-art pretrained models for Natural Language Processing (NLP)
Tutorial
--------
We will walk through how to use projects by executing the `streaming MapReduce example <auto_examples/plot_streaming.html>`_.
Commands always apply to the project in the current directory.
Let us switch into the project directory with
.. code-block:: bash
cd ray/doc/examples/streaming
A session represents a running instance of a project. Let's start one with
.. code-block:: bash
ray session start
The ``ray session start`` command
will bring up a new cluster and initialize the environment of the cluster
according to the `environment` section of the `project.yaml`, installing all
dependencies of the project.
Now we can execute a command in the session. To see a list of all available
commands of the project, run
.. code-block:: bash
ray session commands
which produces the following output:
.. code-block::
Active project: ray-example-streaming
Command "run":
usage: run [--num-mappers NUM_MAPPERS] [--num-reducers NUM_REDUCERS]
Start the streaming example.
optional arguments:
--num-mappers NUM_MAPPERS
Number of mapper actors used
--num-reducers NUM_REDUCERS
Number of reducer actors used
As you see, in this project there is only a single ``run`` command which has arguments
``--num-mappers`` and ``--num-reducers``. We can execute the streaming
wordcount with the default parameters by running
.. code-block:: bash
ray session execute run
You can interrupt the command with ``<Control>-c`` and attach to the running session by executing
.. code-block:: bash
ray session attach --tmux
Inside the session you can for example edit the streaming applications with
.. code-block:: bash
cd ray-example-streaming
emacs streaming.py
Try for example to add the following lines after the ``for count in counts:`` loop:
.. code-block:: python
if "million" in wordcounts:
print("Found the word!")
and re-run the application from outside the session with
.. code-block:: bash
ray session execute run
The session can be terminated from outside the session with
.. code-block:: bash
ray session stop
Project file format (project.yaml)
----------------------------------
A project file contains everything required to run a project.
This includes a cluster configuration, the environment and dependencies
for the application, and the specific inputs used to run the project.
Here is an example for a minimal project format:
.. code-block:: yaml
name: test-project
description: "This is a simple test project"
repo: https://github.com/ray-project/ray
# Cluster to be instantiated by default when starting the project.
cluster:
config: ray-project/cluster.yaml
# Commands/information to build the environment, once the cluster is
# instantiated. This can include the versions of python libraries etc.
# It can be specified as a Python requirements.txt, a conda environment,
# a Dockerfile, or a shell script to run to set up the libraries.
environment:
requirements: requirements.txt
# List of commands that can be executed once the cluster is instantiated
# and the environment is set up.
# A command can also specify a cluster that overwrites the default cluster.
commands:
- name: default
command: python default.py
help: "The command that will be executed if no command name is specified"
- name: test
command: python test.py --param1={{param1}} --param2={{param2}}
help: "A test command"
params:
- name: "param1"
help: "The first parameter"
# The following line indicates possible values this parameter can take.
choices: ["1", "2"]
- name: "param2"
help: "The second parameter"
Project files have to adhere to the following schema:
.. jsonschema:: ../../python/ray/projects/schema.json
Cluster file format (cluster.yaml)
----------------------------------
This is the same as for the autoscaler, see
:ref:`Cluster Launch page <ref-automatic-cluster>`.
doc/source/serialization.rst
+1 -44
View File
@@ -10,7 +10,7 @@ Since Ray processes do not share memory space, data transferred between workers
Plasma Object Store
-------------------
Plasma is an in-memory object store that is being developed as part of `Apache Arrow`_. Ray uses Plasma to efficiently transfer objects across different processes and different nodes. All objects in Plasma object store are **immutable** and held in shared memory. This is so that they can be accessed efficiently by many workers on the same node.
Plasma is an in-memory object store that is being developed as part of Apache Arrow. Ray uses Plasma to efficiently transfer objects across different processes and different nodes. All objects in Plasma object store are **immutable** and held in shared memory. This is so that they can be accessed efficiently by many workers on the same node.
Each node has its own object store. When data is put into the object store, it does not get automatically broadcasted to other nodes. Data remains local to the writer until requested by another task or actor on another node.
@@ -64,49 +64,6 @@ Serialization notes
- Lock objects are mostly unserializable, because copying a lock is meaningless and could cause serious concurrency problems. You may have to come up with a workaround if your object contains a lock.
Last resort: Custom Serialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If none of these options work, you can try registering a custom serializer with ``ray.register_custom_serializer`` (:ref:`docstring <ray-register_custom_serializer-ref>`):
.. code-block:: python
import ray
ray.init()
class Foo(object):
def __init__(self, value):
self.value = value
def custom_serializer(obj):
return obj.value
def custom_deserializer(value):
object = Foo()
object.value = value
return object
ray.register_custom_serializer(
Foo, serializer=custom_serializer, deserializer=custom_deserializer)
object_ref = ray.put(Foo(100))
assert ray.get(object_ref).value == 100
If you find cases where Ray serialization doesn't work or does something unexpected, please `let us know`_ so we can fix it.
.. _`let us know`: https://github.com/ray-project/ray/issues
Advanced: Huge Pages
~~~~~~~~~~~~~~~~~~~~
On Linux, it is possible to increase the write throughput of the Plasma object store by using huge pages. See the `Configuration page <configure.html#using-the-object-store-with-huge-pages>`_ for information on how to use huge pages in Ray.
.. _`Apache Arrow`: https://arrow.apache.org/
Known Issues
------------
doc/source/tune/user-guide.rst
+1 -13
View File
@@ -472,8 +472,7 @@ decide between the two options.
Redirecting stdout and stderr to files
--------------------------------------
The stdout and stderr streams are usually printed to the console. For remote actors,
Ray collects these logs and prints them to the head process, as long as it
has been initialized with ``log_to_driver=True``, which is the default.
Ray collects these logs and prints them to the head process.
However, if you would like to collect the stream outputs in files for later
analysis or troubleshooting, Tune offers an utility parameter, ``log_to_file``,
@@ -508,17 +507,6 @@ too.
If ``log_to_file`` is set, Tune will automatically register a new logging handler
for Ray's base logger and log the output to the specified stderr output file.
Setting ``log_to_file`` does not disable logging to the driver. If you would
like to disable the logs showing up in the driver output (i.e. they should only
show up in the logfiles), initialize Ray accordingly:
.. code-block:: python
ray.init(log_to_driver=False)
tune.run(
trainable,
log_to_file=True)
.. _tune-debugging:
Debugging
doc/source/using-ray-with-gpus.rst
+1 -1
View File
@@ -33,7 +33,7 @@ remote decorator.
print("ray.get_gpu_ids(): {}".format(ray.get_gpu_ids()))
print("CUDA_VISIBLE_DEVICES: {}".format(os.environ["CUDA_VISIBLE_DEVICES"]))
Inside of the remote function, a call to ``ray.get_gpu_ids(as_str=True)`` will return a
Inside of the remote function, a call to ``ray.get_gpu_ids()`` will return a
list of strings indicating which GPUs the remote function is allowed to use.
Typically, it is not necessary to call ``ray.get_gpu_ids()`` because Ray will
automatically set the ``CUDA_VISIBLE_DEVICES`` environment variable.