Minor readability changes (substratusai#16)

* Minor readability changes
* refined to use the hf-based facebook model

Author: brandonjbjelland

README.md

@@ -3,73 +3,71 @@
 This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 You can view live website here: [https://substratus.ai](https://substratus.ai)
 
-### Installation
+## Installation
 
-```
+```bash
 yarn
 ```
 
-### Local Development
+## Local Development
 
-```
+```bash
 yarn start
-# npm start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-#### Notebooks
+### Notebooks
 
 A lot of the documents on this website are generated from Jupyter Notebooks. This allows for testing documentation.
 
 To edit the notebook files, you can either start a notebook (see below) or use VSCode which can edit notebooks directly.
 
-```
+```bash
 npm run notebook
 ```
 
 Convert the notebook files to markdown.
 
-
-```
+```bash
 npm run convert-notebooks
 ```
 
 You can clear notebook outputs:
 
-```
+```bash
 npm run clear-notebooks
 ```
 
-### Build
+## Build
 
-```
+```bash
 yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
 Using SSH:
 
-```
+```bash
 USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```bash
 GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
 
-### Assets
+## Assets
 
-#### Main Icon
+### Main Icon
 
-Source: https://favicon.io/favicon-generator/
+Source: <https://favicon.io/favicon-generator/>
 
 See: `./scratch/favicon_io/`
 
@@ -78,13 +76,12 @@ Settings:
 * Letter: "S" (capital)
 * Font: Saira Stencil One
 
-#### General Icons
+### General Icons
 
-Source: https://fonts.google.com/icons
+Source: <https://fonts.google.com/icons>
 
 Settings:
 
 * Weight: 100 (min)
 * Grade: 0 (middle)
 * Optical Size: 48 (max)
-

docs/introduction.md

@@ -5,13 +5,13 @@ slug: "/"
 
 # Introduction
 
-Substratus is a cross cloud substrate for training and serving ML models. Substratus extends the Kubernetes control plane to orchestrate ML operations through the addition of new API endpoints: Model, ModelServer, Dataset, and Notebook.
+Substratus is a cross-cloud substrate for training and serving ML models. Substratus extends the Kubernetes control plane to orchestrate ML operations through the addition of new API endpoints: Model, ModelServer, Dataset, and Notebook.
 
 ## Why Substratus?
 
-* Train and serve models from within your cloud account. Your data stays private.
+* Train and serve models from within your cloud account, on a portable platform. Your data stays private.
 * Leverage containers to avoid library lock-in and dependency wrangling.
-* Let substratus calculate your resource requirements and automatically provision GPUs, CPUs, and Memory.
+* Let substratus calculate your resource requirements and automatically provision GPUs, CPUs, Storage, and Memory.
 * Adopt best practice conventions by default.
 * Train pre-packaged state of the art models on your own datasets.
 * Leverage GitOps out of the box.
@@ -23,4 +23,3 @@ Substratus is a cross cloud substrate for training and serving ML models. Substr
 <div class="video-container">
   <iframe class="video" src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 </div>
-

docs/quickstart.ipynb

@@ -1,6 +1,7 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "708b18ae-c2ed-4299-9ddd-8375428521fb",
    "metadata": {
@@ -15,7 +16,7 @@
     "\n",
     "<!-- THE MARKDOWN (.md) FILE IS GENERATED FROM THE NOTEBOOK (.ipynb) FILE -->\n",
     "\n",
-    "In this quickstart guide, you will install Substratus into a Google Cloud project. You will then explore how Substratus can be used to build and deploy Open Source LLMs.\n",
+    "In this quickstart guide, you will install Substratus into a Google Cloud Platform project. Then you'll explore how Substratus can be used to build and deploy Open Source LLMs.\n",
     "\n",
     "NOTE: Support for AWS ([GitHub Issue #12](https://github.com/substratusai/substratus/issues/12)) and Azure ([GitHub Issue #63](https://github.com/substratusai/substratus/issues/63)) is planned. Give those issues a thumbs up if you would like to see them prioritized.\n",
     "\n",
@@ -27,6 +28,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3d69245f-c46c-4a2a-9ea3-8762eac462e8",
    "metadata": {},
@@ -87,6 +89,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "c58c96c7-b086-49ec-9963-e8ad6ff01d62",
    "metadata": {},
@@ -106,28 +109,30 @@
    "outputs": [],
    "source": [
     "!docker run -it \\\n",
-    "  -v $HOME/.kube:/root/.kube \\\n",
+    "  -v ${HOME}/.kube:/root/.kube \\\n",
     "  -e PROJECT=$(gcloud config get project) \\\n",
     "  -e TOKEN=$(gcloud auth print-access-token) \\\n",
     "  substratusai/installer gcp-up.sh"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "54555fb1-8bdf-47b0-b97c-177b3db4ddad",
    "metadata": {},
    "source": [
-    "Your kubectl command should now be pointing at the substratus cluster."
+    "`kubectl` should now be pointing at the substratus cluster."
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "e06320d8-daf9-4199-bf74-ac24129ebeda",
    "metadata": {},
    "source": [
     "## Build and Deploy an Open Source Model\n",
     "\n",
-    "To keep things quick, a small model (125 million parameters) will be used."
+    "To keep this quick, we'll use a small model (125 million parameters)."
    ]
   },
   {
@@ -141,11 +146,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "f6288b3b-112b-4a2f-afad-cd1728263d3c",
    "metadata": {},
    "source": [
-    "A container build process is now running in the Substratus cluster. You can declare that you would like the built model to be deployed by applying a ModelServer manifest."
+    "A container build process is now running in the Substratus cluster. Let's also deploy the built model by applying a ModelServer manifest. ModelServer should start serving shortly after the Model build finishes (~3 minutes)."
    ]
   },
   {
@@ -159,6 +165,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "f57db76a-ad3d-42c4-8612-dbab31b8d9c6",
    "metadata": {},
@@ -177,14 +184,16 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "f8408d23-92c6-435d-a510-a5e0bae0ed01",
    "metadata": {},
    "source": [
-    "When the ModelServer is reporting a `Ready` status, proceed to the next section to test it out."
+    "When the ModelServer reports a `Ready` status, proceed to the next section to test it out."
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "239ef216-9318-4679-83f0-98fcbed2a32c",
    "metadata": {
@@ -193,7 +202,7 @@
    "source": [
     "## Testing out the Model Server\n",
     "\n",
-    "The way every company chooses to expose a model will be different. In most cases models are integrated into other business applications and are rarely exposed directly to the internet. Substratus will only serve the model within the Kubernetes cluster (with a Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object). The choice of how to expose the model to your users is up to you.\n",
+    "The way every company chooses to expose a model will be different. In most cases models are integrated into other business applications and are rarely exposed directly to the Internet. By default, substratus will only serve the model within the Kubernetes cluster (with a Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object). From here, it's up to you to expose the model to a wider network (e.g., the internal VPC network or the Internet) via annotated Service or Ingress objects.\n",
     "\n",
     "In order to access the model for exploratory purposes, forward ports from within the cluster to your local machine."
    ]
@@ -209,14 +218,35 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "8bca86a6-8550-4884-a7fc-83b545ffe278",
    "metadata": {},
    "source": [
-    "The packaged model server ships with an API (for application integration) and a GUI interface (for debugging). You can now open up your browser at [http://localhost:8080](http://localhost:8080) and talk to your model!"
+    "All substratus ModelServers ship with an API and interactive frontend. Open up your browser to [http://localhost:8080/](http://localhost:8080/) and talk to your model! Alternatively, request text generation via the HTTP API:"
    ]
   },
   {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "90825af1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! curl http://localhost:8080/v1/completions \\\n",
+    "  -H \"Content-Type: application/json\" \\\n",
+    "  -d '{ \\\n",
+    "    \"model\": \"facebook-opt-125m\", \\\n",
+    "    \"prompt\": \"The quick brown fox \", \\\n",
+    "    \"max_tokens\": 30, \\\n",
+    "    \"temperature\": 0 \\\n",
+    "  }'\n",
+    "  # choices[0].text will very different\n",
+    "{\"id\":\"cmpl-2d4c8871b20dc45e6ac98322\",\"object\":\"text_completion\",\"created\":1688628294,\"model\":\"facebook-opt-125m\",\"choices\":[{\"text\":\"I've read Patrick Beut, Richard Eichel, Elliot Gagné\",\"index\":0,\"logprobs\":null,\"finish_reason\":\"length\"}],\"usage\":{\"prompt_tokens\":1,\"completion_tokens\":16,\"total_tokens\":17}}"
+   ]
+  },
+  {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "95a9966d-5679-4208-9b28-0323aa80cd79",
    "metadata": {},
@@ -225,6 +255,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "cdb508e5-a7e9-4d94-a4d6-f3b4b2cf4e3f",
    "metadata": {},
@@ -245,6 +276,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "c6b78cea-8d41-4319-8769-2fa3ee0e02ff",
    "metadata": {},
@@ -266,6 +298,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "a21c7867-4e73-429c-a8d8-3c0792eb52b3",
    "metadata": {},

docs/quickstart.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 <!-- THE MARKDOWN (.md) FILE IS GENERATED FROM THE NOTEBOOK (.ipynb) FILE -->
 
-In this quickstart guide, you will install Substratus into a Google Cloud project. You will then explore how Substratus can be used to build and deploy Open Source LLMs.
+In this quickstart guide, you will install Substratus into a Google Cloud Platform project. Then you'll explore how Substratus can be used to build and deploy Open Source LLMs.
 
 NOTE: Support for AWS ([GitHub Issue #12](https://github.com/substratusai/substratus/issues/12)) and Azure ([GitHub Issue #63](https://github.com/substratusai/substratus/issues/63)) is planned. Give those issues a thumbs up if you would like to see them prioritized.
 
@@ -49,24 +49,24 @@ Create a substratus GKE cluster along with supporting infrastructure (buckets, s
 
 ```bash
 docker run -it \
-  -v $HOME/.kube:/root/.kube \
+  -v ${HOME}/.kube:/root/.kube \
   -e PROJECT=$(gcloud config get project) \
   -e TOKEN=$(gcloud auth print-access-token) \
   substratusai/installer gcp-up.sh
 ```
 
-Your kubectl command should now be pointing at the substratus cluster.
+`kubectl` should now be pointing at the substratus cluster.
 
 ## Build and Deploy an Open Source Model
 
-To keep things quick, a small model (125 million parameters) will be used.
+To keep this quick, we'll use a small model (125 million parameters).
 
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/substratusai/substratus/main/examples/facebook-opt-125m/model.yaml
 ```
 
-A container build process is now running in the Substratus cluster. You can declare that you would like the built model to be deployed by applying a ModelServer manifest.
+A container build process is now running in the Substratus cluster. Let's also deploy the built model by applying a ModelServer manifest. ModelServer should start serving shortly after the Model build finishes (~3 minutes).
 
 
 ```bash
@@ -80,11 +80,11 @@ You can check on the progress of both processes using a single command.
 kubectl get ai
 ```
 
-When the ModelServer is reporting a `Ready` status, proceed to the next section to test it out.
+When the ModelServer reports a `Ready` status, proceed to the next section to test it out.
 
 ## Testing out the Model Server
 
-The way every company chooses to expose a model will be different. In most cases models are integrated into other business applications and are rarely exposed directly to the internet. Substratus will only serve the model within the Kubernetes cluster (with a Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object). The choice of how to expose the model to your users is up to you.
+The way every company chooses to expose a model will be different. In most cases models are integrated into other business applications and are rarely exposed directly to the Internet. By default, substratus will only serve the model within the Kubernetes cluster (with a Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/) object). From here, it's up to you to expose the model to a wider network (e.g., the internal VPC network or the Internet) via annotated Service or Ingress objects.
 
 In order to access the model for exploratory purposes, forward ports from within the cluster to your local machine.
 
@@ -93,7 +93,21 @@ In order to access the model for exploratory purposes, forward ports from within
 kubectl port-forward service/facebook-opt-125m-modelserver 8080:8080
 ```
 
-The packaged model server ships with an API (for application integration) and a GUI interface (for debugging). You can now open up your browser at [http://localhost:8080](http://localhost:8080) and talk to your model!
+All substratus ModelServers ship with an API and interactive frontend. Open up your browser to [http://localhost:8080/](http://localhost:8080/) and talk to your model! Alternatively, request text generation via the HTTP API:
+
+
+```bash
+ curl http://localhost:8080/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{ \
+    "model": "facebook-opt-125m", \
+    "prompt": "The quick brown fox ", \
+    "max_tokens": 30, \
+    "temperature": 0 \
+  }'
+  # choices[0].text will very different
+{"id":"cmpl-2d4c8871b20dc45e6ac98322","object":"text_completion","created":1688628294,"model":"facebook-opt-125m","choices":[{"text":"I've read Patrick Beut, Richard Eichel, Elliot Gagné","index":0,"logprobs":null,"finish_reason":"length"}],"usage":{"prompt_tokens":1,"completion_tokens":16,"total_tokens":17}}
+```
 
 If you are interested in continuing your journey through Substratus, take a look at the [Guided Walkthrough](./category/walkthrough).
 

docusaurus.config.js

@@ -112,6 +112,10 @@ const config = {
                 label: "Stack Overflow",
                 href: "https://stackoverflow.com/questions/tagged/substratus",
               },
+              {
+                label: "Discord",
+                href: "https://discord.gg/RcUShexGu8",
+              },
             ],
           },
           {