Update README.md (#514)

Author: caleb-kaiser

README.md

@@ -1,122 +1,128 @@
 # Deploy machine learning models in production
 
-Cortex is an open source machine learning deployment platform that makes it simple to deploy your machine learning models as web APIs on AWS. It combines TensorFlow Serving, ONNX Runtime, and Flask into a single tool that takes models from S3 and deploys them as web APIs. It also uses Docker and Kubernetes behind the scenes to autoscale, run rolling updates, and support CPU and GPU inference. The project is maintained by a venture-backed team of infrastructure engineers with backgrounds from Google, Illumio, and Berkeley.
-
-<br>
+Cortex is an open source platform that takes machine learning models—trained with nearly any framework—and turns them into production web APIs in one command. <br>
 
 <!-- CORTEX_VERSION_MINOR x2 (e.g. www.cortex.dev/v/0.8/...) -->
 [install](https://www.cortex.dev/install) • [docs](https://www.cortex.dev) • [examples](examples) • [we're hiring](https://angel.co/cortex-labs-inc/jobs) • [email us](mailto:hello@cortex.dev) • [chat with us](https://gitter.im/cortexlabs/cortex)
 
 <br>
 
 <!-- Set header Cache-Control=no-cache on the S3 object metadata (see https://help.github.com/en/articles/about-anonymized-image-urls) -->
-![Demo](https://cortex-public.s3-us-west-2.amazonaws.com/demo/gif/v0.8.gif)
+![Demo](https://cortex-public.s3-us-west-2.amazonaws.com/demo/gif/v0.8.gif)<br>
 
 <br>
 
-## Key features
-
-- **Minimal declarative configuration:** Deployments can be defined in a single `cortex.yaml` file.
-
-- **Autoscaling:** Cortex automatically scales APIs to handle production workloads.
-
-- **Multi framework:** Cortex supports TensorFlow, Keras, PyTorch, Scikit-learn, XGBoost, and more.
-
-- **Rolling updates:** Cortex updates deployed APIs without any downtime.
-
-- **Log streaming:** Cortex streams logs from your deployed models to your CLI.
-
-- **Prediction monitoring:** Cortex can monitor network metrics and track predictions.
+## Quickstart
 
-- **CPU / GPU support:** Cortex can run inference on CPU or GPU infrastructure.
+<!-- CORTEX_VERSION_MINOR (e.g. www.cortex.dev/v/0.8/...) -->
+Below, we'll walk through how to use Cortex to deploy OpenAI's GPT-2 model as a service on AWS. You'll need to [install Cortex](https://www.cortex.dev/install) on your AWS account before getting started.
 
 <br>
 
-## How it works
+### Step 1: Configure your deployment
 
-### Define your deployment using declarative configuration
+<!-- CORTEX_VERSION_MINOR -->
+Define a `deployment` and an `api` resource. A `deployment` specifies a set of APIs that are deployed as a single unit. An `api` makes a model available as a web service that can serve real-time predictions. The configuration below will download the model from the `cortex-examples` S3 bucket. You can run the code that generated the exported GPT-2 model [here](https://colab.research.google.com/github/cortexlabs/cortex/blob/master/examples/text-generator/gpt-2.ipynb).
 
 ```yaml
 # cortex.yaml
 
+- kind: deployment
+  name: text
+
 - kind: api
-  name: my-api
-  model: s3://my-bucket/my-model.onnx
+  name: generator
+  model: s3://cortex-examples/text-generator/gpt-2/124M
   request_handler: handler.py
-  compute:
-    gpu: 1
 ```
 
-### Customize request handling
+<br>
+
+### Step 2: Add request handling
+
+The model requires encoded data for inference, but the API should accept strings of natural language as input. It should also decode the inference output. This can be implemented in a request handler file using the `pre_inference` and `post_inference` functions:
 
 ```python
 # handler.py
 
-# Load data for preprocessing or postprocessing. For example:
-labels = download_labels_from_s3()
+from encoder import get_encoder
+encoder = get_encoder()
 
 
 def pre_inference(sample, metadata):
-  # Python code
+    context = encoder.encode(sample["text"])
+    return {"context": [context]}
 
 
 def post_inference(prediction, metadata):
-  # Python code
+    response = prediction["sample"]
+    return {encoder.decode(response)}
 ```
 
-### Deploy to AWS using the CLI
+<br>
+
+### Step 3: Deploy to AWS
+
+Deploying to AWS is as simple as running `cortex deploy` from your CLI. `cortex deploy` takes the declarative configuration from `cortex.yaml` and creates it on the cluster. Behind the scenes, Cortex containerizes the model, makes it servable using TensorFlow Serving, exposes the endpoint with a load balancer, and orchestrates the workload on Kubernetes.
 
 ```bash
 $ cortex deploy
 
-Deploying ...
-http://***.amazonaws.com/my-api  # Your API is ready!
+deployment started
 ```
 
-### Serve real-time predictions via autoscaling JSON APIs running on AWS
+You can track the status of a deployment using `cortex get`. The output below indicates that one replica of the API was requested and one replica is available to serve predictions. Cortex will automatically launch more replicas if the load increases and spin down replicas if there is unused capacity.
 
 ```bash
-$ curl http://***.amazonaws.com/my-api -d '{"a": 1, "b": 2, "c": 3}'
+$ cortex get generator --watch
+
+status   up-to-date   available   requested   last update   avg latency
+live     1            1           1           8s            123ms
 
-{ prediction: "def" }
+url: http://***.amazonaws.com/text/generator
 ```
 
 <br>
 
-## Installation
+### Step 4: Serve real-time predictions
 
-<!-- CORTEX_VERSION_README_MINOR -->
+Once you have your endpoint, you can make requests:
 
 ```bash
-# Download the install script
-$ curl -O https://raw.githubusercontent.com/cortexlabs/cortex/0.8/cortex.sh && chmod +x cortex.sh
+$ curl http://***.amazonaws.com/text/generator \
+    -X POST -H "Content-Type: application/json" \
+    -d '{"text": "machine learning"}'
 
-# Install the Cortex CLI on your machine: the CLI sends configuration and code to the Cortex cluster
-$ ./cortex.sh install cli
+Machine learning, with more than one thousand researchers around the world today, are looking to create computer-driven machine learning algorithms that can also be applied to human and social problems, such as education, health care, employment, medicine, politics, or the environment...
+```
 
-# Set your AWS credentials
-$ export AWS_ACCESS_KEY_ID=***
-$ export AWS_SECRET_ACCESS_KEY=***
+Any questions? [chat with us](https://gitter.im/cortexlabs/cortex).
 
-# Configure AWS instance settings
-$ export CORTEX_NODE_TYPE="m5.large"
-$ export CORTEX_NODES_MIN="2"
-$ export CORTEX_NODES_MAX="5"
+<br>
 
-# Install the Cortex cluster in your AWS account: the cluster is responsible for hosting your APIs
-$ ./cortex.sh install
-```
+## More examples
 
-<!-- CORTEX_VERSION_MINOR (e.g. www.cortex.dev/v/0.8/...) -->
-See [installation instructions](https://www.cortex.dev/cluster/install) for more details.
+<!-- CORTEX_VERSION_README_MINOR x3 -->
+- [Iris classification](https://github.com/cortexlabs/cortex/tree/master/examples/iris-classifier)
+
+- [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/master/examples/sentiment-analysis) with BERT
+
+- [Image classification](https://github.com/cortexlabs/cortex/tree/master/examples/image-classifier) with Inception v3 and AlexNet
 
 <br>
 
-## Examples
+## Key features
 
-<!-- CORTEX_VERSION_README_MINOR x3 -->
-- [Text generation](https://github.com/cortexlabs/cortex/tree/0.8/examples/text-generator) with GPT-2
+- **Autoscaling:** Cortex automatically scales APIs to handle production workloads.
+
+- **Multi framework:** Cortex supports TensorFlow, Keras, PyTorch, Scikit-learn, XGBoost, and more.
+
+- **CPU / GPU support:** Cortex can run inference on CPU or GPU infrastructure.
+
+- **Rolling updates:** Cortex updates deployed APIs without any downtime.
+
+- **Log streaming:** Cortex streams logs from deployed models to your CLI.
 
-- [Sentiment analysis](https://github.com/cortexlabs/cortex/tree/0.8/examples/sentiment-analysis) with BERT
+- **Prediction monitoring:** Cortex monitors network metrics and tracks predictions.
 
-- [Image classification](https://github.com/cortexlabs/cortex/tree/0.8/examples/image-classifier) with Inception v3
+- **Minimal declarative configuration:** Deployments are defined in a single `cortex.yaml` file.