Amazon Personalize

2023/05/30 - Amazon Personalize - 7 updated api methods

Changes  This release provides support for the exclusion of certain columns for training when creating a solution and creating or updating a recommender with Amazon Personalize.

CreateRecommender (updated) Link ¶
Changes (request)
{'recommenderConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}

Creates a recommender with the recipe (a Domain dataset group use case) you specify. You create recommenders for a Domain dataset group and specify the recommender's Amazon Resource Name (ARN) when you make a GetRecommendations request.

Minimum recommendation requests per second

Warning

A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

When you create a recommender, you can configure the recommender's minimum recommendation requests per second. The minimum recommendation requests per second ( minRecommendationRequestsPerSecond ) specifies the baseline recommendation request throughput provisioned by Amazon Personalize. The default minRecommendationRequestsPerSecond is 1 . A recommendation request is a single GetRecommendations operation. Request throughput is measured in requests per second and Amazon Personalize uses your requests per second to derive your requests per hour and the price of your recommender usage.

If your requests per second increases beyond minRecommendationRequestsPerSecond , Amazon Personalize auto-scales the provisioned capacity up and down, but never below minRecommendationRequestsPerSecond . There's a short time delay while the capacity is increased that might cause loss of requests.

Your bill is the greater of either the minimum requests per hour (based on minRecommendationRequestsPerSecond) or the actual number of requests. The actual request throughput used is calculated as the average requests/second within a one-hour window. We recommend starting with the default minRecommendationRequestsPerSecond , track your usage using Amazon CloudWatch metrics, and then increase the minRecommendationRequestsPerSecond as necessary.

Status

A recommender can be in one of the following states:

  • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

  • STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE

  • DELETE PENDING > DELETE IN_PROGRESS

To get the recommender status, call DescribeRecommender.

Note

Wait until the status of the recommender is ACTIVE before asking the recommender for recommendations.

Related APIs

See also: AWS API Documentation

Request Syntax

client.create_recommender(
    name='string',
    datasetGroupArn='string',
    recipeArn='string',
    recommenderConfig={
        'itemExplorationConfig': {
            'string': 'string'
        },
        'minRecommendationRequestsPerSecond': 123,
        'trainingDataConfig': {
            'excludedDatasetColumns': {
                'string': [
                    'string',
                ]
            }
        }
    },
    tags=[
        {
            'tagKey': 'string',
            'tagValue': 'string'
        },
    ]
)
type name

string

param name

[REQUIRED]

The name of the recommender.

type datasetGroupArn

string

param datasetGroupArn

[REQUIRED]

The Amazon Resource Name (ARN) of the destination domain dataset group for the recommender.

type recipeArn

string

param recipeArn

[REQUIRED]

The Amazon Resource Name (ARN) of the recipe that the recommender will use. For a recommender, a recipe is a Domain dataset group use case. Only Domain dataset group use cases can be used to create a recommender. For information about use cases see Choosing recommender use cases.

type recommenderConfig

dict

param recommenderConfig

The configuration details of the recommender.

  • itemExplorationConfig (dict) --

    Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).

    • (string) --

      • (string) --

  • minRecommendationRequestsPerSecond (integer) --

    Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

  • trainingDataConfig (dict) --

    Specifies the training data configuration to use when creating a domain recommender.

    • excludedDatasetColumns (dict) --

      Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

      • (string) --

        • (list) --

          • (string) --

type tags

list

param tags

A list of tags to apply to the recommender.

  • (dict) --

    The optional metadata that you apply to resources to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. For more information see Tagging Amazon Personalize recources.

    • tagKey (string) -- [REQUIRED]

      One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.

    • tagValue (string) -- [REQUIRED]

      The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).

rtype

dict

returns

Response Syntax

{
    'recommenderArn': 'string'
}

Response Structure

  • (dict) --

    • recommenderArn (string) --

      The Amazon Resource Name (ARN) of the recommender.

