Como filtrar recomendações em tempo real

Você pode filtrar recomendações em tempo real com o console do Amazon Personalize, AWS Command Line Interface (AWS CLI) ou com os AWS SDKs.

Ao obter recomendações de itens personalizadas ou itens semelhantes, é possível especificar uma promoção na solicitação. Uma promoção usa um filtro para definir regras de negócios adicionais que se aplicam a um subconjunto configurável de itens recomendados. Para ter mais informações, consulte Como promover itens nas recomendações.

Como filtrar recomendações em tempo real (console)

Para usar o console e filtrar recomendações em tempo real, crie um filtro e aplique-o a uma solicitação de recomendação.

nota

Para filtrar recomendações usando um filtro com parâmetros e uma campanha implantada antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a operação UpdateCampaign ou criar uma nova campanha.

Como criar um filtro (console)

Para criar um filtro no console, escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas. Em seguida, forneça um nome de filtro e uma expressão de filtro.

Para criar um filtro (console)

1. Acesse https://console.aws.amazon.com/personalize/home para abrir o console do Amazon Personalize e faça login na sua conta.

2. Escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas.

3. Na página de navegação, selecione Filtros e, depois, Criar filtro. A página Criar filtro é exibida.

   

4. Em Nome do filtro, insira um nome para o filtro. Você escolherá o filtro com esse nome ao aplicá-lo a uma solicitação de recomendação.

5. Para Expressão, escolha Criar expressão ou Adicionar expressão manualmente e crie ou insira sua expressão:

   • Para usar o construtor de expressões, escolha Criar expressão. O construtor de expressões fornece estrutura, campos e diretrizes para criar expressões de filtro formatadas corretamente. Para ter mais informações, consulte Como usar o construtor de expressões de filtro.

   • Para inserir sua própria expressão, escolha Adicionar expressão manualmente. Para ter mais informações, consulte Filtrar elementos de expressão.

6. Escolha Concluir. A página de visão geral do filtro mostra o nome do recurso da Amazon (ARN), o status e a expressão completa do filtro. Para excluir o filtro, escolha Excluir. Para obter informações sobre como encontrar e excluir filtros depois de sair da página de visão geral, consulte Como excluir um filtro (console).

   

Como aplicar um filtro (console)

Para aplicar um filtro, em Testar recomendador (para recomendadores) ou Testar resultados da campanha (para campanhas personalizadas), selecione o filtro e insira os valores dos parâmetros do filtro. Em seguida, obtenha as recomendações para um usuário.

Importante

Para expressões de filtro que usem um elemento INCLUDE, é necessário fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usem um elemento EXCLUDE, é possível omitir os filter-values. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.

Para aplicar um filtro (console)

1. Acesse https://console.aws.amazon.com/personalize/home para abrir o console do Amazon Personalize e faça login na sua conta.

2. Escolha o grupo de conjuntos de dados que contém a campanha ou o recomendador que você deseja usar para obter recomendações filtradas.

3. Dependendo do tipo do grupo de conjuntos de dados ou do tipo de recurso, realize uma das seguintes ações:

   1. Para um grupo de conjuntos de dados de domínio, no painel de navegação, escolha Recomendadores.

   2. Para um grupo de conjuntos de dados ou recursos personalizados, no painel de navegação, selecione Recursos personalizados e escolha Campanhas.

4. Na página Recomendadores ou Campanhas, escolha o recomendador ou a campanha-alvo.

5. A título de comparação, comece obtendo recomendações sem aplicar um filtro. Em Testar recomendador/Testar resultados da campanha, insira o ID do usuário para o qual deseja obter recomendações, ou os IDs dos itens relacionados, e selecione Obter recomendações. Será exibida uma tabela com as principais recomendações.

   

6. Em Nome do filtro, escolha o filtro criado. Se o filtro tiver algum parâmetro de espaço reservado, os campos associados a cada parâmetro serão exibidos.

7. Se você estiver usando um filtro com parâmetros de espaço reservado, insira o valor para definir os critérios do filtro em cada parâmetro. Para usar vários valores em um parâmetro, separe cada um deles com uma vírgula.

