From 7455610d5a0707d7095ddd43e0d55d38ce6627c5 Mon Sep 17 00:00:00 2001 From: Simon Mo Date: Wed, 15 Apr 2020 12:25:37 -0700 Subject: [PATCH] Serve Doc: Quickstart (#7940) --- doc/source/index.rst | 9 ++- doc/source/serve.rst | 23 ------- doc/source/serve/logo.svg | 1 + doc/source/serve/quickstart.rst | 64 +++++++++++++++++++ doc/source/tune/.gitignore | 1 + python/ray/serve/BUILD | 18 +++++- .../serve/examples/doc/quickstart_class.py | 17 +++++ .../serve/examples/doc/quickstart_function.py | 13 ++++ 8 files changed, 121 insertions(+), 25 deletions(-) delete mode 100644 doc/source/serve.rst create mode 100644 doc/source/serve/logo.svg create mode 100644 doc/source/serve/quickstart.rst create mode 100644 doc/source/tune/.gitignore create mode 100644 python/ray/serve/examples/doc/quickstart_class.py create mode 100644 python/ray/serve/examples/doc/quickstart_function.py diff --git a/doc/source/index.rst b/doc/source/index.rst index 4e3441387..9f5b0b816 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,12 +17,14 @@ Ray is packaged with the following libraries for accelerating machine learning w - `Tune`_: Scalable Hyperparameter Tuning - `RLlib`_: Scalable Reinforcement Learning - `RaySGD`_: Distributed Training Wrappers +- `RayServe`_: Scalable and Programmable Serving Star us on `on GitHub`_. You can also get started by visiting our `Tutorials `_. For the latest wheels (nightlies), see the `installation page `__. .. _`on GitHub`: https://github.com/ray-project/ray .. _`RaySGD`: raysgd/raysgd.html +.. _`RayServe`: serve/quickstart.html .. important:: Join our `community slack `_ to discuss Ray! @@ -281,6 +283,12 @@ Getting Involved raysgd/raysgd_tensorflow.rst raysgd/raysgd_ref.rst +.. toctree:: + :maxdepth: -1 + :caption: RayServe + + serve/quickstart.rst + .. toctree:: :maxdepth: -1 :caption: Other Libraries @@ -289,7 +297,6 @@ Getting Involved joblib.rst iter.rst pandas_on_ray.rst - serve.rst .. toctree:: :maxdepth: -1 diff --git a/doc/source/serve.rst b/doc/source/serve.rst deleted file mode 100644 index 4f5425f7e..000000000 --- a/doc/source/serve.rst +++ /dev/null @@ -1,23 +0,0 @@ -Ray Serve -========= - -.. _`issue on GitHub`: https://github.com/ray-project/ray/issues - -Ray Serve is a serving library that exposes python function/classes to HTTP. -It has built-in support for flexible traffic policy. This means you can easy -split incoming traffic to multiple implementations. - -.. warning:: - - Ray Serve is under development and its API may be revised in future Ray releases. If you encounter any bugs, please file an `issue on GitHub`_. - -With Ray Serve, you can deploy your services at any scale. - -Quickstart ----------- -.. literalinclude:: ../../python/ray/serve/examples/echo_full.py - -API ---- -.. automodule:: ray.serve - :members: diff --git a/doc/source/serve/logo.svg b/doc/source/serve/logo.svg new file mode 100644 index 000000000..c7e6b6fbe --- /dev/null +++ b/doc/source/serve/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/doc/source/serve/quickstart.rst b/doc/source/serve/quickstart.rst new file mode 100644 index 000000000..89780afb3 --- /dev/null +++ b/doc/source/serve/quickstart.rst @@ -0,0 +1,64 @@ +RayServe: Scalable and Programmable Serving +============================================ + +.. image:: logo.svg + :align: center + +.. note:: + If you want to try out Serve, join our `community slack `_ + and discuss in ``#serve`` channel. + +There are generally two ways of serving machine learning applications at scale. +The first is wrapping your application in a traditional web server. This approach +is easy but hard to scale each component, and easily leading to high memory usage +as well as concurrency issue. The other approach is to use a cloud-hosted solution +like SageMaker or TFServing. These solutions have high learning costs and lead to +vendor lock-in. + +Serve is a serving library built on top of ray. It is easy-to-use and flexible. + +- Serve is **framework agnostics** and extensible. You can serve your scikit-learn, + PyTorch, and TensorFlow models in the same framework. +- Serve gives you end-to-end control over your API. Your input is just a **Flask + request** instead of arrays. +- Serve scales to many machines. With a single API call, you can run scale your + models to hundreds of GPUs. +- Serve decouples routing and handling so you can update or **A/B test** your models + with zero downtime. +- Serve uses **Python as the configuration language**. Tired of writing repetitive YAMLs + or JSON to configure your services? Serve can be configured directly using the + Python API. +- Serve has built-in **batching and SLO awareness**. This means Serve will maximally + utilize the hardware and reorder queries to meet your latency objective. +- With Ray Autoscaler, you can deploy Serve to **any cloud** (or Kubernetes). + + +Quick start +----------- +Serve a stateless function: + +.. literalinclude:: ../../../python/ray/serve/examples/doc/quickstart_function.py + +Serve a stateful class: + +.. literalinclude:: ../../../python/ray/serve/examples/doc/quickstart_class.py + + +``@serve.route`` decorator is similar to the Flask ``route`` decorator. You can +decorate a function or a class. It specifies how request for HTTP is routed to +your function. + +To make your function servable, the function just need to take in a flask +request as first argument. Your input for web request are just flask request +object, you don't need to learn new API. To make your class servable, implement +``__call__`` method taking in the flask request as well. + +Learn more +---------- +- Serve architecture in depth +- Serve how-to guides + + - Scikit-learn serving with composition + - PyTorch serving with batching + +- Serve deployment guides \ No newline at end of file diff --git a/doc/source/tune/.gitignore b/doc/source/tune/.gitignore new file mode 100644 index 000000000..8f18b41db --- /dev/null +++ b/doc/source/tune/.gitignore @@ -0,0 +1 @@ +generated_guides/ diff --git a/python/ray/serve/BUILD b/python/ray/serve/BUILD index 6250e978d..fbe61852d 100644 --- a/python/ray/serve/BUILD +++ b/python/ray/serve/BUILD @@ -18,11 +18,27 @@ py_test( deps = [":serve_lib"], ) -# Make sure the example showing in doc is tested py_test( name = "echo_full", size = "small", srcs = glob(["examples/*.py"]), tags = ["exclusive"], deps = [":serve_lib"] +) + +# Make sure the example showing in doc is tested +py_test( + name = "quickstart_class", + size = "small", + srcs = glob(["examples/doc/*.py"]), + tags = ["exclusive"], + deps = [":serve_lib"] +) + +py_test( + name = "quickstart_function", + size = "small", + srcs = glob(["examples/doc/*.py"]), + tags = ["exclusive"], + deps = [":serve_lib"] ) \ No newline at end of file diff --git a/python/ray/serve/examples/doc/quickstart_class.py b/python/ray/serve/examples/doc/quickstart_class.py new file mode 100644 index 000000000..c215aa594 --- /dev/null +++ b/python/ray/serve/examples/doc/quickstart_class.py @@ -0,0 +1,17 @@ +from ray import serve +import requests + +serve.init() + + +@serve.route("/counter") +class Counter: + def __init__(self): + self.count = 0 + + def __call__(self, flask_request): + return {"current_counter": self.count} + + +requests.get("http://127.0.0.1:8000/counter").json() +# > {"current_counter": self.count} diff --git a/python/ray/serve/examples/doc/quickstart_function.py b/python/ray/serve/examples/doc/quickstart_function.py new file mode 100644 index 000000000..e2225bf4e --- /dev/null +++ b/python/ray/serve/examples/doc/quickstart_function.py @@ -0,0 +1,13 @@ +from ray import serve +import requests + +serve.init() + + +@serve.route("/hello") +def echo(flask_request): + return "hello " + flask_request.args.get("name", "serve!") + + +requests.get("http://127.0.0.1:8000/hello").text +# > "hello serve!"