Conceitos básicos (AWS CLI)

Neste exercício, você usará a AWS Command Line Interface (AWS CLI) para explorar o Amazon Personalize. Você vai criar uma campanha que retorna recomendações de filmes para um determinado ID de usuário.

Antes de começar este exercício, faça o seguinte:

Consulte os Conceitos básicos Pré-requisitos de conceitos básicos.
Configure a AWS CLI, conforme especificado em Configuração da AWS CLI.

Depois de concluir este exercício, exclua os recursos que você criou para evitar cobranças desnecessárias. Para obter mais informações, consulte Requisitos para excluir recursos do Amazon Personalize.

nota

Os comandos da AWS CLI neste exercício foram testados no Linux. Para obter informações sobre como usar os comandos da AWS CLI no Windows, consulte Como especificar valores de parâmetros para AWS Command Line Interface no Guia do usuário da AWS Command Line Interface.

Siga as etapas para criar um grupo de conjuntos de dados, adicione um conjunto de dados ao grupo e preencha o conjunto de dados usando os dados de classificação do filme.

Crie um grupo de conjuntos de dados executando o seguinte comando. É possível criptografar o grupo de conjuntos de dados transmitindo o ARN de uma chave do AWS Key Management Service e o ARN de um perfil do IAM que tenha permissões de acesso a essa chave como parâmetros de entrada. Para obter mais informações sobre a API, consulte 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
```
O ARN do grupo de conjuntos de dados é exibido, por exemplo:
```
{
  "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup"
}
```
Use o comando describe-dataset-group para exibir o grupo de conjuntos de dados que criou especificando o ARN do grupo de conjuntos de dados retornado.
```
aws personalize describe-dataset-group \
--dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup
```
O grupo de conjuntos de dados e suas propriedades são exibidos, por exemplo:
```
{
    "datasetGroup": {
        "name": "MovieRatingDatasetGroup",
        "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
        "status": "ACTIVE",
        "creationDateTime": 1542392161.262,
        "lastUpdatedDateTime": 1542396513.377
    }
}
```
nota
Aguarde até que o status do grupo de conjuntos de dados seja exibido como ACTIVE (ativo) antes de criar um conjunto de dados no grupo. Em geral, essa operação é rápida.

Se você não lembrar o ARN do grupo de conjuntos de dados, use o comando list-dataset-groups para exibir todos os grupos de conjuntos de dados que criou, juntamente com seus ARNs.
```
aws personalize list-dataset-groups
```
nota
Os comandos describe-object e list-objects estão disponíveis para a maioria dos objetos do Amazon Personalize. Esses comandos não serão mostrados no restante deste exercício, mas eles estão disponíveis.
Crie um arquivo de esquema no formato JSON salvando o código a seguir em um arquivo chamado MovieRatingSchema.json. O esquema corresponde aos cabeçalhos que você adicionou anteriormente ao arquivo ratings.csv. O nome do esquema é Interactions, que corresponde a um dos tipos de conjunto de dados reconhecidos pelo Amazon Personalize. Para obter mais informações, consulte Criar arquivos JSON de esquema para esquemas do Amazon Personalize.
```
{
  "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"
}
```
Crie um esquema executando o seguinte comando. Especifique o arquivo que você salvou na etapa anterior. O exemplo mostra o arquivo como pertencente à pasta atual. Para obter mais informações sobre a API, consulte CreateSchema.
```
aws personalize create-schema \
  --name MovieRatingSchema \
  --schema file://MovieRatingSchema.json
```
O nome do recurso da Amazon (ARN) do esquema é exibido, por exemplo:
```
{
  "schemaArn": "arn:aws:personalize:us-west-2:acct-id:schema/MovieRatingSchema"
}
```

Crie um conjunto de dados vazio executando o seguinte comando. Forneça os dois ARNs, do grupo de conjuntos de dados e do esquema, que foram retornados nas etapas anteriores. O dataset-type deve corresponder ao tipo do esquema name da etapa anterior. Para obter mais informações sobre a API, consulte 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

O ARN do conjunto de dados é exibido, por exemplo:


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

Adicione os dados de treinamento ao conjunto de dados.
1. Crie um trabalho de importação do conjunto de dados executando o seguinte comando. Forneça o ARN do conjunto de dados e o nome do bucket do Amazon S3 que foram retornados nas etapas anteriores. Forneça o ARN do perfil AWS Identity and Access Management (IAM) que você criou em Criar um perfil do IAM para o Amazon Personalize. Para obter mais informações sobre a API, consulte 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://amzn-s3-demo-bucket/ratings.csv \
  --role-arn roleArn
```
  O ARN do trabalho de importação do conjunto de dados é exibido, por exemplo:
```
{
  "datasetImportJobArn": "arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob"
}
```
2. Verifique o status usando o comando describe-dataset-import-job. Forneça o ARN do trabalho de importação do conjunto de dados que foi retornado na etapa anterior. Para obter mais informações sobre a API, consulte DescribeDatasetImportJob.
```
aws personalize describe-dataset-import-job \
  --dataset-import-job-arn arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob
```
  As propriedades do trabalho de importação do conjunto de dados, incluindo seu status, são exibidas. Inicialmente, o status é exibido como CREATE PENDING (criação pendente), por exemplo:
```
{
  "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://amzn-s3-demo-bucket/ratings.csv"
      },
      "roleArn": "role-arn",
      "status": "CREATE PENDING",
      "creationDateTime": 1542392161.837,
      "lastUpdatedDateTime": 1542393013.377
  }
}
```
  A exportação do conjunto de dados estará concluída quando o status for ACTIVE. Agora, você está pronto para treinar o modelo usando o conjunto de dados especificado.
  
  nota
  A importação é demorada. Aguarde até que a importação do conjunto de dados seja concluída antes de treinar o modelo usando o conjunto de dados.

Para treinar um modelo, crie a configuração usando a operação CreateSolution e ative o treinamento automático. A solução inicia automaticamente o treinamento da primeira solução em uma hora.

Você treina um modelo usando uma fórmula e seus dados de treinamento. O Amazon Personalize fornece um conjunto de fórmulas predefinidas. Para obter mais informações, consulte Escolher uma fórmula. Para este exercício, use a fórmula User-Personalization-v2.

Crie a configuração para treinar um modelo executando o comando a seguir. Esse comando cria uma solução que usa treinamento automático. Ele cria automaticamente uma nova versão da solução a cada sete dias (o padrão).


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-v2 \ 
  --perform-auto-training \
  --solution-config "{\"autoTrainingConfig\": {\"schedulingExpression\": \"rate(7 days)\"}}"

O ARN da solução é exibido, por exemplo:


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

Verifique o status de criação usando o comando describe-solution. Forneça o ARN da solução que foi retornado na etapa anterior. Para obter mais informações sobre a API, consulte DescribeSolution.


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

As propriedades da solução e o status de criação são exibidos. Por exemplo:


{      
  "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-v2",
      "datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
      "solutionConfig": {
            "algorithmHyperParameters": {
                "apply_recency_bias": "true"
            },
            "featureTransformationParameters": {},
            "autoTrainingConfig": {
                "schedulingExpression": "rate(7 days)"
            }
       },
      "status": "ACTIVE",
      "creationDateTime": "2021-05-12T16:27:59.819000-07:00",
      "lastUpdatedDateTime": "2021-05-12T16:27:59.819000-07:00"
  }
}

Com o treinamento automático, o treino da versão da solução começa dentro de uma hora após a solução se tornar ATIVA. Após o início do treinamento, você poderá obter o nome do recurso da Amazon (ARN) da versão da solução usando o seguinte comando ListSolutionVersions:
```
aws personalize list-solution-versions --solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution
```
Verifique o status de treinamento da versão da solução usando o comando describe-solution-version. Forneça o ARN da versão da solução que foi retornado na etapa anterior. Para obter mais informações sobre a API, consulte DescribeSolutionVersion.
```
aws personalize describe-solution-version \
  --solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id
```
As propriedades da versão da solução e o status do treinamento são exibidos. Inicialmente, o status é exibido como CREATE PENDING (criação pendente), por exemplo:
```
{
  "solutionVersion": {
      "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/<version-id>",
      ...,
      "status": "CREATE PENDING"
  }
}
```
Quando a versão da solução status estiver ATIVA, o treinamento foi concluído.

Agora você pode revisar as métricas de treinamento e criar uma campanha usando a versão da solução.

nota
O treinamento é demorado. Aguarde até que o treinamento seja concluído (o status do treinamento da versão da solução é exibido como ACTIVE [Ativo]) antes de usar esta versão da solução em uma campanha.

Você pode validar o desempenho da versão da solução analisando as métricas dela. Obtenha as métricas para a versão da solução executando o comando a seguir. Forneça o ARN da versão da solução que foi retornado anteriormente. Para obter mais informações sobre a API, consulte GetSolutionMetrics.


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

Uma resposta de exemplo é mostrada:


{
  "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
    }
}

Antes de obter recomendações, você deve implantar uma versão da solução. A implantação de uma solução também é conhecida como a criação de uma campanha. Depois que você tiver criado a campanha, sua aplicação cliente poderá obter recomendações usando a API GetRecommendations.

Crie uma campanha executando o seguinte comando. Forneça o ARN da versão da solução que foi retornado na etapa anterior. Para obter mais informações sobre a API, consulte 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

Uma resposta de exemplo é mostrada:


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

Verifique o status da implantação executando o seguinte comando. Forneça o ARN da campanha que foi retornado na etapa anterior. Para obter mais informações sobre a API, consulte DescribeCampaign.


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

Uma resposta de exemplo é mostrada:


{
  "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"
  }
}

nota

Aguarde até que o status seja exibido como ACTIVE (ativo) antes de obter recomendações da campanha.

Obtenha recomendações executando o comando get-recommendations. Forneça o ARN da campanha que foi retornado na etapa anterior. Na solicitação, você especifica um ID de usuário do conjunto de dados de classificações de filmes. Para obter mais informações sobre a API, consulte GetRecommendations.

nota

Nem todas as fórmulas são compatíveis com a API GetRecommendations. Para obter mais informações, consulte Escolher uma fórmula.

O comando da AWS CLI chamado nesta etapa, personalize-runtime, é diferente do utilizado nas etapas anteriores.


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

Em resposta, a campanha retorna uma lista de recomendações de itens (IDs de filmes) que o usuário poderá apreciar. A lista é classificada em ordem decrescente de relevância para o usuário.


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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Conceitos básicos (console)

Conceitos básicos (SDK para Python (Boto3))