As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# 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](gs-prerequisites.md).
+ Configure a AWS CLI, conforme especificado em [Configurando o AWS CLI](aws-personalize-set-up-aws-cli.md).
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](deleting-resources.md).
**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](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html) no *Guia do usuário da AWS Command Line Interface*.
## Etapa 1: importar dados de treinamento
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.
1. 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](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) 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 do , consulte [CreateDatasetGroup](API_CreateDatasetGroup.md).
```
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.
1. 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](how-it-works-dataset-schema.md).
```
{
"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"
}
```
1. 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 do , consulte [CreateSchema](API_CreateSchema.md).
```
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"
}
```
1. 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 do , consulte [CreateDataset](API_CreateDataset.md).
```
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"
}
```
1. 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](set-up-required-permissions.md#set-up-create-role-with-permissions). Para obter mais informações sobre a API do , consulte [CreateDatasetImportJob](API_CreateDatasetImportJob.md).
```
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"
}
```
1. 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 do , consulte [DescribeDatasetImportJob](API_DescribeDatasetImportJob.md).
```
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.
## Etapa 2: criar uma solução (treinar o modelo)
Para treinar um modelo, crie a configuração usando a operação [CreateSolution](API_CreateSolution.md) 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](working-with-predefined-recipes.md). Para este exercício, use a fórmula User-Personalization-v2.
1. 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"
}
```
1. 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 do , consulte [DescribeSolution](API_DescribeSolution.md).
```
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"
}
}
```
1. 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](https://docs.aws.amazon.com/personalize/latest/dg/API_ListSolutionVersions.html):
```
aws personalize list-solution-versions --solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution
```
1. 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 do , consulte [DescribeSolutionVersion](API_DescribeSolutionVersion.md).
```
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/",
...,
"status": "CREATE PENDING"
}
}
```
1. 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.
1. 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 do , consulte [GetSolutionMetrics](API_GetSolutionMetrics.md).
```
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/",
"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
}
}
```
## Etapa 3: criar uma campanha (implantar a solução)
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](API_RS_GetRecommendations.md).
1. 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 do , consulte [CreateCampaign](API_CreateCampaign.md).
```
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"
}
```
1. 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 do , consulte [DescribeCampaign](API_DescribeCampaign.md).
```
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/",
"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.
## Etapa 4: obter recomendações
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 do , consulte [GetRecommendations](API_RS_GetRecommendations.md).
**nota**
Nem todas as fórmulas são compatíveis com a API `GetRecommendations`. Para obter mais informações, consulte [Escolher uma fórmula](working-with-predefined-recipes.md).
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"
},
...
]
}
```