8. Usando o mesmo User ID ou Item ID na etapa anterior, selecione Obter recomendações. A tabela de recomendações será exibida.

   

   Por exemplo, se o usuário já tiver comprado um item recomendado, o filtro o removerá da lista de recomendações. Neste exemplo, os itens 2657, 2985 foram substituídos pelos itens mais adequados que o usuário não comprou (itens 2641 e 1573).

Como usar o construtor de expressões de filtro

O construtor de expressões na página Criar filtro fornece estrutura, campos e diretrizes para criar um filtro formatado corretamente.

Para criar uma expressão de filtro:

• Use os campos Tipo, Ação, Propriedade, Operador e Valor para criar uma expressão.

  Insira um valor fixo em Valor ou, para definir critérios de filtro ao receber recomendações, insira $ + um nome de parâmetro. Por exemplo, $GENRES. Ao receber recomendações, você fornecerá o(s) valor(es) para filtrar. Neste exemplo, você forneceria um gênero ou uma lista de gêneros ao receber recomendações.

  Separe vários valores que não são parâmetros com uma vírgula. Não é possível adicionar parâmetros separados por vírgula a um filtro.

  nota

  Depois de escolher uma propriedade (no formato dataset.field), o valor de propriedade para todas as linhas sucessivas encadeadas por condições OR ou AND deve usar o mesmo dataset.

• Use os botões + e X para adicionar ou excluir uma linha da sua expressão. Não é possível excluir a primeira linha.

• Para novas linhas, use os operadores AND, IF ou OR no menu E para criar um encadeamento de condições.

  Para condições IF:

  • Cada expressão pode conter apenas um item IF. Se você remover uma condição IF, o Construtor de expressões removerá todas as condições AND subsequentes.

  • É possível usar condições IF para expressões filtradas por CurrentUser.

• Selecione o botão Adicionar expressão para adicionar outra expressão de filtro para realizar uma filtragem mais precisa. Cada expressão é avaliada primeiro de forma independente, e o resultado é uma união dos dois resultados.

  nota

  Para criar um filtro que use conjuntos de dados de itens e de interações com itens ou conjuntos de dados de ações ou de interações com ações, é necessário usar várias expressões.

Exemplo de construtor de expressão

O exemplo a seguir mostra como criar um filtro que exclui itens com um gênero que você especifica ao receber recomendações (observe o parâmetro de espaço reservado $GENRES). O filtro também exclui itens com DOWNLOAD_COUNT maior que 200, mas somente se a idade do usuário atual for maior que 17.

Como excluir um filtro (console)

Excluir um filtro o remove da lista de filtros de um grupo de conjuntos de dados.

Importante

Não é possível excluir um filtro enquanto um trabalho de inferência em lote está em andamento.

Para excluir um filtro (console)

1. Acesse https://console.aws.amazon.com/personalize/home para abrir o console do Amazon Personalize e faça login na sua conta.

2. Na lista Grupos de conjuntos de dados, escolha o grupo de conjuntos de dados que contém o filtro que você deseja excluir.

3. No painel de navegação, escolha Métricas.

4. Na lista de filtros, escolha o filtro que deseja excluir e depois Visualizar detalhes. A página de detalhes do filtro é exibida.

5. Escolha Excluir e confirme a exclusão na caixa de diálogo de confirmação.

Como filtrar recomendações em tempo real (AWS CLI)

Para filtrar recomendações usando o AWS CLI, você cria um filtro e o aplica especificando o ARN do filtro em GetRecommendations uma GetPersonalizedRanking solicitação or.

Importante

Para filtrar recomendações usando um filtro com parâmetros e uma campanha que você implantou antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a chamada a UpdateCampaign ou criar uma nova campanha.

Como criar um filtro (AWS CLI)

Use a operação create-filter a seguir para criar um filtro e especificar a expressão do filtro.

Substitua o Filter name pelo nome do filtro e Dataset group ARN pelo nome do recurso da Amazon (ARN) do grupo de conjuntos de dados. Substitua a amostra filter-expression por sua própria expressão de filtro.

aws personalize create-filter \
  --name Filter name \
  --dataset-group-arn dataset group arn \
  --filter-expression "EXCLUDE ItemID WHERE Items.CATEGORY IN (\"$CATEGORY\")" 

Se o processo for bem-sucedido, o ARN do filtro será exibido. Salve para uso posterior. Para verificar se o filtro está ativo, use a operação DescribeFilter antes de utilizar o filtro.

