Update our oumi launch documentation. (#1239)

taenin · web-flow · commit 225d9d76fe2f · 2025-01-26T09:42:04.000-08:00
diff --git a/docs/user_guides/launch/custom_cluster.md b/docs/user_guides/launch/custom_cluster.md
@@ -3,21 +3,7 @@ Similar to custom dataset and model classes, you can register a class for your o
 
 This guide is specifically geared towards individuals who have access to a compute cluster that's not hosted on a common cloud provider (e.g. University/personal compute clusters).
 
-We'll cover the following topics:
-1. Prerequisites
-1. The Oumi Launcher Hierarchy
-1. Creating a CustomClient Class
-1. Creating a CustomCluster Class
-1. Creating a CustomCloud Class
-1. Registering Your CustomCloud
-1. Running a Job on Your Cloud
-
-# Prerequisites
-
-## Oumi Installation
-First, let's install Oumi. You can find detailed instructions [here](/get_started/installation.md).
-
-# The Oumi Launcher Hierarchy
+## The Oumi Launcher Hierarchy
 
 ### Preface
 Before diving into this tutorial, lets discuss the hierarchy of the Oumi Launcher. At this point, it's worth reading through our tutorial on {doc}`/user_guides/launch/deploy` to better understand the end-to-end flow of the launcher. Already read it? Great!
@@ -40,7 +26,7 @@ Clients are a completely optional but highly encouraged class. Clients should en
 
 You can find several implementations of Clients [here](https://github.com/oumi-ai/oumi/tree/main/src/oumi/launcher/clients).
 
-# Creating a CustomClient Class
+## Creating a CustomClient Class
 Let's get started by creating a client for our new cloud, `CustomCloud`. Let's create a simple client that randomly sets the state of the job on submission. It also supports canceling jobs, and turning down clusters:
 
 ``` {code-block} python
@@ -127,7 +113,7 @@ class CustomClient:
         pass
 ```
 
-# Creating a CustomCluster Class
+## Creating a CustomCluster Class
 Now that we have a client that talks to our API, we can use the Client to build a Cluster!
 
 ``` {code-block} python
@@ -200,7 +186,7 @@ class CustomCluster(BaseCluster):
         self.down()
 ```
 
-# Creating a CustomCloud Class
+## Creating a CustomCloud Class
 Let's create a CustomCloud to manage our clusters:
 
 ``` {code-block} python
@@ -256,7 +242,7 @@ class CustomCloud(BaseCloud):
 
 Now all that's left to do is register your CustomCloud!
 
-# Registering Your CustomCloud
+## Registering Your CustomCloud
 By implementing the BaseCloud class, you are now ready to register your cloud with Oumi. First, let's take a look at the clouds that are already registered:
 
 ``` {code-block} python
@@ -285,7 +271,7 @@ print(launcher.which_clouds())
 
 Great, our CustomCloud is there!
 
-## Using Your CustomCloud via the CLI
+### Using Your CustomCloud via the CLI
 
 **‼️ Important ‼️** A few extra steps are needed to use your cloud from the CLI.
 
@@ -317,7 +303,7 @@ You can verify that your cloud is now installed by running:
 oumi launch which
 ```
 
-# Running a Job on Your Cloud
+## Running a Job on Your Cloud
 
 Let's take our new Cloud for a spin:
 
diff --git a/docs/user_guides/launch/deploy.md b/docs/user_guides/launch/deploy.md
@@ -4,105 +4,32 @@ In this tutorial we'll take a working {py:class}`~oumi.core.configs.JobConfig` a
 
 This guide dovetails nicely with our [Finetuning Tutorial](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20Finetuning%20Tutorial.ipynb) where you create your own TrainingConfig and run it locally. Give it a try if you haven't already!
 
-We'll cover the following topics:
-1. Prerequisites
-1. Choosing a Cloud
-1. Preparing Your JobConfig
-1. Launching Your Job
-1. \[Advanced\] Deploying a Training Config
 
-## Prerequisites
-
-### Oumi Installation
-First, let's install Oumi. You can find detailed instructions [here](/get_started/installation.md).
-
-### Creating a working directory
-For this tutorial, we'll use the following folder to save our configs.
-
-``` {code-block} python
-from pathlib import Path
-
-tutorial_dir = "deploy_training_tutorial"
-
-Path(tutorial_dir).mkdir(parents=True, exist_ok=True)
-```
-
-## Choosing a Cloud
-We'll be using the Oumi Launcher to run remote training. To use the launcher, you need to specify which cloud you'd like to run training on.
-We'll list the clouds below:
-
-::::{tab-set}
-:::{tab-item} CLI
-``` {code-block} shell
-oumi launch which
-```
-:::
-
-:::{tab-item} Python
-``` {code-block} python
-import oumi.launcher as launcher
-
-# Print all available clouds
-print(launcher.which_clouds())
-```
-:::
-::::
-
-#### Local Cloud
-If you don't have any clouds set up yet, feel free to use the `local` cloud. This will simply execute your job on your current device as if it's a remote cluster. Hardware requirements are ignored for the `local` cloud.
-
-#### Other Providers
-Note that to use a cloud you must already have an account registered with that cloud provider.
-
-For example, GCP, RunPod, and Lambda require accounts with billing enabled.
-
-Once you've picked a cloud, move on to the next step.
-
-## Preparing Your JobConfig
-Let's get started by creating your {py:class}`~oumi.core.configs.JobConfig`. In the config below, feel free to change `cloud: local` to the cloud you chose in the previous step.
-
-A sample job is provided below:
-````{dropdown} deploy_training_tutorial/job.yaml
-```{code-block} yaml
-name: job-tutorial
-resources:
-  cloud: local
-  # Accelerators is ignored for the local cloud.
-  # This is required for other clouds like GCP, AWS, etc.
-  accelerators: A100
-
-# Upload working directory to remote.
-# If on the local cloud, we CD into the working directory before running the job.
-working_dir: .
-
-envs:
-  TEST_ENV_VARIABLE: '"Hello, World!"'
-  OUMI_LOGGING_DIR: "deploy_training_tutorial/logs"
-
-# `setup` will always be executed once when a cluster is created
-setup: |
-  echo "Running setup..."
-
-run: |
-  set -e  # Exit if any command failed.
+## Launching Your Job
 
-  echo "$TEST_ENV_VARIABLE"
+`````{note}
+Try using our sample helloworld job for this tutorial:
+````{dropdown} configs/examples/misc/hello_world_gcp_job.yaml
+```{literalinclude} ../../../configs/examples/misc/hello_world_gcp_job.yaml
+:language: yaml
 ```
 ````
+`````
 
-## Launching Your Job
+Let's get started with launching a job! Don't worry about the nitty-gritty&mdash;we'll
+address configuring your job in the following sections.
 
 ::::{tab-set}
 :::{tab-item} CLI
 You can easily kick off a job directly from the CLI:
 ```{code-block} shell
-oumi launch up --cluster my-cluster -c deploy_training_tutorial/job.yaml
+oumi launch up --cluster my-cluster -c configs/examples/misc/hello_world_gcp_job.yaml
 ```
 
 At any point you can easily change the cloud where your job will run by modifying the job's `resources.cloud` parameter:
 
 ```{code-block} shell
-oumi launch up --cluster my-cluster -c deploy_training_tutorial/job.yaml --resources.cloud local
+oumi launch up --cluster my-cluster -c configs/examples/misc/hello_world_gcp_job.yaml --resources.cloud local
 ```
 :::
 
@@ -111,7 +38,8 @@ First let's load your {py:class}`~oumi.core.configs.JobConfig`:
 ``` {code-block} python
 import oumi.launcher as launcher
 # Read our JobConfig from the YAML file.
-job_config = launcher.JobConfig.from_yaml(str(Path(tutorial_dir) / "job.yaml"))
+working_dir = "YOUR_WORKING_DIRECTORY" # Specify this value
+job_config = launcher.JobConfig.from_yaml(str(Path(working_dir) / "job.yaml"))
 ```
 
 At any point you can easily change the cloud where your job will run by modifying the job's `resources.cloud` parameter:
@@ -146,8 +74,6 @@ We can quickly check on the status of our job using the `cluster` returned in th
 ``` {code-block} shell
 oumi launch status
 ```
-
-If the job was run on the local cluster, we can view the logs at `deploy_training_tutorial/logs/...`
 :::
 
 :::{tab-item} Python
@@ -159,16 +85,6 @@ while job_status and not job_status.done:
 
 print("Job is done!")
 ```
-
-If the job was run on the local cluster, we can view the logs below:
-
-``` {code-block} python
-logs_dir = Path(tutorial_dir) / "logs"
-for log_file in logs_dir.iterdir():
-    print(f"Log file: {log_file}")
-    with open(log_file) as f:
-        print(f.read())
-```
 :::
 ::::
 
@@ -190,8 +106,70 @@ cluster.down()
 :::
 ::::
 
+## Choosing a Cloud
+We'll be using the Oumi Launcher to run remote training. To use the launcher, you need to specify which cloud you'd like to run training on.
+We'll list the clouds below:
+
+::::{tab-set}
+:::{tab-item} CLI
+``` {code-block} shell
+oumi launch which
+```
+:::
+
+:::{tab-item} Python
+``` {code-block} python
+import oumi.launcher as launcher
+
+# Print all available clouds
+print(launcher.which_clouds())
+```
+:::
+::::
+
+#### Local Cloud
+If you don't have any clouds set up yet, feel free to use the `local` cloud. This will simply execute your job on your current device as if it's a remote cluster. Hardware requirements are ignored for the `local` cloud.
+
+#### Other Providers
+Note that to use a cloud you must already have an account registered with that cloud provider.
+
+For example, GCP, RunPod, and Lambda require accounts with billing enabled.
+
+Once you've picked a cloud, move on to the next step.
+
+## Preparing Your JobConfig
+Let's get started by creating your {py:class}`~oumi.core.configs.JobConfig`. In the config below, feel free to change `cloud: local` to the cloud you chose in the previous step.
+
+A sample job is provided below:
+````{dropdown} job.yaml
+```{code-block} yaml
+name: job-tutorial
+resources:
+  cloud: local
+  # Accelerators is ignored for the local cloud.
+  # This is required for other clouds like GCP, AWS, etc.
+  accelerators: A100
+
+# Upload working directory to remote.
+# If on the local cloud, we CD into the working directory before running the job.
+working_dir: .
+
+envs:
+  TEST_ENV_VARIABLE: '"Hello, World!"'
+  OUMI_LOGGING_DIR: "deploy_tutorial/logs"
+
+# `setup` will always be executed once when a cluster is created
+setup: |
+  echo "Running setup..."
+
+run: |
+  set -e  # Exit if any command failed.
+
+  echo "$TEST_ENV_VARIABLE"
+```
+````
 
-## \[Advanced\] Deploying a Training Config
+## Deploying a Training Config
 
 In our [Finetuning Tutorial](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20Finetuning%20Tutorial.ipynb), we created and saved a TrainingConfig. We then invoked training by running
 ```shell
@@ -204,14 +182,15 @@ You can also run that command as a job! Simply update the "run" section of the {
 ::::{tab-set}
 :::{tab-item} CLI
 ``` {code-block} shell
-export PATH_TO_YOUR_TRAIN_CONFIG="deploy_training_tutorial/train.yaml" # Make sure this exists!
-oumi launch up --cluster my-new-cluster -c deploy_training_tutorial/job.yaml --run "oumi train -c $PATH_TO_YOUR_TRAIN_CONFIG" --setup "pip install oumi"
+export PATH_TO_YOUR_TRAIN_CONFIG="deploy_tutorial/train.yaml" # Make sure this exists!
+oumi launch up --cluster my-new-cluster -c deploy_tutorial/job.yaml --run "oumi train -c $PATH_TO_YOUR_TRAIN_CONFIG" --setup "pip install oumi"
 ```
 :::
 
 :::{tab-item} Python
 ``` {code-block} python
-path_to_your_train_config = Path(tutorial_dir) / "train.yaml"  # Make sure this exists!
+working_dir = "YOUR_WORKING_DIRECTORY" # Specify this value
+path_to_your_train_config = Path(working_dir) / "train.yaml"  # Make sure this exists!
 
 # Set the `run` command to run your training script.
 job_config.run = f'oumi train -c "{path_to_your_train_config}"'
diff --git a/docs/user_guides/launch/launch.md b/docs/user_guides/launch/launch.md
