Update docs (#1765)

cortexlabs · Jan 6, 2021 · c3c1da7 · c3c1da7
1 parent 324efd1
commit c3c1da7
Show file tree

Hide file tree

Showing 6 changed files with 94 additions and 70 deletions.
diff --git a/README.md b/README.md
@@ -51,33 +51,34 @@ cortex is ready!
 #### Define an API
 
 ```python
-class PythonPredictor:
-  def __init__(self, config):
-    from transformers import pipeline
+# predictor.py
 
-    self.model = pipeline(task="text-generation")
+from transformers import pipeline
 
-  def predict(self, payload):
-    return self.model(payload["text"])[0]
+class PythonPredictor:
+    def __init__(self, config):
+        self.model = pipeline(task="text-generation")
 
-requirements = ["tensorflow", "transformers"]
+    def predict(self, payload):
+        return self.model(payload["text"])[0]
 ```
 
 #### Configure an API
 
-```python
-api_spec = {
-  "name": "text-generator",
-  "kind": "RealtimeAPI",
-  "compute": {
-    "gpu": 1,
-    "mem": "8Gi"
-  },
-  "autoscaling": {
-    "min_replicas": 1,
-    "max_replicas": 10
-  }
-}
+```yaml
+# text_generator.yaml
+
+- name: text-generator
+  kind: RealtimeAPI
+  predictor:
+    type: python
+    path: predictor.py
+  compute:
+    gpu: 1
+    mem: 8Gi
+  autoscaling:
+    min_replicas: 1
+    max_replicas: 10
 ```
 
 <br>
@@ -92,11 +93,8 @@ api_spec = {
 
 #### Deploy to your cluster
 
-```python
-import cortex
-
-cx = cortex.client("aws")
-cx.create_api(api_spec, predictor=PythonPredictor, requirements=requirements)
+```bash
+$ cortex deploy text_generator.yaml
 
 # creating http://example.com/text-generator
 ```

diff --git a/docs/workloads/realtime/example.md b/docs/workloads/realtime/example.md
@@ -10,47 +10,73 @@ Deploy realtime APIs that can respond to prediction requests on demand.
 * Metrics and log aggregation
 * Rolling updates
 
-## How it works
-
-### Install cortex
+## Install Cortex
 
 ```bash
 $ pip install cortex
 ```
 
-### Spin up a cluster on AWS
+## Create a cluster on AWS
+
+```yaml
+# cluster.yaml
+
+region: us-east-1
+instance_type: g4dn.xlarge
+min_instances: 1
+max_instances: 3
+spot: true
+```
 
 ```bash
-$ cortex cluster up
+$ cortex cluster up --config cluster.yaml
 ```
 
-### Define a realtime API
+## Deploy a realtime API
+
+### Implement your API
+
+```bash
+$ mkdir text-generator && cd text-generator
+$ touch predictor.py requirements.txt text_generator.yaml
+```
 
 ```python
-# text_generator.py
+# predictor.py
 
-import cortex
+from transformers import pipeline
 
 class PythonPredictor:
     def __init__(self, config):
-        from transformers import pipeline
         self.model = pipeline(task="text-generation")
 
     def predict(self, payload):
         return self.model(payload["text"])[0]
+```
 
-requirements = ["tensorflow", "transformers"]
+```python
+# requirements.txt
+
+transformers
+torch
+```
 
-api_spec = {"name": "text-generator", "kind": "RealtimeAPI"}
+```yaml
+# text_generator.yaml
 
-cx = cortex.client("aws")
-cx.create_api(api_spec, predictor=PythonPredictor, requirements=requirements)
+- name: text-generator
+  kind: RealtimeAPI
+  predictor:
+    type: python
+    path: predictor.py
+  compute:
+    gpu: 1
 ```
 
-### Deploy to AWS
+### Deploy
 
 ```bash
-$ python text_generator.py
+$ cortex deploy text_generator.yaml
 ```
 
 ### Monitor
@@ -68,10 +94,10 @@ $ cortex logs text-generator
 ### Make a request
 
 ```bash
-$ curl https://***.execute-api.us-west-2.amazonaws.com/text-generator -X POST -H "Content-Type: application/json" -d '{"text": "hello world"}'
+$ curl http://***.elb.us-west-2.amazonaws.com/text-generator -X POST -H "Content-Type: application/json" -d '{"text": "hello world"}'
 ```
 
-### Delete the API
+### Delete
 
 ```bash
 $ cortex delete text-generator

diff --git a/docs/workloads/realtime/predictors.md b/docs/workloads/realtime/predictors.md
@@ -285,7 +285,7 @@ Here are some examples:
 #### Making the request
 
 ```bash
-$ curl https://***.amazonaws.com/my-api \
+$ curl http://***.amazonaws.com/my-api \
     -X POST -H "Content-Type: application/json" \
     -d '{"key": "value"}'
 ```
@@ -308,7 +308,7 @@ class PythonPredictor:
 #### Making the request
 
 ```bash
-$ curl https://***.amazonaws.com/my-api \
+$ curl http://***.amazonaws.com/my-api \
     -X POST -H "Content-Type: application/octet-stream" \
     --data-binary @object.pkl
 ```
@@ -349,7 +349,7 @@ class PythonPredictor:
 #### Making the request
 
 ```bash
-$ curl https://***.amazonaws.com/my-api \
+$ curl http://***.amazonaws.com/my-api \
     -X POST \
     -F "text=@text.txt" \
     -F "object=@object.pkl" \
@@ -384,7 +384,7 @@ class PythonPredictor:
 #### Making the request
 
 ```bash
-$ curl https://***.amazonaws.com/my-api \
+$ curl http://***.amazonaws.com/my-api \
     -X POST \
     -d "key=value"
 ```
@@ -407,7 +407,7 @@ class PythonPredictor:
 #### Making the request
 
 ```bash
-$ curl https://***.amazonaws.com/my-api \
+$ curl http://***.amazonaws.com/my-api \
     -X POST -H "Content-Type: text/plain" \
     -d "hello world"
 ```

diff --git a/test/apis/batch/image-classifier/README.md b/test/apis/batch/image-classifier/README.md
@@ -159,7 +159,7 @@ $ cortex get image-classifier --env aws
 
 no submitted jobs
 
-endpoint: https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+endpoint: http://***.elb.us-west-2.amazonaws.com/image-classifier
 ```
 
 <br>
@@ -181,7 +181,7 @@ $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DI
 Now that you've deployed a Batch API, you are ready to submit jobs. You can provide image urls directly in the request by specifying the urls in `item_list`. The curl command below showcases how to submit image urls in the request.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DIR=s3://my-bucket/dir
 $ curl $BATCH_API_ENDPOINT \
     -X POST -H "Content-Type: application/json" \
@@ -223,23 +223,23 @@ $ cortex get image-classifier --env aws
 job id             status    progress   start time                 duration
 69d6faf82e4660d3   running   0/3        20 Jul 2020 01:07:44 UTC   3m26s
 
-endpoint: https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+endpoint: http://***.elb.us-west-2.amazonaws.com/image-classifier
 ```
 
 ### Get the job status with an HTTP request
 
-You can make a GET request to your `<BATCH_API_ENDPOINT>/JOB_ID` to get the status of your job.
+You can make a GET request to your `<BATCH_API_ENDPOINT>?JOB_ID` to get the status of your job.
 
 ```bash
-$ curl https://abcdefg.execute-api.us-west-2.amazonaws.com?jobID=69d6faf82e4660d3
+$ curl http://***.elb.us-west-2.amazonaws.com/image-classifier?jobID=69d6faf82e4660d3
 
 {
     "job_status":{
         "job_id":"69d6faf82e4660d3",
         "api_name":"image-classifier",
         ...
     },
-    "endpoint":"https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier"
+    "endpoint":"https://***.elb.us-west-2.amazonaws.com/image-classifier"
 }
 ```
 
@@ -265,7 +265,7 @@ worker stats
 requested   initializing   running   failed   succeeded
 1           1              0         0        0
 
-job endpoint: https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier/69d6faf82e4660d3
+job endpoint: http://***.elb.us-west-2.amazonaws.com/image-classifier/69d6faf82e4660d3
 ```
 
 ### Stream logs
@@ -328,7 +328,7 @@ Before we submit the job, let's perform a dry run to ensure that only the desire
 Get the endpoint from `cortex get image-classifier` if you haven't done so already.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DIR=s3://my-bucket/dir
 $ curl $BATCH_API_ENDPOINT?dryRun=true \
 -X POST -H "Content-Type: application/json" \
@@ -366,7 +366,7 @@ When you submit a job specifying `delimited_files`, your Batch API will get all
 In this example `urls_0.json` and `urls_1.json` each contain 8 urls. Let's classify the images from the URLs listed in those 2 files.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DIR=s3://my-bucket/dir
 $ curl $BATCH_API_ENDPOINT \
 -X POST -H "Content-Type: application/json" \
@@ -438,7 +438,7 @@ We'll classify the 16 images that can be found here `s3://cortex-examples/image-
 Let's do a dry run to make sure the correct list of images will be submitted to the job.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DIR=s3://my-bucket/dir
 $ curl $BATCH_API_ENDPOINT?dryRun=true \
 -X POST -H "Content-Type: application/json" \
@@ -475,7 +475,7 @@ validations passed
 Let's actually submit the job now. Your Batch API will get all of the input S3 files based on `s3_paths` and will apply the filters specified in `includes` and `excludes`.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ export CORTEX_DEST_S3_DIR=<YOUR_S3_DIRECTORY>  # e.g. export CORTEX_DEST_S3_DIR=s3://my-bucket/dir
 $ curl $BATCH_API_ENDPOINT \
 -X POST -H "Content-Type: application/json" \
@@ -541,7 +541,7 @@ You can download the aggregated results file with `aws s3 cp $CORTEX_DEST_S3_DIR
 You can stop a running job by sending a DELETE request to `<BATCH_API_ENDPOINT>/<JOB_ID>`.
 
 ```bash
-$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://abcdefg.execute-api.us-west-2.amazonaws.com/image-classifier
+$ export BATCH_API_ENDPOINT=<BATCH_API_ENDPOINT>  # e.g. export BATCH_API_ENDPOINT=https://***.elb.us-west-2.amazonaws.com/image-classifier
 $ curl -X DELETE $BATCH_API_ENDPOINT?jobID=69d96a01ea55da8c
 
 stopped job 69d96a01ea55da8c

diff --git a/test/apis/pytorch/text-generator/README.md b/test/apis/pytorch/text-generator/README.md
@@ -85,7 +85,7 @@ $ cortex get text-generator --env aws
 status   up-to-date   requested   last update   avg request   2XX
 live     1            1           1m            -             -
 
-endpoint: https://***.execute-api.us-west-2.amazonaws.com/text-generator
+endpoint: http://***.elb.us-west-2.amazonaws.com/text-generator
 ```
 
 ## Run on GPUs

diff --git a/test/apis/traffic-splitter/README.md b/test/apis/traffic-splitter/README.md
@@ -41,30 +41,30 @@ iris-classifier-onnx   30        live     1           1m            -
 iris-classifier-tf     70        live     1           1m            -             -     -
 
 last updated: 1m
-endpoint: https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier
-example curl: curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+endpoint: http://***.elb.us-west-2.amazonaws.com/iris-classifier
+example curl: curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 ...
 ```
 
 ## Make multiple requests
 
 ```bash
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 
-$ curl https://abcedefg.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+$ curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 setosa
 ```
 
@@ -83,8 +83,8 @@ iris-classifier-onnx   30        live     1           4m            6.00791 ms
 iris-classifier-tf     70        live     1           4m            5.81867 ms    5     -
 
 last updated: 4m
-endpoint: https://comtf6hs64.execute-api.us-west-2.amazonaws.com/iris-classifier
-example curl: curl https://comtf6hs64.execute-api.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
+endpoint: http://***.elb.us-west-2.amazonaws.com/iris-classifier
+example curl: curl http://***.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
 ...
 ```