Para obter mais informações sobre a API, consulte CreateFilter. Para obter mais informações e exemplos sobre expressões de filtro, consulte Estrutura e elementos das expressões de filtro.

Como aplicar um filtro (AWS CLI)

Ao usar as operações get-recommendations, get-action-recommendations ou get-personalized-ranking, aplique um filtro enviando o filter-arn e todos os valores de filtro como parâmetros.

Confira a seguir um exemplo da operação get-recommendations. Substitua Campaign ARN pelo nome do recurso da Amazon (ARN) da sua campanha, User ID pelo ID do usuário para o qual você está recebendo recomendações e Filter ARN pelo ARN do seu filtro. Se você estiver recebendo recomendações de um recomendador em vez de uma campanha, use recommender-arn em vez de --campaign-arn e forneça o ARN para o recomendador.

Se sua expressão tiver algum parâmetro, inclua o objeto filter-values. Para cada parâmetro na sua expressão de filtro, forneça o nome do parâmetro (com distinção entre maiúsculas e minúsculas) e os valores. Por exemplo, se sua expressão tiver um parâmetro $GENRE, forneça "GENRE" como chave e um ou mais gêneros, por exemplo "Comedy", como o valor. Separe vários valores com uma vírgula. Por exemplo, "\"comedy\",\"drama\",\"horror"\".

Importante

Para expressões de filtro que usam um elemento INCLUDE para incluir itens, você deve fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usam um elemento EXCLUDE para excluir itens, você pode omitir filter-values. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.

aws personalize-runtime get-recommendations \
  --campaign-arn Campaign ARN \
  --user-id User ID \
  --filter-arn Filter ARN \
  --filter-values '{
      "Parameter name": "\"value\"",
      "Parameter name": "\"value1\",\"value2\",\"value3\""
    }'

Como excluir um filtro (AWS CLI)

Use a operação delete-filter a seguir para excluir um filtro. Substitua filter ARN pelo ARN do filtro.

aws personalize delete-filter --filter-arn Filter ARN

Filtrando recomendações em tempo real (AWS SDKs)

Para filtrar recomendações usando os AWS SDKs, você cria um filtro e o aplica especificando o ARN do filtro em uma solicitação or. GetRecommendations GetPersonalizedRanking

Importante

Para filtrar recomendações usando um filtro com parâmetros e uma campanha que você implantou antes de 10 de novembro de 2020, você deve reimplantar a campanha usando a chamada a UpdateCampaign ou criar uma nova campanha.

Criação de um filtro (AWS SDKs)

Crie um novo filtro com a operação CreateFilter. O código a seguir mostra como criar um filtro. Especifique o nome do filtro, nome do recurso da Amazon (ARN) do seu grupo de conjuntos de dados e forneça sua expressão de filtro.

SDK for Python (Boto3)

import boto3
 
personalize = boto3.client('personalize')
 
response = personalize.create_filter(
    name = 'Filter Name',
    datasetGroupArn = 'Dataset Group ARN',
    filterExpression = 'EXCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY)'
) 
filter_arn = response["filterArn"]
print("Filter ARN: " + filter_arn)

SDK for Java 2.x

