Minimum provisioned TPS Enabling metadata in recommendations Creating a campaign (console)Creating a campaign (Amazon CLI)Creating a campaign (Amazon SDKs)

Creating a campaign

For real-time recommendations with custom resources, after you complete Creating a solution version, you are ready to deploy your solution version with a campaign.

A campaign deploys a solution version (trained model) with a provisioned transaction capacity for generating real-time recommendations. After you create a campaign, you use the GetRecommendations or GetPersonalizedRanking API operations to get recommendations. If you are getting batch recommendations, you don't need to create a campaign. For more information see Batch recommendations and user segments (custom resources).

When you create a campaign, you can enable item metadata in recommendations. For more information, see Enabling metadata in recommendations.

You can create a campaign with the Amazon Personalize console, Amazon Command Line Interface (Amazon CLI), or Amazon SDKs.

Important

If you manually retrain your solution version or want to change an existing campaign's settings, such as enabling metadata in recommendations, you must update your campaign. For more information see Updating a campaign.

Topics

Minimum provisioned transactions per second and auto-scaling
Enabling metadata in recommendations
Creating a campaign (console)
Creating a campaign (Amazon CLI)
Creating a campaign (Amazon SDKs)
Updating a campaign

Minimum provisioned transactions per second and auto-scaling

Important

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

When you create an Amazon Personalize campaign, you can specify the minimum provisioned transactions per second (minProvisionedTPS) for the campaign. This is the baseline transaction throughput for the campaign provisioned by Amazon Personalize. It sets the minimum billing charge for the campaign while it is active. A transaction is a single GetRecommendations or GetPersonalizedRanking request. The default minProvisionedTPS is 1.

If your TPS increases beyond the minProvisionedTPS, Amazon Personalize auto-scales the provisioned capacity up and down, but never below minProvisionedTPS. There's a short time delay while the capacity is increased that might cause loss of transactions. When your traffic reduces, capacity returns to the minProvisionedTPS.

You are charged for the the minimum provisioned TPS or, if your requests exceed the minProvisionedTPS, the actual TPS. The actual TPS is the total number of recommendation requests you make. We recommend starting with a low minProvisionedTPS, track your usage using Amazon CloudWatch metrics, and then increase the minProvisionedTPS as necessary.

For more information about campaign costs, see Amazon Personalize pricing.

Enabling metadata in recommendations

Important

When you enable metadata in recommendations, you incur additional costs. For more information see Amazon Personalize pricing.

When you create a campaign, you can enable the option to include item metadata from your Items dataset with recommendation results. You can then choose the columns from your Items dataset to include in your request for recommendations or personalized ranking. Amazon Personalize returns this data for each item in the recommendation response.

You might use metadata to enrich recommendations in your user interface, such as adding the genres for movies to carousels. Or you might use it to visually assess recommendation quality. If you use generative AI in your app, you can plug the metadata into AI prompts to generate more relevant content. For more information about using Amazon Personalize with generative AI, see Amazon Personalize and generative AI.

To enable metadata with the Amazon Personalize console, when you create the campaign, choose Return items metadata in recommendation results in the Campaign details. For more information, see Creating a campaign (console).
To enable metadata with the Amazon SDKs or Amazon CLI, use the CreateCampaign API operation and in the campaignConfig set enableMetadataInInferenceResponse to true. For more information, see Creating a campaign (Amazon CLI) or Creating a campaign (Amazon SDKs).

To add metadata to recommendations, you must have an Items dataset with a column of metadata. You don't have to use the metadata in training. For information about creating a dataset, see Creating a dataset and a schema. For information managing and updating data, see Managing data.

Creating a campaign (console)

After your solution version status is Active you are ready to deploy it with an Amazon Personalize campaign.

To create a campaign (console)

