kubeflow
/
pipelines
mirror of https://github.com/kubeflow/pipelines.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation for AWS components (#3410) 

* deploy_createModel_readme

* readme for batch and minor updates to deploy and create_model

* updates based on review comments 1

* correct SageMaker typo
This commit is contained in:
Suraj Kota 2020-04-08 22:13:46 +05:30 committed by GitHub
parent 100369a75b
commit fc5f977b19
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 235 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
components/aws/sagemaker/batch_transform/README.md Normal file
View File

@ -0,0 +1,96 @@
# SageMaker Batch Transform Kubeflow Pipeline component
## Summary
Component to get inferences for an entire dataset in SageMaker from a Kubeflow Pipelines workflow.
## Details
With [batch transform](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-batch.html), you create a batch transform job using a trained model and the dataset, which must be stored in Amazon S3. Use batch transform when you:
* Want to get inferences for an entire dataset and index them to serve inferences in real time
* Don't need a persistent endpoint that applications (for example, web or mobile apps) can call to get inferences
* Don't need the subsecond latency that Amazon SageMaker hosted endpoints provide
## Intended Use
Create a transform job in AWS SageMaker.
## Runtime Arguments
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
region | The region where the endpoint is created | No | No | String | | |
endpoint_url | The endpoint URL for the private link VPC endpoint | Yes | Yes | String | | |
job_name | The name of the transform job. The name must be unique within an AWS Region in an AWS account | Yes | Yes | String | | is a generated name (combination of model_name and 'BatchTransform' string)|
model_name | The name of the model that you want to use for the transform job. Model name must be the name of an existing Amazon SageMaker model within an AWS Region in an AWS account | No | No | String | | |
max_concurrent | The maximum number of parallel requests that can be sent to each instance in a transform job | Yes | Yes | Integer | | 0 |
max_payload | The maximum allowed size of the payload, in MB | Yes | Yes | Integer | The value in max_payload must be greater than, or equal to, the size of a single record | 6 |
batch_strategy | The number of records to include in a mini-batch for an HTTP inference request | Yes | Yes | String | | |
environment | The environment variables to set in the Docker container | Yes | Yes | Dict | Maximum length of 1024. Key Pattern: `[a-zA-Z_][a-zA-Z0-9_]*`. Value Pattern: `[\S\s]*`. Upto 16 key and values entries in the map | |
The following parameters construct [`TransformInput`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html) object of the CreateTransformJob API. These describe the input source and the way the transform job consumes it.
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
input_location | The S3 location of the data source that is associated with a channel. [Read more on S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformS3DataSource.html) | No | No | String | | |
data_type | Used by SageMaker to identify the objects from the S3 bucket to be used for batch transform. [Read more on S3DataType](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformS3DataSource.html) | Yes | Yes | String | `ManifestFile`, `S3Prefix`, `AugmentedManifestFile`| `S3Prefix` |
content_type | The multipurpose internet mail extension (MIME) type of the data. Amazon SageMaker uses the MIME type with each http call to transfer data to the transform job | Yes | Yes | String | | |
split_type | The method to use to split the transform job data files into smaller batches | Yes | Yes | String | `Line`, `RecordIO`, `TFRecord`, `None` | `None` |
compression_type | If the transform data is compressed, specify the compression type | Yes | Yes | String | `GZip`, `None` | `None` |
* `input_location` and `data_type` parameters above are used to construct [`S3DataSource`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformS3DataSource.html) object which is part of [`TransformDataSource`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformDataSource.html) object in [`TransformInput`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html) part of the CreateTransformJob API.
```
TransformInput={
'DataSource': {
'S3DataSource': {
'S3DataType': 'ManifestFile'|'S3Prefix'|'AugmentedManifestFile',
'S3Uri': 'string'
}
},
... other input parameters ...
}
```
[Ref](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_transform_job)
The following parameters are used to construct [`TransformOutput`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformOutput.html) object of the CreateTransformJob API. These describe the results of a transform job.
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
output_location | The Amazon S3 path where you want Amazon SageMaker to store the results of the transform job | No | No | String | | |
accept | The MIME type used to specify the output data. Amazon SageMaker uses the MIME type with each http call to transfer data from the transform job | Yes | Yes | String | | |
assemble_with | Defines how to assemble the results of the transform job as a single S3 object. To concatenate the results in binary format, specify None. To add a newline character at the end of every transformed record, specify Line | Yes | Yes | String | `Line`, `None` | `None`|
output_encryption_key | The AWS Key Management Service key to encrypt the model artifacts at rest using Amazon S3 server-side encryption | Yes | Yes | String | [KmsKeyId formats](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformOutput.html) | |
The following parameters are used to construct [`TransformResources`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformResources.html) object of the CreateTransformJob API. These describe the resources, including ML instance types and ML instance count, to use for the transform job.
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
instance_type | The ML compute instance type for the transform job | Yes | Yes | String | ml.m4.xlarge, ml.m4.2xlarge, ml.m4.4xlarge, ml.m4.10xlarge, ml.m4.16xlarge, ml.m5.large, ml.m5.xlarge, ml.m5.2xlarge, ml.m5.4xlarge, ml.m5.12xlarge, ml.m5.24xlarge, ml.c4.xlarge, ml.c4.2xlarge, ml.c4.4xlarge, ml.c4.8xlarge, ml.p2.xlarge, ml.p2.8xlarge, ml.p2.16xlarge, ml.p3.2xlarge, ml.p3.8xlarge, ml.p3.16xlarge, ml.c5.xlarge, ml.c5.2xlarge, ml.c5.4xlarge, ml.c5.9xlarge, ml.c5.18xlarge | ml.m4.xlarge |
instance_count | The number of ML compute instances to use in the transform job | Yes | Yes | Integer | | 1 |
resource_encryption_key | The AWS Key Management Service (AWS KMS) key used to encrypt model data on the storage volume attached to the ML compute instance(s) that run the batch transform job. | Yes | Yes | String | [VolumeKmsKeyId formats](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformResources.html) | |
The following parameters are used to construct [`DataProcessing`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataProcessing.html) object of the CreateTransformJob API. The data structure used to specify the data to be used for inference in a batch transform job and to associate the data that is relevant to the prediction results in the output.
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
input_filter | A JSONPath expression used to select a portion of the input data to pass to the algorithm. [ReadMore on InputFilter](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataProcessing.html) | Yes | Yes | String | | |
output_filter | A JSONPath expression used to select a portion of the joined dataset to save in the output file for a batch transform job. [ReadMore on OutputFilter](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataProcessing.html) | Yes | Yes | String | | |
join_source | Specifies the source of the data to join with the transformed data. [ReadMore on JoinSource](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DataProcessing.html) | Yes | Yes | String | `Input`, `None` | None |
Notes:
* Please use the links in the [Resources section](#Resources) for detailed information on each input parameter and SageMaker APIs used in this component
## Outputs
Name | Description
:--- | :----------
output_location | The Amazon S3 path where you want Amazon SageMaker to store the results of the transform job
## Requirements
* [Kubeflow pipelines SDK](https://www.kubeflow.org/docs/pipelines/sdk/install-sdk/)
* [Kubeflow set-up](https://www.kubeflow.org/docs/aws/deploy/install-kubeflow/)
## Samples
### Integrated into a pipeline
MNIST Classification pipeline: [Pipeline](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/mnist-classification-pipeline.py) | [Steps](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/README.md)
## Resources
* [Batch Transform on SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-batch.html)
* [Create Transform Job API documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html)
* [Boto3 API reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_transform_job)

62
components/aws/sagemaker/deploy/README.md Normal file
View File

@ -0,0 +1,62 @@
# SageMaker Hosting Services - Create Endpoint Kubeflow Pipeline component
## Summary
Component to deploy a model in SageMaker Hosting Service from a Kubeflow Pipelines workflow.
## Details
Deploying a model using Amazon SageMaker hosting services is a three-step process:
1. **Create a model in Amazon SageMaker** - Specify the S3 path where model artifacts are stored and Docker registry path for the image that contains the inference code
2. **Create an endpoint configuration for an HTTPS endpoint** - Specify the name of model in production variants and the type of instance that you want Amazon SageMaker to launch to host the model.
3. **Create an HTTPS endpoint** - Launch the ML compute instances and deploy the model as specified in the endpoint configuration
This component handles Step 2 and 3. Step 1 can be done using the [create model component](https://github.com/kubeflow/pipelines/tree/master/components/aws/sagemaker/model) for AWS SageMaker.
## Intended Use
Create an endpoint in AWS SageMaker Hosting Service for model deployment.
## Runtime Arguments
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
region | The region where the endpoint is created | No | No | String | | |
endpoint_url | The endpoint URL for the private link VPC endpoint | Yes | Yes | String | | |
endpoint_config_name | The name of the endpoint configuration | Yes | Yes | String | | |
endpoint_config_tags | Key-value pairs to tag endpoint configurations in AWS | Yes | Yes | Dict | | {} |
endpoint_tags | Key-value pairs to tag the Hosting endpoint in AWS | Yes | Yes | Dict | | {} |
endpoint_name | The name of the endpoint. The name must be unique within an AWS Region in your AWS account | Yes | Yes | String | | |
In SageMaker, you can create an endpoint that can host multiple models. The set of parameters below represent a production variant. A production variant identifies a model that you want to host and the resources (e.g. instance type, initial traffic distribution etc.) to deploy for hosting it. You must specify at least one production variant to create an endpoint.
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
model_name_[1, 3] | The name of the model that you want to host. This is the name that you specified when creating the model | No | No | String | | |
variant_name_[1, 3] | The name of the production variant | Yes | Yes | String | | variant_name_[1, 3] |
instance_type_[1, 3] | The ML compute instance type | Yes | Yes | String | ml.m4.xlarge, ml.m4.2xlarge, ml.m4.4xlarge, ml.m4.10xlarge, ml.m4.16xlarge, ml.m5.large, ml.m5.xlarge, ml.m5.2xlarge, ml.m5.4xlarge, ml.m5.12xlarge, ml.m5.24xlarge, ml.c4.xlarge, ml.c4.2xlarge, ml.c4.4xlarge, ml.c4.8xlarge, ml.p2.xlarge, ml.p2.8xlarge, ml.p2.16xlarge, ml.p3.2xlarge, ml.p3.8xlarge, ml.p3.16xlarge, ml.c5.xlarge, ml.c5.2xlarge, ml.c5.4xlarge, ml.c5.9xlarge, ml.c5.18xlarge | ml.m4.xlarge |
initial_instance_count_[1, 3] | Number of instances to launch initially | Yes | Yes | Integer | ≥ 1 | 1 |
initial_variant_weight_[1, 3] | Determines initial traffic distribution among all of the models that you specify in the endpoint configuration. The traffic to a production variant is determined by the ratio of the VariantWeight to the sum of all VariantWeight values across all ProductionVariants. | Yes | Yes | Float | Minimum value of 0 | |
accelerator_type_[1, 3] | The size of the Elastic Inference (EI) instance to use for the production variant | Yes | Yes | String| ml.eia1.medium, ml.eia1.large, ml.eia1.xlarge | |
Notes:
* Please use the links in the [Resources section](#Resources) for detailed information on each input parameter and SageMaker APIs used in this component
* The parameters, `model_name_1` through `3`, is intended to be output of [create model component](https://github.com/kubeflow/pipelines/tree/master/components/aws/sagemaker/model) from previous steps in the pipeline. `model_name_[1, 3]` and other parameters for a production variant can be specified directly as well if the component is being used on its own.
## Outputs
Name | Description
:--- | :----------
endpoint_name | HTTPS Endpoint URL where client applications can send requests using [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InvokeEndpoint.html) API
## Requirements
* [Kubeflow pipelines SDK](https://www.kubeflow.org/docs/pipelines/sdk/install-sdk/)
* [Kubeflow set-up](https://www.kubeflow.org/docs/aws/deploy/install-kubeflow/)
## Samples
### Integrated into a pipeline
MNIST Classification pipeline: [Pipeline](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/mnist-classification-pipeline.py) | [Steps](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/README.md)
## Resources
* Create Endpoint Configuration
* [Create Endpoint Configuration API documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html)
* [Boto3 API reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config)
* Create Endpoint
* [Create Endpoint API documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)
* [Boto3 API reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint)

77
components/aws/sagemaker/model/README.md Normal file
View File

@ -0,0 +1,77 @@
# SageMaker Hosting Services - Create Model Kubeflow Pipeline component
## Summary
Component to create a model in SageMaker from a Kubeflow Pipelines workflow.
## Details
Deploying a model using Amazon SageMaker hosting services is a three-step process:
1. **Create a model in Amazon SageMaker** - Specify the S3 path where model artifacts are stored and Docker registry path for the image that contains the inference code
2. **Create an endpoint configuration for an HTTPS endpoint** - Specify the name of model in production variants and the type of instance that you want Amazon SageMaker to launch to host the model.
3. **Create an HTTPS endpoint** - Launch the ML compute instances and deploy the model as specified in the endpoint configuration
This component handles Step 1. Step 2 and 3 can be done using the [deploy component](https://github.com/kubeflow/pipelines/tree/master/components/aws/sagemaker/deploy) for AWS SageMaker.
## Intended Use
Create a model in Amazon SageMaker to be used for [creating an endpoint](https://github.com/kubeflow/pipelines/tree/master/components/aws/sagemaker/deploy) in hosting services or [run a batch transform job](https://github.com/kubeflow/pipelines/tree/master/components/aws/sagemaker/batch_transform).
## Runtime Arguments
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
region | The region where the model is created | No | No | String | | |
endpoint_url | The endpoint URL for the private link VPC endpoint | Yes | Yes | String | | |
tags | Key-value pairs to tag the model created in AWS | Yes | Yes | Dict | | {} |
role | The ARN of the IAM role that Amazon SageMaker can assume to access model artifacts and docker image for deployment on ML compute instances or for batch transform jobs | No | No | String | | |
network_isolation | Isolates the model container. No inbound or outbound network calls can be made to or from the model container | Yes | Yes | Boolean | | True |
model_name | The name of the new model | No | No | String | | |
vpc_subnets | The ID of the subnets in the VPC to which you want to connect your training job or model | No if `vpc_security_group_ids` is specified | No if `vpc_security_group_ids` is specified | Array of Strings | | |
vpc_security_group_ids | The security groups for the VPC that is specified in the vpc_subnets field | No if `vpc_subnets` is specified | No if `vpc_subnets` is specified | Array of Strings | | |
The docker image containing inference code, associated artifacts, and environment map that the inference code uses when the model is deployed for predictions make up the [`ContainerDefinition`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ContainerDefinition.html) object in CreateModel API. The following parameters(except secondary_containers) describes the container, as part of model definition:
Argument | Description | Optional (in pipeline definition) | Optional (in UI) | Data type | Accepted values | Default |
:--- | :---------- | :---------- | :---------- | :----------| :---------- | :----------|
container_host_name | When a ContainerDefinition is part of an [inference pipeline](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipelines.html), the value of the parameter uniquely identifies the container for the purposes of [logging and metrics](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipeline-logs-metrics.html) | Yes | Yes | String | Length Constraints: Maximum length of 63. Pattern: `^[a-zA-Z0-9](-*[a-zA-Z0-9])*` | |
environment | The environment variables to set in the Docker container | Yes | Yes | Dict | Maximum length of 1024. Key Pattern: `[a-zA-Z_][a-zA-Z0-9_]*`. Value Pattern: `[\S\s]*` | {} |
image | The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored | Yes | Yes | String | | |
model_artifact_url | The S3 path where the model artifacts are stored. This path must point to a single gzip compressed tar archive (.tar.gz suffix) | Yes | Yes | String | | |
model_package | The name or Amazon Resource Name (ARN) of the model package to use to create the model | Yes | Yes | String | | |
secondary_containers | List of ContainerDefinition dictionaries in form of string (see Notes below) | Yes | Yes | String| Maximum number of 5 items | |
Notes:
* Please use the links in the [Resources section](#Resources) for detailed information on each input parameter and SageMaker APIs used in this component
* If you don't specify a value for `container_host_name` parameter for a `ContainerDefinition` that is part of an [inference pipeline](https://docs.aws.amazon.com/sagemaker/latest/dg/inference-pipelines.html), a unique name is automatically assigned based on the position of the `ContainerDefinition` in the pipeline. If you specify a value for the `ContainerHostName` for any `ContainerDefinition` that is part of an inference pipeline, you must specify a value for the `ContainerHostName` parameter of every `ContainerDefinition` in that pipeline.
* Each key and value in the `Environment` parameter string to string map can have length of up to 1024. SageMaker supports up to 16 entries in the map.
* Input format to specify `secondary_containers` is:
```
[
{
"ContainerHostname": "string",
"Environment": {
"string" : "string"
},
"Image": "string",
"ModelDataUrl": "string",
"ModelPackageName": "string"
}
]
```
* Specify either an `image` and `model_artifact_url`, OR a `model_package` in the `ContainerDefinition`.
* If you have a single container to define the model, use the parameters `container_host_name`, `environment`, `image`, `model_artifact_url`, `model_package` directly to define the primary container.
## Outputs
Name | Description
:--- | :----------
model_name | The name of the model created in Amazon SageMaker
## Requirements
* [Kubeflow pipelines SDK](https://www.kubeflow.org/docs/pipelines/sdk/install-sdk/)
* [Kubeflow set-up](https://www.kubeflow.org/docs/aws/deploy/install-kubeflow/)
## Samples
### Integrated into a pipeline
MNIST Classification pipeline: [Pipeline](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/mnist-classification-pipeline.py) | [Steps](https://github.com/kubeflow/pipelines/blob/master/samples/contrib/aws-samples/mnist-kmeans-sagemaker/README.md)
## Resources
* [Create Model API documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)
* [Boto3 API reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model)