入門ガイド (AWS CLI)

この演習では、AWS Command Line Interface(AWS CLI) を参照して、Amazon Personalize。映画のレコメンデーションを特定のユーザー ID に返すキャンペーンを作成します。

この演習を開始する前に、以下を実行します。

• 開始方法「入門ガイドの前提条件」を見る

• AWS CLI をセットアップします。「AWS CLI の設定」の手順に従ってください。

入門ガイドの演習を完了したら、不要な料金が発生しないように、リソースをクリーンアップするをクリックして、作成したリソースを削除します。

注記

-AWS CLIこの演習のコマンドは Linux でテストされています。の使用については、AWS CLIWindows でのコマンドの説明については、のパラメータ値の指定AWS Command Line Interface()AWS Command Line Interfaceユーザーガイド。

ステップ 1: トレーニングデータのインポート

次の手順に従って、データセットグループを作成し、このグループにデータセットを追加します。次に、映画のレーティングデータを使用してデータセットを事前設定します。

1. 次のコマンドを実行してデータセットグループを作成します。データセットグループを暗号化するには、AWS Key Management Serviceキー ARN と、そのキーへのアクセス許可を持つ IAM ロールの ARN を入力パラメータとして渡します。この API の詳細については、「 CreateDatasetGroup 」を参照してください。

   aws personalize create-dataset-group --name MovieRatingDatasetGroup --kms-key-arn arn:aws:kms:us-west-2:01234567890:key/1682a1e7-a94d-4d92-bbdf-837d3b62315e --role-arn arn:aws:iam::01234567890:KMS-key-access

   データセットグループの ARN が表示されます。次に例を示します。

   {
     "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup"
   }

   作成したデータセットグループを表示するには、返されたデータセットグループの ARN を指定して、describe-dataset-group コマンドを使用します。

   aws personalize describe-dataset-group \
   --dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup

   データセットグループとそのプロパティが表示されます。次に例を示します。

   {
       "datasetGroup": {
           "name": "MovieRatingDatasetGroup",
           "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
           "status": "ACTIVE",
           "creationDateTime": 1542392161.262,
           "lastUpdatedDateTime": 1542396513.377
       }
   }

   注記

   データセットグループ内にデータセットを作成するには、データセットグループの status が ACTIVE になるまで待ちます。通常、このオペレーションは高速に処理されます。

   データセットグループの ARN が不明な場合は、list-dataset-groups コマンドを使用して、作成したすべてのデータセットグループとその ARN を表示します。

   aws personalize list-dataset-groups

   注記

   -describe-objectおよびlist-objectsコマンドは、ほとんどの Amazon Personalize オブジェクトで使用できます。これらのコマンドは、この演習で以後取り扱いませんが、いつでも使用可能です。

2. 次のコードを MovieRatingSchema.json という名前のファイルに保存して、スキーマファイルを JSON 形式で作成します。スキーマは、以前に ratings.csv に追加したヘッダーと一致します。スキーマ名はInteractionsAmazon Personalize によって認識される 3 種類のデータセットの 1 つと一致します。詳細については、「データセットとスキーマ」を参照してください。

   {
     "type": "record",
     "name": "Interactions",
     "namespace": "com.amazonaws.personalize.schema",
     "fields": [
         {
             "name": "USER_ID",
             "type": "string"
         },
         {
             "name": "ITEM_ID",
             "type": "string"
         },
         {
             "name": "TIMESTAMP",
             "type": "long"
         }
     ],
     "version": "1.0"
   }

3. 次のコマンドを実行してスキーマを作成します。前のステップで保存したファイルを指定します。次の例は、現在のフォルダに属するファイルを示しています。この API の詳細については、「 CreateSchema 」を参照してください。

   aws personalize create-schema \
     --name MovieRatingSchema \
     --schema file://MovieRatingSchema.json

   スキーマの Amazon リソースネーム (ARN) が表示されます。次に例を示します。

   {
     "schemaArn": "arn:aws:personalize:us-west-2:acct-id:schema/MovieRatingSchema"
   }

4. 次のコマンドを実行して空のデータセットを作成します。前のステップで返されたデータセットグループの ARN とスキーマの ARN を指定します。dataset-type は、前のステップのスキーマ name と一致する必要があります。この API の詳細については、「 CreateDataset 」を参照してください。

   aws personalize create-dataset \
     --name MovieRatingDataset \
     --dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup \
     --dataset-type Interactions \
     --schema-arn arn:aws:personalize:us-west-2:acct-id:schema/MovieRatingSchema

   データセットの ARN が表示されます。次に例を示します。

   {
     "datasetArn": "arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS"
   }