CreateSolution (updated) Link ¶
Changes (request)
{'solutionConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}

Creates the configuration for training a model. A trained model is known as a solution version. After the configuration is created, you train the model (create a solution version) by calling the CreateSolutionVersion operation. Every time you call CreateSolutionVersion , a new version of the solution is created.

After creating a solution version, you check its accuracy by calling GetSolutionMetrics. When you are satisfied with the version, you deploy it using CreateCampaign. The campaign provides recommendations to a client through the GetRecommendations API.

To train a model, Amazon Personalize requires training data and a recipe. The training data comes from the dataset group that you provide in the request. A recipe specifies the training algorithm and a feature transformation. You can specify one of the predefined recipes provided by Amazon Personalize.

Note

Amazon Personalize doesn't support configuring the hpoObjective for solution hyperparameter optimization at this time.

Status

A solution can be in one of the following states:

  • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

  • DELETE PENDING > DELETE IN_PROGRESS

To get the status of the solution, call DescribeSolution. Wait until the status shows as ACTIVE before calling CreateSolutionVersion .

Related APIs

See also: AWS API Documentation

Request Syntax

client.create_solution(
    name='string',
    performHPO=True|False,
    performAutoML=True|False,
    recipeArn='string',
    datasetGroupArn='string',
    eventType='string',
    solutionConfig={
        'eventValueThreshold': 'string',
        'hpoConfig': {
            'hpoObjective': {
                'type': 'string',
                'metricName': 'string',
                'metricRegex': 'string'
            },
            'hpoResourceConfig': {
                'maxNumberOfTrainingJobs': 'string',
                'maxParallelTrainingJobs': 'string'
            },
            'algorithmHyperParameterRanges': {
                'integerHyperParameterRanges': [
                    {
                        'name': 'string',
                        'minValue': 123,
                        'maxValue': 123
                    },
                ],
                'continuousHyperParameterRanges': [
                    {
                        'name': 'string',
                        'minValue': 123.0,
                        'maxValue': 123.0
                    },
                ],
                'categoricalHyperParameterRanges': [
                    {
                        'name': 'string',
                        'values': [
                            'string',
                        ]
                    },
                ]
            }
        },
        'algorithmHyperParameters': {
            'string': 'string'
        },
        'featureTransformationParameters': {
            'string': 'string'
        },
        'autoMLConfig': {
            'metricName': 'string',
            'recipeList': [
                'string',
            ]
        },
        'optimizationObjective': {
            'itemAttribute': 'string',
            'objectiveSensitivity': 'LOW'|'MEDIUM'|'HIGH'|'OFF'
        },
        'trainingDataConfig': {
            'excludedDatasetColumns': {
                'string': [
                    'string',
                ]
            }
        }
    },
    tags=[
        {
            'tagKey': 'string',
            'tagValue': 'string'
        },
    ]
)
type name

string

param name

[REQUIRED]

The name for the solution.

type performHPO

boolean

param performHPO

Whether to perform hyperparameter optimization (HPO) on the specified or selected recipe. The default is false .

When performing AutoML, this parameter is always true and you should not set it to false .

type performAutoML

boolean

param performAutoML

Warning

We don't recommend enabling automated machine learning. Instead, match your use case to the available Amazon Personalize recipes. For more information, see Determining your use case.

Whether to perform automated machine learning (AutoML). The default is false . For this case, you must specify recipeArn .

When set to true , Amazon Personalize analyzes your training data and selects the optimal USER_PERSONALIZATION recipe and hyperparameters. In this case, you must omit recipeArn . Amazon Personalize determines the optimal recipe by running tests with different values for the hyperparameters. AutoML lengthens the training process as compared to selecting a specific recipe.

type recipeArn

string

param recipeArn

The ARN of the recipe to use for model training. Only specified when performAutoML is false.

type datasetGroupArn

string

param datasetGroupArn

[REQUIRED]

The Amazon Resource Name (ARN) of the dataset group that provides the training data.

type eventType

string

param eventType

When your have multiple event types (using an EVENT_TYPE schema field), this parameter specifies which event type (for example, 'click' or 'like') is used for training the model.

If you do not provide an eventType , Amazon Personalize will use all interactions for training with equal weight regardless of type.

type solutionConfig

dict

param solutionConfig

The configuration to use with the solution. When performAutoML is set to true, Amazon Personalize only evaluates the autoMLConfig section of the solution configuration.

Note

Amazon Personalize doesn't support configuring the hpoObjective at this time.

  • eventValueThreshold (string) --

    Only events with a value greater than or equal to this threshold are used for training a model.

  • hpoConfig (dict) --

    Describes the properties for hyperparameter optimization (HPO).

    • hpoObjective (dict) --

      The metric to optimize during HPO.

      Note

      Amazon Personalize doesn't support configuring the hpoObjective at this time.

      • type (string) --

        The type of the metric. Valid values are Maximize and Minimize .

      • metricName (string) --

        The name of the metric.

      • metricRegex (string) --

        A regular expression for finding the metric in the training job logs.

    • hpoResourceConfig (dict) --

      Describes the resource configuration for HPO.

      • maxNumberOfTrainingJobs (string) --

        The maximum number of training jobs when you create a solution version. The maximum value for maxNumberOfTrainingJobs is 40 .

      • maxParallelTrainingJobs (string) --

        The maximum number of parallel training jobs when you create a solution version. The maximum value for maxParallelTrainingJobs is 10 .

    • algorithmHyperParameterRanges (dict) --

      The hyperparameters and their allowable ranges.

      • integerHyperParameterRanges (list) --

        The integer-valued hyperparameters and their ranges.

        • (dict) --

          Provides the name and range of an integer-valued hyperparameter.

          • name (string) --

            The name of the hyperparameter.

          • minValue (integer) --

            The minimum allowable value for the hyperparameter.

          • maxValue (integer) --

            The maximum allowable value for the hyperparameter.

      • continuousHyperParameterRanges (list) --

        The continuous hyperparameters and their ranges.

        • (dict) --

          Provides the name and range of a continuous hyperparameter.

          • name (string) --

            The name of the hyperparameter.

          • minValue (float) --

            The minimum allowable value for the hyperparameter.

          • maxValue (float) --

            The maximum allowable value for the hyperparameter.

      • categoricalHyperParameterRanges (list) --

        The categorical hyperparameters and their ranges.

        • (dict) --

          Provides the name and range of a categorical hyperparameter.

          • name (string) --

            The name of the hyperparameter.

          • values (list) --

            A list of the categories for the hyperparameter.

            • (string) --

  • algorithmHyperParameters (dict) --

    Lists the hyperparameter names and ranges.

    • (string) --

      • (string) --

  • featureTransformationParameters (dict) --

    Lists the feature transformation parameters.

    • (string) --

      • (string) --

  • autoMLConfig (dict) --

    The AutoMLConfig object containing a list of recipes to search when AutoML is performed.

    • metricName (string) --

      The metric to optimize.

    • recipeList (list) --

      The list of candidate recipes.

      • (string) --

  • optimizationObjective (dict) --

    Describes the additional objective for the solution, such as maximizing streaming minutes or increasing revenue. For more information see Optimizing a solution.

    • itemAttribute (string) --

      The numerical metadata column in an Items dataset related to the optimization objective. For example, VIDEO_LENGTH (to maximize streaming minutes), or PRICE (to maximize revenue).

    • objectiveSensitivity (string) --

      Specifies how Amazon Personalize balances the importance of your optimization objective versus relevance.

  • trainingDataConfig (dict) --

    Specifies the training data configuration to use when creating a custom solution version (trained model).

    • excludedDatasetColumns (dict) --

      Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

      • (string) --

        • (list) --

          • (string) --

type tags

list

param tags

A list of tags to apply to the solution.

  • (dict) --

    The optional metadata that you apply to resources to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. For more information see Tagging Amazon Personalize recources.

    • tagKey (string) -- [REQUIRED]

      One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.

    • tagValue (string) -- [REQUIRED]

      The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).

