usernameemail
GPU type (for custom cluster only)
ex. Tesla-K80
Upload local file. Format: \[local\_path] or \[local\_path]:\[remote\_path].
ex. --upload-local-file my-project:/root/my-project
Kernel docker image URL
ex. vessl/kernels:py36.full-cpu
Hyperparameters in the form of \[key]=\[value]
ex. -h lr=0.01 -h epochs=100
Dataset mounts in the form of \[mount\_path] \[dataset\_name]
ex. --dataset /input mnist
Credential name registered in vessl credentials.
This option is only required when storage type is `s3` or `gcs`
| | `--cluster-name` |Cluster name of registered in vessl.
This option is only required when storage type is `nfs` or `host-path`
|Source path. The source can be either a local file path or a VESSL volume.
If the source is a VESSL volume, `SOURCE` must follow the format: `volume://{STORAGE_NAME}/{VOLUME_NAME}`.
| | `DEST` |Destination path. The destination can be either a local file path or a VESSL volume.
If the destination is a VESSL volume, `DEST` must follow the format: `volume://{STORAGE_NAME}/{VOLUME_NAME}`.
|Objective goal ex. 0.99
| | `-M`, `--objective-metric` |Objective metric ex. val\_accuracy
Search space parameters in the form of \[name] \[type] \[range\_type] \[values...]. \[type] must be one of categorical, int, or double. \[range\_type] must be either space or list. If space, \[values...] is a 3-tuple of \[min] \[max] \[step]. If list , \[values...] is a list of values to search.
ex. -p epochs int space 100 1000 50
GPU type (for custom cluster only)
ex. Tesla-K80
Kernel docker image URL
ex. vessl/kernels:py36.full-cpu
Early stopping algorithm settings in the format of \[key] \[value]ex. --early-stopping-settings start\_step 4
Hyperparameters in the form of \[key]=\[value]
ex. -h lr=0.01 -h epochs=100
Dataset mounts in the form of \[mount\_path] \[dataset\_name]
ex. --dataset /input mnist
`--dataset /input:mnist\` |
| `--upload-local-file` *(multiple)* | Upload local file. Format: \[local\_path] or \[local\_path]:\[remote\_path].ex. \`--upload-local-file my-project:/root/my-project\`\` |
| `--root-volume-size` | Root volume size (defaults to `100Gi`) |
| `-p`, `--port` *(multiple)* | Format: \[expose\_type] \[port] \[name], ex. `-p 'tcp 22 ssh'`. Jupyter and SSH ports exist by default. |
| `--init-script` | Custom init script |
###
### Connect to a running workspace
```bash theme={null}
vessl workspace ssh [OPTIONS]
```
| Option | Description |
| ---------- | -------------------- |
| --key-path | SSH private key path |
### Connect to workspaces via VSCode Remote-SSH
```bash theme={null}
vessl workspace vscode [OPTIONS]
```
| Option | Description |
| ---------- | -------------------- |
| --key-path | SSH private key path |
```bash theme={null}
$ vessl workspace vscode
Updated '/Users/johndoe/.ssh/config'.
```
### Backup the home directory of the workspace
Create a zip file at `/tmp/workspace-backup.zip` and uploads the backup to VESSL server.
You should run this command inside a running workspace.
```bash theme={null}
vessl workspace backup
```
```bash theme={null}
$ vessl workspace backup
Successfully uploaded 1 out of 1 file(s).
```
### Restore workspace home directory from a backup.
Download the zip file to `/tmp/workspace-backup.zip` and extract to `/root/`.
You should run this command inside a running workspace.
```bash theme={null}
vessl workspace restore
```
```bash theme={null}
$ vessl workspace restore
[?] Select workspace: rash-uncle (backup created 13 minutes ago)
> rash-uncle (backup created 13 minutes ago)
hazel-saver (backup created 2 days ago)
Successfully downloaded 1 out of 1 file(s).
```
### List all workspaces
```
vessl workspace list
```
### View information on the workspace
```
vessl workspace read ID
```
| Argument | Description |
| -------- | ------------ |
| `ID` | Workspace ID |
### View logs of the workspace container
```
vessl workspace logs ID
```
| Argument | Description |
| -------- | ------------ |
| `ID` | Workspace ID |
| Option | Description |
| -------- | --------------------------------------------------------- |
| `--tail` | Number of lines to display from the end (defaults to 200) |
### Start a workspace container
```
vessl workspace start ID
```
| Argument | Description |
| -------- | ------------ |
| `ID` | Workspace ID |
### Stop a workspace container
```
vessl workspace stop ID
```
| Argument | Description |
| -------- | ------------ |
| `ID` | Workspace ID |
### Terminate a workspace container
```
vessl workspace terminate ID
```
| Argument | Description |
| -------- | ------------ |
| `ID` | Workspace ID |
# Cluster
Source: https://docs.vessl.ai/reference/sdk/cluster
### create\_cluster
```python theme={null}
vessl.create_cluster(
param: CreateClusterParam
)
```
Create a VESSL cluster by installing VESSL agent to given Kubernetes
namespace. If you want to override the default organization, then pass
`organization_name` to `param`.
**Args**
* `param` (CreateClusterParam) : Create cluster parameter.
**Example**
```python theme={null}
vessl.install_cluster(
param=vessl.CreateClusterParam(
cluster_name="foo",
...
),
)
```
***
## read\_cluster
```python theme={null}
vessl.read_cluster(
cluster_name: str, **kwargs
)
```
Read cluster in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `cluster_name` (str) : Cluster name.
**Example**
```python theme={null}
vessl.read_cluster(
cluster_name="seoul-cluster",
)
```
***
## list\_clusters
```python theme={null}
vessl.list_clusters(
**kwargs
)
```
List clusters in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Example**
```python theme={null}
vessl.list_clusters()
```
***
## delete\_cluster
```python theme={null}
vessl.delete_cluster(
cluster_id: int, **kwargs
)
```
Delete custom cluster in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `cluster_id` (int) : Cluster ID.
**Example**
```python theme={null}
vessl.delete_cluster(
cluster_id=1,
)
```
***
## rename\_cluster
```python theme={null}
vessl.rename_cluster(
cluster_id: int, new_cluster_name: str, **kwargs
)
```
Rename custom cluster in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `cluster_id` (int) : Cluster ID.
* `new_cluster_name` (str) : Cluster name to change.
**Example**
```python theme={null}
vessl.rename_cluster(
cluster_id=1,
new_cluster_name="seoul-cluster-2",
)
```
***
## list\_cluster\_nodes
```python theme={null}
vessl.list_cluster_nodes(
cluster_id: int, **kwargs
)
```
List custom cluster nodes in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `cluster_id` (int) : Cluster ID.
**Example**
```python theme={null}
vessl.list_cluster_nodes(
cluster_id=1,
)
```
# Dataset (Deprecated)
Source: https://docs.vessl.ai/reference/sdk/dataset
The `dataset` functions are deprecated.
Please use the `vessl.storage` package to manage datasets with VESSL storage volumes.
### read\_dataset
```python theme={null}
vessl.read_dataset(
dataset_name: str, **kwargs
)
```
Read a dataset in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
**Example**
```python theme={null}
vessl.read_dataset(
dataset_name="mnist",
)
```
***
## read\_dataset\_version
```python theme={null}
vessl.read_dataset_version(
dataset_id: int, dataset_version_hash: str, **kwargs
)
```
Read the specific version of dataset in the default organization. If you
want to override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `dataset_id` (int) : Dataset id.
* `dataset_version_hash` (str) : Dataset version hash.
**Example**
```python theme={null}
vessl.read_dataset_version(
dataset_id=1,
dataset_version_hash="hash123"
)
```
***
## list\_datasets
```python theme={null}
vessl.list_datasets(
**kwargs
)
```
List datasets in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Example**
```
vessl.list_datasets()
```
***
## create\_dataset
```python theme={null}
vessl.create_dataset(
dataset_name: str, description: str = None, is_version_enabled: bool = False,
is_public: bool = False, external_path: str = None, aws_role_arn: str = None,
version_path: str = None, **kwargs
)
```
Create a dataset in the default organization. If you want to override
the default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `description` (str) : dataset description. Defaults to None.
* `is_version_enabled` (bool) : True if a dataset versioning is set,
False otherwise. Defaults to False.
* `is_public` (bool) : True if a dataset is source from a public bucket, False
otherwise. Defaults to False.
* `external_path` (str) : AWS S3 or Google Cloud Storage bucket URL. Defaults
to None.
* `aws_role_arn` (str) : AWS Role ARN to access S3. Defaults to None.
* `version_path` (str) : Versioning bucket path. Defaults to None.
**Example**
```python theme={null}
vessl.create_dataset(
dataset_name="mnist",
is_public=True,
external_path="s3://savvihub-public-apne2/mnist"
)
```
***
## list\_dataset\_volume\_files
```python theme={null}
vessl.list_dataset_volume_files(
dataset_name: str, need_download_url: bool = False, path: str = '',
recursive: bool = False, **kwargs
)
```
List dataset volume files in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `need_download_url` (bool) : True if you need a download URL, False
otherwise. Defaults to False.
* `path` (str) : Directory path to list. Defaults to root(""),
* `recursive` (bool) : True if list files recursively, False otherwise.
Defaults to False.
**Example**
```python theme={null}
vessl.list_dataset_volume_files(
dataset_name="mnist",
recursive=True,
)
```
***
## upload\_dataset\_volume\_file
```python theme={null}
vessl.upload_dataset_volume_file(
dataset_name: str, source_path: str, dest_path: str, **kwargs
)
```
Upload file to the dataset. If you want to override the default
organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `source_path` (str) : Local source path.
* `dest_path` (str) : Destination path within the dataset.
**Example**
```python theme={null}
vessl.upload_dataset_volume_file(
dataset_name="mnist",
source_path="test.csv",
dest_path="train",
)
```
***
## download\_dataset\_volume\_file
```python theme={null}
vessl.download_dataset_volume_file(
dataset_name: str, source_path: str, dest_path: str, **kwargs
)
```
Download file from the dataset. If you want to override the default
organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `source_path` (str) : Source path within the dataset.
* `dest_path` (str) : Local destination path.
**Example**
```python theme={null}
vessl.download_dataset_volume_file(
dataset_name="mnist",
source_path="train/test.csv",
dest_path=".",
)
```
***
## copy\_dataset\_volume\_file
```python theme={null}
vessl.copy_dataset_volume_file(
dataset_name: str, source_path: str, dest_path: str, **kwargs
)
```
Copy files within the same dataset. Noted that this is not supported for
externally sourced datasets like S3 or GCS. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `source_path` (str) : Source path within the dataset.
* `dest_path` (str) : Local destination path.
**Example**
```python theme={null}
vessl.download_dataset_volume_file(
dataset_name="mnist",
source_path="train/test.csv",
dest_path="test/test.csv",
)
```
***
## delete\_dataset\_volume\_file
```python theme={null}
vessl.delete_dataset_volume_file(
dataset_name: str, path: str, **kwargs
)
```
Delete the dataset volume file. Noted that this is not supported for
externally sourced datasets like S3 or GCS. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `dataset_name` (str) : Dataset name.
* `path` (str) : File path.
**Example**
```python theme={null}
vessl.delete_dataset_volume_file(
dataset_name="mnist",
path="train/test.csv",
)
```
# Experiment
Source: https://docs.vessl.ai/reference/sdk/experiment
### read\_experiment
```python theme={null}
vessl.read_experiment(
experiment_number: int, **kwargs
)
```
Read experiment in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : experiment number.
**Example**
```python theme={null}
vessl.read_experiment(
experiment_number=23,
)
```
***
## list\_experiments
```python theme={null}
vessl.list_experiments(
statuses: List[str] = None, **kwargs
)
```
List experiments in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `statuses` (List\[str]) : A list of status filter. Defaults to None.
**Example**
```python theme={null}
vessl.list_experiments(
statuses=["completed"]
)
```
***
## create\_experiment
```python theme={null}
vessl.create_experiment(
cluster_name: str, start_command: str, cluster_node_names: List[str] = None,
kernel_resource_spec_name: str = None, processor_type: str = None,
cpu_limit: float = None, memory_limit: str = None, gpu_type: str = None,
gpu_limit: int = None, kernel_image_url: str = None,
docker_credentials_id: Optional[int] = None, *, message: str = None,
termination_protection: bool = False, hyperparameters: List[str] = None,
secrets: List[str] = None, dataset_mounts: List[str] = None,
model_mounts: List[str] = None, git_ref_mounts: List[str] = None,
git_diff_mount: str = None, local_files: List[str] = None,
use_vesslignore: bool = True, upload_local_git_diff: bool = False,
archive_file_mount: str = None, object_storage_mounts: List[str] = None,
root_volume_size: str = None, working_dir: str = None,
output_dir: str = MOUNT_PATH_OUTPUT, worker_count: int = 1,
framework_type: str = None, service_account: str = '', **kwargs
)
```
Create experiment in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`. You can also configure git info by passing
`git_branch` or `git_ref` as `**kwargs`. Pass `use_git_diff=True` if
you want to run experiment with uncommitted changes and pass
`use_git_diff_untracked=True` if you want to run untracked changes(only
valid if `use_git_diff` is set).
**Args**
* `cluster_name` (str) : Cluster name(must be specified before other options).
* `cluster_node_names` (List\[str]) : Node names. The experiment will run on
one of these nodes. Defaults to None(all).
* `start_command` (str) : Start command to execute in experiment container.
* `kernel_resource_spec_name` (str) : Resource type to run an experiment (for
managed cluster only). Defaults to None.
* `cpu_limit` (float) : Number of vCPUs (for custom cluster only). Defaults to
None.
* `memory_limit` (str) : Memory limit in GiB (for custom cluster only).
Defaults to None.
* `gpu_type` (str) : GPU type (for custom cluster only). Defaults to None.
* `gpu_limit` (int) : Number of GPU cores (for custom cluster only). Defaults
to None.
* `kernel_image_url` (str) : Kernel docker image URL. Defaults to None.
* `docker_credentials_id` (int) : Docker credential id. Defaults to None.
* `message` (str) : Message. Defaults to None.
* `termination_protection` (bool) : True if termination protection is enabled,
False otherwise. Defaults to False.
* `hyperparameters` (List\[str]) : A list of hyperparameters. Defaults to None.
* `secrets` (List\[str]) : A list of secrets in form "KEY=VALUE". Defaults to None.
* `dataset_mounts` (List\[str]) : A list of dataset mounts. Defaults to None.
* `model_mounts` (List\[str]) : A list of model mounts. Defaults to None.
* `git_ref_mounts` (List\[str]) : A list of git repository mounts. Defaults to
None.
* `git_diff_mount` (str) : Git diff mounts. Defaults to None.
* `local_files` (List\[str]) : A list of local files to upload. Defaults to
None.
* `use_vesslignore` (bool) : True if local files matching glob patterns
in .vesslignore files should be ignored. Patterns apply relative to
the directory containing that .vesslignore file.
* `upload_local_git_diff` (bool) : True if local git diff to upload, False
otherwise. Defaults to False.
* `archive_file_mount` (str) : Local archive file mounts. Defaults to None.
* `object_storage_mounts` (List\[str]) : Object storage mounts. Defaults to None.
* `root_volume_size` (str) : Root volume size. Defaults to None.
* `working_dir` (str) : Working directory path. Defaults to None.
* `output_dir` (str) : Output directory path. Defaults to "/output/".
* `worker_count` (int) : Number of workers(for distributed experiment only).
Defaults to 1.
* `framework_type` (str) : Specify "pytorch" or "tensorflow" (for distributed
experiment only). Defaults to None.
* `service_account` (str) : Service account name. Defaults to "".
processor\_type(str) cpu or gpu (for custom cluster only). Defaults to
None.
**Example**
```python theme={null}
vessl.create_experiment(
cluster_name="aws-apne2",
kernel_resource_spec_name="v1.cpu-4.mem-13",
kernel_image_url="public.ecr.aws/vessl/kernels:py36.full-cpu",
dataset_mounts=["/input/:mnist"]
start_command="pip install requirements.txt && python main.py",
)
```
***
## list\_experiment\_logs
```python theme={null}
vessl.list_experiment_logs(
experiment_number: int, tail: int = 200, worker_number: int = 0, after: int = 0,
**kwargs
)
```
List experiment logs in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `experiment_name` (int) : Experiment number.
* `tail` (int) : The number of lines to display from the end. Display all if
-1. Defaults to 200.
* `worker_number` (int) : Override default worker number (for distributed
experiments only). Defaults to 0.
* `after` (int) : The number of starting lines to display from the start.
Defaults to 0.
**Example**
```python theme={null}
vessl.list_experiment_logs(
experiment_number=23,
)
```
***
## list\_experiment\_output\_files
```python theme={null}
vessl.list_experiment_output_files(
experiment_number: int, need_download_url: bool = False, recursive: bool = True,
worker_number: int = 0, **kwargs
)
```
List experiment output files in the default organization/project. If you
want to override the default organization/project, then pass
`organization_name` or `project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : Experiment number.
* `need_download_url` (bool) : True if you need a download URL, False
otherwise. Defaults to False.
* `recursive` (bool) : True if list files recursively, False otherwise.
Defaults to True.
* `worker_number` (int) : Override default worker number (for distributed
experiments only). Defaults to 0.
**Example**
```python theme={null}
vessl.list_experiment_output_files(
experiment_number=23,
)
```
***
## download\_experiment\_output\_files
```python theme={null}
vessl.download_experiment_output_files(
experiment_number: int, dest_path: str = os.path.join(os.getcwd(), 'output'),
worker_number: int = 0, **kwargs
)
```
Download experiment output files in the default organization/project.
If you want to override the default organization/project, then pass
`organization_name` or `project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : Experiment number.
* `dest_path` (str) : Local download path. Defaults to "./output".
* `worker_number` (int) : Override default worker number (for distributed
experiments only). Defaults to 0.
**Example**
```python theme={null}
vessl.download_experiment_output_files(
experiment_number=23,
)
```
***
## upload\_experiment\_output\_files
```python theme={null}
vessl.upload_experiment_output_files(
experiment_number: int, path: str, **kwargs
)
```
Upload experiment output files in the default organization/project.
If you want to override the default organization/project, then pass
`organization_name` or `project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : Experiment number.
* `path` (str) : Source path.
**Example**
```python theme={null}
vessl.upload_experiment_output_files(
experiment_number=23,
path="output",
)
```
***
## terminate\_experiment
```python theme={null}
vessl.terminate_experiment(
experiment_number: int, **kwargs
)
```
Terminate experiment in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : Experiment number.
**Example**
```python theme={null}
vessl.terminate_experiment(
experiment_number=23,
)
```
***
## delete\_experiment
```python theme={null}
vessl.delete_experiment(
experiment_number: int, **kwargs
)
```
Delete experiment in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `experiment_number` (int) : Experiment number.
**Example**
```python theme={null}
vessl.delete_experiment(
experiment_number=23,
)
```
# Image
Source: https://docs.vessl.ai/reference/sdk/image
### read\_kernel\_image
```python theme={null}
vessl.read_kernel_image(
image_id: int
)
```
Read the kernel image.
**Args**
* `image_id` (int) : Image ID.
**Example**
```python theme={null}
vessl.read_kernel_image(
image_id=1,
)
```
***
## list\_kernel\_images
```python theme={null}
vessl.list_kernel_images(
**kwargs
)
```
List kernel images in the default organization. If you
want to override the default organization, then pass `organization_name` as
`**kwargs`.
**Example**
```python theme={null}
vessl.list_kernel_images()
```
# Keras
Source: https://docs.vessl.ai/reference/sdk/integrations/keras
VESSL provides integrations for Keras, an interface for the TensorFlow library. You can find a complete example using Keras in our [GitHub repository](https://github.com/vessl-ai/examples/blob/main/deprecated/mnist/keras/main.py).
## ExperimentCallback
`ExperimentCallback` extends Keras' callback class. Add `ExperimentCallback` as a callback parameter in the `fit` function to automatically track Keras metrics at the end of each epoch. You can also log image objects using `ExperimentCallback`.
| Parameter | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `data_type` | Use `image` to log image objects |
| `validation_data` | Tuple of `(validation_data, validation_labels)` |
| `labels` | List of labels to get the caption from the inferred logits.
The argmax value will be used if labels are not provided.
|
| `num_images` | Number of images to log in the validation data |
### Logging metrics
```python theme={null}
# Logging loss and accuracy for each epoch in Keras
from vessl.integration.keras import ExperimentCallback
...
model.fit(..., callbacks=[ExperimentCallback()])
...
```
### Logging image objects
```python theme={null}
# Logging images along with the loss and accuracy for each epoch in Keras
from vessl.keras import ExperimentCallback
...
model.fit(
...,
callbacks=[ExperimentCallback(
data_type='image',
validation_data=(x_val, y_val),
num_images=5,
)]
)
...
```
# Transformers
Source: https://docs.vessl.ai/reference/sdk/integrations/transformers
VESSL provides integrations for 🤗 Transformers by HuggingFace in form of `TrainerCallback`.
## VesslCallback
`VesslCallback` extends `TrainerCallback` in Transformers, which can define the behaviors of `Trainer` during the training.
Add `VesslCallback` to callback parameter of `Trainer` class, so that the metrics logged by trainer are tracked by VESSL as well.
You can add instantiated `VesslCallback` to use another organization and project.
| Parameter | Description |
| --------------------------- | ---------------------------------------------------------- |
| `access_token` | Access token to override. |
| `organization_name` | Organization name to override. |
| `project_name` | Project name to override. |
| `credentials_file` | Credential file to access the organization and the project |
| `force_update_access_token` | True if force update access token |
### Logging metrics
```python theme={null}
from vessl.integration.transformers import VesslCallback
...
# Add callback class itself, so that the default organization and project are used
trainer = Trainer(
...
callbacks=[VesslCallback]
)
# ... or you can specify the configuration you want
callback = VesslCallback(
access_token=YOUR_ACCESS_TOKEN,
organization_name="your_organization",
project_name = "your_project",
)
trainer = Trainer(
...,
callbacks=[callback]
)
trainer.train()
...
```
# Model
Source: https://docs.vessl.ai/reference/sdk/model
### read\_model\_repository
```python theme={null}
vessl.read_model_repository(
repository_name: str, **kwargs
)
```
Read model repository in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
**Example**
```python theme={null}
vessl.read_model_repository(
repository_name="Transformer-ImageNet",
)
```
***
## list\_model\_repositories
```python theme={null}
vessl.list_model_repositories(
**kwargs
)
```
List model repositories in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Example**
```python theme={null}
vessl.list_model_repositories()
```
***
## create\_model\_repository
```python theme={null}
vessl.create_model_repository(
name: str, description: str = None, **kwargs
)
```
Create model repository in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `name` (str) : Model repository name.
* `description` (str) : Model repository description. Defaults to None.
**Example**
```python theme={null}
vessl.create_model_repository(
name="Transformer-ImageNet",
description="Transformer model trained on ImageNet",
)
```
***
## update\_model\_repository
```python theme={null}
vessl.update_model_repository(
name: str, description: str, **kwargs
)
```
Update model repository in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `name` (str) : Model repository name.
* `description` (str) : Model repository description to update.
**Example**
```python theme={null}
vessl.update_model_repository(
name="Transformer-ImageNet",
description="Update description to this",
)
```
***
## delete\_model\_repository
```python theme={null}
vessl.delete_model_repository(
name: str, **kwargs
)
```
Delete model repository in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `name` (str) : Model repository name.
**Example**
```python theme={null}
vessl.delete_model_repository(
name="Transformer-ImageNet",
)
```
***
## read\_model
```python theme={null}
vessl.read_model(
repository_name: str, model_number: int, **kwargs
)
```
Read model in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
**Example**
```python theme={null}
vessl.read_model(
repository_name="Transformer-ImageNet",
model_number=1,
)
```
***
## list\_models
```python theme={null}
vessl.list_models(
repository_name: str, **kwargs
)
```
List models in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
**Example**
```python theme={null}
vessl.list_models(
repository_name="Transformer-ImageNet",
)
```
***
## create\_model
```python theme={null}
vessl.create_model(
repository_name: str, repository_description: str = None, experiment_id: int = None,
model_name: str = None, paths: List[str] = None, **kwargs
)
```
Create model in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`. If the
given model repository name does not exist, then create one with the given
repository\_description. Otherwise, create a model in the existing model
repository.
**Args**
* `repository_name` (str) : Model repository name.
* `repository_description` (str) : Model repository description. Defaults to
None
* `experiment_id` (int) : Pass experiment ID if the model is sourced from the
experiment outputs. Defaults to None.
* `model_name` (str) : Model name is unique and optional. Defaults to None.
* `paths` (List\[str]) : Paths for creating model. Paths could be sub paths of
experiment output files or local file paths. Defaults to root.
**Example**
```python theme={null}
vessl.create_model(
repository_name="Transformer-ImageNet",
repository_description="Transformer model trained on ImageNet",
experiment_id=123456,
model_name="v0.0.1",
)
```
***
## update\_model
```python theme={null}
vessl.update_model(
repository_name: str, model_number: int, name: str, **kwargs
)
```
Update model in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
* `name` (str) : Model name to update.
**Example**
```python theme={null}
vessl.update_model(
repository_name="Transformer-ImageNet",
model_number=1,
name="v0.0.2",
)
```
***
## delete\_model
```python theme={null}
vessl.delete_model(
repository_name: str, model_number: int, **kwargs
)
```
Delete model in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
**Example**
```python theme={null}
vessl.delete_model(
repository_name="Transformer-ImageNet",
model_number=1,
)
```
***
## list\_model\_volume\_files
```python theme={null}
vessl.list_model_volume_files(
repository_name: str, model_number: int, need_download_url: bool = False,
path: str = '', recursive: bool = False, **kwargs
)
```
List model files in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
* `need_download_url` (bool) : True if you need a download URL, False
otherwise. Defaults to False.
* `path` (str) : Directory path to list. Defaults to root.
* `recursive` (bool) : True if file is a directory, False otherwise. Defaults
to False.
**Example**
```python theme={null}
vessl.list_model_volume_files(
repository_name="Transformer-ImageNet",
model_number=1,
recursive=True,
)
```
***
## upload\_model\_volume\_file
```python theme={null}
vessl.upload_model_volume_file(
repository_name: str, model_number: int, source_path: str, dest_path: str,
**kwargs
)
```
Upload file to the model in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
* `source_path` (str) : Local source path.
* `dest_path` (str) : Destination path within the model.
**Example**
```python theme={null}
vessl.upload_model_volume_file(
repository_name="Transformer-ImageNet",
model_number=1,
source_path="model_best.pth",
dest_path="model_best.pth",
)
```
***
## download\_model\_volume\_file
```python theme={null}
vessl.download_model_volume_file(
repository_name: str, model_number: int, source_path: str, dest_path: str,
**kwargs
)
```
Download a model in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
* `source_path` (str) : Source path within the model
* `dest_path` (str) : Local destination path
**Example**
```python theme={null}
vessl.download_model_volume_file(
repository_name="Transformer-ImageNet",
model_number=1,
source_path="model_best.pth",
dest_path="models",
)
```
***
## delete\_model\_volume\_file
```python theme={null}
vessl.delete_model_volume_file(
repository_name: str, model_number: int, path: str, **kwargs
)
```
Delete the model volume file in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int) : Model number.
* `path` (str) : File path within the model
**Example**
```python theme={null}
vessl.delete_model_volume_file(
repository_name="Transformer-ImageNet",
model_number=1,
source_path="models",
recursive=True,
)
```
# Organization
Source: https://docs.vessl.ai/reference/sdk/organization
### read\_organization
```python theme={null}
vessl.read_organization(
organization_name: str
)
```
Read organization
**Args**
* `organization_name` (str) : Organization name.
**Example**
```python theme={null}
vessl.read_organization(
organization_name="foo"
)
```
***
## list\_organizations
```python theme={null}
vessl.list_organizations()
```
List organizations
**Example**
```python theme={null}
vessl.list_organizations()
```
***
## create\_organization
```python theme={null}
vessl.create_organization(
organization_name: str
)
```
Create organization
**Args**
* `organization_name` (str) : Organization name.
**Example**
```python theme={null}
vessl.create_organization(
organization_name="foo",
)
```
# Project
Source: https://docs.vessl.ai/reference/sdk/project
### read\_project
```python theme={null}
vessl.read_project(
project_name: str, **kwargs
)
```
Read project in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `project_name` (str) : Project name.
**Example**
```python theme={null}
vessl.read_project(
project_name="tutorials",
)
```
***
## list\_projects
```python theme={null}
vessl.list_projects(
**kwargs
)
```
List projects in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Example**
```python theme={null}
vessl.list_projects()
```
***
## create\_project
```python theme={null}
vessl.create_project(
project_name: str, description: str = None, **kwargs
)
```
Create project in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `project_name` (str) : Project name.
* `description` (str) : Project description. Defaults to None.
**Example**
```python theme={null}
vessl.create_project(
project_name="tutorials",
description="VESSL tutorial project",
)
```
# RunnerBase
Source: https://docs.vessl.ai/reference/sdk/runnerbase
### RunnerBase
```python theme={null}
RunnerBase()
```
Base class for model registering.
This base class introduces 5 static methods as followings:
* `predict`: Make prediction with given data and model. This method must be overridden. The
data is given from the result of `preprocess_data`, and the return value of this method
will be passed to `postprocess_data` before service.
* `save_model`: Save the model into a file. Return value of this method will be given to the
`load_model` method on model loading. If this method is overriden, `load_model` must be
overriden as well.
* `load_model`: Load the model from a file.
* `preprocess_data`: Preprocess the data before prediction. It converts the API input data to
the model input data.
* `postprocess_data`: Postprocess the data after prediction. It converts the model output data
to the API output data.
Check each method's docstring for more information.
**Methods:**
## .load\_model
```python theme={null}
vessl.load_model(
props: Union[Dict[str, str], None], artifacts: Dict[str, str]
)
```
Load the model instance from file.
`props` is given from the return value of `save_model`, and `artifacts` is
given from the `register_model` method.
If the `save_model` is not overriden, `props` will be None
**Args**
* `props` (dict | None) : Data that was returned by `save_model`. If `save_model` is
not overriden, this will be None.
* `artifacts` (dict) : Data that is given by `register_model` function.
**Returns**
Model instance.
## .preprocess\_data
```python theme={null}
vessl.preprocess_data(
data: InputDataType
)
```
Preprocess the given data.
The data processed by this method will be given to the model.
**Args**
* `data` : Data to be preprocessed.
**Returns**
Preprocessed data that will be given to the model.
## .predict
```python theme={null}
vessl.predict(
model: ModelType, data: ModelInputDataType
)
```
Make prediction with given data and model.
**Args**
* `model` (model\_instance) : Model instance.
* `data` : Data to be predicted.
**Returns**
Prediction result.
## .postprocess\_data
```python theme={null}
vessl.postprocess_data(
data: ModelOutputDataType
)
```
Postprocess the given data.
The data processed by this method will be given to the user.
**Args**
* `data` : Data to be postprocessed.
**Returns**
Postprocessed data that will be given to the user.
## .save\_model
```python theme={null}
vessl.save_model(
model: ModelType
)
```
Save the given model instance into file.
Return value of this method will be given to first argument of `load_model` on model loading.
**Args**
* `model` (model\_instance) : Model instance to save.
**Returns**
(dict) Data that will be passed to `load_model` on model loading.
Must be a dictionary with key and value both string.
***
## register\_model
```python theme={null}
vessl.register_model(
repository_name: str, model_number: Union[int, None], runner_cls: RunnerBase,
model_instance: Union[ModelType, None] = None, requirements: List[str] = None,
artifacts: Dict[str, str] = None, **kwargs
)
```
Register the given model for service. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int | None) : Model number. If None, new model will be
created. In such case, `model_instance` must be given.
* `runner_cls` (RunnerBase) : Runner class that includes code for service.
* `model_instance` (ModelType | None) : Model instance. If None, `runner_cls`
must override `load_model` method. Defaults to None.
* `requirements` (List\[str]) : Python requirements for the model. Defaults to
\[].
* `artifacts` (Dict\[str, str]) : Artifacts to be uploaded. Key is the path to
artifact in local filesystem, and value is the path in the model
volume. Only trailing asterisk(\*) is allowed for glob pattern.
Defaults to .
**Example**
* "model.pt", "checkpoints/*": "checkpoints/*"},
```python theme={null}
register_model(
repository_name="my-model",
model_number=1,
runner_cls=MyRunner,
model_instance=model_instance,
requirements=["torch", "torchvision"],
)
```
***
## register\_torch\_model
```python theme={null}
vessl.register_torch_model(
repository_name: str, model_number: Union[int, None], model_instance: ModelType,
preprocess_data = None, postprocess_data = None, requirements: List[str] = None,
**kwargs
)
```
Register the given torch model instance for model service. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `repository_name` (str) : Model repository name.
* `model_number` (int | None) : Model number. If None, new model will be
created.
* `model_instance` (model\_instance) : Torch model instance.
* `preprocess_data` (callable) : Function that will preprocess data.
Defaults to identity function.
* `postprocess_data` (callable) : Function that will postprocess data.
Defaults to identity function.
* `requirements` (list) : List of requirements. Defaults to \[].
**Example**
```python theme={null}
vessl.register_model(
repository_name="my-model",
model_number=1,
model_instance=model_instance,
)
```
# Service
Source: https://docs.vessl.ai/reference/sdk/service
### list\_services
```python theme={null}
vessl.list_services(
organization: str
)
```
Get a list of all services in an organization
**Args**
* `organization` (str) : The name of the organization.
**Example**
```python theme={null}
vessl.list_services(organization="my-org")
```
***
## read\_service
```python theme={null}
vessl.read_service(
service_name: str
)
```
Get a service from a service name.
**Args**
* `service_name` (str) : The name of the service.
**Example**
```python theme={null}
vessl.read_service(service_name="my-service")
```
***
## create\_revision\_from\_yaml
```python theme={null}
vessl.create_revision_from_yaml(
organization: str, yaml_body: str
)
```
Create a new revision of service from a YAML file.
**Args**
* `organization` (str) : The name of the organization.
* `yaml_body` (str) : The YAML body of the service.
It is not deserialized YAML, but a whole yaml string.
**Example**
```python theme={null}
vessl.create_revision_from_yaml(
organization="my-org",
yaml_body=yaml_body)
```
***
## launch\_revision
```python theme={null}
vessl.launch_revision(
organization: str, service_name: str, revision_number: int
)
```
Launch a service revision from a service name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
**Example**
```python theme={null}
vessl.launch_revision(
organization="my-org",
service_name="my-service",
revision_number=1)
```
***
## read\_revision
```python theme={null}
vessl.read_revision(
organization: str, service_name: str, revision_number: int
)
```
Get a service revision from a service name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
**Example**
```python theme={null}
vessl.read_revision(
organization="my-org",
service_name="my-service",
revision_number=1)
```
***
## terminate\_revision
```python theme={null}
vessl.terminate_revision(
organization: str, service_name: str, revision_number: int
)
```
Terminate a service revision from a service name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
**Example**
```python theme={null}
vessl.terminate_revision(
organization="my-org",
service_name="my-service",
revision_number=1)
```
***
## update\_revision\_autoscaler\_config
```python theme={null}
vessl.update_revision_autoscaler_config(
organization: str, service_name: str, revision_number: int,
autoscaling: V1Autoscaling
)
```
Update the autoscaler config of a service revision from a service name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
* `autoscaling` (V1Autoscaling) : The autoscaler config of the service.
**Example**
```python theme={null}
vessl.update_revision_autoscaler_config(
organization="my-org",
service_name="my-service",
revision_number=1,
autoscaling=V1Autoscaling(
min=1,
max=2,
metric="cpu",
target=80,
))
```
***
## update\_revision\_autoscaling\_v2
```python theme={null}
vessl.update_revision_autoscaling_v2(
organization: str, service_name: str, revision_number: int,
autoscaling: V1Autoscaling
)
```
Update the autoscaler config of a service revision from a service name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
* `autoscaling` (V1Autoscaling) : The autoscaler config of the service.
**Example**
```python theme={null}
vessl.update_revision_autoscaling_v2(
organization="my-org",
service_name="my-service",
revision_number=1,
autoscaling=V1Autoscaling(
min=1,
max=2,
metric="cpu",
target=80,
))
```
***
## list\_revisions
```python theme={null}
vessl.list_revisions(
organization: str, service_name: str
)
```
Get a list of all revisions of a service.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
**Examples**
```python theme={null}
vessl.list_revisions(
organization="my-org",
service_name="my-service")
```
***
## read\_gateway
```python theme={null}
vessl.read_gateway(
organization: str, service_name: str
)
```
Get the gateway of a service.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
**Examples**
```python theme={null}
vessl.read_gateway(
organization="my-org",
service_name="my-service")
```
***
## update\_gateway
```python theme={null}
vessl.update_gateway(
organization: str, service_name: str,
gateway: ModelServiceGatewayUpdateAPIInput
)
```
Update the gateway of a service.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `gateway` (ModelServiceGatewayUpdateAPIInput) : The gateway of the service.
**Examples**
```python theme={null}
from openapi_client import ModelServiceGatewayUpdateAPIInput
from openapi_client import OrmModelServiceGatewayTrafficSplitEntry
gateway = ModelServiceGatewayUpdateAPIInput(
enabled=True,
ingress_host="my-endpoint",
traffic_split=[
OrmModelServiceGatewayTrafficSplitEntry(
revision_number=1,
port=2222,
traffic_weight=100,
)
],
)
vessl.update_gateway(
organization="my-org",
service_name="my-service",
gateway=gateway)
```
***
## update\_gateway\_for\_revision
```python theme={null}
vessl.update_gateway_for_revision(
organization: str, service_name: str, revision_number: int, port: int,
weight: int
)
```
Update the current gateway of a service for a specific revision.
**Args**
* `organization` (str) : The name of the organization.
* `service_name` (str) : The name of the service.
* `revision_number` (int) : The revision number of the service.
* `port` (int) : The port of the revision will use for gateway.
* `weight` (int) : The weight of the traffic will be distributed to revision\_number.
**Examples**
```python theme={null}
vessl.update_gateway_for_revision(
organization="my-org",
service_name="my-service",
revision_number=1,
port=2222,
weight=100)
```
## (deprecated) update\_revision\_autoscaler\_config
```python theme={null}
vessl.update_revision_autoscaler_config(
organization: str, serving_name: str, revision_number: int,
auto_scaler_config: AutoScalerConfig
)
```
(THIS API IS DEPRECATED.)
Update the autoscaler config of a serving revision from a serving name and revision number.
**Args**
* `organization` (str) : The name of the organization.
* `serving_name` (str) : The name of the serving.
* `revision_number` (int) : The revision number of the serving.
* `auto_scaler_config` (AutoScalerConfig) : The autoscaler config of the serving.
**Example**
```python theme={null}
vessl.update_revision_autoscaler_config(
organization="my-org",
serving_name="my-serving",
revision_number=1,
auto_scaler_config=AutoScalerConfig(
min_replicas=1,
max_replicas=2,
target_cpu_utilization_percentage=80,
))
```
***
## (deprecated) update\_gateway\_from\_yaml
```python theme={null}
vessl.update_gateway_from_yaml(
organization: str, serving_name: str, yaml_body: str
)
```
(THIS API IS DEPRECATED.)
Update the gateway of a serving from a YAML file.
**Args**
* `organization` (str) : The name of the organization.
* `serving_name` (str) : The name of the serving.
* `yaml_body` (str) : The YAML body of the serving.
It is not deserialized YAML, but a whole yaml string
**Examples**
```python theme={null}
vessl.update_gateway_from_yaml(
organization="my-org",
serving_name="my-serving",
yaml_body=yaml_body)
```
# SSH-key
Source: https://docs.vessl.ai/reference/sdk/ssh-key
### list\_ssh\_keys
```python theme={null}
vessl.list_ssh_keys()
```
List ssh public keys.
**Example**
```python theme={null}
vessl.list_ssh_keys()
```
***
## create\_ssh\_key
```python theme={null}
vessl.create_ssh_key(
key_path: str, key_name: str, ssh_public_key_value: str
)
```
Create a SSH public key.
**Args**
* `key_path` (str) : SSH public key path.
* `key_name` (str) : SSH public key name,
* `ssh_public_key_value` (str) : SSH public key value.
**Example**
```python theme={null}
vessl.create_ssh_key(
key_path="/Users/johndoe/.ssh/id_ed25519.pub",
key_name="john@abcd.com",
ssh_public_key_value="ssh-public-key-value",
)
```
***
## delete\_ssh\_key
```python theme={null}
vessl.delete_ssh_key(
key_id: int
)
```
Delete the ssh public key.
**Args**
* `key_id` (int) : Key ID.
**Example**
```python theme={null}
vessl.delete_ssh_key(
key_id=123456,
)
```
# Storage
Source: https://docs.vessl.ai/reference/sdk/storage
### create\_storage
```python theme={null}
vessl.storage.create_storage(
name: str,
storage_type: vessl.storage.StorageType,
path: str,
credential_name: Optional[str],
cluster_name: Optional[str],
)
```
Create an external storage.
VESSL External Storage acts as a bridge to external storage services (e.g., S3, GCS, etc.).
Make sure to configure the external storage settings before proceeding.
If you do not want to use external storage, you can use the default VESSL storage, `vessl-storage`.
**Args**
* `name` (str) : The name of the storage to create.
* `storage_type` (StorageType) : The type of storage to create. Options: `StorageType.S3`, `StorageType.GCS`, `StorageType.NFS`, `StorageType.HOST_PATH`
* `path` (str) : The path of the storage.
* For `s3` : Path must in `{bucket_name}/{path}` (e.g. my-bucket)
* For `gcs` : Path must in `{bucket_name}/{path}` (e.g. my-bucket)
* For `nfs` : Path must be in `{server}:{path}` format (e.g. 192.168.1.100:/shared/data)
* For `host-path` : Path must be an absolute local path (e.g. /data/host-folder)
* `credential_name` (str) : The name of the credential to use. Required if `storage_type` is `S3` or `GCS`
* `cluster_name` (str) : The name of the cluster to use. Required if `storage_type` is `NFS` or `HOST_PATH`
**Examples**
* Create an S3 storage:
```python theme={null}
vessl.storage.create_storage(
name="my-s3-storage",
storage_type=vessl.storage.StorageType.S3,
path="my-bucket",
credential_name="my-aws-credential",
)
```
* Create a GCS(Google Cloud Storage) storage:
```python theme={null}
vessl.storage.create_storage(
name="my-gcs-storage",
storage_type=vessl.storage.StorageType.GCS,
path="my-bucket",
credential_name="my-aws-credential",
)
```
* Create an NFS storage:
```python theme={null}
vessl.storage.create_storage(
name="my-nfs-storage",
storage_type=vessl.storage.StorageType.NFS,
path="my.nfs.com:/shared/data",
cluster_name="my-cluster",
)
```
* Create an HOST PATH storage:
```python theme={null}
vessl.storage.create_storage(
name="my-host-path-storage",
storage_type=vessl.storage.StorageType.HOST_PATH,
path=" /data/host-folder",
cluster_name="my-cluster",
)
```
### list\_storages
```python theme={null}
vessl.storage.list_storages(**kwargs)
```
List storages in the default organization. If you want to override the default organization, then pass `organization_name` as `**kwargs`.
**Example**
```python theme={null}
vessl.storage.list_storages()
```
### delete\_storage
```python theme={null}
vessl.storage.delete_storage(
name: str,
)
```
Delete storage.
**Args**
* name (str) : Name of the storage to delete.
**Example**
```python theme={null}
vessl.storage.delete_storage(name="my-storage")
```
### create\_volume
```python theme={null}
vessl.storage.create_volume(
name: str,
storage_name: str,
tags: tuple[str, ...],
)
```
Create a volume in storage.
**Args**
* name (str) : Name of the volume.
* storage\_name (str) : Name of the storage.
* tags (tuple\[str, ...]) : Tags of the volume.
**Example**
```python theme={null}
vessl.storage.create_volume(
name="my-volume",
storage_name="my-storage",
tags=("my-tag1", "my-tag2"),
)
```
### list\_volumes
```python theme={null}
vessl.storage.list_volumes(
storage_name: str,
keyword: Optional[str],
)
```
List volumes in storage.
**Args**
* storage\_name (str) : Name of the storage.
* keyword (str) : Optional search keyword.
**Example**
```python theme={null}
vessl.storage.list_volumes(storage_name="my-storage")
```
### delete\_volume
```python theme={null}
vessl.storage.delete_volume(
name: str,
storage_name: str,
)
```
Delete volume in storage.
**Args**
* name (str) : Name of the volume.
* storage\_name (str) : Name of the storage.
**Example**
```python theme={null}
vessl.storage.delete_volume(
name="my-volume",
storage_name="my-storage",
)
```
### list\_volume\_files
```python theme={null}
vessl.storage.list_volume_files(
storage_name: str,
volume_name: str,
path: Optional[str],
)
```
List all files in a volume.
**Args**
* storage\_name (str) : Name of the storage.
* volume\_name (str) : Name of the volume.
* path (Optional\[str]) : Path of directory to list. Defaults to "".
**Example**
```python theme={null}
vessl.storage.list_volume_files(
storage_name="my-storage",
volume_name="my-volume",
)
```
### upload\_volume\_file
```python theme={null}
vessl.storage.upload_volume_file(
source_path: str,
dest_storage_name: str,
dest_volume_name: str,
dest_path: Optional[str],
)
```
Upload a file to a volume.
**Args**
* source\_path (str) : Path of local directory of file to upload.
* dest\_storage\_name (str) : Name of the storage.
* dest\_volume\_name (str) : Name of the volume.
* dest\_path (str) : Path of volume directory to upload the file to. Defaults to "/".
**Example**
```python theme={null}
vessl.storage.upload_volume_file(
source_path="/path/to/file",
dest_storage_name="my-storage",
dest_volume_name="my-volume",
)
```
### download\_volume\_file
```python theme={null}
vessl.storage.download_volume_file(
source_storage_name: str,
source_volume_name: str,
dest_path: str,
)
```
Download a file from a volume.
**Args**
* source\_storage\_name (str) : Name of the storage.
* source\_volume\_name (str) : Name of the volume in the storage.
* dest\_path (str) : Path of local directory to download the file to.
**Example**
```python theme={null}
vessl.storage.download_volume_file(
source_storage_name="my-storage",
source_volume_name="my-volume",
dest_path="models"
)
```
### delete\_volume\_file
```python theme={null}
vessl.storage.delete_volume_file(
storage_name: str,
volume_name: str,
path: str,
recursive: Optional[bool],
)
```
Delete a file from a volume.
**Args**
* storage\_name (str) : Name of the storage.
* volume\_name (str) : Name of the volume in the storage.
* path (str) : Path of directory or file in volume to delete.
* recursive (Optional\[bool]) : If true, delete all files in this directory. Defaults to False.
**Example**
```python theme={null}
vessl.storage.delete_volume_file(
storage_name="my-storage",
volume_name="my-volume",
path="model.pth"
)
```
# Sweep
Source: https://docs.vessl.ai/reference/sdk/sweep
### read\_sweep
```python theme={null}
vessl.read_sweep(
sweep_name: str, **kwargs
)
```
Read sweep in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `sweep_name` (str) : Sweep name.
**Example**
```python theme={null}
vessl.read_sweep(
sweep_name="pitch-lord",
)
```
***
## list\_sweeps
```python theme={null}
vessl.list_sweeps(
**kwargs
)
```
List sweeps in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Example**
```python theme={null}
vessl.list_sweeps()
```
***
## create\_sweep
```python theme={null}
vessl.create_sweep(
name: str, algorithm: str, parameters: List[SweepParameter], cluster_name: str,
command: str, objective: SweepObjective = None, max_experiment_count: int = None,
parallel_experiment_count: int = None, max_failed_experiment_count: int = None,
resource_spec_name: str = None, processor_type: str = None, cpu_limit: float = None,
memory_limit: str = None, gpu_type: str = 'Any', gpu_limit: int = None,
image_url: str = None, *, early_stopping_name: str = None,
early_stopping_settings: List[Tuple[str, str]] = None, message: str = None,
hyperparameters: List[Tuple[str, str]] = None, dataset_mounts: List[str] = None,
git_ref_mounts: List[str] = None, git_diff_mount: str = None,
archive_file_mount: str = None, object_storage_mount: str = None,
root_volume_size: str = None, working_dir: str = None,
output_dir: str = MOUNT_PATH_OUTPUT, **kwargs
)
```
Create sweep in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`. Pass `use_git_diff=True` if you want to run
experiment with uncommitted changes and pass `use_git_diff_untracked=True`
if you want to run untracked changes(only valid if `use_git_diff` is set).
**Args**
* `name` (str) : Name
* `objective` (Optional\[vessl.SweepObjective]) : A sweep objective including goal, metric,
and type.
* `max_experiment_count` (Optional\[int]) : The maximum number of experiments to run.
Required unless grid search.
* `parallel_experiment_count` (Optional\[int]) : The number of experiments to run in
parallel. Default: 1.
* `max_failed_experiment_count` (Optional\[int]) : The maximum number of experiments to
allow to fail. Default: 1.
* `algorithm` (str) : Parameter suggestion algorithm. `grid`, `random`, or
`bayesian`.
* `parameters` (List\[vessl.SweepParameter]) : A list of parameters to search.
* SweepParameter
* name(str): The names of hyperparameters to search.
* type(str): `int`, `double`, `categorical`.
* range(SweepParameterRange): Search range.
* list(List\[str]): A list of values to try.
If `list` is given, `min`, `max` and `step` will be ignored.
* min(str): The minimum value of the search range (inclusive).
* max(str): The maximum value of the search range (inclusive).
* step(Optional\[str]): If provided, the values are limited to min + n\*step.
* `cluster_name` (str) : Cluster name(must be specified before other options).
* `command` (str) : Start command to execute in experiment container.
* `resource_spec_name` (str) : Resource type to run an experiment (for
managed cluster only). Defaults to None.
* `cpu_limit` (float) : Number of vCPUs (for custom cluster only). Defaults to
None.
* `memory_limit` (str) : Memory limit (for custom cluster only).
Defaults to None. Example: "100Gi", "500Mi"
* `gpu_type` (str) : GPU type(name) (for custom cluster only). Defaults to "Any".
processor\_type(str) cpu or gpu (for custom cluster only). Defaults to
None.
**Example**
* `gpu_limit` (int) : Number of GPU cores (for custom cluster only). Defaults
to None.
* `image_url` (str) : Kernel docker image URL. Defaults to None.
* `early_stopping_name` (str) : Early stopping algorithm name. Defaults to
None.
* `early_stopping_settings` (List\[Tuple\[str, str]]) : Early stopping algorithm
settings. Defaults to None.
* `message` (str) : Message. Defaults to None.
* `hyperparameters` (List\[str]) : A list of fixed hyperparameters. Defaults to None.
* `dataset_mounts` (List\[str]) : A list of dataset mounts. Defaults to None.
* `git_ref_mounts` (List\[str]) : A list of git repository mounts. Defaults to
None.
* `git_diff_mount` (str) : Git diff mounts. Defaults to None.
* `archive_file_mount` (str) : Local archive file mounts. Defaults to None.
* `object_storage_mount` (str) : Object storage mounts. Defaults to None.
* `root_volume_size` (str) : Root volume size. Defaults to None.
* `working_dir` (str) : Working directory path. Defaults to None.
* `output_dir` (str) : Output directory path. Defaults to "/output/".
**Example**
```python theme={null}
sweep_objective = vessl.SweepObjective(
type="maximize",
goal="0.99",
metric="val_accuracy",
)
parameters = [
vessl.SweepParameter(
name="optimizer",
type="categorical",
range=vessl.SweepParameterRange(
list=["adam", "sgd", "adadelta"]
)
),
vessl.SweepParameter(
name="batch_size",
type="int",
range=vessl.SweepParameterRange(
max="256",
min="64",
step="8",
)
)
]
# Custom Cluster
vessl.create_sweep(
name="example-sweep-name",
objective=sweep_objective,
max_experiment_count=4,
parallel_experiment_count=2,
max_failed_experiment_count=2,
algorithm="random",
parameters=parameters,
dataset_mounts=["/input:mnist"],
cluster_name="dgx-cluster",
processor_type="gpu",
gpu_type="NVIDIA-A100-SXM4-80GB",
gpu_limit=2,
cpu_limit=30,
memory_limit="100Gi",
kernel_image_url="public.ecr.aws/vessl/kernels:py36.full-cpu",
start_command="pip install requirements.txt && python main.py",
)
# VESSL-Managed Cluster
vessl.create_sweep(
name="example-sweep-name",
objective=sweep_objective,
max_experiment_count=4,
parallel_experiment_count=2,
max_failed_experiment_count=2,
algorithm="random",
parameters=parameters,
dataset_mounts=["/input:mnist"],
cluster_name="aws-apne2",
kernel_resource_spec_name="v1.cpu-4.mem-13",
kernel_image_url="public.ecr.aws/vessl/kernels:py36.full-cpu",
start_command="pip install requirements.txt && python main.py",
)
```
***
## terminate\_sweep
```python theme={null}
vessl.terminate_sweep(
sweep_name: str, **kwargs
)
```
Terminate sweep in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `sweep_name` (str) : Sweep name.
**Example**
```python theme={null}
vessl.terminate_sweep(
sweep_name="pitch-lord",
)
```
***
## list\_sweep\_logs
```python theme={null}
vessl.list_sweep_logs(
sweep_name: str, tail: int = 200, **kwargs
)
```
List sweep logs in the default organization/project. If you want to
override the default organization/project, then pass `organization_name` or
`project_name` as `**kwargs`.
**Args**
* `sweep_name` (str) : Sweep name.
* `tail` (int) : The number of lines to display from the end. Display all if
-1. Defaults to 200.
**Example**
```python theme={null}
vessl.list_sweep_logs(
sweep_name="pitch-lord",
)
```
***
## get\_best\_sweep\_experiment
```python theme={null}
vessl.get_best_sweep_experiment(
sweep_name: str, **kwargs
)
```
Read sweep and return the best experiment info in the default
organization/project. If you want to override the default
organization/project, then pass `organization_name` or `project_name` as
`**kwargs`.
**Args**
* `sweep_name` (str) : Sweep name.
**Example**
```python theme={null}
vessl.get_best_sweep_experiment(
sweep_name="pitch-lord",
)
```
# vessl.Audio
Source: https://docs.vessl.ai/reference/sdk/utilities/audio
Use the `vessl.Audio` class to log audio data. This takes the audio data and saves it as a local WAV file in the `vessl-media/audio` directory with randomly generated names.
| Parameter | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `data_or_path` | Supported types - numpy.ndarray : the audio data
- str: the audio path
|
| `sample_rate` | The sample rate of the audio file. Required if the `numpy.ndarray` of audio data is provided as `data_or_path` |
| `caption` | Label of the given audio |
### `numpy.ndarray`
```python theme={null}
import vessl
import soundfile as sf
audio_path = "sample.wav"
data, sample_rate = sf.read(audio_path)
# Sample rate is required if numpy.ndarray is provided
vessl.log(
payload={
"test-audio": [
vessl.Audio(data, sample_rate=sample_rate, caption="audio with data example")
]
}
)
```
### `str`
```python theme={null}
import vessl
vessl.log(
payload={
"test-audio": [
vessl.Audio(audio_path, caption="audio with path example")
]
}
)
```
# vessl.configure
Source: https://docs.vessl.ai/reference/sdk/utilities/configure
### vessl.configure
```python theme={null}
vessl.configure(
*, access_token: str = None, organization_name: str = None, project_name: str = None,
credentials_file: str = None, force_update_access_token: bool = False
)
```
Configure VESSL Client API.
**Args**
* `access_token` (str) : Access token to override. Defaults to
`access_token` from `~/.vessl/config`.
* `organization_name` (str) : Organization name to override. Defaults to
`organization_name` from `~/.vessl/config`.
* `project_name` (str) : Project name to override. Defaults to
`project name` from `~/.vessl/config`.
* `credentials_file` (str) : Defaults to None.
* `force_update_access_token` (bool) : True if force update access token,
False otherwise. Defaults to False.
**Example**
```python theme={null}
vessl.configure()
```
# vessl.Image
Source: https://docs.vessl.ai/reference/sdk/utilities/image
Use the `vessl.Image` class to log image data. This takes the image data and saves it as a local PNG file in the `vessl-media/image` directory with randomly generated names.
| Parameter | Description |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | Supported types - PIL Image: the Image module of Pillow
- torch.Tensor: a PyTorch tensor
- numpy.ndarray: a NumPy array
- str: the image path
|
| `caption` | Label of the given image |
### `PIL Image`
```python theme={null}
import vessl
from PIL import Image
my_PIL_image = Image.open('my-image.png')
vessl.Image(
data=my_PIL_image,
caption='my-caption',
)
```
### `torch.Tensor`
```python theme={null}
import vessl
import torch
vessl.Image()
test_loader = torch.utils.data.DataLoader(
test_dataset, batch_size=10, shuffle=True)
for data, target in test_loader:
vessl.Image(
data=data[0],
caption=f'Target:{target[0]}',
)
```
### `numpy.ndarray`
```python theme={null}
import vessl
import numpy as np
my_np_image = np.array([[0,1,1,0],[1,0,0,1],[0,1,1,0]])
vessl.Image(
data= my_np_image,
caption='my-caption',
)
```
### `str`
```python theme={null}
import vessl
my_image_path = 'my-image.png'
vessl.Image(
data=my_image_path,
caption='my-caption',
)
```
# vessl.log
Source: https://docs.vessl.ai/reference/sdk/utilities/log
Use `vessl.log` in a training or testing loop to log a dictionary of metrics. Provide the step parameter for the loop unit – like the epoch value – and any metrics you want to log as a dictionary in the `row` parameter.
You can also log images or audio types of objects. Provide a list of `vessl.Image` objects or `vessl.Audio` with data and captions as the `payload` parameter with any dictionary key. Note that only the first key will be logged.
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------- |
| `step` | Unit size of the loop |
| `payload` | Dictionary of metrics or a list of `vessl.Image` objects or `vessl.Audio` objects |
### Logging metrics
```python theme={null}
# Logging loss values for each epoch in PyTorch
import vessl
for epoch in range(epochs):
...
vessl.log(step=epoch, payload={'loss': loss.item})
```
### Logging image objects
```python theme={null}
# Logging images in PyTorch
import vessl
def test(model, test_loader, ...):
...
test_images = []
with torch.no_grad():
for data, target in test_loader:
...
output = model(data)
...
test_images.append(
vessl.Image(
data[0],
caption=f'Pred: {output[0].item()} Truth: {target[0]}'
)
)
...
vessl.log(payload={"test-images": test_images})
```
### Logging audio objects
```python theme={null}
# Logging audio
import vessl
import soundfile as sf
audio_path = "sample.wav"
data, sample_rate = sf.read(audio_path)
# Log audio with data
vessl.log(
payload={
"test-audio": [
vessl.Audio(data, sample_rate=sample_rate, caption="audio with data example")
]
}
)
```
# vessl.progress
Source: https://docs.vessl.ai/reference/sdk/utilities/progress
# vessl.progress
Use `vessl.progress` to track the progress of your experiment. VESSL provides an estimate of a remaining training time by calculating the average elapsed time of previous epochs or batch sizes. You can view this information by hovering over the status of a running experiment. This can be used in both VESSL's managed server or in a local environment.
| Parameter | Description |
| --------- | -------------------------------------------------- |
| `value` | Amount of progress (decimal value between 0 and 1) |
### Examples
```python theme={null}
import vessl
for epoch in range(epochs):
...
# Update experiment progress every epoch
vessl.progress((epoch+1) / epochs)
```
```python theme={null}
def train(model, device, train_loader, optimizer, epoch, start_epoch):
model.train()
loss = 0
for batch_idx, (data, label) in enumerate(train_loader):
...
# Update experiment progress every batch
vessl.progress(
((epoch+1)*batch_size + batch_idx) / (batch_size * epochs))
)
```
# vessl.hp.update
Source: https://docs.vessl.ai/reference/sdk/utilities/update
To record hyperparameters in VESSL **experiments**, set `vessl.hp` and update with `vessl.hp.update` as follows.
#### Option 1: record hyperparameters with Python dictionary
```python theme={null}
import vessl
d = {"lr": 0.1, "optimizer": "sgd"}
vessl.hp.update(d)
```
#### Option 2: record hyperparameters with Python argparse module
```python theme={null}
import argparse
import vessl
parser = argparse.ArgumentParser()
parser.add_argument('-n', '--num_layers', type=int, default=3)
args = parser.parse_args(args=[])
vessl.hp.update(args)
```
# Volume (Deprecated)
Source: https://docs.vessl.ai/reference/sdk/volume
The `volume` functions have been deprecated.
Please use the `vessl.storage` package for managing VESSL storage volumes.
### read\_volume\_file
```python theme={null}
vessl.read_volume_file(
volume_id: int, path: str
)
```
Read a file in the volume.
**Args**
* `volume_id` (int) : Volume ID.
* `path` (str) : Path within the volume.
**Example**
```python theme={null}
vessl.read_volume_file(
volume_id=123456,
path="train.csv",
)
```
***
## list\_volume\_files
```python theme={null}
vessl.list_volume_files(
volume_id: int, need_download_url: bool = False, path: str = '',
recursive: bool = False
)
```
List files in the volume.
**Args**
* `volume_id` (int) : Volume ID.
* `need_download_url` (bool) : True if you need a download URL, False
otherwise. Defaults to False.
* `path` (str) : Path within the volume. Defaults to root.
* `recursive` (bool) : True if list files recursively, False otherwise.
Defaults to False.
**Example**
```python theme={null}
vessl.list_volume_files(
volume_id=123456,
)
```
***
## create\_volume\_file
```python theme={null}
vessl.create_volume_file(
volume_id: int, is_dir: bool, path: str
)
```
Create file in the volume.
**Args**
* `volume_id` (int) : Volume ID.
* `is_dir` (bool) : True if a file is directory, False otherwise.
* `path` (str) : Path within the volume.
**Example**
```python theme={null}
vessl.create_volume_file(
volume_id=123456,
is_dir=False,
path="models"
)
```
***
## delete\_volume\_file
```python theme={null}
vessl.delete_volume_file(
volume_id: int, path: str
)
```
Delete file in the volume.
**Args**
* `volume_id` (int) : Volume ID.
* `path` (str) : Path within the volume.
**Example**
```python theme={null}
vessl.delete_volume_file(
volume_id=123456,
path="model.pth",
)
```
***
## upload\_volume\_file
```python theme={null}
vessl.upload_volume_file(
volume_id: int, path: str
)
```
Upload file in the volume.
**Args**
* `volume_id` (int) : Volume ID.
* `path` (str) : Local file path to upload
**Example**
```python theme={null}
vessl.upload_volume_file(
volume_id=123456,
path="model.pth",
)
```
***
## copy\_volume\_file
```python theme={null}
vessl.copy_volume_file(
source_volume_id: Optional[int], source_path: str,
dest_volume_id: Optional[int], dest_path: str, quiet: bool = False
)
```
Copy file either from local to remote, remote to local, or remote to
remote.
**Args**
* `source_volume_id` (Optional\[int]) : Source volume file id. If not
specified, source is assumed to be local.
* `source_path` (str) : If source\_volume\_id is empty, local source path.
Otherwise, remote source path.
* `dest_volume_id` (Optional\[int]) : Destination volume file id. If not
specified, destination is assumed to be local.
* `dest_path` (str) : If dest\_volume\_id is empty, local destination path.
Otherwise, remote destination path.
* `quiet` (bool) : True if the muted output, False otherwise. Defaults to
False.
**Example**
```python theme={null}
vessl.copy_volume_file(
source_volume_id=123456,
source_path="model.pth",
dest_volume_id=123457,
dest_path="model.pth",
)
```
# Workspace
Source: https://docs.vessl.ai/reference/sdk/workspace
### read\_workspace
```python theme={null}
vessl.read_workspace(
workspace_id: int, **kwargs
)
```
Read workspace in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `workspace_id` (int) : Workspace ID.
**Example**
```python theme={null}
vessl.read_workspace(
workspace_id=123456,
)
```
***
## list\_workspaces
```python theme={null}
vessl.list_workspaces(
cluster_id: int = None, statuses: List[str] = None, mine: bool = True, **kwargs
)
```
List workspaces in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `cluster_id` (int) : Defaults to None.
* `statuses` (List\[str]) : A list of status filter. Defaults to None.
* `mine` (bool) : True if list only my workspaces, False otherwise. Defaults
to True.
**Example**
```python theme={null}
vessl.list_workspaces(
cluster_id=123456,
statuses=["running"],
)
```
***
## create\_workspace
```python theme={null}
vessl.create_workspace(
name: str, cluster_name: str, cluster_node_names: List[str] = None,
kernel_resource_spec_name: str = None, processor_type: str = None,
cpu_limit: float = None, memory_limit: str = None, gpu_type: str = None,
gpu_limit: int = None, kernel_image_url: str = None, max_hours: int = 24,
dataset_mounts: List[str] = None, local_files: List[str] = None,
use_vesslignore: bool = True, root_volume_size: str = '100Gi', ports: List[Dict[str,
Any]] = None, init_script: str = None, **kwargs
)
```
Create workspace in the default organization. If you want to override the
default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `name` (str) : Workspace name.
* `cluster_name` (str) : Cluster name(must be specified before other options).
* `cluster_node_names` (List\[str]) : A list of candidate cluster node names.
Defaults to None.
* `kernel_resource_spec_name` (str) : Resource type to run an experiment (for
managed cluster only). Defaults to None.
* `cpu_limit` (float) : Number of vCPUs (for custom cluster only). Defaults to
None.
* `memory_limit` (str) : Memory limit in GiB (for custom cluster only).
Defaults to None.
* `gpu_type` (str) : GPU type (for custom cluster only). Defaults to None.
* `gpu_limit` (int) : Number of GPU cores (for custom cluster only). Defaults
to None.
* `kernel_image_url` (str) : Kernel docker image URL. Defaults to None.
* `max_hours` (int) : Max hours limit to run. Defaults to 24.
* `dataset_mounts` (List\[str]) : A list of dataset mounts. Defaults to None.
* `local_files` (List\[str]) : A list of local file mounts. Defaults to None.
* `use_vesslignore` (bool) : True if local files matching glob patterns
in .vesslignore files should be ignored. Patterns apply relative to
the directory containing that .vesslignore file.
* `root_volume_size` (str) : Root volume size. Defaults to "100Gi".
* `ports` (List\[Dict\[str, Any]]) : Port numbers to expose. Defaults to None.
processor\_type(str) cpu or gpu (for custom cluster only). Defaults to
None.
init\_script(str) Custom init script. Defaults to None.
**Example**
```python theme={null}
vessl.create_workspace(
name="modern-kick",
cluster_name="aws-apne2",
kernel_resource_spec_name="v1.cpu-0.mem-1",
kernel_image_url="public.ecr.aws/vessl/kernels:py36.full-cpu.jupyter",
)
```
***
## list\_workspace\_logs
```python theme={null}
vessl.list_workspace_logs(
workspace_id: int, tail: int = 200, **kwargs
)
```
List experiment logs in the default organization. If you want to override
the default organization, then pass `organization_name` as `**kwargs`.
**Args**
* `workspace_id` (int) : Workspace ID.
* `tail` (int) : The number of lines to display from the end. Display all if
-1. Defaults to 200.
**Example**
```python theme={null}
vessl.list_workspace_logs(
workspace_id=123456,
)
```
***
## start\_workspace
```python theme={null}
vessl.start_workspace(
workspace_id: int, **kwargs
)
```
Start the workspace container in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `workspace_id` (int) : Workspace ID.
**Example**
```python theme={null}
vessl.start_workspace(
workspace_id=123456,
)
```
***
## stop\_workspace
```python theme={null}
vessl.stop_workspace(
workspace_id: int, **kwargs
)
```
Stop the workspace container in the default organization. If you want to
override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `workspace_id` (int) : Workspace ID.
**Example**
```python theme={null}
vessl.stop_workspace(
workspace_id=123456,
)
```
***
## terminate\_workspace
```python theme={null}
vessl.terminate_workspace(
workspace_id: int, **kwargs
)
```
Terminate the workspace container in the default organization. If you
want to override the default organization, then pass `organization_name` as
`**kwargs`.
**Args**
* `workspace_id` (int) : Workspace ID.
**Example**
```python theme={null}
vessl.terminate_workspace(
workspace_id=123456,
)
```
***
## backup\_workspace
```python theme={null}
vessl.backup_workspace()
```
Backup the home directory of the workspace. This command should be called
inside a workspace.
**Example**
```python theme={null}
vessl.backup_workspace()
```
***
## restore\_workspace
```python theme={null}
vessl.restore_workspace()
```
Restore the home directory from the previous backup. This command should
be called inside a workspace.
**Example**
```python theme={null}
vessl.restore_workspace()
```
***
## connect\_workspace\_ssh
```python theme={null}
vessl.connect_workspace_ssh(
private_key_path: str
)
```
Connect to a running workspace via SSH.
**Args**
* `private_key_path` (str) : SSH private key path
**Example**
```python theme={null}
vessl.connect_workspace_ssh(
private_key_path="~/.ssh/key_path",
)
```
***
## update\_vscode\_remote\_ssh
```python theme={null}
vessl.update_vscode_remote_ssh(
private_key_path: str
)
```
Update .ssh/config file for VSCode Remote-SSH plugin.
**Args**
* `private_key_path` (str) : SSH private key path
**Example**
```python theme={null}
vessl.update_vscode_remote_ssh(
private_key_path="~/.ssh/key_path",
)
```
# Create an asynchronous request
Source: https://docs.vessl.ai/reference/serverless-api/create-async-request
POST {base_url}/async
# Overview
Create and enqueue an asynchronous request.
Asynchronous requests will be queued. If the service is available at the moment, it will
soon be processed. Otherwise, if the service is currently scaled down to zero, the request
will get processed after the service becomes available.
The result can be queried in [output-fetching API](get-async-request-output).
## Interaction code example
```shell curl theme={null}
$ echo '
{
"method": "POST",
"path": "/predictions/my-model",
"data": {
"question": "How are you?"
}
}' | curl \
-H "Authorization: Bearer ${TOKEN}" \
"${BASE_URL}/async" \
--json @-
{"id": "98nlux8b0eu6"}
```
```python Python theme={null}
import requests
base_url = "https://..."
token = "..."
r = requests.post(
f"{base_url}/async",
headers={"Authorization": f"Bearer {token}"},
json={
"data": {"question": "How are you?"}
"method": "POST",
"path": "/predictions/my-model",
}
)
request_id = r.json()["id"]
print(request_id) # prints: 98nlux8b0eu6
```
# Request
Authorization
You must provide a token in `Authorization` header with `Bearer` scheme, as:
```
Authorization: Bearer
```
The token can be found in the web UI (in service overview's Request dialog).
## Path parameters
Base URL for your service. This value can be found in the web UI (in service overview's
Request dialog).
Typical value: `https://serve-api.dev2.vssl.ai/api/v1/services/`
## JSON body parameters
JSON data to send as body in the request to your service.
Method to use in request. If unspecified, `POST` will be used.
Path to use in request. If unspecified, `/` (root path) will be used.
# Response
On successful operation, this API will respond with HTTP status code 201 (Created).
ID of the newly created request. It can be used to fetch its status and output.
This is a lowercase-alphanumeric string with length 1 to 16.
Example: `98nlux8b0eu6`
```json Request body theme={null}
{
"method": "POST",
"path": "/predictions/my-model",
"data": {
"question": "How are you?"
}
}
```
```json Response body (201 Created) theme={null}
{
"id": "98nlux8b0eu6"
}
```
# Fetch output of an asynchronous request
Source: https://docs.vessl.ai/reference/serverless-api/get-async-request-output
GET {base_url}/async/{request_id}/output
# Overview
Fetch the status and output of an asynchronous request
(that was created in [request creation API](create-async-request)).
The response will be considered as success or failure depending on its status code.
All status codes between `200` and `299` will be considered as a successful request and display
status `"completed"`; other status codes, especially `400`-`499` (cilent errors) and `500`-`599`
(server errors) will be handled as status `"failed"`.
## Interaction code example
```shell curl theme={null}
$ curl \
-H "Authorization: Bearer ${TOKEN}" \
"${BASE_URL}/async/${REQUEST_ID}/output" | jq
{
"status": "completed",
"status_code": 200,
"raw_output": "{\"text\": \"Hello!\"}",
"output": {
"text": "Hello!"
}
}
```
```python Python theme={null}
import requests
base_url = "https://..."
token = "..."
request_id = "98nlux8b0eu6"
r = requests.get(
f"{base_url}/async/{request_id}/output",
headers={"Authorization": f"Bearer {token}"}
)
print(r.json())
# prints:
# {'status': 'completed', 'status_code': 200, 'raw_output': '{"text": "Hello!"}', 'output': {'text': 'Hello!'}}
```
# Request
Authorization
You must provide a token in `Authorization` header with `Bearer` scheme, as:
```
Authorization: Bearer
```
The token can be found in the web UI (in service overview's Request dialog).
## Path parameters
Base URL for your service. This value can be found in the web UI (in service overview's
Request dialog).
Typical value: `https://serve-api.dev2.vssl.ai/api/v1/services/`
Request ID from [request creation API](create-async-request).
Example: `98nlux8b0eu6`
# Response
Status of the request. Its possible values and meanings are as follows.
* `"pending"`: The request is waiting in the queue.
* `"in_progress"`: The request is being processed.
* `"completed"`: The request has ended with status code `200`-`299`.
* `"failed"`: The request has ended with status code other than `200`-`299`,
or an internal error has occurred. In either case, `fail_reason`
field will also be present.
Status code response.
This field is only present when `status` is either `"completed"` or `"failed"`.
Raw bytes of the response body.
This field is only present when `status` is either `"completed"` or `"failed"`.
Response body, decoded as JSON. If the response body is not a valid JSON, this field
is omitted.
This field is only present when `status` is either `"completed"` or `"failed"`.
Human-readable explanation for failure.
This field is only present when `status` is `"failed"`.
```json Completed theme={null}
{
"status": "completed",
"status_code": 200,
"raw_output": "{\"text\": \"Hello!\"}",
"output": {
"text": "Hello!"
}
}
```
```json Failed theme={null}
{
"status": "failed",
"status_code": 400,
"raw_output": "{\"message\":\"Request body must contain field 'data'.\"}",
"output": {
"message": "Request body must contain field 'data'."
},
"fail_reason": "Server responded with status code 400"
}
```
```json Pending theme={null}
{
"status": "pending"
}
```
# Send a request
Source: https://docs.vessl.ai/reference/serverless-api/send-a-request
POST {base_url}/request/{path}
# Overview
Send a request and fetch the result directly.
In contrast to asynchronous APIs, this API will return the result in the same connection,
and there is no JSON wrapping in either input or outputs. Thus, you can use this API
as if you are directly accessing your service.
When the service is in a cold state (i.e. there are no running replicas due to service
idleness) and a new request is made, a new replica will be started immediately.
In such case, the first few requests **may get aborted** due to timeouts,
until the replica becomes up and running. Please consult your HTTP client's timeout configuration.
## Interaction code example
```shell curl theme={null}
$ curl \
-H "Authorization: Bearer ${TOKEN}" \
"${BASE_URL}/request/predictions/my-model" \
--json '{"question": "1+1 = ?"}'
{"answer": "The answer is 3. No, it's 11."}
```
```python Python theme={null}
import requests
base_url = "https://..."
token = "..."
path="/predictions/my-model"
r = requests.post(
f"{base_url}/request/{path[1:]}",
headers={"Authorization": f"Bearer {token}"},
json={
"question": "1+1 = ?"
}
)
print(r.text)
```
# Request
Authorization
You must provide a token in `Authorization` header with `Bearer` scheme, as:
```
Authorization: Bearer
```
The token can be found in the web UI (in service overview's Request dialog).
## Path parameters
Base URL for your service. This value can be found in the web UI (in service overview's
Request dialog).
Typical value: `https://serve-api.dev2.vssl.ai/api/v1/services/`
Path to use to make a request to your service.
Your service should provide corresponding endpoint. Common path values used for inference include:
* `/v2/models/my-model/infer`
* `/predictions/my-model`
* `/v1/completions`
# Response
Response from your service will be relayed. Thus, there is no fixed form of response.
The response will be streamed with low latency, so it can be used in live streamed applications,
e.g. chatting or text completions using large language models (LLMs).
HTTP response headers from your service will be generally stripped out.
**Only the following headers** will be passed along:
* `Content-Type`
* `Content-Length`
```text Request example theme={null}
POST /predictions/my-model
(...)
Content-Type: application/json
Content-Length: 23
{"question": "1+1 = ?"}
```
```text Response example theme={null}
200 OK
(...)
Content-Type: application/json
Content-Length: 43
{"answer": "The answer is 3. No, it's 11."}
```
# Cheat Sheet
Source: https://docs.vessl.ai/reference/yaml/cheatsheet
Full list of YAML configurations.
```yaml Full YAML configurations theme={null}
name: stable-diffusion
description: This is the inference example of stable diffusion.
tags:
- "best"
- "A100-80g"
- "20epochs"
resources:
cluster: vessl-oci-sanjose
preset: gpu-l4-small
node_names:
- "n01"
- "n03"
- "n04"
import:
/import/code: git://github.com/{accountName}/{repoName}
/import/code-verbose:
git:
url: https://github.com/{accountName}/{repoName}
ref: c0ffee
credential_name: my-git-cred-name
/import/dataset: vessl-dataset://{organizationName}/{datasetName}
/import/dataset-verbose:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/import/model: vessl-model://{organizationName}/{modelRepositoryName}/{modelNumber}
/import/model-verbose:
model:
organization_name: {organizationName}
model_repository_name: {modelRepositoryName}
model_number: {modelNumber}
/import/artifact: vessl-artifact://{organiztionName}/{projectName}/{artifactName}
/import/artifact-verbose:
artifact:
organization_name: {organizationName}
project_name: {projectName}
name: {artifactName}
/import/artifact-verbose-same-project:
artifact:
name: {artifactName}
/import/s3: s3://{bucketName}/{path}
/import/s3-verbose:
s3:
bucket: {bucketName}
prefix: {prefix}
credential_name: my-s3-cred-name
/import/gs: gs://{buckeName}/{path}
/import/gs-verbose:
gs:
bucket: {bucketName}
prefix: {prefix}
credential_name: my-gs-cred-name
mount:
/mount/dataset: vessl-dataset://{organizationName}/{datasetName}
/mount/dataset-verbose:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/mount/hostpath: hostpath://{path}
/mount/hostpath-verbose:
hostpath:
path: {path}
readonly: true
/mount/nfs: nfs://{server}/{path}
/mount/nfs-verbose:
nfs:
server: {server}
path: {path}
readonly: false
export:
/export/output-artifact: vessl-artifact://
/export/output-artifact-verbose:
artifact:
/export/backup-artifact: vessl-artifact://{organizationName}/{projectName}/{artifactName}
/export/backup-artifact-verbose:
artifact:
organization_name: {organizationName}
project_name: {projectName}
artifact_name: {artifactName}
/export/dataset: vessl-dataset://{organizationName}/{datasetName}
/export/dataset-verbose:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/export/model: vessl-model://{organizationName}/{modelRepositoryName}
/export/model-verbose:
model:
organization_name: {organizationName}
model_repository_name: {modelRepositoryName}
/export/s3: s3://{buckeName}/{prefix}
/export/s3-verbose:
s3:
bucket: {bucketName}
prefix: {prefix}
endpoint: in-house.endpoint.co.kr
credential_name: my-s3-cred-name
/export/gs: gs://{bucketName}/{prefix}
/export/gs-verbose:
gs:
bucket: {bucketName}
prefix: {prefix}
run:
- workdir: /input/data1
command: |
python data_preprocessing.py
- wait: 10s
- workdir: /root/git-examples
command: |
python train.py --learning_rate=$learning_rate --batch_size=$batch_size
interactive:
max_runtime: 24h # required if interactive
jupyter: # required if interactive
idle_timeout: 120m # required if interactive
ports:
- 3000
- name: streamlit
type: http
port: 8501
env:
learning_rate: 0.001
postgres_password:
value: OUR_DB_PW
secret: true
```
# Run YAML
Source: https://docs.vessl.ai/reference/yaml/run-yaml
VESSL Run is configured through a single YAML file.
## Field types
### Metadata
`name`, `description`, and `tags` fields are the metadata of Run. They should be ideally represent the specific characteristics or purposes of your run for better identification.
| Name | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------- |
| `name` | string | Required | The name of the run. |
| `description` | string | Optional | The description of the run. |
| `tags` | list | Optional | The tags of the run. |
```yaml Specify run metadata theme={null}
name: stable-diffusion
description: This is the inference example of stable diffusion.
tags:
- "best"
- "A100-80g"
- "20epochs"
```
### Resources
`resources` specifies the resource specs to use for run. Use `preset` provided by VESSL or request the desired resource with `requests`.
0. Common fields
| Name | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `cluster` | string | Optional | The cluster to be used for the run. (default: VESSL-managed cluster) |
| `node_names` | list | Optional | Specify candidate nodes for workload assignment. If it's not set, we'll find any available node. |
1. Using `preset` with common fields
| Name | Type | Required | Description |
| -------- | ------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preset` | string | Required without `requests` | The name of resource spec preset that specified in VESSL. If the preset is not specified, we will offer the best option for you based on `reqeusts`. |
```yaml Run resource specs with preset theme={null}
resources:
cluster: vessl-oci-sanjose
preset: gpu-l4-small
```
```yaml Run resource specs with preset and node candidates theme={null}
resources:
cluster: my-on-premises-cluster
preset: v100-1
node_names:
- "n01"
- "n03"
- "n04"
```
2. Using `requests` with common fields (Upcomming feature)
| Name | Type | Required | Description |
| ---------------- | ------ | ------------------------- | ------------------------------------------------------------------------- |
| `requests` | map | Required without `preset` | The desired resource specs. |
| `cpu` | string | Optional | The number of cpu cores. |
| `memory` | string | Optional | The memory size in GB. |
| `nvidia.com/gpu` | map | Optional | The `device_type` and `quanity` of the NVIDIA GPU to be used for the run. |
```yaml Run resource specs with requests theme={null}
resources:
cluster: vessl-oci-sanjose
requests:
cpu: "4"
memory: 12Gi
nvidia.com/gpu:
device_type: V100
quantity: "2"
```
```yaml Run resource specs with requests and node candidates theme={null}
resources:
cluster: my-on-premises-cluster
requests:
cpu: "4"
memory: 12Gi
nvidia.com/gpu:
device_type: V100
quantity: "2"
node_names:
- "n01"
- "n03"
- "n04"
```
You can list available clusters or resource specs with the CLI command: `vessl cluster list` or `vessl resource list`.
```bash List VESSL clusters theme={null}
pip install vessl
vessl cluster list
```
```bash List resource specs theme={null}
pip install vessl
vessl resource list
```
### Container Image
The `image` field is a string that specifies the container image to be used in the run. This is typically a Docker image that includes all the necessary dependencies and environment for your machine learning model.
| Name | Type | Required | Description |
| ----------------- | ------------- | -------- | ------------------------------------------------------------ |
| `image` | string or map | Requried | Container image url or map of `url` and `credential_name`. |
| `url` | string | Optional | Container image url. |
| `credential_name` | string | Optional | Registered credential name at VESSL for private image usage. |
```yaml Use a VESSL-managed image theme={null}
image: quay.io/vessl-ai/torch:2.3.1-cuda12.1-r5
```
```yaml Use a public custom image theme={null}
image: my-docker-account/public-repo-name:tag-name
```
```yaml Use a private custom image theme={null}
image:
url: my-docker-account/private-repo-name:tag-name
credential_name: docker_hub_cred
```
You can list available VESSL-managed images with the CLI command: `vessl image list`.
```bash List VESSL-manged images with the VESSL CLI theme={null}
pip install vessl
vessl image list
```
### Volumes
There are three type of volumes: `import`, `mount`, and `export`. Each field is a map that specifies a target path as a key and a source information as a value. The value is either a simple string with prefix or another map that holds more detailed information.
1. Import
The `import` type signifies that the data will be downloaded from the source to a target path in the running container.
| Prefix | Type | Required | Description |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `git://` | string | Optional | Import a git repository. The repository will be cloned into the specified target path when container starts. |
| `vessl-dataset://` | string | Optional | Import a dataset stored in VESSL Dataset. |
| `vessl-model://` | string | Optional | Import a model stored in VESSL Model Registry. |
| `vessl-artifact://` | string | Optional | Import an artifact stored in VESSL Artifact. |
| `s3://` | string | Optional | Import an AWS S3 bucket. |
| `gs://` | string | Optional | Import a Google Cloud Storage. |
```yaml String import value with prefix theme={null}
import:
/import/code: git://github.com/{accountName}/{repoName}
/import/dataset: vessl-dataset://{organizationName}/{datasetName}
/import/model: vessl-model://{organizationName}/{modelRepositoryName}/{modelNumber}
/import/artifact: vessl-artifact://{organiztionName}/{projectName}/{artifactName}
/import/s3: s3://{bucketName}/{path}
/import/gs: gs://{buckeName}/{path}
```
```yaml Verbose import value theme={null}
import:
/import/code:
git:
url: https://github.com/{accountName}/{repoName}
ref: c0ffee
credential_name: my-git-cred-name
/import/dataset:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/import/model:
model:
organization_name: {organizationName}
model_repository_name: {modelRepositoryName}
model_number: {modelNumber}
/import/artifact:
artifact:
organization_name: {organizationName}
project_name: {projectName}
name: {artifactName}
/import/artifact-same-project:
artifact:
name: {artifactName}
/import/s3:
s3:
bucket: {bucketName}
prefix: {prefix}
credential_name: my-s3-cred-name
/import/gs:
gs:
bucket: {bucketName}
prefix: {prefix}
credential_name: my-gs-cred-name
```
2. Mount
The `mount` type means that the data will be directly mounted to a target path in the run container, providing direct access to the user.
| Prefix | Type | Required | Description |
| ------------------ | ------- | -------- | ---------------------------------------------------------- |
| `vessl-dataset://` | string | Optional | Mount a dataset stored in VESSL Dataset. |
| `hostpath://` | string | Optional | Mount a file or directory from the host node's filesystem. |
| `nfs://` | string | Optional | Mount a Network File System(NFS). |
| `readonly` | boolean | Optional | True if readonly mode. (default: True) |
```yaml String mount value with prefix theme={null}
mount:
/mount/dataset: vessl-dataset://{organizationName}/{datasetName}
/mount/hostpath: hostpath://{path}
/mount/nfs: nfs://{server}/{path}
```
```yaml Verbose mount value theme={null}
mount:
/mount/dataset:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/mount/hostpath:
hostpath:
path: {path}
readonly: true
/mount/nfs:
nfs:
server: {server}
path: {path}
readonly: false
```
3. Export
The `export` type is desgined for uploading data from a path in the run container to a target path after run execution.
| Prefix | Type | Required | Description |
| ------------------- | ------ | -------- | ------------------------------- |
| `vessl-artifact://` | string | Optional | Export to VESSL Artifact. |
| `vessl-dataset://` | string | Optional | Export to VESSL Dataset. |
| `vessl-model://` | string | Optional | Export to VESSL Model. |
| `s3://` | string | Optional | Export to Amazon S3 bucket. |
| `gs://` | string | Optional | Export to Google Cloud Storage. |
```yaml String export value with prefix theme={null}
export:
/export/output-artifact: vessl-artifact://
/export/backup-artifact: vessl-artifact://{organizationName}/{projectName}/{artifactName}
/export/dataset: vessl-dataset://{organizationName}/{datasetName}
/export/model: vessl-model://{organizationName}/{modelRepositoryName}
/export/s3: s3://{buckeName}/{prefix}
/export/gs: gs://{bucketName}/{prefix}
```
```yaml Verbose export value theme={null}
export:
/export/output-artifact:
artifact:
/export/backup-artifact:
artifact:
organization_name: {organizationName}
project_name: {projectName}
artifact_name: {artifactName}
/export/dataset:
dataset:
organization_name: {organizationName}
dataset_name: {datasetName}
/export/model:
model:
organization_name: {organizationName}
model_repository_name: {modelRepositoryName}
/export/s3:
s3:
bucket: {bucketName}
prefix: {prefix}
endpoint: in-house.endpoint.co.kr
credential_name: my-s3-cred-name
/export/gs:
gs:
bucket: {bucketName}
prefix: {prefix}
credential_name: my-gs-cred-name
```
### Run Command
The `run` field is a list that contains commands to be run in the container. Each item in the list is a map with the following keys. `run` could be empty if it's an interactive run.
| Name | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------- |
| `workdir` | string | Optional | The working directory for the command. |
| `command` | string | Required | The command to be run. |
| `wait` | string | Optional | How long to wait after a command. |
```yaml Run a single command theme={null}
run:
- command: |
python train.py --learning_rate=$learning_rate --batch_size=$batch_size
```
```yaml Run multiple commands theme={null}
run:
- workdir: /input/data1
command: |
python data_preprocessing.py
- wait: 10s
- workdir: /root/git-examples
command: |
python train.py --learning_rate=$learning_rate --batch_size=$batch_size
```
### Interactive
The `interactive` field is used to specify if the run allows interactive communication with the user. It provides multiple ways to interact with the container during the run, such as JupyterLab, SSH, or a custom service via specified ports.
| Name | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `interactive` | map | Optional | Mark run as an interactive type that includes `max_runtime`, `jupyter`, and `idle_timeout` |
| `max_runtime` | string | Required | The amount of time to run. Set `0` for infintie use. |
| `jupyter` | map | Required | Jupyter configurations that includes `idle_timeout` |
| `idle_timeout` | string | Required | The amount of time a server can be inactive before it will be culled. |
```yaml Maximum runtime 24h and idle_timeout 120m theme={null}
interactive:
max_runtime: 24h
jupyter:
idle_timeout: 120m
```
### Ports
The `ports` field is a list of map that specifies the port information to expose.
| Name | Type | Required | Description |
| ------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `ports` | list | Optional | List of port numbers or port information that includes `name`, `type`, and `port` to expose. |
| `name` | string | Optional | The port name. |
| `type` | string | Optional | The protocol of port. (http or tcp) |
| `port` | int | Optional | The port number. |
```yaml Expose port by number theme={null}
ports:
- 3000
```
```yaml Expose port by name, number, and type theme={null}
ports:
- name: streamlit
type: http
port: 8501
```
### Environment Variables
The `env` field is a map that specifies the environment variables for the run. Each key-value pair in this map represents an environment variable and its value.
| Name | Type | Required | Description |
| -------- | ------- | -------- | --------------------------------------------------------------- |
| `env` | map | Optional | Key-value pairs for environment variables in the run container. |
| `value` | string | Optional | Value of environment variables. |
| `secret` | boolean | Optional | True if the variable is secret. |
```yaml Set multiple environment variables theme={null}
env:
learning_rate: 0.001
postgres_password:
value: OUR_DB_PW
secret: true
```
# Serve YAML
Source: https://docs.vessl.ai/reference/yaml/serve-yaml
VESSL Serve is configured through a single YAML file.
## Revision YAML Field Types
### Name
Service name created by the user.
| Name | Type | Required | Description |
| ---- | ------ | -------- | ------------ |
| name | string | Requried | Service name |
```yaml theme={null}
name: vessl-test-service
```
### Message
Write a message for the Service Revision. We recommend writing an identical message for each revision to distinguish them.
| Name | Type | Required | Description |
| ------- | ------ | -------- | ---------------------------- |
| message | string | Requried | Description of the revision. |
```yaml theme={null}
message: vessl-yaml-revision
```
### Image
The name of the docker image that will be used for inference. You can also use a custom docker image.
| Name | Type | Required | Description |
| ----- | ------ | -------- | ----------------- |
| image | string | Requried | Docker image url. |
```yaml theme={null}
image: quay.io/vessl-ai/torch:2.3.1-cuda12.1-r5
```
### Resources
Write down the compute resources you want to use for Service. You can specify the resources you want to use in the Cluster settings.
| Name | Type | Required | Description |
| ------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------- |
| cluster | string | Optional | The cluster to be used for the run. (default: VESSL-managed cluster) |
| preset | string | Optional | The preset to be used for the run. |
| spot | one of (empty, SpotOnly, SpotFirst, OnDemandOnly) | Optional | Whether to use spot instances for the run or not. |
```yaml theme={null}
resources:
cluster: vessl-oci-sanjose
preset: gpu-l4-small-spot
```
### Import
Write the datasets and volumes imported in the Revision container when the Revision is deployed.
| Prefix | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| git:// | string | Optional | Mount a git repository into your container. The repository will be cloned into the specified mount path when container starts. |
| hf:// | string | Optional | Mount a huggingface repository into your container. The repository will be cloned into the specified mount path when container starts. |
| vessl-dataset:// | string | Optional | Mount a dataset stored in VESSL. Replace organizationName with the name of your organization and datasetName with the name of the dataset. |
| s3:// | string | Optional | Mount an AWS S3 bucket into your container. Replace bucketName with the name of your S3 bucket and path with the path to te file or folder you want to mount. |
| gs\:// | string | Optional | Mount an GCP GCS bucket into your container. Replace bucketName with the name of your GCS bucket and path with the path to te file or folder you want to mount. |
| vessl-model:// | string | Optional | Mount a VESSL Model into your container. |
| vessl-artifact:// | string | Optional | Mount a VESSL Artifact into your container. |
```yaml theme={null}
import:
/root/git-examples: git://github.com/vessl-ai/examples
/root/hf: hf:///opt/data1
/input/config: gs://config.yaml
/input/data2: s3://192.168.10.2:~/
/input/data3: vessl-dataset://{organization_name}/{dataset_name}
```
### Mount
Write down the volumes that will be mounted in the Revision Service container when the Revision is deployed.
| Prefix | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hf:// | string | Optional | Mount a huggingface repository into your container. The repository will be cloned into the specified mount path when container starts. |
| hostpath:// | string | Optional | Mount a file or directory from the host node’s filesystem into your container. Replace path with the path to the file or folder you want to mount. |
| nfs\:// | string | Optional | Mount a Network File System(NFS) into your container. Replace ip with the IP address of your NFS server and path with the path to the file or folder you want to mount. |
| cifs\:// | string | Optional | Mount a Command Internet File System(CIFS) into your contianer. Replace ip with the IP address of your NFS server and path with the path to the file or folder you want to mount. |
| gcs-fuse:// | string | Optional | Mount a GCS with FUSE csi driver. |
### Run
Write down what commands you want to run on the service container when the Revision is deployed.
| Name | Type | Required | Description |
| ------- | ------ | -------- | -------------------------------------- |
| workdir | string | Optional | The working directory for the command. |
| command | string | Required | The command to be run. |
```yaml theme={null}
run:
- workdir: /root/git-examples
command: |
vessl model launch service.py:Service -p 3000
```
### Env
Write down the environment variables that will be set in the Revision Service container.
| Name | Type | Required | Description |
| ---- | ---- | -------- | --------------------------------------------------------------- |
| env | map | Optional | Key-value pairs for environment variables in the run container. |
```yaml theme={null}
env:
learning_rate: 0.001
batch_size: 64
optimizer: sgd
```
### Ports
Write down the ports and protocols that the Revision Service container should open.
| Name | Type | Required | Description |
| ---- | ------ | -------- | ------------------------------- |
| name | string | Required | The name for the opening port. |
| type | string | Required | The protocol the port will use. |
| port | int | Required | The number of the port. |
```yaml theme={null}
ports:
- name: web-service
type: http
port: 8000
- name: web-service-2
type: http
port: 8001
```
### Autoscaling
Sets the value for how the Revision Pod will autoscale.
| Name | Type | Required | Description |
| ------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| min | string | Required | Minimum number of Pods to autoscale. |
| max | string | Required | Maximum number of Pods to autoscale. |
| metric | int | Required | Determine what conditions you want to autoscale under. You can select cpu, gpu, memory, and custom |
| target | int | Required | A metric threshold percentage. If the metric is above the target, then the Autoscaler automatically scale-out. |
```yaml theme={null}
autoscaling:
min: 1
max: 3
metric: cpu
target: 50
```