5. トレーニングデータをデータセットに追加します。

   1. 次のコマンドを実行してデータセットのインポートジョブを作成します。前のステップで返されたデータセットの ARN と Amazon S3 バケットの名前を指定します。を供給します。AWS Identity and Access Managementで作成した (IAM) ロール ARNAmazon Personalize の IAM サービスロールの作成。この API の詳細については、「 CreateDatasetImportJob 」を参照してください。

      aws personalize create-dataset-import-job \
        --job-name MovieRatingImportJob \
        --dataset-arn arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS \
        --data-source dataLocation=s3://bucketname/ratings.csv \
        --role-arn roleArn

      データセットのインポートジョブの ARN が表示されます。次に例を示します。

      {
        "datasetImportJobArn": "arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob"
      }

   2. describe-dataset-import-job コマンドを使用してステータスを確認します。前のステップで返されたデータセットのインポートジョブの ARN を指定します。この API の詳細については、「 DescribeDatasetImportJob 」を参照してください。

      aws personalize describe-dataset-import-job \
        --dataset-import-job-arn arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob

      データセットのインポートジョブのプロパティとそのステータスが表示されます。最初、status は CREATE PENDING と表示されます。次に例を示します。

      {
        "datasetImportJob": {
            "jobName": "MovieRatingImportJob",
            "datasetImportJobArn": "arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob",
            "datasetArn": "arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS",
            "dataSource": {
                "dataLocation": "s3://<bucketname>/ratings.csv"
            },
            "roleArn": "role-arn",
            "status": "CREATE PENDING",
            "creationDateTime": 1542392161.837,
            "lastUpdatedDateTime": 1542393013.377
        }
      }

      ステータスが ACTIVE と表示されると、データセットのインポートが完了します。これで、指定したデータセットを使用してモデルをトレーニングする準備が整いました。

      注記

      インポートには時間がかかります。データセットのインポートが完了するまで待ってから、データセットを使用してモデルのトレーニングを開始します。

ステップ 2: ソリューションの作成 (モデルのトレーニング)

モデルを初めてトレーニングするには 2 つのステップが必要です。まず、 CreateSolution オペレーションを使用してモデルをトレーニングするための設定を作成します。​ 次に、 CreateSolutionVersion オペレーションを使用してモデルをトレーニングします。

レシピとトレーニングデータを使用してモデルをトレーニングします。Amazon Personalize には、一連の定義済みレシピが用意されています。詳細については、「ステップ 1: レシピの選択」を参照してください。この演習では、User-Personalization レシピを使用します。

1. モデルトレーニングの設定を作成するには、次のコマンドを実行します。

   aws personalize create-solution \
     --name MovieSolution \
     --dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup \
     --recipe-arn arn:aws:personalize:::recipe/aws-user-personalization

   ソリューションの ARN が表示されます。次に例を示します。

   {
     "solutionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution"
   }

2. をチェックします。作成を使用したステータスの作成describe-solutionコマンド。前のステップで返されたソリューションの ARN を指定します。この API の詳細については、「 DescribeSolution 」を参照してください。

   aws personalize describe-solution \
     --solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution

   ソリューションのプロパティと作成の status が表示されます。最初、ステータスには CREATE PENDING と表示されます。次に例を示します。

   {      
     "solution": {
         "name": "MovieSolution",
         "solutionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution",
         "performHPO": false,
         "performAutoML": false,
         "recipeArn": "arn:aws:personalize:::recipe/aws-user-personalization",
         "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
         "solutionConfig": {},
         "status": "ACTIVE",
         "creationDateTime": "2021-05-12T16:27:59.819000-07:00",
         "lastUpdatedDateTime": "2021-05-12T16:27:59.819000-07:00"
     }
   }

3. ソリューションが ACTIVE の場合は、次のコマンドを実行してモデルをトレーニングします。

   aws personalize create-solution-version \
     --solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution

   ソリューションバージョンの ARN が表示されます。次に例を示します。

   {
     "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/<version-id>"
   }

   をチェックします。トレーニングソリューションバージョンのステータスを確認するには、describe-solution-versionコマンド。前のステップで返ったソリューションバージョンの ARN を指定します。この API の詳細については、「 DescribeSolutionVersion 」を参照してください。

   aws personalize describe-solution-version \
     --solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id

   ソリューションバージョンのプロパティとトレーニングの status が表示されます。最初、ステータスには CREATE PENDING と表示されます。次に例を示します。

   {
     "solutionVersion": {
         "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/<version-id>",
         ...,
         "status": "CREATE PENDING"
     }
   }