public static String createFilter(PersonalizeClient personalizeClient,
                                 String filterName,
                                 String datasetGroupArn,
                                 String filterExpression) {
    try {
        CreateFilterRequest request = CreateFilterRequest.builder()
                .name(filterName)
                .datasetGroupArn(datasetGroupArn)
                .filterExpression(filterExpression)
                .build();

        return personalizeClient.createFilter(request).filterArn();
    }
    catch(PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
    return "";
}

SDK for JavaScript v3

// Get service clients module and commands using ES6 syntax.
import { CreateFilterCommand } from
  "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the filter's parameters.
export const createFilterParam = {
  datasetGroupArn: 'DATASET_GROUP_ARN', /* required */
  name: 'NAME', /* required */
  filterExpression: 'FILTER_EXPRESSION' /*required */
}

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

Registre o ARN do filtro para uso posterior. Para verificar se o filtro está ativo, use a operação DescribeFilter antes de utilizar o filtro. Para obter mais informações sobre a API, consulte CreateFilter. Para obter mais informações e exemplos sobre expressões de filtro, consulte Estrutura e elementos das expressões de filtro.

Aplicando um filtro (AWS SDKs)

Ao usar as GetPersonalizedRanking operações GetRecommendations GetActionRecommendations, ou, aplique um filtro passando um filterArn e quaisquer valores de filtro como parâmetros.

O código a seguir mostra como obter recomendações filtradas de itens do Amazon Personalize para um usuário. Especifique o ID do usuário para que você deseja obter recomendações, o nome do recurso da Amazon (ARN) da sua campanha e o ARN do seu filtro. Se você estiver recebendo recomendações de um recomendador em vez de uma campanha, use recommenderArn em vez de campaignArn e forneça o ARN para o recomendador.

Para cada filterValues em cada parâmetro opcional na sua expressão de filtro, forneça o nome do parâmetro (com distinção entre maiúsculas e minúsculas) e os valores. Por exemplo, se sua expressão tiver um parâmetro $GENRES, forneça "GENRES" como chave e um ou mais gêneros, por exemplo "\"Comedy"\", como o valor. Para usar vários valores, separe cada um deles com uma vírgula. Por exemplo, "\"comedy\",\"drama\",\"horror\"".

Importante

Para expressões de filtro que usam um elemento INCLUDE para incluir itens, você deve fornecer valores para todos os parâmetros definidos na expressão. Para filtros com expressões que usam um elemento EXCLUDE para excluir itens, você pode omitir filter-values. Nesse caso, o Amazon Personalize não usa essa parte da expressão para filtrar recomendações.

SDK for Python (Boto3)

import boto3

personalize_runtime = boto3.client("personalize-runtime")

response = personalize_runtime.get_recommendations(
    campaignArn = "Campaign ARN",
    userId = "User ID",
    filterArn = "Filter ARN",
    filterValues = {
      "Parameter name": "\"value1\"",
      "Parameter name": "\"value1\",\"value2\",\"value3\""
      ....
    }
)

SDK for Java 2.x

O exemplo a seguir usa dois parâmetros, um com dois valores e outro com um valor. Dependendo da sua expressão de filtro, modifique o código para adicionar ou remover os campos parameterName e parameterValue.

public static void getFilteredRecs(PersonalizeRuntimeClient personalizeRuntimeClient,
                                   String campaignArn,
                                   String userId,
                                   String filterArn,
                                   String parameter1Name,
                                   String parameter1Value1,
                                   String parameter1Value2,
                                   String parameter2Name,
                                   String parameter2Value){

    try {

        Map<String, String> filterValues = new HashMap<>();

        filterValues.put(parameter1Name, String.format("\"%1$s\",\"%2$s\"",
                parameter1Value1, parameter1Value2));
        filterValues.put(parameter2Name, String.format("\"%1$s\"",
                parameter2Value));

        GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
                .campaignArn(campaignArn)
                .numResults(20)
                .userId(userId)
                .filterArn(filterArn)
                .filterValues(filterValues)
                .build();

        GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient.getRecommendations(recommendationsRequest);
        List<PredictedItem> items = recommendationsResponse.itemList();

        for (PredictedItem item: items) {
            System.out.println("Item Id is : "+item.itemId());
            System.out.println("Item score is : "+item.score());
        }
    } catch (PersonalizeRuntimeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}

SDK for JavaScript v3

// Get service clients module and commands using ES6 syntax.
import { GetRecommendationsCommand } from
  "@aws-sdk/client-personalize-runtime";
import { personalizeRuntimeClient } from "./libs/personalizeClients.js";
// Or, create the client here:
// const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"});

// Set recommendation request parameters.
export const getRecommendationsParam = {
  campaignArn: 'CAMPAIGN_ARN', /* required */
  userId: 'USER_ID',      /* required */
  numResults: 15,    /* optional */
  filterArn: 'FILTER_ARN',   /* required to filter recommendations */
  filterValues: {
    "PROPERTY": "\"VALUE\""  /* Only required if your filter has a placeholder parameter */
  }
}

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

Excluindo um filtro (AWS Python SDK)

Use o método delete_filter a seguir para excluir um filtro. Substitua filter ARN pelo ARN do filtro.

import boto3
personalize = boto3.client("personalize")

response = personalize.delete_filter(
  filterArn = "filter ARN"
)