Open the Amazon Personalize console at https://console.amazonaws.cn/personalize/home and sign into your account.
Choose the dataset group with the solution version you want to deploy.
In the navigation pane, under Custom resources, choose Campaigns.
On the Campaigns page, choose Create campaign.
On the Create new campaign page, for Campaign details, provide the following information:
- Campaign name – Enter the name of the campaign. The text you enter here appears on the Campaign dashboard and details page.
- Solution – Choose the solution that you just created.
- Solution version ID – Choose the ID of the solution version that you just created.
- Minimum provisioned transactions per second (called minProvisionedTPS in APIs) – Set the minimum provisioned transactions per second that Amazon Personalize supports. A high value will increase your bill. We recommend starting with 1 (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary. For more information, see Minimum provisioned transactions per second and auto-scaling.
- Return items metadata in recommendation results – Choose this option if you want to be able to include metadata with recommendation results. If enabled, you can specify the columns from your Items dataset in your request for recommendations or personalized ranking. Amazon Personalize returns this data for each item in the recommendation response.
  
  To enable metadata, you must have an Items dataset with a column of metadata.
If you used the User-Personalization recipe, in Campaign configuration optionally enter values for the Exploration weight and Exploration item age cut off. For more information see User-Personalization.
For Tags, optionally add any tags. For more information about tagging Amazon Personalize resources, see Tagging Amazon Personalize resources.
Choose Create campaign.
On the campaign details page, when the campaign status is Active, you can use the campaign to get recommendations and record impressions. For more information, see Step 4: Getting recommendations.

The campaign is ready when its status is ACTIVE. If you retrain your solution version or want to change your campaign settings, you must update your campaign. For more information see Updating a campaign.

Creating a campaign (Amazon CLI)

After your solution version status is Active, you are ready to deploy it with an Amazon Personalize campaign. Use the following create-campaign Amazon CLI command to create a campaign that deploys a solution version trained using the User-Personalization recipe. Give the campaign a name and specify the solution version ARN (Amazon Resource Name). Optionally change the minProvisionedTPS if your use case requires a higher provisioned capacity. The minimum value is 1.

The campaign-config parameters are specific to the recipe that you used to train the solution version (for more information about recipes see Choosing a recipe).

The example uses the following User-Personalization recipe specific itemExplorationConfig fields with their default values: explorationWeight and explorationItemAgeCutOff. If you omit the campaign-config parameter, the default values apply. For more information about the itemExplorationConfig fields, see the Properties and hyperparameters for the User-Personalization recipe.

If you have an Items dataset and want the option to include metadata when you get recommendations, update the campaign-config to add an enableMetadataWithRecommendations field and set it to true.

For a complete list of all parameters, see CreateCampaign.


aws personalize create-campaign \
--name campaign name \
--solution-version-arn solution version arn \
--min-provisioned-tps 1 \
--campaign-config "{\"itemExplorationConfig\":{\"explorationWeight\":\"0.3\",\"explorationItemAgeCutOff\":\"30\"}}"

The campaign is ready when its status is ACTIVE. To get the current status, call DescribeCampaign and check that the status field is ACTIVE.

If you retrain your solution version or want to change your campaign settings, you must update your campaign. For more information see Updating a campaign.

Amazon Personalize provides operations for managing campaigns such as ListCampaigns to list the campaigns you have created. You can delete a campaign by calling DeleteCampaign. If you delete a campaign, the solution versions that are part of the campaign are not deleted.

After you have created your campaign, use it to make recommendations. For more information, see Step 4: Getting recommendations.

Creating a campaign (Amazon SDKs)

After your solution version status is Active you are ready to deploy it with an Amazon Personalize campaign. Use the following code to create a campaign. Give the campaign a name, specify the Amazon Resource Name (ARN) of the solution version to deploy, and optionally specify the Minimum provisioned TPS the campaign will support (the default value for this parameter is 1). If you use the User-Personalization recipe, you can configure item exploration with the itemExplorationWeight and explorationItemAgeCutOff parameters.

If you have an Items dataset and want the option to include metadata when you get recommendations, update the campaignConfig code to include an enableMetadataWithRecommendations attribute and set it true.

For a complete list of all parameters, see CreateCampaign.

SDK for Python (Boto3)

In this example, the itemExplorationWeight and explorationItemAgeCutOff parameters are specific to the User-Personalization recipe. The default itemExplorationWeight is 0.3 and the default explorationItemAgeCutOff is 30. If you leave out campaign configuration parameters, the default values apply.


import boto3

personalize = boto3.client('personalize')

response = personalize.create_campaign(
    name = 'campaign name',
    solutionVersionArn = 'solution version arn',
    minProvisionedTPS = 1,
    campaignConfig = {"itemExplorationConfig": {"explorationWeight": "0.3", "explorationItemAgeCutOff": "30"}}
)

arn = response['campaignArn']

description = personalize.describe_campaign(campaignArn = arn)['campaign']
print('Name: ' + description['name'])
print('ARN: ' + description['campaignArn'])
print('Status: ' + description['status'])

SDK for Java 2.x


public static void createCampaign(PersonalizeClient personalizeClient, 
                                String campaignName, 
                                String solutionVersionArn, 
                                Integer minProvisionedTPS, 
                                String itemExplorationWeight, 
                                String explorationItemAgeCutOff) {
                                
    //Optional code to instantiate a HashMap and add the explorationWeight and explorationItemAgeCutOff values.
    //Remove if you aren't using User-Personaliztion.
    Map<String,String> itemExploration = new HashMap<String,String>();
    itemExploration.put("explorationWeight", itemExplorationWeight);
    itemExploration.put("explorationItemAgeCutOff", explorationItemAgeCutOff);

    try {
        // Build a User-Personalization recipe specific campaignConfig object with the itemExploration map.
        // CampaignConfig construction will vary by recipe.
        CampaignConfig campaignConfig = CampaignConfig.builder()
            .itemExplorationConfig(itemExploration)
            .build();
    
        // build the createCampaignRequest
        CreateCampaignRequest createCampaignRequest = CreateCampaignRequest.builder()
            .name(campaignName)
            .solutionVersionArn(solutionVersionArn)
            .minProvisionedTPS(minProvisionedTPS)
            .campaignConfig(campaignConfig) //
            .build();

        // create the campaign
        CreateCampaignResponse campaignResponse = personalizeClient.createCampaign(createCampaignRequest);
        String campaignArn = campaignResponse.campaignArn();
        
        DescribeCampaignRequest campaignRequest = DescribeCampaignRequest.builder()
            .campaignArn(campaignArn)
            .build();
    
        DescribeCampaignResponse campaignResponse = personalizeClient.describeCampaign(campaignRequest);
        Campaign newCampaign = campaignResponse.campaign();
        
        System.out.println("The Campaign status is " + newCampaign.status());
    
    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}

SDK for JavaScript v3


// Get service clients module and commands using ES6 syntax.
import { CreateCampaignCommand, PersonalizeClient } from
  "@aws-sdk/client-personalize";

// create personalizeClient
const personalizeClient = new PersonalizeClient({ region: "REGION" });

// set the campaign parameters
export const createCampaignParam = {
  solutionVersionArn: "SOLUTION_VERSION_ARN",    /* required */
  name: "CAMPAIGN_NAME",                         /* required */
  minProvisionedTPS: 1,                          /* optional */
  campaignConfig: {
    itemExplorationConfig: {
      explorationWeight: "0.3",                  /* optional */
      explorationItemAgeCutOff: "30",            /* optional */
    },
  },
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateCampaignCommand(createCampaignParam)
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();

The campaign is ready when its status is ACTIVE. To get the current status, call DescribeCampaign and check that the status field is ACTIVE.

If you manually retrain your solution version or want to change your campaign settings, you must update your campaign. For more information see Updating a campaign.

After you have created your campaign, use it to make recommendations. For more information, see Step 4: Getting recommendations.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Evaluating a solution version with metrics

Updating a campaign