4. ソリューションバージョンstatusACTIVE の場合、トレーニングは完了します。

   次に、トレーニングメトリクスを確認し、このソリューションバージョンを使用してキャンペーンを作成できます。

   注記

   トレーニングには時間がかかります。トレーニングが完了する (ソリューションバージョンのトレーニングのステータスが ACTIVE と表示される) まで待ってから、このバージョンのソリューションをキャンペーンで使用します。

5. ソリューションバージョンのパフォーマンスを検証するには、そのメトリクスを確認できます。次のコマンドを実行して、ソリューションバージョンのメトリクスを取得します。以前に返ったソリューションバージョンの ARN を指定します。この API の詳細については、「 GetSolutionMetrics 」を参照してください。

   aws personalize get-solution-metrics \
     --solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id

   レスポンスの例を次に示します。

   {
     "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/www-solution/<version-id>",
     "metrics": {
           "coverage": 0.0485,
           "mean_reciprocal_rank_at_25": 0.0381,
           "normalized_discounted_cumulative_gain_at_10": 0.0363,
           "normalized_discounted_cumulative_gain_at_25": 0.0984,
           "normalized_discounted_cumulative_gain_at_5": 0.0175,
           "precision_at_10": 0.0107,
           "precision_at_25": 0.0207,
           "precision_at_5": 0.0107
       }
   }

ステップ 3: キャンペーンの作成 (ソリューションをデプロイ) します。

レコメンデーションを取得するには、事前にソリューションバージョンをデプロイする必要があります。ソリューションのデプロイは、キャンペーンの作成とも呼ばれます。キャンペーンを作成すると、クライアントアプリケーションは GetRecommendations API を使用してレコメンデーションを取得できます。

1. 次のコマンドを実行してキャンペーンを作成します。前のステップで返ったソリューションバージョンの ARN を指定します。この API の詳細については、「 CreateCampaign 」を参照してください。

   aws personalize create-campaign \
     --name MovieRecommendationCampaign \
     --solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id \
     --min-provisioned-tps 1

   レスポンスの例を次に示します。

   {
     "campaignArn": "arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign"
   }

2. 次のコマンドを実行してデプロイのステータスを確認します。前のステップで返されたキャンペーンの ARN を指定します。この API の詳細については、「 DescribeCampaign 」を参照してください。

   aws personalize describe-campaign \
     --campaign-arn arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign

   レスポンスの例を次に示します。

   {
     "campaign": { 
         "name": "MovieRecommendationCampaign",
         "campaignArn": "arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign",
         "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/<version-id>",
         "minProvisionedTPS": "1",
         "creationDateTime": 1543864775.923,
         "lastUpdatedDateTime": 1543864791.923,
         "status": "CREATE IN_PROGRESS"
     }
   }

   注記

   キャンペーンからレコメンデーションを取得するには、status が ACTIVE と表示されるまで待ちます。

ステップ 4: 推奨事項の取得

get-recommendations コマンドを実行してレコメンデーションを取得します。前のステップで返されたキャンペーンの ARN を指定します。リクエストでは、映画のレーティングデータセットのユーザー ID を指定します。この API の詳細については、「 GetRecommendations 」を参照してください。

注記

すべてのレシピで GetRecommendations API がサポートされているわけではありません。詳細については、「ステップ 1: レシピの選択」を参照してください。

このステップで呼び出す AWS CLI コマンド (personalize-runtime) は、以前のステップとは異なります。

aws personalize-runtime get-recommendations \
  --campaign-arn arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign \
  --user-id 123

キャンペーンは、ユーザーが好むと思われるアイテムのレコメンデーション (映画 ID) のリストをレスポンスで返します。リストは、ユーザーに関連する度合いの高い順 (降順) にソートされます。

{
  "itemList": [
      {
          "itemId": "14"
      },
      {
          "itemId": "15"
      },
      {
          "itemId": "275"
      },
      {
          "itemId": "283"
      },
      {
          "itemId": "273"
      },
      ...
  ]
}