diff --git a/.gitignore b/.gitignore index 13e25623..faa00067 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/api/autogluon.cloud.*.rst # PyBuilder target/ @@ -133,4 +134,4 @@ VERSION.minor .idea .vscode .DS_Store -results.xml \ No newline at end of file +results.xml diff --git a/README.md b/README.md index 90eac27f..cf84c609 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,91 @@ -
- -
+
+ -# AutoGluon-Cloud +## Train and Deploy AutoGluon in the Cloud +[![Latest Release](https://img.shields.io/github/v/release/autogluon/autogluon-cloud)](https://github.com/autogluon/autogluon-cloud/releases) +[![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/autogluon.cloud/) +[![GitHub license](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE) [![Continuous Integration](https://github.com/autogluon/autogluon-cloud/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/autogluon/autogluon-cloud/actions/workflows/continuous_integration.yml) [AutoGluon-Cloud Documentation](https://auto.gluon.ai/cloud/stable/index.html) | [AutoGluon Documentation](https://auto.gluon.ai) -AutoGluon-Cloud aims to provide user tools to train, fine-tune and deploy [AutoGluon](https://auto.gluon.ai/stable/index.html) backed models on the cloud. With just a few lines of codes, users could train a model and perform inference on the cloud without worrying about MLOps details such as resource management. +
+ +AutoGluon-Cloud makes it easy to run [AutoGluon](https://auto.gluon.ai/stable/index.html) in the cloud. With a few lines of code, you can train models and run inference on [Amazon SageMaker](https://aws.amazon.com/sagemaker/) — without managing infrastructure or installing AutoGluon's heavy dependencies on your local machine. + +It supports two workflows: -Currently, AutoGluon-Cloud supports [Amazon SageMaker](https://aws.amazon.com/sagemaker/) as the cloud backend. +- **Train AutoGluon predictors in the cloud** — the same `fit → deploy → predict` workflow as local AutoGluon, with all the heavy lifting offloaded to SageMaker. +- **Run pretrained foundation models** — deploy state-of-the-art pretrained models like Chronos-2 for zero-shot inference, with no training required. + +## 💾 Installation & setup -## Installation ```bash -pip install -U pip -pip install -U setuptools wheel pip install autogluon.cloud ``` -## Example +Then provision the IAM role and S3 bucket AutoGluon-Cloud needs on AWS: + ```python +from autogluon.cloud import bootstrap +bootstrap() +``` + +See the [Setup tutorial](https://auto.gluon.ai/cloud/stable/tutorials/setup.html) for the full walkthrough, including how to register an existing role and bucket instead. + +## ⚙️ Train your own model + +```python from autogluon.cloud import TabularCloudPredictor -import pandas as pd -train_data = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv") -test_data = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv") -test_data.drop(columns=['class'], inplace=True) -cloud_predictor = TabularCloudPredictor(cloud_output_path='YOUR_S3_BUCKET_PATH') + +# `train_data` and `test_data` can be a local path, S3 URL, or pandas DataFrame +train_data = "https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv" +test_data = "https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv" + +# Train +cloud_predictor = TabularCloudPredictor() cloud_predictor.fit( - train_data=train_data, # path or DataFrame + train_data=train_data, predictor_init_args={"label": "class"}, # passed to TabularPredictor() predictor_fit_args={"time_limit": 120}, # passed to TabularPredictor.fit() ) + +# Real-time inference endpoint cloud_predictor.deploy() result = cloud_predictor.predict_real_time(test_data) cloud_predictor.cleanup_deployment() -# Batch inference + +# Batch prediction result = cloud_predictor.predict(test_data) ``` + +## 🚀 Run a pretrained foundation model + +```python +from autogluon.cloud import TimeSeriesFoundationModel + +# `data` can be a local path, S3 URL, or pandas DataFrame +data = "https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_tiny/train.csv" + +model = TimeSeriesFoundationModel("chronos-2") + +# Batch prediction — no training required +predictions = model.predict( + data=data, + target="target", + prediction_length=24, +) + +# Real-time inference endpoint +endpoint = model.deploy() +predictions = endpoint.predict( + data=data, + target="target", + prediction_length=24, +) +endpoint.delete_endpoint() +``` diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst index e03319b8..dede8018 100644 --- a/docs/_templates/autosummary/base.rst +++ b/docs/_templates/autosummary/base.rst @@ -1,4 +1,4 @@ -{{ objname | escape | underline}} +{{ objname.split('.')[-1] | escape | underline}} .. currentmodule:: {{ module }} diff --git a/docs/_templates/custom_class.rst b/docs/_templates/custom_class.rst index e66afb2d..6a13de3c 100644 --- a/docs/_templates/custom_class.rst +++ b/docs/_templates/custom_class.rst @@ -1,12 +1,10 @@ -{{ fullname | escape | underline}} +{{ objname | escape | underline}} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} {% block methods %} - .. automethod:: __init__ - {% if methods %} .. rubric:: {{ _('Methods') }} diff --git a/docs/_templates/foundation_model_class.rst b/docs/_templates/foundation_model_class.rst deleted file mode 100644 index 1c11881e..00000000 --- a/docs/_templates/foundation_model_class.rst +++ /dev/null @@ -1,9 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. autoclass:: {{ objname }} - - .. automethod:: __init__ - .. automethod:: deploy - .. automethod:: predict diff --git a/docs/api.rst b/docs/api.rst index bb8eacd0..5a1c9f05 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -16,18 +16,25 @@ API :template: custom_class.rst :methods: - MultiModalCloudPredictor + TimeSeriesCloudPredictor .. autosummary:: :toctree: api :template: custom_class.rst :methods: - TimeSeriesCloudPredictor + TimeSeriesFoundationModel .. autosummary:: :toctree: api - :template: foundation_model_class.rst + :template: custom_class.rst + :methods: - TimeSeriesFoundationModel + TimeSeriesEndpoint +.. autosummary:: + :toctree: api + :template: custom_class.rst + :methods: + + MultiModalCloudPredictor diff --git a/docs/api/multimodal.rst b/docs/api/multimodal.rst new file mode 100644 index 00000000..4b760d16 --- /dev/null +++ b/docs/api/multimodal.rst @@ -0,0 +1,10 @@ +Multimodal +========== + +.. currentmodule:: autogluon.cloud + +.. autosummary:: + :toctree: . + :template: custom_class.rst + + MultiModalCloudPredictor diff --git a/docs/api/setup.rst b/docs/api/setup.rst new file mode 100644 index 00000000..d515ade9 --- /dev/null +++ b/docs/api/setup.rst @@ -0,0 +1,15 @@ +Setup +===== + +Functions for managing AutoGluon-Cloud's AWS configuration. See the :doc:`Setup tutorial ` for usage. + +.. currentmodule:: autogluon.cloud + +.. autosummary:: + :toctree: . + :nosignatures: + + bootstrap + register + status + teardown diff --git a/docs/api/tabular.rst b/docs/api/tabular.rst new file mode 100644 index 00000000..368b8f84 --- /dev/null +++ b/docs/api/tabular.rst @@ -0,0 +1,10 @@ +Tabular +======= + +.. currentmodule:: autogluon.cloud + +.. autosummary:: + :toctree: . + :template: custom_class.rst + + TabularCloudPredictor diff --git a/docs/api/timeseries.rst b/docs/api/timeseries.rst new file mode 100644 index 00000000..bfca0472 --- /dev/null +++ b/docs/api/timeseries.rst @@ -0,0 +1,12 @@ +Time Series +=========== + +.. currentmodule:: autogluon.cloud + +.. autosummary:: + :toctree: . + :template: custom_class.rst + + TimeSeriesCloudPredictor + TimeSeriesFoundationModel + TimeSeriesEndpoint diff --git a/docs/conf.py b/docs/conf.py index 27fe1162..87201b66 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,9 @@ autosummary_generate = True numpydoc_show_class_members = False +# Merge __init__ docstring (with Parameters) into the class docstring, +# and suppress the long signature lines on class/__init__ headers. +autoclass_content = "both" googleanalytics_id = "UA-96378503-20" @@ -43,7 +46,7 @@ nb_execution_excludepatterns = ["jupyter_execute"] -nb_dirs_to_exec = [os.path.join("tutorials", tag) for tag in tags if os.path.isdir(os.path.join("tutorials", tag))] +nb_dirs_to_exec = [os.path.join("tutorials", tag) for tag in tags if os.path.isdir(os.path.join("tutorials", tag))] # noqa: F821 if len(nb_dirs_to_exec) > 0: nb_dirs_to_exclude = [ @@ -90,3 +93,14 @@ html_static_path = ["_static"] html_css_files = ["custom.css"] html_js_files = ["custom.js"] + + +def _skip_meta_private(app, what, name, obj, skip, options): + doc = getattr(obj, "__doc__", None) or "" + if ":meta private:" in doc: + return True + return None + + +def setup(app): + app.connect("autodoc-skip-member", _skip_meta_private) diff --git a/docs/index.md b/docs/index.md index 43b6c970..4412c585 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,94 +27,121 @@ hide-toc: true :child-align: justify :class: sd-text-white sd-fs-3 -AutoGluon-Cloud: Train and Deploy AutoGluon on the Cloud +Train and Deploy AutoGluon in the Cloud ::: :::: :::::: -AutoGluon-Cloud aims to provide user tools to train, fine-tune and deploy [AutoGluon]() backed models on the cloud. With just a few lines of code, users can train a model and perform inference on the cloud without worrying about MLOps details such as resource management. +AutoGluon-Cloud makes it easy to run [AutoGluon]() in the cloud. With a few lines of code, you can train models and run inference on [Amazon SageMaker]() — without managing infrastructure or installing AutoGluon's heavy dependencies on your local machine. -Currently, AutoGluon-Cloud supports [Amazon SageMaker]() as the cloud backend. +It supports two workflows: -## {octicon}`rocket` Quick Examples +- **Train AutoGluon predictors in the cloud** — the same `fit → deploy → predict` workflow as local AutoGluon, with all the heavy lifting offloaded to SageMaker. +- **Run pretrained foundation models** — deploy state-of-the-art pretrained models like Chronos-2 for zero-shot inference, with no training required. + +## {octicon}`gear` Train AutoGluon predictors in the cloud + +*Full walkthrough: [Train Your Own Models](tutorials/autogluon-cloud.md)* :::{dropdown} Tabular :animate: fade-in-slide-down :open: :color: primary +Train a classification or regression model on tabular data. + ```python -import pandas as pd from autogluon.cloud import TabularCloudPredictor -train_data = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv") -test_data = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv") -test_data.drop(columns=["class"], inplace=True) -cloud_predictor = TabularCloudPredictor(cloud_output_path="YOUR_S3_BUCKET_PATH") +# `train_data` and `test_data` can be a local path, S3 URL, or pandas DataFrame +train_data = "https://autogluon.s3.amazonaws.com/datasets/Inc/train.csv" +test_data = "https://autogluon.s3.amazonaws.com/datasets/Inc/test.csv" + +# Train +cloud_predictor = TabularCloudPredictor() cloud_predictor.fit( - train_data=train_data, # path or DataFrame + train_data=train_data, predictor_init_args={"label": "class"}, # passed to TabularPredictor() predictor_fit_args={"time_limit": 120}, # passed to TabularPredictor.fit() ) + +# Real-time inference endpoint cloud_predictor.deploy() result = cloud_predictor.predict_real_time(test_data) cloud_predictor.cleanup_deployment() -# Batch inference + +# Batch prediction result = cloud_predictor.predict(test_data) ``` ::: -:::{dropdown} Multimodal +:::{dropdown} Time Series :animate: fade-in-slide-down :color: primary +Forecast future values of time series. + ```python -import pandas as pd -from autogluon.cloud import MultiModalCloudPredictor +from autogluon.cloud import TimeSeriesCloudPredictor -train_data = pd.read_parquet("https://autogluon-text.s3-accelerate.amazonaws.com/glue/sst/train.parquet") -test_data = pd.read_parquet("https://autogluon-text.s3-accelerate.amazonaws.com/glue/sst/dev.parquet") -test_data.drop(columns=["label"], inplace=True) -cloud_predictor = MultiModalCloudPredictor(cloud_output_path="YOUR_S3_BUCKET_PATH") +# `data` can be a local path, S3 URL, or pandas DataFrame +data = "https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_tiny/train.csv" + +# Train +cloud_predictor = TimeSeriesCloudPredictor() cloud_predictor.fit( - train_data=train_data, # path or DataFrame - predictor_init_args={"label": "label"}, # passed to MultiModalPredictor() + train_data=data, + predictor_init_args={"target": "target", "prediction_length": 24}, # passed to TimeSeriesPredictor() + predictor_fit_args={"time_limit": 120}, # passed to TimeSeriesPredictor.fit() ) + +# Real-time inference endpoint cloud_predictor.deploy() -result = cloud_predictor.predict_real_time(test_data) +result = cloud_predictor.predict_real_time(data) cloud_predictor.cleanup_deployment() -# Batch inference -result = cloud_predictor.predict(test_data) + +# Batch prediction +result = cloud_predictor.predict(data) ``` ::: -:::{dropdown} TimeSeries +## {octicon}`rocket` Run pretrained foundation models + +*Full walkthrough: [Use Foundation Models](tutorials/foundation_model.md)* + +:::{dropdown} Time Series (Chronos-2) :animate: fade-in-slide-down :color: primary +Zero-shot forecasts with a pretrained model — no training required. + ```python -import pandas as pd -from autogluon.cloud import TimeSeriesCloudPredictor +from autogluon.cloud import TimeSeriesFoundationModel -data = pd.read_csv("https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_tiny/train.csv") +# `data` can be a local path, S3 URL, or pandas DataFrame +data = "https://autogluon.s3.amazonaws.com/datasets/timeseries/m4_hourly_tiny/train.csv" -cloud_predictor = TimeSeriesCloudPredictor(cloud_output_path="YOUR_S3_BUCKET_PATH") -cloud_predictor.fit( - train_data=data, # path or DataFrame - predictor_init_args={"target": "target", "prediction_length": 24}, # passed to TimeSeriesPredictor() - predictor_fit_args={"time_limit": 120}, # passed to TimeSeriesPredictor.fit() - id_column="item_id", - timestamp_column="timestamp", +model = TimeSeriesFoundationModel("chronos-2") + +# Batch prediction +predictions = model.predict( + data=data, + target="target", + prediction_length=24, ) -cloud_predictor.deploy() -result = cloud_predictor.predict_real_time(data) -cloud_predictor.cleanup_deployment() -# Batch inference -result = cloud_predictor.predict(data) + +# Real-time inference endpoint +endpoint = model.deploy() +predictions = endpoint.predict( + data=data, + target="target", + prediction_length=24, +) +endpoint.delete_endpoint() ``` ::: @@ -126,41 +153,44 @@ result = cloud_predictor.predict(data) ![](https://img.shields.io/pypi/dm/autogluon.cloud) ```bash -pip install -U pip -pip install -U setuptools wheel -pip install --pre autogluon.cloud # You don't need to install autogluon itself locally -pip install -U sagemaker # This is required to ensure the information about newly released containers is available. +pip install autogluon.cloud ``` +Before running the examples above, set up your AWS resources (IAM role + S3 bucket) by following the [Setup](tutorials/setup.md) tutorial. + ```{toctree} --- caption: Tutorials -maxdepth: 3 +maxdepth: 1 hidden: --- -Cloud +Setup +Train Your Own Models +Use Foundation Models ``` ```{toctree} --- -caption: Resources +caption: API maxdepth: 1 hidden: --- -Versions +Setup +Tabular +Time Series +Multimodal ``` ```{toctree} --- -caption: API +caption: Resources maxdepth: 1 hidden: --- -TabularCloudPredictor -MultiModalCloudPredictor -TimeSeriesCloudPredictor -TimeSeriesFoundationModel +Versions +AutoGluon documentation +GitHub ``` diff --git a/docs/tutorials/distributed-training.md b/docs/tutorials/distributed-training.md deleted file mode 100644 index 8418429c..00000000 --- a/docs/tutorials/distributed-training.md +++ /dev/null @@ -1,43 +0,0 @@ -# AutoGluon-Cloud Distributed Training -AutoGluon-Cloud currently supports distributed training for Tabular. - -Tabular predictor trains multiple folds of models underneath and parallelize model training on a single machine. It is natural to expand this strategy to a cluster of machines. - -With AutoGluon-Cloud, we help you to spin up the cluster, dispatch the jobs, and tear down the cluster. And it is not much different from how you would normally train a `TabularCloudPredictor`. All you need to do is specify `backend="ray_aws"` when you init the predictor - -```python -cloud_predictor = TabularCloudPredictor( - ..., - backend="ray_aws" -) -``` - -And you would call fit as normal - -```python -cloud_predictor.fit( - train_data=train_data, - predictor_init_args=predictor_init_args, - predictor_fit_args=predictor_fit_args, -) -``` - -## How to Control Number of Instances in the Cluster -The default number of instances being launched will be introduced in the following section. You can control how many instances are created in the cluster by passing `instance_count` to `fit()`. -```python -cloud_predictor.fit(..., instance_count=4) -``` - -### General Strategy on How to Decide `instance_count` - -#### Non-HPO -By default, this value will be determined by number of folds (`num_bag_folds` in `TabularPredictor`). We will launch as many instances as the number of folds, so each fold will be trained on a dedicated machine. The default value should work most of the time - -You can of course lower this value to save budgets, but this will slow the training process as a single instance will need to train multiple folds in parallel and split its resources. Setting value larger than number of folds is meaningless, as we do not support distributed training of a single model. - -#### HPO -When doing HPO, it's very hard to pre-determine how many instances to use. Therefore, we default to 1 instance, and you would need to specify the number of instances you want to use. The fastest option of course will be matching the number of instances and number of trials. However, this is likely impossible as HPO typically involves big number of trials. - -In general, the recommendation would be try to make it so that (#vcpus_per_instance * #instances) is divisible by number of trials. We evenly distribute resources to tasks; therefore, a non-divisible value would results in some resources not being utilized. - -To give a recommended example, suppose you want to do HPO with 128 trials. Choosing 8 `m5.2xlarge` (8 vcpus), would make the computing resources divisible by the number of trials: 128 / (8 * 8) = 2. This would results in two batches each containing 64 jobs being distributed on 64 vcpus. diff --git a/docs/tutorials/faq.md b/docs/tutorials/faq.md deleted file mode 100644 index 70ab3648..00000000 --- a/docs/tutorials/faq.md +++ /dev/null @@ -1,51 +0,0 @@ -# AutoGluon-Cloud FAQ - -## Supported Docker Containers -`autogluon.cloud` supports AutoGluon Deep Learning Containers version 0.6.0 and newer. - -## How to use Previous Versions of AutoGluon containers -By default, `autogluon.cloud` will fetch the latest version of AutoGluon DLC. However, you can supply `framework_version` to fit/inference APIs to access previous versions, i.e. -```python -cloud_predictor.fit(..., framework_version="0.6") -``` -It is always recommended to use the latest version as it has more features and up-to-date security patches. - - -## How to Build a Cloud Compatible Custom Container -If the official DLC doesn't meet your requirement, and you would like to build your own container. - -You can either build on top of our [DLC](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#autogluon-training-containers) -or refer to our [Dockerfiles](https://github.com/aws/deep-learning-containers/tree/master/autogluon) - -## How to Use Custom Containers -Though not recommended, `autogluon.cloud` supports using your custom containers by specifying `custom_image_uri`. - -```python -cloud_predictor.fit(..., custom_image_uri="CUSTOM_IMAGE_URI") -cloud_predictor.predict_real_time(..., custom_image_uri="CUSTOM_IMAGE_URI") -cloud_predictor.predict(..., custom_image_uri="CUSTOM_IMAGE_URI") -``` - -If this custom image lives under a certain ECR, you would need to grant access permission to the IAM role used by the Cloud module. - -## Run into Permission Issues -You can try to get the necessary IAM permission and trust relationship through -```python -from autogluon.cloud import TabularCloudPredictor # Can be other CloudPredictor as well - -TabularCloudPredictor.generate_default_permission( - backend="BACKNED_YOU_WANT" # We currently support sagemaker and ray_aws - account_id="YOUR_ACCOUNT_ID", # The AWS account ID you plan to use for CloudPredictor. - cloud_output_bucket="S3_BUCKET" # S3 bucket name where intermediate artifacts will be uploaded and trained models should be saved. You need to create this bucket beforehand. -) -``` - -The util function above would give you two json files describing the trust replationship and the iam policy. -**Make sure you review those files and make necessary changes according to your use case before applying them.** - -We recommend you to create an IAM Role for your IAM User to delegate as IAM Role doesn't have permanent long-term credentials and is used to directly interact with AWS services. -Refer to this [tutorial](https://aws.amazon.com/premiumsupport/knowledge-center/iam-assume-role-cli/) to - -1. create the IAM Role with the trust relationship and iam policy you generated above -2. setup the credential -3. assume the role diff --git a/docs/tutorials/image-modality.md b/docs/tutorials/image-modality.md deleted file mode 100644 index 214ec2d4..00000000 --- a/docs/tutorials/image-modality.md +++ /dev/null @@ -1,54 +0,0 @@ -# Training/Inference with Image Modality -If your training and inference tasks involve image modality, your data would contain a column representing the path to the image file, i.e. - -```python - feature_1 image label -0 1 image/train/train_1.png 0 -1 2 image/train/train_1.png 1 -``` - -### Preparing the Image Column -Currently, AutoGluon-Cloud only supports one image per row. -If your dataset contains one or more images per row, we first need to preprocess the image column to only contain the first image of each row. - -For example, if your images are seperated with `;`, you can preprocess it via: - -```python -# image_col is the column name containing the image path. In the example above, it would be `image` -train_data[image_col] = train_data[image_col].apply(lambda ele: ele.split(';')[0]) -test_data[image_col] = test_data[image_col].apply(lambda ele: ele.split(';')[0]) -``` - -Now we update the path to an absolute path. - -For example, if your directory is similar to this: - -```bash -. -└── current_working_directory/ - ├── train.csv - ├── test.csv - └── images/ - ├── train/ - │ └── train_1.png - └── test/ - └── test_1.png -``` - -You can replace your image column to absolute paths via: - -```python -train_data[image_col] = train_data[image_col].apply(lambda path: os.path.abspath(path)) -test_data[image_col] = test_data[image_col].apply(lambda path: os.path.abspath(path)) -``` - -### Perform Training/Inference with Image Modality -Provide argument `image_column` as the column name containing image paths to `CloudPredictor` fit/inference APIs along with other arguments that you would normally pass to a CloudPredictor -In the example above, `image_column` would be `image` - -```python -cloud_predictor = TabularCloudPredictor(cloud_output_path="YOUR_S3_BUCKET_PATH") -cloud_predictor.fit(..., image_column="IMAGE_COLUMN_NAME") -cloud_predictor.predict_real_time(..., image_column="IMAGE_COLUMN_NAME") -cloud_predictor.predict(..., image_column="IMAGE_COLUMN_NAME") -``` diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md deleted file mode 100644 index 01ed1845..00000000 --- a/docs/tutorials/index.md +++ /dev/null @@ -1,36 +0,0 @@ -# Tutorials - -::::{grid} 2 - :gutter: 3 - -:::{grid-item-card} Setup - :link: setup.html - - Set up AutoGluon-Cloud on AWS in one command with `bootstrap`, or register existing AWS resources you already have. -::: - -:::{grid-item-card} AutoGluon-Cloud - :link: autogluon-cloud.html - - A tutorial on using AutoGluon-Cloud module to train/deploy AutoGluon backed models on SageMaker. -::: - -:::{grid-item-card} Foundation Models - :link: foundation_model.html - - Use pretrained time series foundation models for zero-shot forecasting on SageMaker. -::: - -```{toctree} ---- -maxdepth: 2 -hidden: true ---- - -Setup -Essentials -Foundation Models -Image Modality -Distributed Training -FAQ -``` diff --git a/src/autogluon/cloud/__init__.py b/src/autogluon/cloud/__init__.py index 1f40ee5f..3cae57aa 100644 --- a/src/autogluon/cloud/__init__.py +++ b/src/autogluon/cloud/__init__.py @@ -3,6 +3,7 @@ from autogluon.common.utils.log_utils import _add_stream_handler from .cloud_setup import bootstrap, register, status, teardown +from .endpoint.timeseries_endpoint import TimeSeriesEndpoint from .model.foundation_model import TimeSeriesFoundationModel from .predictor import MultiModalCloudPredictor, TabularCloudPredictor, TimeSeriesCloudPredictor @@ -13,6 +14,7 @@ "MultiModalCloudPredictor", "TabularCloudPredictor", "TimeSeriesCloudPredictor", + "TimeSeriesEndpoint", "TimeSeriesFoundationModel", "bootstrap", "register", diff --git a/src/autogluon/cloud/endpoint/timeseries_endpoint.py b/src/autogluon/cloud/endpoint/timeseries_endpoint.py index 26d7d891..a88039e1 100644 --- a/src/autogluon/cloud/endpoint/timeseries_endpoint.py +++ b/src/autogluon/cloud/endpoint/timeseries_endpoint.py @@ -41,21 +41,24 @@ def predict( Parameters ---------- data - Historical time series in long format. + Historical time series to forecast from, in long format, as a DataFrame or local/S3 path to + a data file. See the `TimeSeriesPredictor docs `_ + for the expected format. known_covariates - Future values of known covariates. + Future values of the known covariates over the forecast horizon. static_features - Static metadata for individual items. + Static (time-independent) features describing each individual time series. prediction_length - Number of time steps to forecast. + Forecast horizon: how many time steps into the future the model should predict. target - Name of the target column. + Name of the column that contains the target values to forecast. id_column - Name of the item ID column. + Name of the column with the unique identifier of each time series (item). timestamp_column - Name of the timestamp column. + Name of the column with the observation timestamps. quantile_levels - Quantiles to predict. + List of increasing decimals between 0 and 1 specifying which quantiles to estimate. Defaults + to ``[0.1, 0.2, ..., 0.9]``. accept Response format. Options: 'application/x-parquet', 'text/csv', 'application/json'. diff --git a/src/autogluon/cloud/model/foundation_model.py b/src/autogluon/cloud/model/foundation_model.py index 5ee8c7c1..6298dfab 100644 --- a/src/autogluon/cloud/model/foundation_model.py +++ b/src/autogluon/cloud/model/foundation_model.py @@ -195,6 +195,8 @@ def fit( ------- FoundationModel New instance with hyperparameters pointing to the fine-tuned artifact. + + :meta private: """ if not self._config.get("fine_tunable", False): raise ValueError(f"Model '{self.model_id}' does not support fine-tuning.") @@ -216,6 +218,8 @@ def cache_model_artifact(self, s3_path: str) -> str: ------- str S3 path to the cached artifact. + + :meta private: """ raise NotImplementedError @@ -325,22 +329,25 @@ def predict( Parameters ---------- data - Historical time series in long format, as a DataFrame or local/S3 path to a data file. + Historical time series to forecast from, in long format, as a DataFrame or local/S3 path to + a data file. See the `TimeSeriesPredictor docs `_ + for the expected format. target - Name of the target column to forecast. + Name of the column that contains the target values to forecast. id_column - Name of the item ID column. + Name of the column with the unique identifier of each time series (item). timestamp_column - Name of the timestamp column. + Name of the column with the observation timestamps. known_covariates - Future values of known covariates over the forecast horizon. Covariate column names are + Future values of the known covariates over the forecast horizon. Covariate column names are inferred from the columns (excluding ``id_column`` and ``timestamp_column``). static_features - Metadata attributes of individual items. + Static (time-independent) features describing each individual time series. prediction_length - Number of time steps to forecast. + Forecast horizon: how many time steps into the future the model should predict. quantile_levels - Quantiles to predict. + List of increasing decimals between 0 and 1 specifying which quantiles to estimate. Defaults + to ``[0.1, 0.2, ..., 0.9]``. hyperparameters Model hyperparameters for inference. Overrides values passed to the constructor. instance_type diff --git a/src/autogluon/cloud/predictor/multimodal_cloud_predictor.py b/src/autogluon/cloud/predictor/multimodal_cloud_predictor.py index 95fc1c1c..194954ce 100644 --- a/src/autogluon/cloud/predictor/multimodal_cloud_predictor.py +++ b/src/autogluon/cloud/predictor/multimodal_cloud_predictor.py @@ -7,6 +7,12 @@ class MultiModalCloudPredictor(CloudPredictor): + """Train and deploy AutoGluon multimodal models (image, text, tabular) on AWS SageMaker. + + Wraps :class:`autogluon.multimodal.MultiModalPredictor` (`docs `_) + and runs ``fit``, ``predict``, and endpoint deployment as managed SageMaker jobs. + """ + predictor_file_name = "MultiModalCloudPredictor.pkl" backend_map = {SAGEMAKER: MULTIMODL_SAGEMAKER} diff --git a/src/autogluon/cloud/predictor/tabular_cloud_predictor.py b/src/autogluon/cloud/predictor/tabular_cloud_predictor.py index 904ede07..456547ae 100644 --- a/src/autogluon/cloud/predictor/tabular_cloud_predictor.py +++ b/src/autogluon/cloud/predictor/tabular_cloud_predictor.py @@ -7,6 +7,12 @@ class TabularCloudPredictor(CloudPredictor): + """Train and deploy AutoGluon tabular models (classification and regression) on AWS SageMaker. + + Wraps :class:`autogluon.tabular.TabularPredictor` (`docs `_) + and runs ``fit``, ``predict``, and endpoint deployment as managed SageMaker jobs. + """ + predictor_file_name = "TabularCloudPredictor.pkl" backend_map = {SAGEMAKER: TABULAR_SAGEMAKER, RAY_AWS: TABULAR_RAY_AWS} diff --git a/src/autogluon/cloud/predictor/timeseries_cloud_predictor.py b/src/autogluon/cloud/predictor/timeseries_cloud_predictor.py index 24e96546..4a8591c1 100644 --- a/src/autogluon/cloud/predictor/timeseries_cloud_predictor.py +++ b/src/autogluon/cloud/predictor/timeseries_cloud_predictor.py @@ -16,6 +16,12 @@ class TimeSeriesCloudPredictor(CloudPredictor): + """Train and deploy AutoGluon time series forecasting models on AWS SageMaker. + + Wraps :class:`autogluon.timeseries.TimeSeriesPredictor` (`docs `_) + and runs ``fit``, ``predict``, and endpoint deployment as managed SageMaker jobs. + """ + predictor_file_name = "TimeSeriesCloudPredictor.pkl" backend_map = {SAGEMAKER: TIMESERIES_SAGEMAKER} @@ -35,11 +41,10 @@ def fit( self, train_data: Optional[Union[str, Path, pd.DataFrame]] = None, *, - tuning_data: Optional[Union[str, Path, pd.DataFrame]] = None, - known_covariates: Optional[Union[str, Path, pd.DataFrame]] = None, - static_features: Optional[Union[str, Path, pd.DataFrame]] = None, predictor_init_args: Dict[str, Any], predictor_fit_args: Optional[Dict[str, Any]] = None, + tuning_data: Optional[Union[str, Path, pd.DataFrame]] = None, + static_features: Optional[Union[str, Path, pd.DataFrame]] = None, id_column: str = "item_id", timestamp_column: str = "timestamp", framework_version: str = "latest", @@ -50,6 +55,7 @@ def fit( custom_image_uri: Optional[str] = None, wait: bool = True, backend_kwargs: Optional[Dict] = None, + known_covariates: Optional[Union[str, Path, pd.DataFrame]] = None, ) -> TimeSeriesCloudPredictor: """ Fit the predictor with SageMaker. @@ -59,23 +65,27 @@ def fit( Parameters ---------- train_data: Union[str, pathlib.Path, pd.DataFrame] - Training time-series data, as a DataFrame or local/S3 path to a data file. - tuning_data: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None - Optional tuning data. - known_covariates: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None - Future values of the known covariates over the forecast horizon. - static_features: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None - Optional metadata attributes for each item. For details, see the ``TimeSeriesDataFrame`` - documentation: https://auto.gluon.ai/stable/api/autogluon.timeseries.TimeSeriesDataFrame.html + Training time series in long format, as a DataFrame or local/S3 path to a data file. + See the `TimeSeriesPredictor.fit docs `_ + for the expected format. predictor_init_args: dict - Init args for the predictor. + Arguments forwarded to ``TimeSeriesPredictor()``. See the + `TimeSeriesPredictor docs `_ + for available options (e.g. ``target``, ``prediction_length``, ``freq``, ``eval_metric``, + ``quantile_levels``, ``known_covariates_names``). predictor_fit_args: Optional[dict], default = None - Additional fit args forwarded to ``TimeSeriesPredictor.fit()``. Must NOT contain ``train_data``, - ``tuning_data``, or ``known_covariates`` — pass those as explicit arguments above. + Additional fit args forwarded to ``TimeSeriesPredictor.fit()``. See the + `TimeSeriesPredictor.fit docs `_ + for available options. Must NOT contain ``train_data`` or ``tuning_data`` — pass those as + explicit arguments above. + tuning_data: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None + Optional tuning data in long format, as a DataFrame or local/S3 path to a data file. + static_features: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None + Static (time-independent) features describing each individual time series. id_column: str, default = "item_id" - Name of the item ID column. + Name of the column with the unique identifier of each time series (item). timestamp_column: str, default = "timestamp" - Name of the timestamp column. + Name of the column with the observation timestamps. framework_version: str, default = `latest` Training container version of autogluon. If `latest`, will use the latest available container version. @@ -177,17 +187,13 @@ def predict_real_time( Parameters ---------- data: Union(str, pandas.DataFrame) - The data to forecast from. - Can be a pandas.DataFrame or a local path to a csv file. + Historical time series to forecast from, in long format, as a DataFrame or local/S3 path to + a data file. static_features: Optional[pd.DataFrame] - An optional data frame describing the metadata attributes of individual items in the item index. - For more detail, please refer to `TimeSeriesDataFrame` documentation: - https://auto.gluon.ai/stable/api/autogluon.timeseries.TimeSeriesDataFrame.html + Static (time-independent) features describing each individual time series. known_covariates : Optional[pd.DataFrame] - If ``known_covariates_names`` were specified when creating the predictor, it is necessary to provide the - values of the known covariates for each time series during the forecast horizon. - For more details, please refer to the `TimeSeriesPredictor.predictor` documentation: - https://auto.gluon.ai/stable/api/autogluon.timeseries.TimeSeriesPredictor.predict.html + Future values of the known covariates over the forecast horizon. Must be provided if + ``known_covariates_names`` was specified at fit time. accept: str, default = application/x-parquet Type of accept output content. Valid options are application/x-parquet, text/csv, application/json @@ -208,6 +214,9 @@ def predict_real_time( ) def predict_proba_real_time(self, **kwargs) -> pd.DataFrame: + """ + :meta private: + """ raise ValueError(f"{self.__class__.__name__} does not support predict_proba operation.") def predict( @@ -237,14 +246,13 @@ def predict( Parameters ---------- data: Union(str, pandas.DataFrame) - The data to forecast from. - Can be a pandas.DataFrame or a local path to a csv file. + Historical time series to forecast from, in long format, as a DataFrame or local/S3 path to + a data file. static_features: Optional[Union[str, pd.DataFrame]] - An optional data frame describing the metadata attributes of individual items in the item index. - For more detail, please refer to `TimeSeriesDataFrame` documentation: - https://auto.gluon.ai/stable/api/autogluon.timeseries.TimeSeriesDataFrame.html + Static (time-independent) features describing each individual time series. known_covariates: Optional[Union[str, pd.DataFrame]] - Future values of the known covariates over the forecast horizon. + Future values of the known covariates over the forecast horizon. Must be provided if + ``known_covariates_names`` was specified at fit time. predictor_path: str Path to the predictor tarball you want to use to predict. Path can be both a local path or a S3 location. @@ -310,16 +318,19 @@ def predict_proba( self, **kwargs, ) -> Optional[pd.DataFrame]: + """ + :meta private: + """ raise ValueError(f"{self.__class__.__name__} does not support predict_proba operation.") def fit_predict( self, train_data: Union[str, Path, pd.DataFrame], *, - known_covariates: Optional[Union[str, Path, pd.DataFrame]] = None, - static_features: Optional[Union[str, Path, pd.DataFrame]] = None, predictor_init_args: Dict[str, Any], predictor_fit_args: Optional[Dict[str, Any]] = None, + known_covariates: Optional[Union[str, Path, pd.DataFrame]] = None, + static_features: Optional[Union[str, Path, pd.DataFrame]] = None, id_column: str = "item_id", timestamp_column: str = "timestamp", framework_version: str = "latest", @@ -345,23 +356,26 @@ def fit_predict( Parameters ---------- train_data: Union[str, pathlib.Path, pd.DataFrame] - Historical time-series data to train on and forecast from, as a DataFrame or local/S3 path to - a data file. - known_covariates: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None - Values of the known covariates for each time series during the forecast horizon. Forwarded to - ``TimeSeriesPredictor.predict`` in the container. For details, see: - https://auto.gluon.ai/stable/api/autogluon.timeseries.TimeSeriesPredictor.predict.html - static_features: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None - Optional metadata attributes per item. + Historical time series to train on and forecast from, in long format, as a DataFrame or + local/S3 path to a data file. predictor_init_args: dict - Init args for the predictor (must include ``prediction_length``). + Arguments forwarded to ``TimeSeriesPredictor()``. Must include ``prediction_length``. See the + `TimeSeriesPredictor docs `_ + for available options. predictor_fit_args: Optional[dict], default = None - Additional fit args for the predictor. Must NOT contain ``train_data``, ``tuning_data``, or + Additional fit args forwarded to ``TimeSeriesPredictor.fit()``. See the + `TimeSeriesPredictor.fit docs `_ + for available options. Must NOT contain ``train_data``, ``tuning_data``, or ``known_covariates`` — pass those as explicit arguments above. + known_covariates: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None + Future values of the known covariates over the forecast horizon. Must be provided if + ``known_covariates_names`` was specified in ``predictor_init_args``. + static_features: Optional[Union[str, pathlib.Path, pd.DataFrame]], default = None + Static (time-independent) features describing each individual time series. id_column: str, default = "item_id" - Name of the item ID column. + Name of the column with the unique identifier of each time series (item). timestamp_column: str, default = "timestamp" - Name of the timestamp column. + Name of the column with the observation timestamps. framework_version, job_name, instance_type, instance_count, volume_size, custom_image_uri, wait, backend_kwargs: Same semantics as ``fit()``.