rtype

dict

returns

Response Syntax

{
    'solutionArn': 'string'
}

Response Structure

  • (dict) --

    • solutionArn (string) --

      The ARN of the solution.

DescribeRecommender (updated) Link ¶
Changes (response)
{'recommender': {'latestRecommenderUpdate': {'recommenderConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}},
                 'recommenderConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}}

Describes the given recommender, including its status.

A recommender can be in one of the following states:

  • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

  • STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE

  • DELETE PENDING > DELETE IN_PROGRESS

When the status is CREATE FAILED , the response includes the failureReason key, which describes why.

The modelMetrics key is null when the recommender is being created or deleted.

For more information on recommenders, see CreateRecommender.

See also: AWS API Documentation

Request Syntax

client.describe_recommender(
    recommenderArn='string'
)
type recommenderArn

string

param recommenderArn

[REQUIRED]

The Amazon Resource Name (ARN) of the recommender to describe.

rtype

dict

returns

Response Syntax

{
    'recommender': {
        'recommenderArn': 'string',
        'datasetGroupArn': 'string',
        'name': 'string',
        'recipeArn': 'string',
        'recommenderConfig': {
            'itemExplorationConfig': {
                'string': 'string'
            },
            'minRecommendationRequestsPerSecond': 123,
            'trainingDataConfig': {
                'excludedDatasetColumns': {
                    'string': [
                        'string',
                    ]
                }
            }
        },
        'creationDateTime': datetime(2015, 1, 1),
        'lastUpdatedDateTime': datetime(2015, 1, 1),
        'status': 'string',
        'failureReason': 'string',
        'latestRecommenderUpdate': {
            'recommenderConfig': {
                'itemExplorationConfig': {
                    'string': 'string'
                },
                'minRecommendationRequestsPerSecond': 123,
                'trainingDataConfig': {
                    'excludedDatasetColumns': {
                        'string': [
                            'string',
                        ]
                    }
                }
            },
            'creationDateTime': datetime(2015, 1, 1),
            'lastUpdatedDateTime': datetime(2015, 1, 1),
            'status': 'string',
            'failureReason': 'string'
        },
        'modelMetrics': {
            'string': 123.0
        }
    }
}

Response Structure

  • (dict) --

    • recommender (dict) --

      The properties of the recommender.

      • recommenderArn (string) --

        The Amazon Resource Name (ARN) of the recommender.

      • datasetGroupArn (string) --

        The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.

      • name (string) --

        The name of the recommender.

      • recipeArn (string) --

        The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.

      • recommenderConfig (dict) --

        The configuration details of the recommender.

        • itemExplorationConfig (dict) --

          Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).

          • (string) --

            • (string) --

        • minRecommendationRequestsPerSecond (integer) --

          Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

        • trainingDataConfig (dict) --

          Specifies the training data configuration to use when creating a domain recommender.

          • excludedDatasetColumns (dict) --

            Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

            • (string) --

              • (list) --

                • (string) --

      • creationDateTime (datetime) --

        The date and time (in Unix format) that the recommender was created.

      • lastUpdatedDateTime (datetime) --

        The date and time (in Unix format) that the recommender was last updated.

      • status (string) --

        The status of the recommender.

        A recommender can be in one of the following states:

        • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

        • STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE

        • DELETE PENDING > DELETE IN_PROGRESS

      • failureReason (string) --

        If a recommender fails, the reason behind the failure.

      • latestRecommenderUpdate (dict) --

        Provides a summary of the latest updates to the recommender.

        • recommenderConfig (dict) --

          The configuration details of the recommender update.

          • itemExplorationConfig (dict) --

            Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).

            • (string) --

              • (string) --

          • minRecommendationRequestsPerSecond (integer) --

            Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

          • trainingDataConfig (dict) --

            Specifies the training data configuration to use when creating a domain recommender.

            • excludedDatasetColumns (dict) --

              Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

              • (string) --

                • (list) --

                  • (string) --

        • creationDateTime (datetime) --

          The date and time (in Unix format) that the recommender update was created.

        • lastUpdatedDateTime (datetime) --

          The date and time (in Unix time) that the recommender update was last updated.

        • status (string) --

          The status of the recommender update.

          A recommender can be in one of the following states:

          • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

          • STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE

          • DELETE PENDING > DELETE IN_PROGRESS

        • failureReason (string) --

          If a recommender update fails, the reason behind the failure.

      • modelMetrics (dict) --

        Provides evaluation metrics that help you determine the performance of a recommender. For more information, see Evaluating a recommender.

        • (string) --

          • (float) --

DescribeSolution (updated) Link ¶
Changes (response)
{'solution': {'solutionConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}}

Describes a solution. For more information on solutions, see CreateSolution.

See also: AWS API Documentation

Request Syntax

client.describe_solution(
    solutionArn='string'
)
type solutionArn

string

param solutionArn

[REQUIRED]

The Amazon Resource Name (ARN) of the solution to describe.

rtype

dict

returns

Response Syntax

{
    'solution': {
        'name': 'string',
        'solutionArn': 'string',
        'performHPO': True|False,
        'performAutoML': True|False,
        'recipeArn': 'string',
        'datasetGroupArn': 'string',
        'eventType': 'string',
        'solutionConfig': {
            'eventValueThreshold': 'string',
            'hpoConfig': {
                'hpoObjective': {
                    'type': 'string',
                    'metricName': 'string',
                    'metricRegex': 'string'
                },
                'hpoResourceConfig': {
                    'maxNumberOfTrainingJobs': 'string',
                    'maxParallelTrainingJobs': 'string'
                },
                'algorithmHyperParameterRanges': {
                    'integerHyperParameterRanges': [
                        {
                            'name': 'string',
                            'minValue': 123,
                            'maxValue': 123
                        },
                    ],
                    'continuousHyperParameterRanges': [
                        {
                            'name': 'string',
                            'minValue': 123.0,
                            'maxValue': 123.0
                        },
                    ],
                    'categoricalHyperParameterRanges': [
                        {
                            'name': 'string',
                            'values': [
                                'string',
                            ]
                        },
                    ]
                }
            },
            'algorithmHyperParameters': {
                'string': 'string'
            },
            'featureTransformationParameters': {
                'string': 'string'
            },
            'autoMLConfig': {
                'metricName': 'string',
                'recipeList': [
                    'string',
                ]
            },
            'optimizationObjective': {
                'itemAttribute': 'string',
                'objectiveSensitivity': 'LOW'|'MEDIUM'|'HIGH'|'OFF'
            },
            'trainingDataConfig': {
                'excludedDatasetColumns': {
                    'string': [
                        'string',
                    ]
                }
            }
        },
        'autoMLResult': {
            'bestRecipeArn': 'string'
        },
        'status': 'string',
        'creationDateTime': datetime(2015, 1, 1),
        'lastUpdatedDateTime': datetime(2015, 1, 1),
        'latestSolutionVersion': {
            'solutionVersionArn': 'string',
            'status': 'string',
            'creationDateTime': datetime(2015, 1, 1),
            'lastUpdatedDateTime': datetime(2015, 1, 1),
            'failureReason': 'string'
        }
    }
}

Response Structure

  • (dict) --

    • solution (dict) --

      An object that describes the solution.

      • name (string) --

        The name of the solution.

      • solutionArn (string) --

        The ARN of the solution.

      • performHPO (boolean) --

        Whether to perform hyperparameter optimization (HPO) on the chosen recipe. The default is false .

      • performAutoML (boolean) --

        Warning

        We don't recommend enabling automated machine learning. Instead, match your use case to the available Amazon Personalize recipes. For more information, see Determining your use case.

        When true, Amazon Personalize performs a search for the best USER_PERSONALIZATION recipe from the list specified in the solution configuration ( recipeArn must not be specified). When false (the default), Amazon Personalize uses recipeArn for training.

      • recipeArn (string) --

        The ARN of the recipe used to create the solution.

      • datasetGroupArn (string) --

        The Amazon Resource Name (ARN) of the dataset group that provides the training data.

      • eventType (string) --

        The event type (for example, 'click' or 'like') that is used for training the model. If no eventType is provided, Amazon Personalize uses all interactions for training with equal weight regardless of type.

      • solutionConfig (dict) --

        Describes the configuration properties for the solution.

        • eventValueThreshold (string) --

          Only events with a value greater than or equal to this threshold are used for training a model.

        • hpoConfig (dict) --

          Describes the properties for hyperparameter optimization (HPO).

          • hpoObjective (dict) --

            The metric to optimize during HPO.

            Note

            Amazon Personalize doesn't support configuring the hpoObjective at this time.

            • type (string) --

              The type of the metric. Valid values are Maximize and Minimize .

            • metricName (string) --

              The name of the metric.

            • metricRegex (string) --

              A regular expression for finding the metric in the training job logs.

          • hpoResourceConfig (dict) --

            Describes the resource configuration for HPO.

            • maxNumberOfTrainingJobs (string) --

              The maximum number of training jobs when you create a solution version. The maximum value for maxNumberOfTrainingJobs is 40 .

            • maxParallelTrainingJobs (string) --

              The maximum number of parallel training jobs when you create a solution version. The maximum value for maxParallelTrainingJobs is 10 .

          • algorithmHyperParameterRanges (dict) --

            The hyperparameters and their allowable ranges.

            • integerHyperParameterRanges (list) --

              The integer-valued hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of an integer-valued hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • minValue (integer) --

                  The minimum allowable value for the hyperparameter.

                • maxValue (integer) --

                  The maximum allowable value for the hyperparameter.

            • continuousHyperParameterRanges (list) --

              The continuous hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of a continuous hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • minValue (float) --

                  The minimum allowable value for the hyperparameter.

                • maxValue (float) --

                  The maximum allowable value for the hyperparameter.

            • categoricalHyperParameterRanges (list) --

              The categorical hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of a categorical hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • values (list) --

                  A list of the categories for the hyperparameter.

                  • (string) --

        • algorithmHyperParameters (dict) --

          Lists the hyperparameter names and ranges.

          • (string) --

            • (string) --

        • featureTransformationParameters (dict) --

          Lists the feature transformation parameters.

          • (string) --

            • (string) --

        • autoMLConfig (dict) --

          The AutoMLConfig object containing a list of recipes to search when AutoML is performed.

          • metricName (string) --

            The metric to optimize.

          • recipeList (list) --

            The list of candidate recipes.

            • (string) --

        • optimizationObjective (dict) --

          Describes the additional objective for the solution, such as maximizing streaming minutes or increasing revenue. For more information see Optimizing a solution.

          • itemAttribute (string) --

            The numerical metadata column in an Items dataset related to the optimization objective. For example, VIDEO_LENGTH (to maximize streaming minutes), or PRICE (to maximize revenue).

          • objectiveSensitivity (string) --

            Specifies how Amazon Personalize balances the importance of your optimization objective versus relevance.

        • trainingDataConfig (dict) --

          Specifies the training data configuration to use when creating a custom solution version (trained model).

          • excludedDatasetColumns (dict) --

            Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

            • (string) --

              • (list) --

                • (string) --

      • autoMLResult (dict) --

        When performAutoML is true, specifies the best recipe found.

        • bestRecipeArn (string) --

          The Amazon Resource Name (ARN) of the best recipe.

      • status (string) --

        The status of the solution.

        A solution can be in one of the following states:

        • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

        • DELETE PENDING > DELETE IN_PROGRESS

      • creationDateTime (datetime) --

        The creation date and time (in Unix time) of the solution.

      • lastUpdatedDateTime (datetime) --

        The date and time (in Unix time) that the solution was last updated.

      • latestSolutionVersion (dict) --

        Describes the latest version of the solution, including the status and the ARN.

        • solutionVersionArn (string) --

          The Amazon Resource Name (ARN) of the solution version.

        • status (string) --

          The status of the solution version.

          A solution version can be in one of the following states:

          • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

        • creationDateTime (datetime) --

          The date and time (in Unix time) that this version of a solution was created.

        • lastUpdatedDateTime (datetime) --

          The date and time (in Unix time) that the solution version was last updated.

        • failureReason (string) --

          If a solution version fails, the reason behind the failure.

DescribeSolutionVersion (updated) Link ¶
Changes (response)
{'solutionVersion': {'solutionConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}}

Describes a specific version of a solution. For more information on solutions, see CreateSolution

See also: AWS API Documentation

Request Syntax

client.describe_solution_version(
    solutionVersionArn='string'
)
type solutionVersionArn

string

param solutionVersionArn

[REQUIRED]

The Amazon Resource Name (ARN) of the solution version.

rtype

dict

returns

Response Syntax

{
    'solutionVersion': {
        'name': 'string',
        'solutionVersionArn': 'string',
        'solutionArn': 'string',
        'performHPO': True|False,
        'performAutoML': True|False,
        'recipeArn': 'string',
        'eventType': 'string',
        'datasetGroupArn': 'string',
        'solutionConfig': {
            'eventValueThreshold': 'string',
            'hpoConfig': {
                'hpoObjective': {
                    'type': 'string',
                    'metricName': 'string',
                    'metricRegex': 'string'
                },
                'hpoResourceConfig': {
                    'maxNumberOfTrainingJobs': 'string',
                    'maxParallelTrainingJobs': 'string'
                },
                'algorithmHyperParameterRanges': {
                    'integerHyperParameterRanges': [
                        {
                            'name': 'string',
                            'minValue': 123,
                            'maxValue': 123
                        },
                    ],
                    'continuousHyperParameterRanges': [
                        {
                            'name': 'string',
                            'minValue': 123.0,
                            'maxValue': 123.0
                        },
                    ],
                    'categoricalHyperParameterRanges': [
                        {
                            'name': 'string',
                            'values': [
                                'string',
                            ]
                        },
                    ]
                }
            },
            'algorithmHyperParameters': {
                'string': 'string'
            },
            'featureTransformationParameters': {
                'string': 'string'
            },
            'autoMLConfig': {
                'metricName': 'string',
                'recipeList': [
                    'string',
                ]
            },
            'optimizationObjective': {
                'itemAttribute': 'string',
                'objectiveSensitivity': 'LOW'|'MEDIUM'|'HIGH'|'OFF'
            },
            'trainingDataConfig': {
                'excludedDatasetColumns': {
                    'string': [
                        'string',
                    ]
                }
            }
        },
        'trainingHours': 123.0,
        'trainingMode': 'FULL'|'UPDATE',
        'tunedHPOParams': {
            'algorithmHyperParameters': {
                'string': 'string'
            }
        },
        'status': 'string',
        'failureReason': 'string',
        'creationDateTime': datetime(2015, 1, 1),
        'lastUpdatedDateTime': datetime(2015, 1, 1)
    }
}

Response Structure

  • (dict) --

    • solutionVersion (dict) --

      The solution version.

      • name (string) --

        The name of the solution version.

      • solutionVersionArn (string) --

        The ARN of the solution version.

      • solutionArn (string) --

        The ARN of the solution.

      • performHPO (boolean) --

        Whether to perform hyperparameter optimization (HPO) on the chosen recipe. The default is false .

      • performAutoML (boolean) --

        When true, Amazon Personalize searches for the most optimal recipe according to the solution configuration. When false (the default), Amazon Personalize uses recipeArn .

      • recipeArn (string) --

        The ARN of the recipe used in the solution.

      • eventType (string) --

        The event type (for example, 'click' or 'like') that is used for training the model.

      • datasetGroupArn (string) --

        The Amazon Resource Name (ARN) of the dataset group providing the training data.

      • solutionConfig (dict) --

        Describes the configuration properties for the solution.

        • eventValueThreshold (string) --

          Only events with a value greater than or equal to this threshold are used for training a model.

        • hpoConfig (dict) --

          Describes the properties for hyperparameter optimization (HPO).

          • hpoObjective (dict) --

            The metric to optimize during HPO.

            Note

            Amazon Personalize doesn't support configuring the hpoObjective at this time.

            • type (string) --

              The type of the metric. Valid values are Maximize and Minimize .

            • metricName (string) --

              The name of the metric.

            • metricRegex (string) --

              A regular expression for finding the metric in the training job logs.

          • hpoResourceConfig (dict) --

            Describes the resource configuration for HPO.

            • maxNumberOfTrainingJobs (string) --

              The maximum number of training jobs when you create a solution version. The maximum value for maxNumberOfTrainingJobs is 40 .

            • maxParallelTrainingJobs (string) --

              The maximum number of parallel training jobs when you create a solution version. The maximum value for maxParallelTrainingJobs is 10 .

          • algorithmHyperParameterRanges (dict) --

            The hyperparameters and their allowable ranges.

            • integerHyperParameterRanges (list) --

              The integer-valued hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of an integer-valued hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • minValue (integer) --

                  The minimum allowable value for the hyperparameter.

                • maxValue (integer) --

                  The maximum allowable value for the hyperparameter.

            • continuousHyperParameterRanges (list) --

              The continuous hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of a continuous hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • minValue (float) --

                  The minimum allowable value for the hyperparameter.

                • maxValue (float) --

                  The maximum allowable value for the hyperparameter.

            • categoricalHyperParameterRanges (list) --

              The categorical hyperparameters and their ranges.

              • (dict) --

                Provides the name and range of a categorical hyperparameter.

                • name (string) --

                  The name of the hyperparameter.

                • values (list) --

                  A list of the categories for the hyperparameter.

                  • (string) --

        • algorithmHyperParameters (dict) --

          Lists the hyperparameter names and ranges.

          • (string) --

            • (string) --

        • featureTransformationParameters (dict) --

          Lists the feature transformation parameters.

          • (string) --

            • (string) --

        • autoMLConfig (dict) --

          The AutoMLConfig object containing a list of recipes to search when AutoML is performed.

          • metricName (string) --

            The metric to optimize.

          • recipeList (list) --

            The list of candidate recipes.

            • (string) --

        • optimizationObjective (dict) --

          Describes the additional objective for the solution, such as maximizing streaming minutes or increasing revenue. For more information see Optimizing a solution.

          • itemAttribute (string) --

            The numerical metadata column in an Items dataset related to the optimization objective. For example, VIDEO_LENGTH (to maximize streaming minutes), or PRICE (to maximize revenue).

          • objectiveSensitivity (string) --

            Specifies how Amazon Personalize balances the importance of your optimization objective versus relevance.

        • trainingDataConfig (dict) --

          Specifies the training data configuration to use when creating a custom solution version (trained model).

          • excludedDatasetColumns (dict) --

            Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

            • (string) --

              • (list) --

                • (string) --

      • trainingHours (float) --

        The time used to train the model. You are billed for the time it takes to train a model. This field is visible only after Amazon Personalize successfully trains a model.

      • trainingMode (string) --

        The scope of training to be performed when creating the solution version. The FULL option trains the solution version based on the entirety of the input solution's training data, while the UPDATE option processes only the data that has changed in comparison to the input solution. Choose UPDATE when you want to incrementally update your solution version instead of creating an entirely new one.

        Warning

        The UPDATE option can only be used when you already have an active solution version created from the input solution using the FULL option and the input solution was trained with the User-Personalization recipe or the HRNN-Coldstart recipe.

      • tunedHPOParams (dict) --

        If hyperparameter optimization was performed, contains the hyperparameter values of the best performing model.

        • algorithmHyperParameters (dict) --

          A list of the hyperparameter values of the best performing model.

          • (string) --

            • (string) --

      • status (string) --

        The status of the solution version.

        A solution version can be in one of the following states:

        • CREATE PENDING

        • CREATE IN_PROGRESS

        • ACTIVE

        • CREATE FAILED

        • CREATE STOPPING

        • CREATE STOPPED

      • failureReason (string) --

        If training a solution version fails, the reason for the failure.

      • creationDateTime (datetime) --

        The date and time (in Unix time) that this version of the solution was created.

      • lastUpdatedDateTime (datetime) --

        The date and time (in Unix time) that the solution was last updated.

ListRecommenders (updated) Link ¶
Changes (response)
{'recommenders': {'recommenderConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}}

Returns a list of recommenders in a given Domain dataset group. When a Domain dataset group is not specified, all the recommenders associated with the account are listed. The response provides the properties for each recommender, including the Amazon Resource Name (ARN). For more information on recommenders, see CreateRecommender.

See also: AWS API Documentation

Request Syntax

client.list_recommenders(
    datasetGroupArn='string',
    nextToken='string',
    maxResults=123
)
type datasetGroupArn

string

param datasetGroupArn

The Amazon Resource Name (ARN) of the Domain dataset group to list the recommenders for. When a Domain dataset group is not specified, all the recommenders associated with the account are listed.

type nextToken

string

param nextToken

A token returned from the previous call to ListRecommenders for getting the next set of recommenders (if they exist).

type maxResults

integer

param maxResults

The maximum number of recommenders to return.

rtype

dict

returns

Response Syntax

{
    'recommenders': [
        {
            'name': 'string',
            'recommenderArn': 'string',
            'datasetGroupArn': 'string',
            'recipeArn': 'string',
            'recommenderConfig': {
                'itemExplorationConfig': {
                    'string': 'string'
                },
                'minRecommendationRequestsPerSecond': 123,
                'trainingDataConfig': {
                    'excludedDatasetColumns': {
                        'string': [
                            'string',
                        ]
                    }
                }
            },
            'status': 'string',
            'creationDateTime': datetime(2015, 1, 1),
            'lastUpdatedDateTime': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • recommenders (list) --

      A list of the recommenders.

      • (dict) --

        Provides a summary of the properties of the recommender.

        • name (string) --

          The name of the recommender.

        • recommenderArn (string) --

          The Amazon Resource Name (ARN) of the recommender.

        • datasetGroupArn (string) --

          The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.

        • recipeArn (string) --

          The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.

        • recommenderConfig (dict) --

          The configuration details of the recommender.

          • itemExplorationConfig (dict) --

            Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).

            • (string) --

              • (string) --

          • minRecommendationRequestsPerSecond (integer) --

            Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

          • trainingDataConfig (dict) --

            Specifies the training data configuration to use when creating a domain recommender.

            • excludedDatasetColumns (dict) --

              Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

              • (string) --

                • (list) --

                  • (string) --

        • status (string) --

          The status of the recommender. A recommender can be in one of the following states:

          • CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED

          • STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE

          • DELETE PENDING > DELETE IN_PROGRESS

        • creationDateTime (datetime) --

          The date and time (in Unix format) that the recommender was created.

        • lastUpdatedDateTime (datetime) --

          The date and time (in Unix format) that the recommender was last updated.

    • nextToken (string) --

      A token for getting the next set of recommenders (if they exist).

UpdateRecommender (updated) Link ¶
Changes (request)
{'recommenderConfig': {'trainingDataConfig': {'excludedDatasetColumns': {'string': ['string']}}}}

Updates the recommender to modify the recommender configuration. If you update the recommender to modify the columns used in training, Amazon Personalize automatically starts a full retraining of the models backing your recommender. While the update completes, you can still get recommendations from the recommender. The recommender uses the previous configuration until the update completes. To track the status of this update, use the latestRecommenderUpdate returned in the DescribeRecommender operation.

See also: AWS API Documentation

Request Syntax

client.update_recommender(
    recommenderArn='string',
    recommenderConfig={
        'itemExplorationConfig': {
            'string': 'string'
        },
        'minRecommendationRequestsPerSecond': 123,
        'trainingDataConfig': {
            'excludedDatasetColumns': {
                'string': [
                    'string',
                ]
            }
        }
    }
)
type recommenderArn

string

param recommenderArn

[REQUIRED]

The Amazon Resource Name (ARN) of the recommender to modify.

type recommenderConfig

dict

param recommenderConfig

[REQUIRED]

The configuration details of the recommender.

  • itemExplorationConfig (dict) --

    Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).

    • (string) --

      • (string) --

  • minRecommendationRequestsPerSecond (integer) --

    Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.

  • trainingDataConfig (dict) --

    Specifies the training data configuration to use when creating a domain recommender.

    • excludedDatasetColumns (dict) --

      Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

      • (string) --

        • (list) --

          • (string) --

rtype

dict

returns

Response Syntax

{
    'recommenderArn': 'string'
}

Response Structure

  • (dict) --

    • recommenderArn (string) --

      The same recommender Amazon Resource Name (ARN) as given in the request.