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á.
# Amazon Neptune ML para machine learning em grafos
Muitas vezes, há informações valiosas em grandes conjuntos de dados conectados que podem ser difíceis de extrair usando consultas baseadas apenas na intuição humana. As técnicas de machine learning (ML) podem ajudar a encontrar correlações ocultas em grafos com bilhões de relacionamentos. Essas correlações podem ser úteis para recomendar produtos, prever a capacidade de crédito, identificar fraudes e muitas outras coisas.
O atributo Neptune ML possibilita criar e treinar modelos úteis de machine learning úteis em grafos grandes em horas e não em semanas. [Para fazer isso, o Neptune ML usa a tecnologia de rede neural gráfica (GNN) desenvolvida pela [ SageMaker Amazon](https://aws.amazon.com/sagemaker/) AI e pela [Deep Graph Library (DGL) (que é de código aberto](https://www.dgl.ai/)).](https://github.com/dmlc/dgl/) As redes neurais de grafos são um campo emergente em inteligência artificial (consulte, por exemplo, [A Comprehensive Survey on Graph Neural Networks](https://arxiv.org/abs/1901.00596)). Para um tutorial prático sobre como usar GNNs com o DGL, consulte [Aprendendo redes neurais gráficas com a Deep Graph Library](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library).
**nota**
Os vértices do grafo são identificados nos modelos do Neptune ML como “nós”. Por exemplo, a classificação de vértices usa um modelo de machine learning de classificação de nós e a regressão de vértices usa um modelo de regressão de nós.
## O que o Neptune ML pode fazer
O Neptune é compatível tanto com a inferência transdutiva, que gera previsões que foram pré-calculadas no momento do treinamento, com base nos dados de grafos da época, quanto a inferência indutiva, que se aplica ao processamento de dados e à avaliação de modelos em tempo real, com base nos dados atuais. Consulte [A diferença entre inferência indutiva e transdutiva](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference).
O Neptune ML pode treinar modelos de machine learning para oferecer compatibilidade com cinco categorias diferentes de inferência:
**Tipos de tarefa de inferência atualmente compatíveis com o Neptune ML**
+ **Classificação de nós**: prevê o atributo categórico de uma propriedade de vértice.
Por exemplo, considerando-se o filme *Um Sonho de Liberdade*, o Neptune ML pode prever a propriedade `genre` como `story` partir de um conjunto candidato de `[story, crime, action, fantasy, drama, family, ...]`.
Há dois tipos de tarefas de classificação de nós:
+ **Classificação de classe única**: nesse tipo de tarefa, cada nó tem apenas um atributo de destino. Por exemplo, a propriedade, `Place_of_birth` de `Alan Turing` tem o valor `UK`.
+ **Classificação de várias classes**: nesse tipo de tarefa, cada nó pode ter mais de um atributo de destino. Por exemplo, a propriedade `genre` do filme *O Poderoso Chefão* tem os valores `crime` e `story`.
+ **Regressão de nós**: prevê uma propriedade numérica de um vértice.
Por exemplo, considerando-se o filme *Vingadores: Ultimato*, o Neptune ML pode prever que a propriedade `popularity` tem um valor de `5.0`.
+ **Classificação de bordas**: prevê o atributo categórico de uma propriedade de borda.
Há dois tipos de tarefas de classificação de bordas:
+ **Classificação de classe única**: nesse tipo de tarefa, cada borda tem apenas um atributo de destino. Por exemplo, uma borda de avaliação entre um usuário e um filme pode ter a propriedade `liked`, com um valor de “Sim” ou “Não”.
+ **Classificação de várias classes**: nesse tipo de tarefa, cada borda pode ter mais de um atributo de destino. Por exemplo, uma avaliação entre um usuário e um filme pode ter vários valores para a tag de propriedade, como “Engraçado”, “Emocionante”, “Assustador”, etc.
+ **Regressão de bordas**: prevê uma propriedade numérica de uma borda.
Por exemplo, uma borda de classificação entre um usuário e um filme pode ter a propriedade numérica `score` para a qual o Neptune ML pode prever um valor considerando-se a um usuário e um filme.
+ **Previsão de links**: prevê os nós de destino mais prováveis para um nó de origem e uma borda de saída específicos, ou os nós de origem mais prováveis para um nó de destino e uma borda de entrada específicos.
Por exemplo, com um grafo de conhecimento sobre medicamentos e doenças, fornecidos `Aspirin` como o nó de origem e `treats` como a borda de saída, o Neptune ML pode prever os nós de destino mais relevantes como `heart disease`, `fever`, etc.
Ou, com o gráfico de conhecimento da Wikimedia, fornecidos `President-of` como borda ou relação e `United-States` como nó de destino, o Neptune ML pode prever os presidentes mais relevantes como `George Washington`, `Abraham Lincoln`, `Franklin D. Roosevelt`, etc.
**nota**
A classificação de nós e a classificação de bordas são compatíveis somente com valores de string. Isso significa que valores de propriedades numéricas, como `0` ou `1`, não são compatíveis, embora a string seja equivalente a `"0"` e `"1"`. Da mesma forma, os valores de propriedade booliana `true` e `false` não funcionam, mas `"true"` e `"false"` funcionam.
Com o Neptune ML, é possível usar modelos de machine learning que se enquadram em duas categorias gerais:
**Tipos de modelo de machine learning no momento compatíveis com o Neptune ML**
+ **Modelos de rede neural gráfica (GNN)** — incluem [redes convolucionais de grafos relacionais (](https://arxiv.org/abs/1703.06103)R-). GCNs Os modelos de GNN funcionam para todos os três tipos de tarefa acima.
+ **Modelos Knowledge-Graph Embedding (KGE)**: incluem modelos `TransE`, `DistMult` e `RotatE`. Eles só funcionam para previsão de links.
**Modelos definidos pelo usuário**: o Neptune ML também permite que você forneça sua própria implementação de modelos personalizados para todos os tipos de tarefas listados acima. Você pode usar o [kit de ferramentas do Neptune ML](https://github.com/awslabs/neptuneml-toolkit) para desenvolver e testar a implementação de modelos personalizados baseados em python antes de usar a API de treinamento do Neptune ML com o modelo. Consulte [Modelos personalizados no Neptune ML](machine-learning-custom-models.md) para obter detalhes sobre como estruturar e organizar a implementação para que ela seja compatível com a infraestrutura de treinamento do Neptune ML.
# Configurar o Neptune ML
A maneira mais fácil de começar a usar o Neptune ML é [usar CloudFormation o modelo de início rápido](machine-learning-quick-start.md). Esse modelo instala todos os componentes necessários, incluindo um novo cluster de banco de dados do Neptune, todos os perfis necessários do IAM e um novo bloco de anotações de grafos do Neptune para facilitar o trabalho com o Neptune ML.
Você também pode instalar o Neptune ML manualmente, conforme explicado em [Configurando o Neptune ML sem usar o modelo de início rápido CloudFormation](machine-learning-manual-setup.md).
# Usar o modelo AWS CloudFormation do Neptune ML para começar rapidamente em um novo cluster de banco de dados
A maneira mais fácil de começar a usar o Neptune ML é usar o modelo de início rápido do CloudFormation. Esse modelo instala todos os componentes necessários, incluindo um novo cluster de banco de dados do Neptune, todos os perfis necessários do IAM e um novo bloco de anotações de grafos do Neptune para facilitar o trabalho com o Neptune ML.
**Como criar a pilha de início rápido do Neptune ML**
1. Para iniciar a pilha do CloudFormation no console do CloudFormation, selecione um dos botões **Iniciar pilha** na seguinte tabela:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/machine-learning-quick-start.html)
1. Na página **Select Template**, escolha **Next**.
1. Na página **Specify Details (Especificar detalhes)**, escolha **Next (Próximo)**.
1. Na página **Options (Opções)**, escolha **Next (Avançar)**.
1. Na página **Revisar**, há duas caixas de seleção que você precisa marcar:
+ A primeira confirma que o AWS CloudFormation pode criar recursos do IAM com nomes personalizados.
+ A segunda confirma que o AWS CloudFormation pode exigir a capacidade `CAPABILITY_AUTO_EXPAND` para a nova pilha. O `CAPABILITY_AUTO_EXPAND` permite explicitamente que o CloudFormation expanda macros automaticamente ao criar a pilha, sem revisão prévia.
Os clientes geralmente criam um conjunto de alterações a partir de um modelo processado para que as alterações feitas pelos macros possam ser revisadas antes de criar a pilha. Para obter mais informações, consulte a API [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) do CloudFormation.
Escolha **Criar**.
O modelo de início rápido cria e configura o seguinte:
+ Um cluster de banco de dados do Neptune
+ Os perfis necessários do IAM (e os anexa).
+ O grupo de segurança necessário do Amazon EC2.
+ Os endpoints da VPC do SageMaker AI necessários.
+ Um grupo de parâmetros de cluster de banco de dados para Neptune ML.
+ Os parâmetros necessários nesse grupo de parâmetros.
+ Um bloco de anotações do SageMaker AI com exemplos de bloco de anotações preenchidos previamente para o Neptune ML. Observe que nem todos os tamanhos de instância estão disponíveis em todas as regiões, então você precisa ter certeza de que o tamanho de instância do bloco de anotações selecionado é compatível com sua região.
+ O serviço Neptune-Export.
Quando a pilha de início rápido estiver pronta, acesse o bloco de anotações do SageMaker AI criado pelo modelo e confira os exemplos preenchidos previamente. Eles ajudarão você a baixar exemplos de conjunto de dados para usar na experimentação dos recursos do Neptune ML.
Eles também podem proporcionar uma grande economia de tempo ao usar o Neptune ML. Por exemplo, veja a magia de linha [%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml) e a magia de célula [%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml) compatíveis com esses blocos de anotações.
Você também pode usar o seguinte comando AWS CLI para executar o modelo de início rápido CloudFormation:
```
aws cloudformation create-stack \
--stack-name neptune-ml-fullstack-$(date '+%Y-%m-%d-%H-%M') \
--template-url https://aws-neptune-customer-samples.s3.amazonaws.com/v2/cloudformation-templates/neptune-ml-nested-stack.json \
--parameters ParameterKey=EnableIAMAuthOnExportAPI,ParameterValue=(true if you have IAM auth enabled, or false otherwise) \
ParameterKey=Env,ParameterValue=test$(date '+%H%M')\
--capabilities CAPABILITY_IAM \
--region (the AWS region, like us-east-1) \
--disable-rollback \
--profile (optionally, a named CLI profile of yours)
```
# Configurando o Neptune ML sem usar o modelo de início rápido CloudFormation
Este guia fornece step-by-step instruções para configurar o Amazon Neptune ML sem usar AWS CloudFormation o modelo de início rápido. Ele pressupõe que você já tem um cluster de banco de dados do Neptune em funcionamento e abrange a configuração necessária, incluindo a instalação do serviço Neptune-Export, a criação de perfis do IAM personalizados e a configuração do cluster de banco de dados para habilitar o Neptune ML. O guia também explica como criar dois endpoints de SageMaker IA em sua VPC Neptune para dar ao Neptune Engine acesso ao gerenciamento de IA necessário. SageMaker APIs Seguindo essas instruções, você pode configurar o Neptune ML em sua infraestrutura existente do Neptune sem depender do modelo. CloudFormation
## Começar com um cluster de banco de dados do Neptune funcional
Se você não usar o modelo de CloudFormation início rápido para configurar o Neptune ML, precisará de um cluster de banco de dados Neptune existente com o qual trabalhar. Se quiser, poderá usar um existente, clonar um que você já esteja usando ou criar outro (consulte [Criar cluster do Neptune](get-started-create-cluster.md)).
## Instalar o serviço Neptune-Export
Se você ainda não o fez, instale o serviço Neptune Export, conforme explicado em [Usar o serviço Neptune-Export para exportar dados do Neptune](export-service.md).
Adicione uma regra de entrada ao grupo de segurança `NeptuneExportSecurityGroup` criado pela instalação, com as seguintes configurações:
+ *Digite*: `Custom TCP`
+ *Protocolo:* `TCP`
+ *Intervalo de portas*: `80 - 443`
+ *Origem*: *(Neptune DB cluster security group ID)*
## Crie uma função personalizada NeptuneLoadFrom do S3 IAM
Se você ainda não o fez, crie um perfil do IAM `NeptuneLoadFromS3` personalizado, conforme explicado em [Criar um perfil do IAM para acessar o Amazon S3](bulk-load-tutorial-IAM-CreateRole.md).
## Crie um NeptuneSageMaker IAMRole papel personalizado
Use o [console do IAM](https://console.aws.amazon.com/iam/) para criar um `NeptuneSageMakerIAMRole` personalizado, usando a seguinte política:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:CreateVpcEndpoint",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DescribeDhcpOptions",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcEndpoints",
"ec2:DescribeVpcs"
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"ecr:GetAuthorizationToken",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::*:role/*"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"sagemaker.amazonaws.com"
]
}
},
"Effect": "Allow"
},
{
"Action": [
"kms:CreateGrant",
"kms:Decrypt",
"kms:GenerateDataKey*"
],
"Resource": "arn:aws:kms:*:*:key/*",
"Effect": "Allow"
},
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents"
],
"Resource": [
"arn:aws:logs:*:*:log-group:/aws/sagemaker/*"
],
"Effect": "Allow"
},
{
"Action": [
"sagemaker:AddTags",
"sagemaker:CreateEndpoint",
"sagemaker:CreateEndpointConfig",
"sagemaker:CreateHyperParameterTuningJob",
"sagemaker:CreateModel",
"sagemaker:CreateProcessingJob",
"sagemaker:CreateTrainingJob",
"sagemaker:CreateTransformJob",
"sagemaker:DeleteEndpoint",
"sagemaker:DeleteEndpointConfig",
"sagemaker:DeleteModel",
"sagemaker:DescribeEndpoint",
"sagemaker:DescribeEndpointConfig",
"sagemaker:DescribeHyperParameterTuningJob",
"sagemaker:DescribeModel",
"sagemaker:DescribeProcessingJob",
"sagemaker:DescribeTrainingJob",
"sagemaker:DescribeTransformJob",
"sagemaker:InvokeEndpoint",
"sagemaker:ListTags",
"sagemaker:ListTrainingJobsForHyperParameterTuningJob",
"sagemaker:StopHyperParameterTuningJob",
"sagemaker:StopProcessingJob",
"sagemaker:StopTrainingJob",
"sagemaker:StopTransformJob",
"sagemaker:UpdateEndpoint",
"sagemaker:UpdateEndpointWeightsAndCapacities"
],
"Resource": [
"arn:aws:sagemaker:*:*:*"
],
"Effect": "Allow"
},
{
"Action": [
"sagemaker:ListEndpointConfigs",
"sagemaker:ListEndpoints",
"sagemaker:ListHyperParameterTuningJobs",
"sagemaker:ListModels",
"sagemaker:ListProcessingJobs",
"sagemaker:ListTrainingJobs",
"sagemaker:ListTransformJobs"
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::*"
],
"Effect": "Allow"
}
]
}
```
------
Ao criar esse perfil, edite o relacionamento de confiança da seguinte forma:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"ec2.amazonaws.com",
"rds.amazonaws.com",
"sagemaker.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Por fim, copie o ARN atribuído a esse novo perfil `NeptuneSageMakerIAMRole`.
**Importante**
Garanta que as permissões do Amazon S3 no `NeptuneSageMakerIAMRole` correspondam às indicadas acima.
O ARN universal, `arn:aws:s3:::*`, é usado para o recurso do Amazon S3 na política acima. Se, por algum motivo, o ARN universal não puder ser usado, o `arn:aws:s3:::graphlytics*` e o ARN de qualquer outro recurso do Amazon S3 do cliente que os comandos do NeptuneML usarão deverá ser adicionado à seção de recursos.
## Configurar o cluster de banco de dados do para habilitar o Neptune ML
**Como configurar o cluster de banco de dados do Neptune ML**
1. No [console do Neptune](https://console.aws.amazon.com/neptune), acesse **Grupos de parâmetros** e, depois, o grupo de parâmetros do cluster de banco de dados associado ao cluster de banco de dados que você usará. Defina o parâmetro `neptune_ml_iam_role` como o ARN atribuído ao perfil `NeptuneSageMakerIAMRole` que você acabou de criar.
1. Navegue até Bancos de dados e, depois, selecione o cluster de banco de dados que você usará para o Neptune ML. Selecione **Ações** e, depois, **Gerenciar perfis do IAM**.
1. Na página **Gerenciar perfis do IAM**, selecione **Adicionar perfil** e adicione o `NeptuneSageMakerIAMRole`. Depois, adicione o perfil `NeptuneLoadFromS3`.
1. Reinicialize a instância de gravador do cluster de banco de dados.
## Crie dois endpoints de SageMaker IA em sua VPC Neptune
Por fim, para permitir que o Neptune Engine acesse o APIs gerenciamento de IA SageMaker necessário, você precisa criar SageMaker dois endpoints de IA em sua VPC Neptune, conforme explicado em. [Crie dois endpoints para SageMaker IA em sua VPC Neptune](machine-learning-cluster-setup.md#machine-learning-sm-endpoints)
# Configurar manualmente um bloco de anotações Neptune para o Neptune ML
Os notebooks SageMaker Neptune AI vêm pré-carregados com uma variedade de notebooks de amostra para o Neptune ML. Você pode visualizar essas amostras no repositório de [cadernos gráficos de GitHub código aberto](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning).
É possível usar um dos blocos de anotações Neptune existentes ou, se quiser, criar um de sua preferência, seguindo as instruções em [Usar a bancada de trabalho do Neptune para hospedar blocos de anotações Neptune](graph-notebooks.md#graph-notebooks-workbench).
Você também pode configurar um bloco de anotações Neptune padrão para uso com o Neptune ML seguindo estas etapas:
**Modificar um bloco de anotações para o Neptune ML**
1. Abra o console do Amazon SageMaker AI em [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/).
1. No painel de navegação à esquerda, selecione **Bloco de anotações** e, depois, **Instâncias do bloco de anotações**. Procure o nome do bloco de anotações Neptune que você gostaria de usar para o Neptune ML e selecione-o para acessar a página de detalhes.
1. Se a instância do bloco de anotações estiver em execução, selecione o botão **Interromper**, no canto superior direito da página de detalhes do bloco de anotações.
1. Nas **Configurações da instância do bloco de anotações**, em **Configuração do ciclo de vida**, selecione o link para abrir a página do ciclo de vida do bloco de anotações.
1. Selecione **Editar** no canto superior direito e, depois, **Continuar**.
1. Na guia **Iniciar bloco de anotações**, modifique o script para incluir comandos de exportação adicionais e preencher os campos do perfil do IAM do Neptune ML e o URI do serviço de exportação, algo parecido com o seguinte, dependendo do shell:
```
echo "export NEPTUNE_ML_ROLE_ARN=(your Neptune ML IAM role ARN)" >> ~/.bashrc
echo "export NEPTUNE_EXPORT_API_URI=(your export service URI)" >> ~/.bashrc
```
1. Selecione **Atualizar**.
1. Volte para a página da instância do bloco de anotações. Em **Permissões e criptografia**, há um campo para o **ARN do perfil do IAM**. Selecione o link nesse campo para acessar o perfil do IAM com o qual essa instância de bloco de anotações é executada.
1. Crie uma política em linha como esta:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"cloudwatch:PutMetricData"
],
"Resource": "arn:aws:cloudwatch:us-east-1:111122223333:*",
"Sid": "AllowPutMetrics",
"Effect": "Allow"
},
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:GetLogEvents"
],
"Resource": "arn:aws:logs:us-east-1:111122223333:*",
"Sid": "AllowCreateLogs",
"Effect": "Allow"
},
{
"Action": [
"s3:Put*",
"s3:Get*",
"s3:List*"
],
"Resource": "arn:aws:s3:::*",
"Sid": "AllowS3Actions",
"Effect": "Allow"
},
{
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111122223333:*/*",
"Sid": "AllowExecute",
"Effect": "Allow"
},
{
"Action": [
"sagemaker:CreateModel",
"sagemaker:CreateEndpointConfig",
"sagemaker:CreateEndpoint",
"sagemaker:DescribeModel",
"sagemaker:DescribeEndpointConfig",
"sagemaker:DescribeEndpoint",
"sagemaker:DeleteModel",
"sagemaker:DeleteEndpointConfig",
"sagemaker:DeleteEndpoint"
],
"Resource": "arn:aws:sagemaker:us-east-1:111122223333:*/*",
"Sid": "AllowApiActions",
"Effect": "Allow"
},
{
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/role-name",
"Sid": "AllowPassRole",
"Effect": "Allow"
}
]
}
```
------
1. Salve essa nova política e anexe-a ao perfil do IAM na etapa 8.
1. Selecione **Iniciar** no canto superior direito da página de detalhes da instância do notebook SageMaker AI para iniciar a instância do notebook.
# Usando o AWS CLI para configurar o Neptune ML em um cluster de banco de dados
Além do modelo de CloudFormation início rápido e do Console de gerenciamento da AWS, você também pode configurar o Neptune ML usando o. AWS CLI
## Criar um grupo de parâmetros de cluster de banco de dados para o novo cluster do Neptune ML
Os AWS CLI comandos a seguir criam um novo grupo de parâmetros do cluster de banco de dados e o configuram para funcionar com o Neptune ML:
**Como criar e configurar um grupo de parâmetros de cluster de banco de dados para o Neptune ML**
1. Crie um grupo de parâmetros de cluster de banco de dados:
```
aws neptune create-db-cluster-parameter-group \
--db-cluster-parameter-group-name (name of the new DB cluster parameter group) \
--db-parameter-group-family neptune1
--description "(description of your machine learning project)" \
--region (AWS region, such as us-east-1)
```
1. Crie um parâmetro de `neptune_ml_iam_role` cluster de banco de dados definido como o ARN do `SageMakerExcecutionIAMRole` para seu cluster de banco de dados usar ao chamar a SageMaker IA para criar trabalhos e obter previsões de modelos de ML hospedados:
```
aws neptune modify-db-cluster-parameter-group \
--db-cluster-parameter-group-name (name of the new DB cluster parameter group) \
--parameters "ParameterName=neptune_ml_iam_role, \
ParameterValue=ARN of the SageMakerExcecutionIAMRole, \
Description=NeptuneMLRole, \
ApplyMethod=pending-reboot" \
--region (AWS region, such as us-east-1)
```
Definir esse parâmetro permite que o Neptune SageMaker acesse a IA sem que você precise passar a função a cada chamada.
Para obter informações sobre como criar o `SageMakerExcecutionIAMRole`, consulte [Crie um NeptuneSageMaker IAMRole papel personalizado](machine-learning-manual-setup.md#ml-manual-setup-sm-role).
1. Por fim, use `describe-db-cluster-parameters` para conferir se todos os parâmetros no novo grupo de parâmetros do cluster de banco de dados estão definidos da forma desejada:
```
aws neptune describe-db-cluster-parameters \
--db-cluster-parameter-group-name (name of the new DB cluster parameter group) \
--region (AWS region, such as us-east-1)
```
## Anexar o novo grupo de parâmetros de cluster de banco de dados ao cluster de banco de dados a ser usado com o Neptune ML
Agora é possível anexar o novo grupo de parâmetros do cluster de banco de dados que você acabou de criar a um cluster de banco de dados existente usando o seguinte comando:
```
aws neptune modify-db-cluster \
--db-cluster-identifier (the name of your existing DB cluster) \
--apply-immediately
--db-cluster-parameter-group-name (name of your new DB cluster parameter group) \
--region (AWS region, such as us-east-1)
```
Para tornar todos os parâmetros efetivos, você pode então reinicializar o cluster de banco de dados:
```
aws neptune reboot-db-instance
--db-instance-identifier (name of the primary instance of your DB cluster) \
--profile (name of your AWS profile to use) \
--region (AWS region, such as us-east-1)
```
Ou, se estiver criando um cluster de banco de dados para usar com o Neptune ML, você poderá usar o seguinte comando para criar o cluster com o novo grupo de parâmetros anexado e, depois, criar uma instância principal (de gravador):
```
cluster-name=(the name of the new DB cluster)
aws neptune create-db-cluster
--db-cluster-identifier ${cluster-name}
--engine graphdb \
--engine-version 1.0.4.1 \
--db-cluster-parameter-group-name (name of your new DB cluster parameter group) \
--db-subnet-group-name (name of the subnet to use) \
--region (AWS region, such as us-east-1)
aws neptune create-db-instance
--db-cluster-identifier ${cluster-name}
--db-instance-identifier ${cluster-name}-i \
--db-instance-class (the instance class to use, such as db.r5.xlarge)
--engine graphdb \
--region (AWS region, such as us-east-1)
```
## Anexe o `NeptuneSageMakerIAMRole` ao seu cluster de banco de dados para que ele possa acessar os recursos de SageMaker IA e Amazon S3
Por fim, siga as instruções [Crie um NeptuneSageMaker IAMRole papel personalizado](machine-learning-manual-setup.md#ml-manual-setup-sm-role) para criar uma função do IAM que permitirá que seu cluster de banco de dados se comunique com a SageMaker IA e o Amazon S3. Depois, use o seguinte comando para anexar o perfil `NeptuneSageMakerIAMRole` que você criou ao cluster de banco de dados:
```
aws neptune add-role-to-db-cluster
--db-cluster-identifier ${cluster-name}
--role-arn arn:aws:iam::(the ARN number of the role's ARN):role/NeptuneMLRole \
--region (AWS region, such as us-east-1)
```
## Crie dois endpoints para SageMaker IA em sua VPC Neptune
O Neptune ML precisa de SageMaker dois endpoints de IA na VPC do seu cluster de banco de dados Neptune:
+ `com.amazonaws.(AWS region, like us-east-1).sagemaker.runtime`
+ `com.amazonaws.(AWS region, like us-east-1).sagemaker.api`
Se você não usou o CloudFormation modelo de início rápido, que os cria automaticamente para você, você pode usar os seguintes AWS CLI comandos para criá-los:
Este cria o endpoint `sagemaker.runtime`:
```
aws ec2 create-vpc-endpoint
--vpc-id (the ID of your Neptune DB cluster's VPC)
--vpc-endpoint-type Interface
--service-name com.amazonaws.(AWS region, like us-east-1).sagemaker.runtime
--subnet-ids (the subnet ID or IDs that you want to use)
--security-group-ids (the security group for the endpoint network interface, or omit to use the default)
--private-dns-enabled
```
E este cria o endpoint `sagemaker.api`:
```
aws ec2 create-vpc-endpoint
--vpc-id (the ID of your Neptune DB cluster's VPC)
--vpc-endpoint-type Interface
--service-name com.amazonaws.(AWS region, like us-east-1).sagemaker.api
--subnet-ids (the subnet ID or IDs that you want to use)
--security-group-ids (the security group for the endpoint network interface, or omit to use the default)
--private-dns-enabled
```
Você também pode usar o [console da VPC](https://console.aws.amazon.com/vpc/) para criar esses endpoints. Consulte [Chamadas de previsão seguras na Amazon SageMaker com AWS PrivateLink](https://aws.amazon.com/blogs/machine-learning/secure-prediction-calls-in-amazon-sagemaker-with-aws-privatelink/) e [Protegendo todas as chamadas de SageMaker API da Amazon com AWS PrivateLink](https://aws.amazon.com/blogs/machine-learning/securing-all-amazon-sagemaker-api-calls-with-aws-privatelink/).
## Crie um parâmetro de endpoint de inferência de SageMaker IA em seu grupo de parâmetros do cluster de banco de dados
Para evitar a necessidade de especificar o endpoint de inferência de SageMaker IA do modelo que você está usando em cada consulta que você faz a ele, crie um parâmetro de cluster de banco de dados chamado `neptune_ml_endpoint` no grupo de parâmetros do cluster de banco de dados para o Neptune ML. Defina o parâmetro como o `id` do endpoint da instância em questão.
Você pode usar o seguinte AWS CLI comando para fazer isso:
```
aws neptune modify-db-cluster-parameter-group \
--db-cluster-parameter-group-name neptune-ml-demo \
--parameters "ParameterName=neptune_ml_endpoint, \
ParameterValue=(the name of the SageMaker AI inference endpoint you want to query), \
Description=NeptuneMLEndpoint, \
ApplyMethod=pending-reboot" \
--region (AWS region, such as us-east-1)
```
# Visão geral de como usar o atributo Neptune ML
O recurso do Neptune ML no Amazon Neptune fornece um fluxo de trabalho simplificado para aproveitar modelos de machine learning em um banco de dados de grafos. O processo envolve várias etapas essenciais: exportar dados do Neptune para o formato CSV, pré-processar os dados para prepará-los para o treinamento de modelo, treinar o modelo de machine learning usando o Amazon SageMaker AI, criar um endpoint de inferência para fornecer previsões e, em seguida, consultar o modelo diretamente das consultas do Gremlin. A bancada de trabalho do Neptune fornece comandos mágicos de linha e célula convenientes para ajudar a gerenciar e automatizar essas etapas. Ao integrar os recursos de machine learning diretamente ao banco de dados de grafos, o Neptune ML permite que os usuários obtenham informações valiosas e façam previsões usando os ricos dados relacionais armazenados no grafo do Neptune.
## Iniciar o fluxo de trabalho para usar o Neptune ML
O uso do atributo Neptune ML no Amazon Neptune geralmente envolve estas cinco etapas para começar:
![\[Diagrama do fluxo de trabalho do Neptune ML\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/images/neptune-ML-workflow.png)
1. **Exportação e configuração de dados**: a etapa de exportação de dados usa o serviço Neptune-Export ou a ferramenta de linha de comando `neptune-export` para exportar dados do Neptune para o Amazon Simple Storage Service (Amazon S3) em formato CSV. Um arquivo de configuração chamado `training-data-configuration.json` é gerado automaticamente ao mesmo tempo, o que especifica como os dados exportados podem ser carregados em um grafo treinável.
1. **Pré-processamento de dados**: nessa etapa, o conjunto de dados exportado é pré-processado usando técnicas padrão para prepará-lo para o treinamento de modelos. A normalização de atributos pode ser realizada para dados numéricos e os atributos de texto podem ser codificados usando `word2vec`. No final dessa etapa, um grafo DGL (biblioteca Deep Graph) é gerado a partir do conjunto de dados exportado para uso na etapa de treinamento de modelos.
Essa etapa é implementada usando um trabalho de processamento do SageMaker AI na conta, e os dados resultantes são armazenados em um local do Amazon S3 especificado.
1. **Treinamento de modelos**: a etapa de treinamento de modelos treina o modelo de machine learning que será usado para previsões.
O treinamento de modelos é realizado em duas etapas:
+ A primeira etapa usa uma tarefa de processamento do SageMaker AI para gerar um conjunto de configurações da estratégia de treinamento de modelos que especifique o tipo de modelo e intervalos de hiperparâmetros que serão usados para o treinamento de modelos.
+ Depois, a segunda fase usa uma tarefa de ajuste de modelos do SageMaker AI para testar diferentes configurações de hiperparâmetros e selecionar a tarefa de treinamento que produziu o modelo com melhor desempenho. O trabalho de ajuste executa um número pré-especificado de testes de trabalho de treinamento de modelos nos dados processados. No final dessa etapa, os parâmetros do modelo treinado do melhor trabalho de treinamento são usados para gerar artefatos de modelo para inferência.
1. **Criar um endpoint de inferência no Amazon SageMaker AI**: o endpoint de inferência é uma instância de endpoint do SageMaker AI que é lançada com os artefatos do modelo produzidos pela melhor tarefa de treinamento. Cada modelo é vinculado a um único endpoint. O endpoint pode aceitar solicitações recebidas do banco de dados de grafos e exibir as previsões do modelo para entradas nas solicitações. Depois de criar o endpoint, ele permanece ativo até que você o exclua.
1. **Consulta ao modelo de machine learning usando o Gremlin**: é possível usar extensões à linguagem de consulta Gremlin para consultar previsões por meio do endpoint de inferência.
**nota**
A [bancada de trabalho do Neptune](graph-notebooks.md#graph-notebooks-workbench) contém uma magia de linha e uma magia de célula que podem proporcionar uma grande economia de tempo no gerenciamento dessas etapas, ou seja:
[%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml)
[%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml)
# Fazendo previsões com base na evolução dos dados de grafos.
Com um grafo em constante mudança, convém criar previsões em lote periodicamente usando dados novos. Consultar previsões pré-calculadas (inferência transdutiva) pode ser significativamente mais rápido do que gerar novas previsões em tempo real com base nos dados mais recentes (inferência indutiva). As duas abordagens têm sua utilidade, dependendo da rapidez com que os dados mudam e dos requisitos de desempenho.
## A diferença entre inferência indutiva e transdutiva
Ao realizar inferência transdutiva, o Neptune pesquisa e exibe previsões que foram pré-calculadas no momento do treinamento.
Ao realizar inferência indutiva, o Neptune cria o subgrafo relevante e busca as respectivas propriedades. O modelo DGL GNN então aplica o processamento de dados e a avaliação do modelo em tempo real.
Portanto, a inferência indutiva pode gerar previsões envolvendo nós e bordas que não estavam presentes no momento do treinamento e que refletem o estado atual do grafo. No entanto, isso ocorre à custa de uma maior latência.
Se o grafo for dinâmico, será conveniente usar a inferência indutiva para levar em conta os dados mais recentes, mas se o grafo for estático, a inferência transdutiva será mais rápida e eficiente.
A inferência indutiva é desabilitada por padrão. É possível habilitá-la para uma consulta usando o predicado [Neptune\$1ml.inductiveInference](machine-learning-gremlin-inference-query-predicates.md#machine-learning-gremlin-inference-neptune-ml-inductiveInference) do Gremlin na consulta da seguinte forma:
```
.with( "Neptune#ml.inductiveInference")
```
# Fluxos transdutivos incrementais
Embora você atualize os artefatos do modelo simplesmente executando novamente as etapas de um a três (da **Exportação e configuração de dados** à **Transformação de modelos**), o Neptune ML aceita maneiras mais simples de atualizar as previsões de ML em lote usando novos dados. Uma delas é usar um [fluxo de trabalho de modelo incremental](#machine-learning-overview-incremental) e outra é usar o [novo treinamento de modelos com uma inicialização a quente](#machine-learning-overview-model-retraining).
## Fluxo de trabalho de modelo incremental
Nesse fluxo de trabalho, você atualiza as previsões de ML sem treinar o modelo de ML novamente.
**nota**
Você só poderá fazer isso quando os dados do grafo tiverem sido atualizados com novos nós e/ou bordas. No momento, ele não funcionará quando os nós forem removidos.
1. **Exportação e configuração de dados**: essa etapa é a mesma do fluxo de trabalho principal.
1. **Pré-processamento incremental de dados**: essa etapa é semelhante à etapa de pré-processamento de dados no fluxo de trabalho principal, mas usa a mesma configuração de processamento usada anteriormente, que corresponde a um modelo treinado específico.
1. **Transformação de modelos**: em vez de uma etapa de treinamento do modelo, essa etapa de transformação de modelos retira o modelo treinado do fluxo de trabalho principal e dos resultados da etapa de pré-processamento incremental de dados e gera novos artefatos do modelo para uso na inferência. A etapa de transformação de modelos inicia uma tarefa de processamento do SageMaker AI para realizar o cálculo que gera os artefatos atualizados do modelo.
1. **Atualizar o endpoint de inferência do Amazon SageMaker AI**: opcionalmente, se você tiver um endpoint de inferência existente, essa etapa atualizará o endpoint com os novos artefatos do modelo gerados pela etapa de transformação de modelos. Como alternativa, você também pode criar um endpoint de inferência com os novos artefatos do modelo.
## Novo treinamento de modelos com uma inicialização a quente
Usando esse fluxo de trabalho, é possível treinar e implantar um novo modelo de ML para fazer previsões usando os dados de grafos incrementais, mas comece com um modelo existente gerado usando o fluxo de trabalho principal:
1. **Exportação e configuração de dados**: essa etapa é a mesma do fluxo de trabalho principal.
1. **Pré-processamento incremental de dados**: essa etapa é a mesma do fluxo de trabalho de inferência de modelo incremental. Os novos dados de grafos devem ser processados com o mesmo método de processamento usado anteriormente para o treinamento de modelos.
1. **Treinamento de modelos com inicialização a quente**: o treinamento de modelos é semelhante ao que acontece no fluxo de trabalho principal, mas é possível acelerar a pesquisa de hiperparâmetros do modelo aproveitando as informações da tarefa anterior de treinamento do modelo.
1. **Atualizar o endpoint de inferência do Amazon SageMaker AI**: essa etapa é a mesma do fluxo de trabalho de inferência do modelo incremental.
# Fluxos de trabalho para modelos personalizados no Neptune ML
O Neptune ML permite implementar, treinar e implantar os próprios modelos personalizados para qualquer uma das tarefas compatíveis com o Neptune ML. O fluxo de trabalho para desenvolver e implantar um modelo personalizado é essencialmente o mesmo dos modelos integrados, com algumas diferenças, conforme explicado em [Fluxo de trabalho de modelos personalizados](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow).
# Seleção de instâncias para os estágios do Neptune ML
Os diferentes estágios do processamento do Neptune ML usam diferentes instâncias do SageMaker AI. Aqui, abordamos como escolher o tipo de instância correto para cada estágio. É possível encontrar informações sobre os tipos e preços de instâncias do SageMaker AI em [Preço do Amazon SageMaker](https://aws.amazon.com/sagemaker/pricing/).
## Selecionar uma instância para processamento de dados
A etapa de [processamento de dados](machine-learning-on-graphs-processing.md) do SageMaker AI requer uma [instância de processamento](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) que tenha memória e armazenamento em disco suficientes para os dados de entrada, intermediários e de saída. A quantidade específica de memória e armazenamento em disco necessária depende das características do grafo do Neptune ML e de os respectivos atributos exportados.
Por padrão, o Neptune ML escolhe a menor instância `ml.r5` cuja memória é dez vezes maior que o tamanho dos dados de grafos exportados no disco.
## Selecionar uma instância para treinamento e transformação de modelos
Selecionar o tipo de instância certo para [treinamento de modelos](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html) ou [transformação de modelos](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-batch.html) depende do tipo de tarefa, do tamanho do grafo e dos requisitos de entrega. As instâncias de GPU oferecem o melhor desempenho. Geralmente, recomendamos instâncias seriais `p3` e `g4dn`. Também é possível usar instâncias `p2` ou `p4d`.
Por padrão, o Neptune ML escolhe a menor instância de GPU com mais memória do que o treinamento e a transformação de modelos exigem. É possível encontrar qual é essa seleção no arquivo `train_instance_recommendation.json`, no local de saída do processamento de dados do Amazon S3. Veja um exemplo do conteúdo de um arquivo `train_instance_recommendation.json`:
```
{
"instance": "(the recommended instance type for model training and transform)",
"cpu_instance": "(the recommended instance type for base processing instance)",
"disk_size": "(the estimated disk space required)",
"mem_size": "(the estimated memory required)"
}
```
## Selecionar uma instância para um endpoint de inferência
Selecionar o tipo de instância certo para um [endpoint de inferência](machine-learning-on-graphs-inference-endpoint.md) depende do tipo de tarefa, do tamanho do grafo e do seu orçamento. Por padrão, o Neptune ML escolhe a menor instância `ml.m5d` com mais memória do que o endpoint de inferência exige.
**nota**
Se forem necessários mais de 384 GB de memória, o Neptune ML usará uma instância `ml.r5d.24xlarge`.
É possível ver qual tipo de instância o Neptune ML recomenda no arquivo `infer_instance_recommendation.json` presente na localização do Amazon S3 que você está usando para treinamento de modelos. Veja uma amostra do conteúdo desse arquivo:
```
{
"instance" : "(the recommended instance type for an inference endpoint)",
"disk_size" : "(the estimated disk space required)",
"mem_size" : "(the estimated memory required)"
}
```
# Usar a ferramenta neptune-export ou o serviço Neptune-Export para exportar dados do Neptune para o Neptune ML
O Neptune ML exige que você forneça dados de treinamento para a [Deep Graph Library (DGL](https://www.dgl.ai/)) criar e avaliar modelos.
É possível exportar dados do Neptune usando o [serviço Neptune-Export](export-service.md) ou o [utilitário `neptune-export`](export-utility.md). Tanto o serviço quanto a ferramenta de linha de comando publicam dados no Amazon Simple Storage Service (Amazon S3) em um formato CSV, criptografados usando criptografia no lado do servidor Amazon S3 (`SSE-S3`). Consulte [Arquivos exportados pelo Neptune-Export e `neptune-export`](exported-files.md).
Além disso, quando você configura uma exportação de dados de treinamento para o Neptune ML, o trabalho de exportação cria e publica um arquivo de configuração de treinamento de modelo criptografado junto com os dados exportados. Por padrão, esse arquivo é denominado `training-data-configuration.json`.
# Exemplos de uso do serviço Neptune-Export para exportar dados de treinamento do Neptune ML
Essa solicitação exporta dados de treinamento do grafo de propriedades para uma tarefa de classificação de nós:
```
curl \
(your NeptuneExportApiUri) \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification"
}
]
}
}
}'
```
Essa solicitação exporta dados de treinamento do RDF para uma tarefa de classificação de nós:
```
curl \
(your NeptuneExportApiUri) \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"command": "export-rdf",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre",
"type": "classification"
}
]
}
}
}'
```
# Campos a serem definidos no objeto de parâmetro ao exportar dados de treinamento
O objeto `params` em uma solicitação de exportação pode conter vários campos, conforme descrito na [documentação de `params`](export-params-fields.md). Veja os mais relevantes para exportar dados de treinamento de machine learning:
****
+ **`endpoint`**: use `endpoint` para especificar um endpoint de uma instância do Neptune no cluster de banco de dados que o processo de exportação pode consultar para extrair dados.
+ **`profile`**: o campo `profile` no objeto `params` deve ser definido como **`neptune-ml`**.
Isso faz com que o processo de exportação formate os dados exportados adequadamente para o treinamento de modelos do Neptune ML, em formato CSV para dados de grafos de propriedades ou como N-Triples para dados do RDF. Isso também faz com que um arquivo `training-data-configuration.json` seja criado e gravado no mesmo local do Amazon S3 que os dados de treinamento exportados.
+ **`cloneCluster`**: se definido como `true`, o processo de exportação clona o cluster de banco de dados, exporta do clone e, depois, exclui o clone ao terminar.
+ **`useIamAuth`**: se o cluster de banco de dados tiver a [autenticação do IAM](iam-auth-enable.md) habilitada, você deverá incluir esse campo definido como `true`.
O processo de exportação também fornece várias maneiras de filtrar os dados exportados (consulte [estes exemplos](export-filtering-examples.md)).
# Usar o objeto additionalParams para ajustar a exportação de informações de treinamento de modelos
O objeto `additionalParams` contém campos que você pode usar para especificar rótulos e atributos de classe de machine learning para fins de treinamento e orientar a criação de um arquivo de configuração de dados de treinamento.
O processo de exportação não pode inferir automaticamente quais propriedades do nó e da borda devem ser os rótulos das classes de machine learning para servir como exemplos para fins de treinamento. Ele também não pode inferir automaticamente a melhor codificação de atributos para propriedades numéricas, categóricas e de texto, portanto, você precisa fornecer dicas usando campos no objeto `additionalParams` para especificar esses itens ou substituir a codificação padrão.
Para dados de grafos de propriedades, a estrutura geral de `additionalParams` em uma solicitação de exportação pode ter a seguinte aparência:
```
{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
}
}
}
```
Para dados do RDF, a estrutura geral pode ter a seguinte aparência:
```
{
"command": "export-rdf",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [ (an array of node and edge class label targets) ]
}
}
}
```
Também é possível fornecer várias configurações de exportação usando o campo `jobs`:
```
{
"command": "export-pg",
"outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export",
"params": {
"endpoint": "(your Neptune endpoint DNS name)",
"profile": "neptune_ml"
},
"additionalParams" : {
"neptune_ml" : {
"version": "v2.0",
"jobs": [
{
"name" : "(training data configuration name)",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
},
{
"name" : "(another training data configuration name)",
"targets": [ (an array of node and edge class label targets) ],
"features": [ (an array of node feature hints) ]
}
]
}
}
}
```
# Elementos de nível superior no campo neptune\$1ml em additionalParams
## O elemento versão em neptune\$1ml
Especifica a versão da configuração dos dados de treinamento a ser gerada.
(*Opcional*), *Tipo*: string, *Padrão*: “v2.0”.
Se você incluir `version`, defina-o como `v2.0`.
## O campo tarefas em neptune\$1ml
Contém uma matriz de objetos de configuração de dados de treinamento, cada um definindo um trabalho de processamento de dados e contendo:
+ **`name`**: o nome da configuração dos dados de treinamento a ser criada.
Por exemplo, uma configuração de dados de treinamento com o nome “job-number-1" gera um arquivo de configuração de dados de treinamento chamado `job-number-1.json`.
+ **`targets`**: uma matriz JSON de destinos de rótulos de classes de nós e bordas que representam os rótulos de classes de machine learning para fins de treinamento. Consulte [O campo de destinos em um objeto neptune\$1ml](machine-learning-neptune_ml-targets.md).
+ **`features`**: uma matriz JSON de atributos de propriedades de nós. Consulte [O campo de recursos no neptune\$1ml](machine-learning-neptune_ml-features.md).
# O campo de destinos em um objeto neptune\$1ml
O campo `targets` em uma configuração de exportação de dados de treinamento JSON contém uma matriz de objetos de destino que especificam uma tarefa de treinamento e os rótulos das classes de machine learning para treinar essa tarefa. O conteúdo dos objetos de destino varia dependendo se você está treinando com dados de grafos de propriedades ou dados do RDF.
Para tarefas de classificação e regressão de nós do grafo de propriedades, os objetos de destino na matriz podem ter a seguinte aparência:
```
{
"node": "(node property-graph label)",
"property": "(property name)",
"type" : "(used to specify classification or regression)",
"split_rate": [0.8,0.2,0.0],
"separator": ","
}
```
Para tarefas de classificação de bordas, regressão ou previsão de links de grafos de propriedades, elas podem ter a seguinte aparência:
```
{
"edge": "(edge property-graph label)",
"property": "(property name)",
"type" : "(used to specify classification, regression or link_prediction)",
"split_rate": [0.8,0.2,0.0],
"separator": ","
}
```
Para tarefas de classificação e regressão do RDF, os objetos de destino na matriz podem ter a seguinte aparência:
```
{
"node": "(node type of an RDF node)",
"predicate": "(predicate IRI)",
"type" : "(used to specify classification or regression)",
"split_rate": [0.8,0.2,0.0]
}
```
Para tarefas de previsão de links do RDF, os objetos de destino na matriz podem ter a seguinte aparência:
```
{
"subject": "(source node type of an edge)",
"predicate": "(relation type of an edge)",
"object": "(destination node type of an edge)",
"type" : "link_prediction",
"split_rate": [0.8,0.2,0.0]
}
```
Os objetos de destino podem conter os seguintes campos:
**Contents**
+ [Campos de destino do grafo de propriedades](#machine-learning-property-graph-neptune_ml-targets)
+ [nó](#machine-learning-property-graph-neptune_ml-targets-node)
+ [borda](#machine-learning-property-graph-neptune_ml-targets-edge)
+ [property](#machine-learning-property-graph-neptune_ml-targets-property)
+ [type](#machine-learning-property-graph-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-property-graph-neptune_ml-targets-split_rate)
+ [separador](#machine-learning-property-graph-neptune_ml-targets-separator)
+ [Campos de destino do RDF](#machine-learning-RDF-neptune_ml-targets)
+ [nó](#machine-learning-RDF-neptune_ml-targets-node)
+ [subject](#machine-learning-RDF-neptune_ml-targets-subject)
+ [predicado](#machine-learning-RDF-neptune_ml-targets-predicate)
+ [objeto](#machine-learning-RDF-neptune_ml-targets-object)
+ [type](#machine-learning-RDF-neptune_ml-targets-type)
+ [split\$1rate](#machine-learning-RDF-neptune_ml-targets-split_rate)
## Campos em um objeto de destino do grafo de propriedades
### O campo nó (vértice) em um objeto de destino
O rótulo do grafo de propriedades de um nó de destino (vértice). Um objeto de destino deve conter um elemento `node` ou `edge`, mas não ambos.
O `node` pode assumir um único valor, como este:
```
"node": "Movie"
```
Ou, no caso de um vértice com vários rótulos, ele pode usar uma série de valores, como esta:
```
"node": ["Content", "Movie"]
```
### O campo borda em um objeto de destino do grafo de propriedades
Especifica uma borda de destino pelos rótulos de nó inicial, o próprio rótulo e os rótulos de nó final. Um objeto de destino deve conter um elemento `edge` ou `node`, mas não ambos.
O valor de um campo `edge` é uma matriz JSON de três strings que representam os rótulos do grafo de propriedades do nó inicial, o rótulo do grafo de propriedades da própria borda e os rótulos do grafo de propriedades do nó final, desta forma:
```
"edge": ["Person_A", "knows", "Person_B"]
```
Se o nó and/or final do nó inicial tiver vários rótulos, coloque-os em uma matriz, como esta:
```
"edge": [ ["Admin", Person_A"], "knows", ["Admin", "Person_B"] ]
```
### O campo propriedade em um objeto de destino do grafo de propriedades
Especifica uma propriedade do vértice ou da borda de destino, desta forma:
```
"property" : "rating"
```
Esse campo é obrigatório, exceto quando a tarefa de destino é a previsão de links.
### O campo tipo em um objeto de destino do grafo de propriedades
Indica o tipo de tarefa de destino a ser realizada no `node` ou na `edge`, desta forma:
```
"type" : "regression"
```
Os tipos de tarefa compatíveis com nós são:
+ `classification`
+ `regression`
Os tipos de tarefa compatíveis com bordas são:
+ `classification`
+ `regression`
+ `link_prediction`
Este campo é obrigatório.
### O campo split\$1rate em um objeto de destino do grafo de propriedades
(*Opcional*) Uma estimativa das proporções de nós ou bordas que as fases de treinamento, validação e teste usarão, respectivamente. Essas proporções são representadas por uma matriz JSON de três números entre zero e um que somam um:
```
"split_rate": [0.7, 0.1, 0.2]
```
Se você não fornecer o campo opcional `split_rate`, o valor estimado padrão será `[0.9, 0.1, 0.0]` para tarefas de classificação e regressão e `[0.9,0.05, 0.05]` para tarefas de previsão de links.
### O campo separador em um objeto de destino do grafo de propriedades
(*Opcional*) Usado com uma tarefa de classificação.
O campo `separator` especifica um caractere usado para dividir um valor de propriedade de destino em vários valores categóricos quando é usado para armazenar vários valores de categoria em uma string. Por exemplo:
```
"separator": "|"
```
A presença de um campo `separator` indica que a tarefa é de classificação com vários destinos.
## Campos em um objeto de destino do RDF
### O campo nó em um objeto de destino do RDF
Define o tipo dos nós de destino. Usado com tarefas de classificação ou regressão de nós. O tipo de um nó no RDF é definido por:
```
node_id, , node_type
```
Um `node` do RDF pode assumir um único valor, como este:
```
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
### O campo assunto em um objeto de destino do RDF
Para tarefas de previsão de links, `subject` define o tipo de nó de origem das bordas de destino.
```
"subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director"
```
**nota**
Para tarefas de previsão de links, `subject` deve ser usado junto com `predicate` e `object`. Se algum desses três não for fornecido, todas as bordas serão tratadas como o destino do treinamento.
### O campo predicado em um objeto de destino do RDF
Para tarefas de classificação e regressão de nós, `predicate` define quais dados literais são usados como o atributo de um nó de destino.
```
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre"
```
**nota**
Se os nós de destino tiverem apenas um predicado que defina o atributo do nó de destino, o campo `predicate` poderá ser omitido.
Para tarefas de previsão de links, `predicate` define o tipo de relação das bordas de destino.
```
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/direct"
```
**nota**
Para tarefas de previsão de links, `predicate` deve ser usado junto com `subject` e `object`. Se algum desses três não for fornecido, todas as bordas serão tratadas como o destino do treinamento.
### O campo objeto em um objeto de destino do RDF
Para tarefas de previsão de links, `object` define o tipo de nó de destino das bordas de destino:
```
"object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie"
```
**nota**
Para tarefas de previsão de links, `object` deve ser usado junto com `subject` e `predicate`. Se algum desses três não for fornecido, todas as bordas serão tratadas como o destino do treinamento.
### O campo tipo em um objeto de destino do RDF
Indica o tipo de tarefa de destino a ser realizada, desta forma:
```
"type" : "regression"
```
Os tipos de tarefa compatíveis com dados do RDF são:
+ `link_prediction`
+ `classification`
+ `regression`
Este campo é obrigatório.
### O campo `split_rate` em um objeto de destino do grafo de propriedades
(*Opcional*) Uma estimativa das proporções de nós ou bordas que as fases de treinamento, validação e teste usarão, respectivamente. Essas proporções são representadas por uma matriz JSON de três números entre zero e um que somam um:
```
"split_rate": [0.7, 0.1, 0.2]
```
Se você não fornecer o campo `split_rate` opcional, o valor estimado padrão será `[0.9, 0.1, 0.0]`.
# O campo de recursos no neptune\$1ml
Os valores das propriedades e os literais do RDF têm diferentes formatos e tipos de dados. Para obter um bom desempenho no machine learning, é essencial converter esses valores em codificações numéricas conhecidas como *atributos*.
O Neptune ML realiza extração e codificação de atributos como parte das etapas de exportação e processamento de dados, conforme descrito em [Codificação de atributos no Neptune ML](machine-learning-feature-encoding.md).
Para conjuntos de dados de grafos de propriedades, o processo de exportação infere automaticamente atributos `auto` para propriedades de string e propriedades numéricas que contêm vários valores. Para propriedades numéricas que contenham valores únicos, ele infere atributos `numerical`. Para propriedades de data, ele infere atributos `datetime`.
Se você quiser substituir uma especificação de recurso inferida automaticamente ou adicionar uma especificação numérica de bucket, TF-IDF ou SBERT para uma propriedade FastText, você pode controlar a codificação do recurso usando o campo features.
**nota**
É possível usar o campo `features` somente para controlar as especificações do atributo para dados de grafos de propriedades, não para dados do RDF.
Para texto de formato livre, o Neptune ML pode usar vários modelos diferentes para converter a sequência de tokens em um valor de propriedade de string em um vetor de valor real de tamanho fixo:
+ [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features): usa a codificação [fastText](https://fasttext.cc/). É a codificação recomendada para atributos que usam um e somente um dos cinco idiomas aceitos pela codificação fastText.
+ [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-sbert-features): usa os modelos de codificação [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). É a codificação recomendada para texto que não é compatível com `text_fasttext`.
+ [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features): usa algoritmos [Word2Vec](https://wikipedia.org/wiki/Word2vec) originalmente publicados pelo [Google](https://code.google.com/archive/p/word2vec/) para codificar texto. O Word2Vec é compatível apenas com inglês.
+ [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features): usa um vetorizador de [frequência de termo – frequência inversa do documento](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) para codificar texto. A codificação TF-IDF é compatível com atributos estatísticos não aceitos por outras codificações.
O campo `features` contém uma matriz JSON de atributos de propriedade do nó. Os objetos na matriz podem conter os seguintes campos:
**Contents**
+ [nó](#machine-learning-neptune_ml-features-node)
+ [borda](#machine-learning-neptune_ml-features-edge)
+ [property](#machine-learning-neptune_ml-features-property)
+ [type](#machine-learning-neptune_ml-feature-types)
+ [norma](#machine-learning-neptune_ml-features-norm)
+ [idioma](#machine-learning-neptune_ml-features-language)
+ [max\$1length](#machine-learning-neptune_ml-features-max_length)
+ [separador](#machine-learning-neptune_ml-features-separator)
+ [intervalo](#machine-learning-neptune_ml-features-range)
+ [bucket\$1cnt](#machine-learning-neptune_ml-features-bucket_cnt)
+ [slide\$1window\$1size](#machine-learning-neptune_ml-features-slide_window_size)
+ [estimador](#machine-learning-neptune_ml-features-imputer)
+ [max\$1features](#machine-learning-neptune_ml-features-max_features)
+ [min\$1df](#machine-learning-neptune_ml-features-min_df)
+ [ngram\$1range](#machine-learning-neptune_ml-features-ngram_range)
+ [datetime\$1parts](#machine-learning-neptune_ml-features-datetime_parts)
## O campo nó em recursos
O campo `node` especifica um rótulo de grafo de propriedades de um vértice de atributo. Por exemplo:
```
"node": "Person"
```
Se um vértice tiver vários rótulos, use uma matriz para contê-los. Por exemplo:
```
"node": ["Admin", "Person"]
```
## O campo borda em recursos
O campo `edge` especifica o tipo de uma borda de atributo. Um tipo de borda consiste em uma matriz que contém os rótulos do grafo de propriedades do vértice de origem, o rótulo do grafo de propriedades da borda e os rótulos do grafo de propriedades do vértice de destino. É necessário fornecer todos os três valores ao especificar um atributo de borda. Por exemplo:
```
"edge": ["User", "reviewed", "Movie"]
```
Se um vértice de origem ou destino de um tipo de borda tiver vários rótulos, use outra matriz para contê-los. Por exemplo:
```
"edge": [["Admin", "Person"]. "edited", "Post"]
```
## O campo propriedade em recursos
Use o parâmetro propriedade para especificar uma propriedade do vértice identificado pelo parâmetro `node`. Por exemplo:
```
"property" : "age"
```
## Valores possíveis do campo de tipo para recursos
O parâmetro `type` especifica o tipo de atributo que está sendo definido. Por exemplo:
```
"type": "bucket_numerical"
```
**Valores possíveis do parâmetro `type`**
+ **`"auto"`**: especifica que o Neptune ML deve detectar automaticamente o tipo de propriedade e aplicar uma codificação de atributo adequada. Um atributo `auto` também pode ter um campo `separator` opcional.
Consulte [Codificação de atributos automáticos no Neptune ML](machine-learning-feature-encoding.md#machine-learning-auto-encoding).
+ **`"category"`**: essa codificação de atributo representa um valor de propriedade como uma das várias categorias. Em outras palavras, o atributo pode assumir um ou mais valores distintos. Um atributo `category` também pode ter um campo `separator` opcional.
Consulte [Atributos categóricos no Neptune ML](machine-learning-feature-encoding.md#machine-learning-categorical-features).
+ **`"numerical"`**: essa codificação de atributo representa valores de propriedade numérica como números em um intervalo contínuo em que “maior que” e “menor que” têm significado.
Um atributo `numerical` também pode ter campos `norm`, `imputer` e `separator` opcionais.
Consulte [Atributos numéricos no Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features).
+ **`"bucket_numerical"`**: essa codificação de atributos divide os valores de propriedade numérica em um conjunto de *buckets* ou categorias.
Por exemplo, é possível codificar a idade das pessoas em quatro buckets: crianças (de 0 a 20 anos), jovens adultos (de 20 a 40 anos), meia idade (de 40 a 60 anos) e idosos (de 60 anos em diante).
Um `bucket_numerical` recurso requer um `bucket_cnt` campo `range` e um e, opcionalmente, também pode incluir um `imputer` and/or `slide_window_size` campo.
Consulte [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
+ **`"datetime"`**: essa codificação de atributos representa um valor de propriedade de data e hora como uma matriz desses atributos categóricos: ano, mês, dia da semana e hora.
Uma ou mais dessas quatro categorias podem ser eliminadas usando o parâmetro `datetime_parts`.
Consulte [Atributos de data e hora no Neptune ML](machine-learning-feature-encoding.md#machine-learning-datetime-features).
+ **`"text_fasttext"`**: essa codificação de atributos converte valores de propriedade que consistem em frases ou texto de formato livre em vetores numéricos usando modelos [fastText](https://fasttext.cc/). Ela é compatível com cinco idiomas, a saber, inglês (`en`), chinês (`zh`), hindi (`hi`), espanhol (`es`) e francês (`fr`). Para valores de propriedade de texto em qualquer um desses cinco idiomas, `text_fasttext` é a codificação recomendada. No entanto, ela não consegue lidar com casos em que a mesma frase contenha palavras em mais de um idioma.
Para outros idiomas além dos compatíveis com a fastText, use a codificação `text_sbert`.
Se você tiver muitas strings de texto de valor de propriedade maiores que, digamos, 120 tokens, use o campo `max_length` para limitar o número de tokens em cada string codificada por `"text_fasttext"`.
Consulte [Codificação *fastText* de valores de propriedades de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-fasttext-features).
+ **`"text_sbert"`**: essa codificação converte valores de propriedade de texto em vetores numéricos usando modelos [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). O Neptune é compatível com dois métodos SBERT, ou seja, `text_sbert128`, que será o padrão se você apenas especificar `text_sbert` e `text_sbert512`. A diferença entre eles é o número máximo de tokens em uma propriedade de texto codificada. A codificação `text_sbert128` codifica apenas os primeiros 128 tokens, enquanto `text_sbert512` codifica até 512 tokens. Como resultado, o uso de `text_sbert512` pode exigir mais tempo de processamento do que `text_sbert128`. Os dois métodos são mais lentos do que `text_fasttext`.
Os métodos `text_sbert*` são compatíveis com vários idiomas e podem codificar uma frase que contenha mais de um idioma.
Consulte [Codificação Sentence BERT (SBERT) de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-sbert-features).
+ **`"text_word2vec"`**: essa codificação converte valores de propriedade de texto em vetores numéricos usando algoritmos [Word2Vec](https://wikipedia.org/wiki/Word2vec). Ela aceita apenas inglês.
Consulte [Codificação Word2Vec de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-word2vec-features).
+ **`"text_tfidf"`**: essa codificação converte valores de propriedade de texto em vetores numéricos usando um vetorizador de [frequência de termo – frequência inversa de documento](https://wikipedia.org/wiki/Tf-idf) (TF-IDF).
Você define os parâmetros de uma codificação de atributos `text_tfidf` usando os campos `ngram_range`, `min_df` e `max_features`.
Consulte [Codificação TF-IDF de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features).
+ **`"none"`**: usar o tipo `none` faz com que nenhuma codificação de atributos ocorra. Em vez disso, os valores brutos das propriedades são analisados e salvos.
Use `none` somente se você planeja realizar a própria codificação de atributos personalizados como parte do treinamento de modelos personalizados.
## O campo norma
Esse campo é obrigatório para atributos numéricos. Ele especifica um método de normalização a ser usado em valores numéricos:
```
"norm": "min-max"
```
Os seguintes métodos de normalização são compatíveis:
+ **“mín-máx”**: normalize cada valor subtraindo o valor mínimo e dividindo-o pela diferença entre o valor máximo e o mínimo.
+ **“padrão”**: normalize cada valor dividindo-o pela soma de todos os valores.
+ **“nenhum”**: não normalize os valores numéricos durante a codificação.
Consulte [Atributos numéricos no Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features).
## O campo idioma
O campo de idioma especifica o idioma usado nos valores das propriedades de texto. O uso depende do método de codificação de texto:
+ Para a codificação [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), esse campo é obrigatório e deve especificar um dos seguintes idiomas:
+ `en` (inglês)
+ `zh` (chinês)
+ `hi` (hindi)
+ `es` (espanhol)
+ `fr` (francês)
+ Para a codificação [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), esse campo não é usado, pois a codificação SBERT é multilíngue.
+ Para a codificação [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features), esse campo é opcional, pois `text_word2vec` só é compatível com inglês. Se presente, ele deve especificar o nome do modelo em inglês:
```
"language" : "en_core_web_lg"
```
+ Para a codificação [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features), esse campo não é usado.
## O campo max\$1length
O campo `max_length` é opcional para atributos `text_fasttext`, no qual ele especifica o número máximo de tokens em um atributo de texto de entrada que será codificado. Texto de entrada maior do que `max_length` é truncado. Por exemplo, definir max\$1length como 128 indica que qualquer token após o 128º em uma sequência de texto será ignorado:
```
"max_length": 128
```
## O campo separador
Esse campo é usado opcionalmente com os atributos `category`, `numerical` e `auto`. Ele especifica um caractere que pode ser usado para dividir o valor de uma propriedade em vários valores categóricos ou valores numéricos:
```
"separator": ";"
```
Use o campo `separator` somente quando a propriedade armazena vários valores delimitados em uma única string, como `"Actor;Director"` ou `"0.1;0.2"`.
Consulte [Atributos categóricos](machine-learning-feature-encoding.md#machine-learning-categorical-features), [Atributos numéricos](machine-learning-feature-encoding.md#machine-learning-numerical-features) e [Codificação automática](machine-learning-feature-encoding.md#machine-learning-auto-encoding).
## O campo intervalo
Esse campo é obrigatório para atributos `bucket_numerical`. Ele especifica o intervalo de valores numéricos que devem ser divididos em buckets, no formato `[lower-bound, upper-bound]`:
```
"range" : [20, 100]
```
Se o valor de uma propriedade for menor que o limite inferior, ele será atribuído ao primeiro bucket ou, se for maior que o limite superior, será atribuído ao último bucket.
Consulte [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
## O campo bucket\$1cnt
Esse campo é obrigatório para atributos `bucket_numerical`. Ele especifica o número de buckets nos quais o intervalo numérico definido pelo parâmetro `range` deve ser dividido:
```
"bucket_cnt": 10
```
Consulte [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
## O campo slide\$1window\$1size
Esse campo é usado opcionalmente com atributos `bucket_numerical` para atribuir valores a mais de um bucket:
```
"slide_window_size": 5
```
Uma janela de controle deslizante funciona da seguinte forma: o Neptune ML considera o tamanho da janela **`s`** e transforma cada valor numérico **`v`** de uma propriedade em um intervalo de ` v - s/2 ` a ` v + s/2 `. O valor é então atribuído a cada bucket ao qual o intervalo se sobrepõe.
Consulte [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
## O campo estimador
Esse campo é usado opcionalmente com atributos `numerical` e `bucket_numerical` para fornecer uma técnica de imputação a fim de preencher valores ausentes:
```
"imputer": "mean"
```
As técnicas de imputação compatíveis são:
+ `"mean"`
+ `"median"`
+ `"most-frequent"`
Se você não incluir o parâmetro estimador, o pré-processamento de dados será interrompido e encerrado quando um valor ausente for encontrado.
Consulte [Atributos numéricos no Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features) e [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
## O campo max\$1features
Esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar o número máximo de termos a serem codificados:
```
"max_features": 100
```
Uma configuração de cem faz com que o vetorizador TF-IDF codifique somente os cem termos mais comuns. O valor padrão, se você não incluir `max_features` será cinco mil.
Consulte [Codificação TF-IDF de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features).
## O campo min\$1df
Esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar a frequência mínima de documentos de termos a serem codificados:
```
"min_df": 5
```
Uma configuração de cinco indica que um termo deve aparecer em pelo menos cinco valores de propriedade diferentes para ser codificado.
O valor padrão se você não incluir o parâmetro `min_df` será `2`.
Consulte [Codificação TF-IDF de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features).
## O campo ngram\$1range
Esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar quais sequências de tamanho de palavras ou tokens devem ser consideradas como possíveis termos individuais a serem codificados:
```
"ngram_range": [2, 4]
```
O valor `[2, 4]` especifica que sequências de dois, três e quatro palavras devem ser consideradas como possíveis termos individuais.
O padrão, se você não definir explicitamente `ngram_range` será `[1, 1]`, o que significa que somente palavras ou tokens individuais são considerados termos a serem codificados.
Consulte [Codificação TF-IDF de atributos de texto no Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features).
## O campo datetime\$1parts
Esse campo é usado opcionalmente pelos atributos `datetime` para especificar quais partes do valor de data e hora devem ser codificadas categoricamente:
```
"datetime_parts": ["weekday", "hour"]
```
Se você não incluir `datetime_parts`, por padrão, o Neptune ML codificará as partes de ano, mês, dia da semana e hora do valor de data e hora. O valor `["weekday", "hour"]` indica que somente os valores do dia da semana e da hora da data e hora devem ser codificados categoricamente no atributo.
Se uma das partes não tiver mais de um valor exclusivo no conjunto de treinamento, ela não será codificada.
Consulte [Atributos de data e hora no Neptune ML](machine-learning-feature-encoding.md#machine-learning-datetime-features).
# Exemplos de uso de parâmetros em additionalParams para ajustar a configuração de treinamento de modelo
Os exemplos a seguir demonstram como utilizar o recurso “additionalParams” em grafos de propriedades e modelos de dados RDF para configurar vários aspectos do processo de treinamento de modelos para uma aplicação do Neptune ML. Os exemplos abrangem uma ampla variedade de funcionalidades, incluindo a especificação de taxas de divisão padrão para training/validation/test dados, a definição de tarefas de classificação de nós, regressão e previsão de links, bem como a configuração de diferentes tipos de recursos, como compartimentos numéricos, incorporações de texto, data e hora e dados categóricos. Essas configurações detalhadas permitem que você adapte o pipeline de machine learning aos seus requisitos específicos de dados e modelagem, liberando todo o potencial dos recursos do Neptune ML.
**Contents**
+ [Exemplos de grafo de propriedades usando additionalParams](#machine-learning-property-graph-additionalParams-examples)
+ [Especificar uma taxa de divisão padrão para a configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-default-split-rate-example)
+ [Especificar uma tarefa de classificação de nós para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-node-classification-example)
+ [Especificar uma tarefa de classificação de nós de várias classes para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-multi-class-example)
+ [Especificar uma tarefa de regressão de nós para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-node-regression-example)
+ [Especificar uma tarefa de classificação de bordas para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-edge-classification-example)
+ [Especificar uma tarefa de classificação de bordas de várias classes para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-multi-edge-classification-example)
+ [Especificar uma regressão de bordas para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-edge-regression-example)
+ [Especificar uma tarefa de previsão de links para configuração de treinamento de modelos](#machine-learning-property-graph-additionalParams-link-prediction-example)
+ [Especificar um atributo de bucket numérico](#machine-learning-property-graph-additionalParams-numeric-bucket-example)
+ [Especificar um atributo `Word2Vec`](#machine-learning-property-graph-additionalParams-word2vec-example)
+ [Especificar um atributo `FastText`](#machine-learning-property-graph-additionalParams-fasttext-example)
+ [Especificar um atributo `Sentence BERT`](#machine-learning-property-graph-additionalParams-sbert-example)
+ [Especificar um atributo `TF-IDF`](#machine-learning-property-graph-additionalParams-tf-idf-example)
+ [Especificar um atributo `datetime`](#machine-learning-property-graph-additionalParams-datetime-example)
+ [Especificar um atributo `category`](#machine-learning-property-graph-additionalParams-category-example)
+ [Especificar um atributo `numerical`](#machine-learning-property-graph-additionalParams-numerical-example)
+ [Especificar um atributo `auto`](#machine-learning-property-graph-additionalParams-auto-example)
+ [Exemplos do RDF usando `additionalParams`](#machine-learning-RDF-additionalParams-examples)
+ [Especificar uma taxa de divisão padrão para a configuração de treinamento de modelos](#machine-learning-RDF-additionalParams-default-split-rate-example)
+ [Especificar uma tarefa de classificação de nós para configuração de treinamento de modelos](#machine-learning-RDF-additionalParams-node-classification-example)
+ [Especificar uma tarefa de regressão de nós para configuração de treinamento de modelos](#machine-learning-RDF-additionalParams-node-regression-example)
+ [Especificar uma tarefa de previsão de links para bordas específicas](#machine-learning-RDF-additionalParams-link-prediction-example)
+ [Especificar uma tarefa de previsão de links para todas as bordas](#machine-learning-RDF-additionalParams-link-prediction-example)
## Exemplos de grafo de propriedades usando additionalParams
### Especificar uma taxa de divisão padrão para a configuração de treinamento de modelos
No exemplo a seguir, o parâmetro `split_rate` define a taxa de divisão padrão para o treinamento de modelos. Se nenhuma taxa de divisão padrão for especificada, o treinamento usará um valor de [0,9, 0,1, 0,0]. É possível substituir o valor padrão por destino especificando uma `split_rate` para cada destino.
No seguinte exemplo, o campo `default split_rate` indica que uma taxa de divisão de `[0.7,0.1,0.2]` deve ser usada, a menos que seja substituída por destino:”
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"split_rate": [0.7,0.1,0.2],
"targets": [
(...)
],
"features": [
(...)
]
}
}
```
### Especificar uma tarefa de classificação de nós para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém exemplos rotulados para fins de treinamento, adicione um elemento de classificação de nós à matriz `targets`, usando `"type" : "classification"`. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
No exemplo a seguir, o destino `node` indica que a propriedade `genre` de cada nó `Movie` deve ser tratada como um rótulo de classe de nó. O valor `split_rate` substitui a taxa de divisão padrão:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification",
"split_rate": [0.7,0.1,0.2]
}
],
"features": [
(...)
]
}
}
```
### Especificar uma tarefa de classificação de nós de várias classes para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém vários exemplos rotulados para fins de treinamento, adicione um elemento de classificação de nós à matriz de destinos, usando `"type" : "classification"` e `separator` para especificar um caractere que pode ser usado para dividir o valor de uma propriedade de destino em vários valores categóricos. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
No exemplo a seguir, o destino `node` indica que a propriedade `genre` de cada nó `Movie` deve ser tratada como um rótulo de classe de nó. O campo `separator` indica que cada propriedade de gênero contém vários valores separados por ponto e vírgula:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "genre",
"type": "classification",
"separator": ";"
}
],
"features": [
(...)
]
}
}
```
### Especificar uma tarefa de regressão de nós para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém regressões rotuladas para fins de treinamento, adicione um elemento de regressão de nós à matriz de destinos, usando `"type" : "regression"`. Adicione um campo split\$1rate se quiser substituir a taxa de divisão padrão.
O seguinte destino `node` indica que a propriedade `rating` de cada nó `Movie` deve ser tratada como um rótulo de regressão de nós:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "Movie",
"property": "rating",
"type" : "regression",
"split_rate": [0.7,0.1,0.2]
}
],
"features": [
...
]
}
}
```
### Especificar uma tarefa de classificação de bordas para configuração de treinamento de modelos
Para indicar qual propriedade de borda contém exemplos rotulados para fins de treinamento, adicione um elemento de borda à matriz `targets`, usando `"type" : "regression"`. Adicione um campo split\$1rate se quiser substituir a taxa de divisão padrão.
O seguinte destino `edge` indica que a propriedade `metAtLocation` de cada borda `knows` deve ser tratada como um rótulo de classe de borda:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "knows", "Person"],
"property": "metAtLocation",
"type": "classification"
}
],
"features": [
(...)
]
}
}
```
### Especificar uma tarefa de classificação de bordas de várias classes para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém vários exemplos rotulados para fins de treinamento, adicione um elemento de borda à matriz `targets` usando um campo `"type" : "classification"` e um `separator` para especificar um caractere usado para dividir o valor de uma propriedade de destino em vários valores categóricos. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
O destino `edge` a seguir indica que a propriedade `sentiment` de cada borda `repliedTo` deve ser tratada como um rótulo de classe de borda. O campo separador indica que cada propriedade de sentimento contém vários valores separados por vírgula:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "repliedTo", "Message"],
"property": "sentiment",
"type": "classification",
"separator": ","
}
],
"features": [
(...)
]
}
}
```
### Especificar uma regressão de bordas para configuração de treinamento de modelos
Para indicar qual propriedade de borda contém exemplos de regressão rotulados para fins de treinamento, adicione um elemento `edge` à matriz `targets`, usando `"type" : "regression"`. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
O seguinte destino `edge` indica que a propriedade `rating` de cada borda `reviewed` deve ser tratada como uma regressão de bordas:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Person", "reviewed", "Movie"],
"property": "rating",
"type" : "regression"
}
],
"features": [
(...)
]
}
}
```
### Especificar uma tarefa de previsão de links para configuração de treinamento de modelos
Para indicar quais bordas devem ser usadas para fins de treinamento de previsão de links, adicione um elemento de borda à matriz de destinos usando `"type" : "link_prediction"`. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
O seguinte destino `edge` indica que as bordas `cites` devem ser usadas para previsão de links:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"edge": ["Article", "cites", "Article"],
"type" : "link_prediction"
}
],
"features": [
(...)
]
}
}
```
### Especificar um atributo de bucket numérico
É possível especificar um atributo de dados numéricos para uma propriedade de nó adicionando `"type": "bucket_numerical"` à matriz `features`.
O seguinte atributo `node` indica que a propriedade `age` de cada nó `Person` deve ser tratada como um atributo de bucket numérico:
```
"additionalParams": {
"neptune_ml": {
"targets": [
...
],
"features": [
{
"node": "Person",
"property": "age",
"type": "bucket_numerical",
"range": [1, 100],
"bucket_cnt": 5,
"slide_window_size": 3,
"imputer": "median"
}
]
}
}
```
### Especificar um atributo `Word2Vec`
É possível especificar um atributo `Word2Vec` para uma propriedade de nó adicionando `"type": "text_word2vec"` à matriz `features`.
O seguinte atributo `node` indica que a propriedade `description` de cada nó `Movie` deve ser tratada como um atributo `Word2Vec`:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_word2vec",
"language": "en_core_web_lg"
}
]
}
}
```
### Especificar um atributo `FastText`
É possível especificar um atributo `FastText` para uma propriedade de nó adicionando `"type": "text_fasttext"` à matriz `features`. O campo `language` é obrigatório e deve especificar um dos seguintes códigos de idioma:
+ `en` (inglês)
+ `zh` (chinês)
+ `hi` (hindi)
+ `es` (espanhol)
+ `fr` (francês)
Observe que a codificação `text_fasttext` não pode lidar com mais de um idioma por vez em um atributo.
O seguinte atributo `node` indica que a propriedade `description` de francês de cada nó `Movie` deve ser tratada como um atributo `FastText`:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_fasttext",
"language": "fr",
"max_length": 1024
}
]
}
}
```
### Especificar um atributo `Sentence BERT`
É possível especificar um atributo `Sentence BERT` para uma propriedade de nó adicionando `"type": "text_sbert"` à matriz `features`. Não é necessário especificar o idioma, pois o método codifica automaticamente os atributos de texto usando um modelo de idioma multilíngue.
O seguinte atributo `node` indica que a propriedade `description` de cada nó `Movie` deve ser tratada como um atributo `Sentence BERT`:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "description",
"type": "text_sbert128",
}
]
}
}
```
### Especificar um atributo `TF-IDF`
É possível especificar um atributo `TF-IDF` para uma propriedade de nó adicionando `"type": "text_tfidf"` à matriz `features`.
O seguinte atributo `node` indica que a propriedade `bio` de cada nó `Person` deve ser tratada como um atributo `TF-IDF`:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Movie",
"property": "bio",
"type": "text_tfidf",
"ngram_range": [1, 2],
"min_df": 5,
"max_features": 1000
}
]
}
}
```
### Especificar um atributo `datetime`
O processo de exportação infere automaticamente atributos `datetime` para propriedades de data. No entanto, se você quiser limitar `datetime_parts` usado de um atributo `datetime` ou substituir uma especificação de atributo para que uma propriedade que normalmente seria tratada como um atributo `auto` seja explicitamente tratada como um atributo `datetime`, você pode fazer isso adicionando `"type": "datetime"` a à matriz de atributos.
O seguinte atributo `node` indica que a propriedade `createdAt` de cada nó `Post` deve ser tratada como um atributo `datetime`:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Post",
"property": "createdAt",
"type": "datetime",
"datetime_parts": ["month", "weekday", "hour"]
}
]
}
}
```
### Especificar um atributo `category`
O processo de exportação infere automaticamente atributos `auto` para propriedades de string e propriedades numéricas que contenham vários valores. Para propriedades numéricas que contenham valores únicos, ele infere atributos `numerical`. Para propriedades de data, ele infere atributos `datetime`.
Se você quiser substituir uma especificação de atributo para que uma propriedade seja tratada como um atributo categórico, adicione `"type": "category"` à matriz de atributos. Se a propriedade contiver vários valores, inclua um campo `separator`. Por exemplo:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Post",
"property": "tag",
"type": "category",
"separator": "|"
}
]
}
}
```
### Especificar um atributo `numerical`
O processo de exportação infere automaticamente atributos `auto` para propriedades de string e propriedades numéricas que contenham vários valores. Para propriedades numéricas que contenham valores únicos, ele infere atributos `numerical`. Para propriedades de data, ele infere atributos `datetime`.
Se você quiser substituir uma especificação de atributo para que uma propriedade seja tratada como um atributo `numerical`, adicione `"type": "numerical"` à matriz de atributos. Se a propriedade contiver vários valores, inclua um campo `separator`. Por exemplo:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "Recording",
"property": "duration",
"type": "numerical",
"separator": ","
}
]
}
}
```
### Especificar um atributo `auto`
O processo de exportação infere automaticamente atributos `auto` para propriedades de string e propriedades numéricas que contenham vários valores. Para propriedades numéricas que contenham valores únicos, ele infere atributos `numerical`. Para propriedades de data, ele infere atributos `datetime`.
Se você quiser substituir uma especificação de atributo para que uma propriedade seja tratada como um atributo `auto`, adicione `"type": "auto"` à matriz de atributos. Se a propriedade contiver vários valores, inclua um campo `separator`. Por exemplo:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
...
],
"features": [
{
"node": "User",
"property": "role",
"type": "auto",
"separator": ","
}
]
}
}
```
## Exemplos do RDF usando `additionalParams`
### Especificar uma taxa de divisão padrão para a configuração de treinamento de modelos
No exemplo a seguir, o parâmetro `split_rate` define a taxa de divisão padrão para o treinamento de modelos. Se nenhuma taxa de divisão padrão for especificada, o treinamento usará um valor de [0,9, 0,1, 0,0]. É possível substituir o valor padrão por destino especificando uma `split_rate` para cada destino.
No seguinte exemplo, o campo `default split_rate` indica que uma taxa de divisão de `[0.7,0.1,0.2]` deve ser usada, a menos que seja substituída por destino:”
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"split_rate": [0.7,0.1,0.2],
"targets": [
(...)
]
}
}
```
### Especificar uma tarefa de classificação de nós para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém exemplos rotulados para fins de treinamento, adicione um elemento de classificação de nós à matriz `targets`, usando `"type" : "classification"`. Adicione um campo de nó para indicar o tipo dos nós de destino. Adicione um campo `predicate` para definir quais dados literais são usados como o atributo do nó de destino. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
No exemplo a seguir, o destino `node` indica que a propriedade `genre` de cada nó `Movie` deve ser tratada como um rótulo de classe de nó. O valor `split_rate` substitui a taxa de divisão padrão:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre",
"type": "classification",
"split_rate": [0.7,0.1,0.2]
}
]
}
}
```
### Especificar uma tarefa de regressão de nós para configuração de treinamento de modelos
Para indicar qual propriedade de nó contém regressões rotuladas para fins de treinamento, adicione um elemento de regressão de nós à matriz de destinos, usando `"type" : "regression"`. Adicione um campo `node` para indicar o tipo dos nós de destino. Adicione um campo `predicate` para definir quais dados literais são usados como o atributo do nó de destino. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
O seguinte destino `node` indica que a propriedade `rating` de cada nó `Movie` deve ser tratada como um rótulo de regressão de nós:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/rating",
"type": "regression",
"split_rate": [0.7,0.1,0.2]
}
]
}
}
```
### Especificar uma tarefa de previsão de links para bordas específicas
Para indicar quais bordas devem ser usadas para fins de treinamento de previsão de links, adicione um elemento de borda à matriz de destinos usando `"type" : "link_prediction"`. Adicione os campos `subject`, `predicate` e `object` para especificar o tipo de borda. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
O seguinte destino `edge` indica que as bordas `directed` que conectam `Directors` a `Movies` devem ser usadas para previsão de links:
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director",
"predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/directed",
"object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie",
"type" : "link_prediction"
}
]
}
}
```
### Especificar uma tarefa de previsão de links para todas as bordas
Para indicar que todas as bordas devem ser usadas para fins de treinamento de previsão de links, adicione um elemento `edge` à matriz de destinos usando `"type" : "link_prediction"`. Não adicione campos `subject`, `predicate` nem `object`. Adicione um campo `split_rate` se quiser substituir a taxa de divisão padrão.
```
"additionalParams": {
"neptune_ml": {
"version": "v2.0",
"targets": [
{
"type" : "link_prediction"
}
]
}
}
```
# Processar os dados de grafos exportados do Neptune para treinamento
A etapa de processamento de dados usa os dados de grafos do Neptune criados pelo processo de exportação e cria as informações que são usadas pela [Deep Graph Library](https://www.dgl.ai/) (DGL) durante o treinamento. Isso inclui a realização de vários mapeamentos e transformações de dados:
+ Análise de nós e bordas para criar os arquivos de mapeamento de grafos e de ID exigidos pela DGL.
+ Conversão das propriedades do nó e da borda nos atributos do nó e da borda exigidos pela DGL.
+ Divisão dos dados em conjuntos de treinamento, validação e teste.
## Gerenciamento da etapa de processamento de dados do Neptune ML.
Depois de exportar os dados do Neptune que você deseja usar para treinamento de modelos, é possível iniciar um trabalho de processamento de dados usando um comando `curl` (ou `awscurl`) como o seguinte:
```
curl \
-X POST https://(your Neptune endpoint)/ml/dataprocessing \
-H 'Content-Type: application/json' \
-d '{
"inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)",
"id" : "(a job ID for the new job)",
"processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)",
"configFileName" : "training-job-configuration.json"
}'
```
Os detalhes de como usar esse comando são explicados em [O comando de processamento de dados](machine-learning-api-dataprocessing.md), junto com informações sobre como obter o status de um trabalho em execução, como interrompê-lo e como listar todos os trabalhos em execução.
## Processar dados de grafos atualizados para o Neptune ML
Também é possível fornecer um `previousDataProcessingJobId` à API para garantir que o novo trabalho de processamento de dados use o mesmo método de processamento de um trabalho anterior. Esse procedimento é necessário quando você deseja obter previsões para dados de grafos atualizados no Neptune, seja treinando novamente o modelo antigo nos novos dados ou recalculando os artefatos do modelo nos novos dados.
Faça isso usando um comando `curl` (ou `awscurl`) desta forma:
```
curl \
-X POST https://(your Neptune endpoint)/ml/dataprocessing \
-H 'Content-Type: application/json' \
-d '{ "inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)",
"id" : "(a job ID for the new job)",
"processedDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your output folder)",
"previousDataProcessingJobId", "(the job ID of the previous data-processing job)"}'
```
Defina o valor do parâmetro `previousDataProcessingJobId` como o ID de trabalho do processamento de dados anterior correspondente ao modelo treinado.
**nota**
No momento, exclusões de nós no grafo atualizado não são aceitas. Se os nós tiverem sido removidos em um grafo atualizado, você precisará iniciar um trabalho de processamento de dados completamente novo em vez de usar `previousDataProcessingJobId`.
# Codificação de atributos no Neptune ML
Os valores das propriedades têm diferentes formatos e tipos de dados. Para obter um bom desempenho no machine learning, é essencial converter esses valores em codificações numéricas conhecidas como *atributos*.
O Neptune ML realiza extração e codificação de atributos como parte das etapas de exportação e processamento de dados, usando técnicas de codificação de atributos descritas aqui.
**nota**
Se você planeja implementar a própria codificação de atributos em uma implementação de modelo personalizado, é possível desabilitar a codificação automática de atributos na fase de pré-processamento de dados selecionando `none` como o tipo de codificação de atributos. Nenhuma codificação de atributos ocorre nessa propriedade de nó ou borda e, em vez disso, os valores brutos da propriedade são analisados e salvos em um dicionário. O pré-processamento de dados ainda cria o grafo DGL a partir do conjunto de dados exportado, mas o grafo DGL criado não tem os atributos pré-processados para treinamento.
Você deve usar essa opção se planeja realizar a própria codificação de atributos personalizados como parte do treinamento de modelos personalizados. Para obter detalhes, consulte [Modelos personalizados no Neptune ML](machine-learning-custom-models.md).
## Atributos categóricos no Neptune ML
Uma propriedade que pode receber um ou mais valores distintos de uma lista fixa de valores possíveis é um atributo categórico. No Neptune ML, os atributos categóricos são codificados usando a [codificação one-hot](https://en.wikipedia.org/wiki/One-hot). O seguinte exemplo mostra como o nome da propriedade de diferentes alimentos é codificado como one-hot de acordo com a categoria:
```
Food Veg. Meat Fruit Encoding
--------- ---- ---- ----- --------
Apple 0 0 1 001
Chicken 0 1 0 010
Broccoli 1 0 0 100
```
**nota**
O número máximo de categorias em qualquer atributo categórico é cem. Se uma propriedade tiver mais de cem categorias de valor, somente as 99 mais comuns serão colocadas em categorias distintas e as demais serão colocadas em uma categoria especial chamada `OTHER`.
## Atributos numéricos no Neptune ML
Qualquer propriedade cujos valores sejam números reais pode ser codificada como um atributo numérico no Neptune ML. Os atributos numéricos são codificados usando números de ponto flutuante.
É possível especificar um método de normalização de dados a ser usado ao codificar atributos numéricos, como este: `"norm": "normalization technique"` As seguintes técnicas de normalização são compatíveis:
+ **“nenhum”**: não normalize os valores numéricos durante a codificação.
+ **“mín-máx”**: normalize cada valor subtraindo o valor mínimo e dividindo-o pela diferença entre o valor máximo e o mínimo.
+ **“padrão”**: normalize cada valor dividindo-o pela soma de todos os valores.
## Atributos numéricos de bucket no Neptune ML
Em vez de representar uma propriedade numérica usando números brutos, é possível condensar valores numéricos em categorias. Por exemplo, é possível dividir a idade das pessoas em categorias como crianças (0 a 20 anos), jovens adultos (20 a 40), pessoas de meia idade (40 a 60 anos) e idosos (de 60 anos em diante). Usando esses buckets numéricos, você transformaria uma propriedade numérica em um tipo de atributo categórico.
No Neptune ML, é possível fazer com que uma propriedade numérica seja codificada como um atributo numérico de bucket. Você deve fornecer dois itens:
+ Um intervalo numérico no formato, ` "range": [a, b] `, em que `a` e `b` são números inteiros.
+ Uma contagem de buckets, no formato ` "bucket_cnt": c `, em que `c` é o número de buckets, também um número inteiro.
Depois, o Neptune ML calcula o tamanho de cada bucket como ` ( b - a ) / c ` e codifica cada valor numérico como o número de qualquer bucket em que ele se enquadra. Qualquer valor menor que `a` é considerado pertencente ao primeiro bucket, e qualquer valor maior que `b` é considerado pertencente ao último bucket.
Você também pode fazer com que os valores numéricos se enquadrem em mais de um bucket, especificando um tamanho de janela deslizante, como este :` "slide_window_size": s `, em que `s` é um número. Depois, o Neptune ML transforma cada valor numérico `v` da propriedade em um intervalo de ` v - s/2 ` a ` v + s/2 ` e atribui o valor `v` a cada bucket coberto pelo intervalo.
Por fim, também é possível fornecer uma forma de preencher valores ausentes para atributos numéricos e atributos numéricos de bucket. Você faz isso usando ` "imputer": "imputation technique "`, em que a técnica de imputação é uma das seguintes: `"mean"`, `"median"` ou `"most-frequent"`. Se não for especificado um estimador, um valor ausente poderá fazer com que o processamento seja interrompido.
## Codificação de atributos de texto no Neptune ML
Para texto de formato livre, o Neptune ML pode usar vários modelos diferentes para converter a sequência de tokens em uma string de valor de propriedade em um vetor de valor real de tamanho fixo:
+ [`text_fasttext`](#machine-learning-fasttext-features): usa a codificação [fastText](https://fasttext.cc/). É a codificação recomendada para atributos que usam um e somente um dos cinco idiomas aceitos pela codificação fastText.
+ [`text_sbert`](#machine-learning-sbert-features): usa os modelos de codificação [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). É a codificação recomendada para texto que não é compatível com `text_fasttext`.
+ [`text_word2vec`](#machine-learning-word2vec-features): usa os algoritmos [Word2Vec](https://wikipedia.org/wiki/Word2vec) originalmente publicados pelo [Google](https://code.google.com/archive/p/word2vec/) para codificar texto. O Word2Vec é compatível apenas com inglês.
+ [`text_tfidf`](#machine-learning-tfidf-features): usa um vetorizador de [frequência de termo – frequência inversa do documento](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) para codificar texto. A codificação TF-IDF é compatível com atributos estatísticos não aceitos por outras codificações.
### Codificação *fastText* de valores de propriedades de texto no Neptune ML
O Neptune ML pode usar os modelos de [fastText](https://fasttext.cc/) para converter valores de propriedades de texto em vetores de valor real de tamanho fixo. Esse é o método de codificação recomendado para valores de propriedades de texto em qualquer um dos cinco idiomas compatíveis com o fastText:
+ `en` (inglês)
+ `zh` (chinês)
+ `hi` (hindi)
+ `es` (espanhol)
+ `fr` (francês)
Observe que a codificação fastText não consegue lidar com palavras em mais de um idioma.
O método `text_fasttext` pode usar o campo `max_length` que especifica o número máximo de tokens em um valor de propriedade de texto que será codificado, após o qual a string será truncada. Isso pode melhorar o desempenho quando os valores das propriedades de texto contêm strings longas, porque, se `max_length` não for especificado, a fastText codificará todos os tokens, independentemente do tamanho da string.
Este exemplo especifica que os títulos de filmes franceses são codificados usando fastText:
```
{
"file_name" : "nodes/movie.csv",
"separator" : ",",
"node" : ["~id", "movie"],
"features" : [
{
"feature": ["title", "title", "text_fasttext"],
"language": "fr",
"max_length": 1024
}
]
}
```
### Codificação Sentence BERT (SBERT) de atributos de texto no Neptune ML
O Neptune ML pode converter a sequência de tokens de um valor de propriedade de string em um vetor de valor real de tamanho fixo usando modelos de [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). O Neptune é compatível com dois métodos de SBERT, ou seja, `text_sbert128`, que será o padrão se você especificar apenas `text_sbert` e `text_sbert512`. A diferença entre os dois é o tamanho máximo de uma string de valor de propriedade de texto codificada. A codificação `text_sbert128` trunca strings de texto depois de codificar 128 tokens, enquanto `text_sbert512` trunca strings de texto depois de codificar 512 tokens. Como resultado, `text_sbert512` pode exigir mais tempo de processamento do que `text_sbert128`. Os dois métodos são mais lentos do que `text_fasttext`.
A codificação SBERT é multilíngue, portanto, não há necessidade de especificar um idioma para o texto do valor da propriedade que você está codificando. O SBERT é compatível com vários idiomas e pode codificar uma frase que contenha mais de um idioma. Se você estiver codificando valores de propriedades que contenham texto em um idioma ou idiomas que o fastText não aceita, o SBERT será o método de codificação recomendado.
O exemplo a seguir especifica que os títulos de filmes sejam codificados como SBERT até no máximo 128 tokens:
```
{
"file_name" : "nodes/movie.csv",
"separator" : ",",
"node" : ["~id", "movie"],
"features" : [
{ "feature": ["title", "title", "text_sbert128"] }
]
}
```
### Codificação Word2Vec de atributos de texto no Neptune ML
O Neptune ML pode codificar valores de propriedades de string como um atributo do Word2Vec ([atributos Word2Vec](https://wikipedia.org/wiki/Word2vec) foram publicados originalmente pelo [Google)](https://code.google.com/archive/p/word2vec/). O método `text_word2vec` codifica os tokens em uma string como um vetor denso usando um dos [modelos treinados pelo spaCy](https://spacy.io/models). Isso é compatível apenas com o idioma inglês usando o [modelo en\$1core\$1web\$1lg](https://spacy.io/models/en#en_core_web_lg)).
O seguinte exemplo especifica que os títulos dos filmes sejam codificados usando Word2Vec:
```
{
"file_name" : "nodes/movie.csv",
"separator" : ",",
"node" : ["~id", "movie"],
"features" : [
{
"feature": ["title", "title", "text_word2vec"],
"language": "en_core_web_lg"
}
]
}
```
Observe que o campo de idioma é opcional, pois o modelo `en_core_web_lg` em inglês é o único compatível com o Neptune.
### Codificação TF-IDF de atributos de texto no Neptune ML
O Neptune ML pode codificar valores de propriedades de texto como atributos `text_tfidf`. Essa codificação converte a sequência de palavras no texto em um vetor numérico usando um vetorizador de [frequência de termo – frequência inversa de documento](https://wikipedia.org/wiki/Tf-idf) (TF-IDF), seguido por uma operação de redução de dimensionalidade.
[TF-IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf) (frequência de termo – frequência inversa de documento) é um valor numérico destinado a medir a importância de uma palavra em um conjunto de documentos. É calculado dividindo o número de vezes que uma palavra aparece em um valor de propriedade específico pelo número total desses valores de propriedade em que ela aparece.
Por exemplo, se a palavra “kiss” aparecer duas vezes em um título de filme específico (digamos, “kiss kiss bang bang”) e “kiss” aparecer no título de quatro filmes ao todo, o valor TF-IDF de “kiss” no título “kiss kiss bang bang” será ` 2 / 4 `.
O vetor criado inicialmente tem dimensões ***d***, em que ***d*** é o número de termos exclusivos em todos os valores de propriedade desse tipo. A operação de redução de dimensionalidade usa uma projeção esparsa aleatória para reduzir esse número a um máximo de cem. O vocabulário de um grafo é então gerado pela fusão de todos os atributos `text_tfidf` contidos nele.
É possível controlar o vetorizador TF-IDF de várias maneiras:
+ **`max_features`**: usando o parâmetro `max_features`, é possível limitar o número de termos nos atributos `text_tfidf` aos mais comuns. Por exemplo, se você definir `max_features` como cem, somente os cem termos mais usados serão incluídos. O valor padrão para `max_features` se você não o definir explicitamente será 5 mil.
+ **`min_df`**: usando o parâmetro `min_df`, você poderá limitar o número de termos nos atributos `text_tfidf` àqueles que tenham pelo menos uma frequência de documento especificada. Por exemplo, se você definir `min_df` como cinco, somente os termos exibidos em pelo menos cinco valores de propriedade diferentes serão usados. O valor padrão para `min_df` se você não o definir explicitamente será dois.
+ **`ngram_range`**: o parâmetro `ngram_range` determina quais combinações de palavras são tratadas como termos. Por exemplo, se você definir `ngram_range` como `[2, 4]`, os seguintes seis termos serão encontrados no título “kiss kiss bang bang”:
+ *Termos de duas palavras*: “kiss kiss”, “kiss bang” e “bang bang”.
+ *Termos de três palavras*: “kiss kiss bang” e “kiss bang bang”.
+ *Termos de quatro palavras*: “kiss kiss bang bang”.
A configuração padrão para `ngram_range` é `[1, 1]`.
## Atributos de data e hora no Neptune ML
O Neptune ML pode converter partes de valores de propriedades `datetime` em atributos categóricos codificando-os como [matrizes one-hot](https://en.wikipedia.org/wiki/One-hot). Use o parâmetro `datetime_parts` para especificar uma ou mais das seguintes partes a serem codificadas: `["year", "month", "weekday", "hour"]`. Se você não definir `datetime_parts`, por padrão, todas as quatro partes serão codificadas.
Por exemplo, se o intervalo de valores de data e hora abranger os anos de 2010 a 2012, as quatro partes da entrada de data e hora `2011-04-22 01:16:34` serão as seguintes:
+ **ano**: `[0, 1, 0]`.
Como há apenas três anos no período (2010, 2011 e 2012), a matriz one-hot tem três entradas, uma para cada ano.
+ **mês**: `[0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0]`.
Aqui, a matriz one-hot tem uma entrada para cada mês do ano.
+ **dia da semana**: `[0, 0, 0, 0, 1, 0, 0]`.
O padrão ISO 8601 estabelece que segunda-feira é o primeiro dia da semana e, como 22 de abril de 2011 foi sexta-feira, a matriz de dia da semana one-hot correspondente está ativa na quinta posição.
+ **hora**: `[0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]`.
A hora da 1h é definida em uma matriz one-hot de 24 membros.
Dia do mês, minuto e segundo não são codificados categoricamente.
Se o intervalo `datetime` total em questão incluir apenas datas de um único ano, nenhuma matriz `year` será codificada.
É possível especificar uma estratégia de imputação para preencher os valores `datetime` ausentes, usando o parâmetro `imputer` e uma das estratégias disponíveis para atributos numéricos.
## Codificação de atributos automáticos no Neptune ML
Em vez de especificar manualmente os métodos de codificação de atributos a serem usados para as propriedades em seu grafo, você pode definir `auto` como um método de codificação de atributos. Depois, o Neptune ML tenta inferir a melhor codificação de atributos para cada propriedade com base no tipo de dados subjacente.
Veja algumas das heurísticas que o Neptune ML usa para selecionar as codificações de atributos apropriadas:
+ Se a propriedade tiver somente valores numéricos e puder ser convertida em tipos de dados numéricos, o Neptune ML geralmente a codificará como um valor numérico. No entanto, se o número de valores exclusivos da propriedade for menor que 10% do número total de valores e a cardinalidade desses valores exclusivos for menor que cem, o Neptune ML usará uma codificação categórica.
+ Se os valores das propriedades puderem ser convertidos em um tipo `datetime`, o Neptune ML os codificará como um atributo `datetime`.
+ Se os valores das propriedades puderem ser forçados a boolianos (1/0 ou verdadeiro/falso), o Neptune ML usará a codificação de categorias.
+ Se a propriedade for uma string com mais de 10% de seus valores exclusivos e o número médio de tokens por valor for maior ou igual a três, o Neptune ML vai inferir que o tipo de propriedade é texto e detectará automaticamente o idioma que está sendo usado. Se o idioma detectado for um dos aceitos pelo [fastText](#machine-learning-fasttext-features), ou seja, inglês, chinês, hindi, espanhol e francês, o Neptune ML usará `text_fasttext` para codificar o texto . Caso contrário, o Neptune ML usará [`text_sbert`](#machine-learning-sbert-features).
+ Se a propriedade for uma string não classificada como um atributo de texto, o Neptune ML presumirá que seja um atributo categórico e usará a codificação de categoria.
+ Se cada nó tiver o próprio valor exclusivo para uma propriedade inferida como um atributo de categoria, o Neptune ML vai retirar a propriedade do grafo de treinamento porque provavelmente é um ID que não seria informativo para aprendizado.
+ Se a propriedade contiver separadores válidos do Neptune, como ponto e vírgula (“;”), o Neptune ML só poderá tratar a propriedade como `MultiNumerical` ou `MultiCategorical`.
+ O Neptune ML primeiro tenta codificar os valores como atributos numéricos. Se isso for bem-sucedido, o Neptune ML usará codificação numérica para criar atributos de vetor numérico.
+ Caso contrário, o Neptune ML codificará os valores como multicategóricos.
+ Se o Neptune ML não puder inferir o tipo de dados dos valores de uma propriedade, o Neptune ML eliminará a propriedade do grafo de treinamento.
# Editar um arquivo de configuração de dados de treinamento
O processo de exportação do Neptune exporta dados do Neptune ML de um cluster de banco de dados do Neptune para um bucket do S3. Ele exporta nós e bordas separadamente para uma pasta `nodes/` e uma `edges/`. Ele também cria um arquivo de configuração de dados de treinamento JSON, denominado `training-data-configuration.json` por padrão. Esse arquivo contém informações sobre o esquema do grafo, os tipos de atributos, as operações de transformação e normalização de atributos e o atributo de destino para uma tarefa de classificação ou regressão.
Pode haver casos em que você queira modificar o arquivo de configuração diretamente. Um desses casos é quando você deseja alterar a forma como os atributos são processados ou como o grafo é criado, sem precisar executar novamente a exportação toda vez que quiser modificar a especificação da tarefa de machine learning que você está resolvendo.
**Como editar o arquivo de configuração de dados de treinamento**
1. **Baixe o arquivo na máquina local.**
A menos que você tenha especificado um ou mais trabalhos nomeados no parâmetro `additionalParams/neptune_ml` transmitido para o processo de exportação, o arquivo terá o nome padrão, que é `training-data-configuration.json`. Você pode usar um comando AWS CLI como este para baixar o arquivo:
```
aws s3 cp \
s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json \
./
```
1. **Edite o arquivo usando um editor de texto.**
1. **Faça upload do arquivo modificado.** Faça o upload do arquivo modificado de volta para o mesmo local no Amazon S3 do qual você o baixou, usando um comando de AWS CLI como este:
```
aws s3 cp \
training-data-configuration.json \
s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json
```
# Exemplo de arquivo de configuração de dados de treinamento JSON
Veja um exemplo de arquivo de configuração de dados de treinamento que descreve um grafo para uma tarefa de classificação de nós:
```
{
"version" : "v2.0",
"query_engine" : "gremlin",
"graph" : [
{
"edges" : [
{
"file_name" : "edges/(movie)-included_in-(genre).csv",
"separator" : ",",
"source" : ["~from", "movie"],
"relation" : ["", "included_in"],
"dest" : [ "~to", "genre" ]
},
{
"file_name" : "edges/(user)-rated-(movie).csv",
"separator" : ",",
"source" : ["~from", "movie"],
"relation" : ["rating", "prefixname"], # [prefixname#value]
"dest" : ["~to", "genre"],
"features" : [
{
"feature" : ["rating", "rating", "numerical"],
"norm" : "min-max"
}
]
}
],
"nodes" : [
{
"file_name" : "nodes/genre.csv",
"separator" : ",",
"node" : ["~id", "genre"],
"features" : [
{
"feature": ["name", "genre", "category"],
"separator": ";"
}
]
},
{
"file_name" : "nodes/movie.csv",
"separator" : ",",
"node" : ["~id", "movie"],
"features" : [
{
"feature": ["title", "title", "word2vec"],
"language": ["en_core_web_lg"]
}
]
},
{
"file_name" : "nodes/user.csv",
"separator" : ",",
"node" : ["~id", "user"],
"features" : [
{
"feature": ["age", "age", "numerical"],
"norm" : "min-max",
"imputation": "median",
},
{
"feature": ["occupation", "occupation", "category"],
}
],
"labels" : [
{
"label": ["gender", "classification"],
"split_rate" : [0.8, 0.2, 0.0]
}
]
}
]
},
"warnings" : [ ]
]
}
```
# A estrutura dos arquivos de configuração de dados de treinamento JSON
O arquivo de configuração de treinamento se refere aos arquivos CSV salvos pelo processo de exportação nas pastas `nodes/` e `edges/`.
Cada arquivo em `nodes/` armazena informações sobre nós que têm o mesmo rótulo de nó do grafo de propriedades. Cada coluna em um arquivo de nó armazena o ID ou a propriedade do nó. A primeira linha do arquivo contém um cabeçalho que especifica o `~id` ou o nome da propriedade de cada coluna.
Cada arquivo em `edges/` armazena informações sobre nós que têm o mesmo rótulo de borda do grafo de propriedades. Cada coluna em um arquivo de nó armazena o ID do nó de origem, o ID do nó de destino ou a propriedade da borda. A primeira linha do arquivo contém um cabeçalho que especifica `~from`, `~to` ou o nome da propriedade de cada coluna.
O arquivo de configuração de dados de treinamento tem três elementos gerais:
```
{
"version" : "v2.0",
"query_engine" : "gremlin",
"graph" : [ ... ]
}
```
+ `version`: (string) a versão do arquivo de configuração que está sendo usado.
+ `query_engine`: (string) a linguagem de consulta usada para exportar os dados do grafo. No momento, somente “gremlin” é válido.
+ `graph`: (matriz JSON) lista um ou mais objetos de configuração que contêm parâmetros de modelo para cada um dos nós e bordas que serão usados.
Os objetos de configuração na matriz de grafos têm a estrutura descrita na próxima seção.
## Conteúdo de um objeto de configuração listado na matriz `graph`
Um objeto de configuração na matriz `graph` pode conter três nós gerais:
```
{
"edges" : [ ... ],
"nodes" : [ ... ],
"warnings" : [ ... ],
}
```
+ `edges`: (matriz de objetos JSON) cada objeto JSON especifica um conjunto de parâmetros para definir como uma borda no grafo será tratada durante o processamento e o treinamento de modelos. Isso só é usado com o mecanismo do Gremlin.
+ `nodes`: (matriz de objetos JSON) cada objeto JSON especifica um conjunto de parâmetros para definir como um nó no grafo será tratado durante o processamento e o treinamento de modelos. Isso só é usado com o mecanismo do Gremlin.
+ `warnings`: (matriz de objetos JSON) cada objeto contém um aviso gerado durante o processo de exportação de dados.
## Conteúdo de um objeto de configuração de borda listado na matriz `edges`
Um objeto de configuração de borda listado em uma matriz `edges` pode conter os seguintes campos gerais:
```
{
"file_name" : "(path to a CSV file)",
"separator" : "(separator character)",
"source" : ["(column label for starting node ID)", "(starting node type)"],
"relation" : ["(column label for the relationship name)", "(the prefix name for the relationship name)"],
"dest" : ["(column label for ending node ID)", "(ending node type)"],
"features" : [(array of feature objects)],
"labels" : [(array of label objects)]
}
```
+ **`file_name`**: uma string especificando o caminho para um arquivo CSV que armazena informações sobre bordas com o mesmo rótulo de grafo de propriedades.
A primeira linha desse arquivo contém uma linha de cabeçalho de rótulos de coluna.
Os dois primeiros rótulos de coluna são `~from` e `~to`. A primeira coluna (`~from`) armazena o ID do nó inicial da borda e a segunda (`~to`) armazena o ID do nó final da borda.
Os rótulos das colunas restantes na linha do cabeçalho especificam, para cada coluna restante, o nome da propriedade da borda cujos valores foram exportados para essa coluna.
+ **`separator`**: uma string contendo o delimitador que separa as colunas nesse arquivo CSV.
+ **`source`**: uma matriz JSON contendo duas strings que especificam o nó inicial da borda. A primeira string contém o nome do cabeçalho da coluna na qual o ID do nó inicial está armazenado. A segunda string especifica o tipo de nó.
+ **`relation`**: uma matriz JSON contendo duas strings que especificam o tipo de relação da borda. A primeira string contém o nome do cabeçalho da coluna na qual o nome da relação (`relname`) está armazenado. A segunda string contém o prefixo para o nome da relação (`prefixname`).
O tipo de relação completo consiste em duas strings combinadas, com um caractere de hífen entre elas, como: `prefixname-relname`.
Se a primeira string estiver vazia, todas as bordas terão o mesmo tipo de relação, ou seja, a string `prefixname`.
+ **`dest`**: uma matriz JSON contendo duas strings que especificam o nó final da borda. A primeira string contém o nome do cabeçalho da coluna na qual o ID do nó está armazenado. A segunda string especifica o tipo de nó.
+ **`features`**: uma matriz JSON de objetos de atributos de valor de propriedade. Cada objeto de atributo de valor de propriedade contém os seguintes campos:
+ **atributo**: uma matriz JSON de três strings. A primeira string contém o nome do cabeçalho da coluna que contem o valor de propriedade. A segunda string contém o nome do atributo. A terceira string contém o tipo de atributo.
+ **norma**: (*opcional*) especifica um método de normalização a ser aplicado aos valores da propriedade.
+ **`labels`**: uma matriz JSON de objetos. Cada um dos objetos define um atributo de destino das bordas e especifica as proporções das bordas que as fases de treinamento e validação devem assumir. Cada objeto contém os seguintes campos:
+ **rótulo**: uma matriz JSON de duas strings. A primeira string contém o nome do cabeçalho da coluna que contem o valor de propriedade do atributo de destino. A segunda string especifica um dos seguintes tipos de tarefa de destino:
+ `"classification"`: uma tarefa de classificação de borda. Os valores das propriedades fornecidos na coluna identificada pela primeira string na matriz `label` são tratados como valores categóricos. Para uma tarefa de classificação de bordas, a primeira string na matriz `label` não pode estar vazia.
+ `"regression"`: uma tarefa de regressão de bordas. Os valores das propriedades fornecidos na coluna identificada pela primeira string na matriz `label` são tratados como valores numéricos. Para uma tarefa de regressão de bordas, a primeira string na matriz `label` não pode estar vazia.
+ `"link_prediction"`: uma tarefa de previsão de links. Nenhum valor de propriedade é obrigatório. Para uma tarefa de previsão de links, a primeira string na matriz `label` é ignorada.
+ **`split_rate`**: uma matriz JSON contendo três números entre zero e um que somam um e representam uma estimativa das proporções de nós que as fases de treinamento, validação e teste usarão, respectivamente. Esse campo ou `custom_split_filenames` podem ser definidos, mas não ambos. Veja [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate).
+ **`custom_split_filenames`**: um objeto JSON que especifica os nomes dos arquivos que definem as populações de treinamento, validação e teste. Esse campo ou `split_rate` podem ser definidos, mas não ambos. Consulte [train-validation-testProporções personalizadas](#machine-learning-custom-stages-splits) para obter mais informações.
## Conteúdo de um objeto de configuração de nó listado na matriz `nodes`
Um objeto de configuração de nó listado em uma matriz `nodes` pode conter os seguintes campos:
```
{
"file_name" : "(path to a CSV file)",
"separator" : "(separator character)",
"node" : ["(column label for the node ID)", "(node type)"],
"features" : [(feature array)],
"labels" : [(label array)],
}
```
+ **`file_name`**: uma string especificando o caminho para um arquivo CSV que armazena informações sobre nó com o mesmo rótulo de grafo de propriedades.
A primeira linha desse arquivo contém uma linha de cabeçalho de rótulos de coluna.
O rótulo da primeira coluna é `~id`, e a primeira coluna (`~id`) armazena o ID do nó.
Os rótulos das colunas restantes na linha do cabeçalho especificam, para cada coluna restante, o nome da propriedade do nó cujos valores foram exportados para essa coluna.
+ **`separator`**: uma string contendo o delimitador que separa as colunas nesse arquivo CSV.
+ **`node`**: uma matriz JSON contendo duas strings. A primeira string contém o nome do cabeçalho da coluna que armazena o nó IDs. A segunda string especifica o tipo de nó no grafo, que corresponde a um rótulo de grafo de propriedades do nó.
+ **`features`**: uma matriz JSON de objetos de atributos de nós. Consulte [Conteúdo de um objeto de atributo listado em uma matriz `features` para um nó ou uma borda](#machine-learning-graph-node-features-config).
+ **`labels`**: uma matriz JSON de objetos de rótulos de nós. Consulte [Conteúdo de um objeto de rótulo de nó listado em uma matriz `labels` de nós](#machine-learning-graph-node-labels-config).
## Conteúdo de um objeto de atributo listado em uma matriz `features` para um nó ou uma borda
Um objeto de atributo de nó listado em uma matriz `features` de nó pode conter os seguintes campos gerais:
+ **`feature`**: uma matriz JSON de três strings. A primeira string contém o nome do cabeçalho da coluna que contem o valor de propriedade do atributo. A segunda string contém o nome do atributo.
A terceira string contém o tipo de atributo. Os tipos de atributos válidos estão listados em [Valores possíveis do campo de tipo para recursos](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-feature-types).
+ **`norm`**: esse campo é obrigatório para atributos numéricos. Ele especifica um método de normalização a ser usado em valores numéricos. Os valores válidos são `"none"`, `"min-max"` e “padrão”. Para obter detalhes, consulte [O campo norma](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-norm).
+ **`language`**: o campo de idioma especifica o idioma usado nos valores das propriedades de texto. O uso depende do método de codificação de texto:
+ Para a codificação [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), esse campo é obrigatório e deve especificar um dos seguintes idiomas:
+ `en` (inglês)
+ `zh` (chinês)
+ `hi` (hindi)
+ `es` (espanhol)
+ `fr` (francês)
No entanto, `text_fasttext` não consegue lidar com mais de um idioma por vez.
+ Para a codificação [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), esse campo não é usado, pois a codificação SBERT é multilíngue.
+ Para a codificação [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features), esse campo é opcional, pois `text_word2vec` só é compatível com inglês. Se presente, ele deve especificar o nome do modelo em inglês:
```
"language" : "en_core_web_lg"
```
+ Para a codificação [`tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features), esse campo não é usado.
+ **`max_length`**: esse campo é opcional para atributos [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), no qual ele especifica o número máximo de tokens em um atributo de texto de entrada que será codificado. O texto de entrada após `max_length` ser atingido é ignorado. Por exemplo, definir max\$1length como 128 indica que qualquer token após o 128º em uma sequência de texto será ignorado.
+ **`separator`**: esse campo é usado opcionalmente com os atributos `category`, `numerical` e `auto`. Ele especifica um caractere que pode ser usado para dividir o valor de uma propriedade em vários valores categóricos ou valores numéricos.
Consulte [O campo separador](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-separator).
+ **`range`**: esse campo é obrigatório para atributos `bucket_numerical`. Ele especifica o intervalo de valores numéricos que devem ser divididos em buckets.
Consulte [O campo intervalo](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-range).
+ **`bucket_cnt`**: esse campo é obrigatório para atributos `bucket_numerical`. Ele especifica o número de buckets nos quais o intervalo numérico definido pelo parâmetro `range` deve ser dividido:
Consulte [Atributos numéricos de bucket no Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features).
+ **`slide_window_size`**: esse campo é usado opcionalmente com atributos `bucket_numerical` para atribuir valores a mais de um bucket:
Consulte [O campo slide\$1window\$1size](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-slide_window_size).
+ **`imputer`**: esse campo é usado opcionalmente com atributos `numerical`, `bucket_numerical` e `datetime` para fornecer uma técnica de imputação a fim de preencher valores ausentes. As técnicas de imputação compatíveis são `"mean"`, `"median"` e `"most_frequent"`.
Consulte [O campo estimador](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-imputer).
+ **`max_features`**: esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar o número máximo de termos a serem codificados.
Consulte [O campo max\$1features](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-max_features).
+ **`min_df`**: esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar a frequência mínima de documentos de termos a serem codificados.
Consulte [O campo min\$1df](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-min_df).
+ **`ngram_range`**: esse campo é usado opcionalmente pelos atributos `text_tfidf` para especificar um intervalo de números de palavras ou tokens a serem considerados como possíveis termos individuais a serem codificados.
Consulte [O campo ngram\$1range](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-ngram_range).
+ **`datetime_parts`**: esse campo é usado opcionalmente pelos atributos `datetime` para especificar quais partes do valor de data e hora devem ser codificadas categoricamente:
Consulte [O campo datetime\$1parts](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-datetime_parts).
## Conteúdo de um objeto de rótulo de nó listado em uma matriz `labels` de nós
Um objeto de rótulo listado em uma matriz `labels` de nós define um atributo de destino de nó e especifica as proporções dos nós que as fases de treinamento, validação e teste usarão. Cada objeto pode conter os seguintes campos:
```
{
"label" : ["(column label for the target feature property value)", "(task type)"],
"split_rate" : [(training proportion), (validation proportion), (test proportion)],
"custom_split_filenames" : {"train": "(training file name)", "valid": "(validation file name)", "test": "(test file name)"},
"separator" : "(separator character for node-classification category values)",
}
```
+ **`label`**: uma matriz JSON contendo duas strings. A primeira string contém o nome do cabeçalho da coluna que armazena os valores de propriedade do atributo. A segunda string especifica o tipo de tarefa de destino, que pode ser:
+ `"classification"`: uma tarefa de classificação de nós. Os valores das propriedades na coluna especificada são usados para criar um atributo categórico.
+ `"regression"`: uma tarefa de regressão de nós. Os valores das propriedades na coluna especificada são usados para criar um atributo numérico.
+ **`split_rate`**: uma matriz JSON contendo três números entre zero e um que somam um e representam uma estimativa das proporções de nós que as fases de treinamento, validação e teste usarão, respectivamente. Consulte [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate).
+ **`custom_split_filenames`**: um objeto JSON que especifica os nomes dos arquivos que definem as populações de treinamento, validação e teste. Esse campo ou `split_rate` podem ser definidos, mas não ambos. Consulte [train-validation-testProporções personalizadas](#machine-learning-custom-stages-splits) para obter mais informações.
+ **`separator`**: uma string contendo o delimitador que separa os valores de atributos categóricos de uma tarefa de classificação.
**nota**
Se nenhum objeto de rótulo for fornecido para bordas e nós, a tarefa será automaticamente considerada como previsão de links, e as bordas serão divididas aleatoriamente em 90% para treinamento e 10% para validação.
## train-validation-testProporções personalizadas
Por padrão, o parâmetro `split_rate` é usado pelo Neptune ML para dividir o grafo aleatoriamente em populações de treinamento, validação e teste usando as proporções definidas nesse parâmetro. Para ter um controle mais preciso sobre quais entidades são usadas nessas diferentes populações, podem ser criados arquivos que as definam explicitamente e, depois, o [arquivo de configuração de dados de treinamento pode ser editado](machine-learning-processing-training-config-file.md) para associar esses arquivos de indexação às populações. Esse mapeamento é especificado por um objeto JSON para a chave [`custom_split_filesnames`](#custom_split_filenames) no arquivo de configuração de treinamento. Se essa opção for usada, os nomes dos arquivos deverão ser fornecidos para as chaves `train` e `validation` e é opcional para a chave `test`.
A formatação desses arquivos deve corresponder ao [formato de dados do Gremlin](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-systemheaders). Especificamente, para tarefas em nível de nó, cada arquivo deve conter uma coluna com o `~id` cabeçalho que lista o nó e IDs, para tarefas em nível de borda, os arquivos devem especificar `~from` e `~to` indicar os nós de origem e destino das bordas, respectivamente. Esses arquivos precisam ser colocados no mesmo local do Amazon S3 que os dados exportados que são usados para processamento de dados (consulte: [`outputS3Path`](export-parameters.md#export-parameters-outputS3Path)).
Para tarefas de classificação ou regressão de propriedades, esses arquivos podem definir os rótulos para a tarefa de machine learning. Nesse caso, os arquivos precisam ter uma coluna de propriedades com o mesmo nome de cabeçalho [definido no arquivo de configuração de dados de treinamento](#machine-learning-graph-node-labels-config). Se os rótulos de propriedades forem definidos nos arquivos de nó e borda exportados e nos arquivos de divisão personalizada, a prioridade será fornecida aos arquivos de divisão personalizada.
# Treinar um modelo usando o Neptune ML
Depois de exportar os dados exportados do Neptune para treinamento de modelos, é possível iniciar um trabalho de processamento de modelos usando um comando `curl` (ou `awscurl`) como o seguinte:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
}'
```
Os detalhes de como usar esse comando são explicados em [O comando modeltraining](machine-learning-api-modeltraining.md), junto com informações sobre como obter o status de um trabalho em execução, como interrompê-lo e como listar todos os trabalhos em execução.
Você também pode fornecer um `previousModelTrainingJobId` para usar informações de um trabalho de treinamento de modelos do Neptune ML concluído para acelerar a pesquisa de hiperparâmetros em um novo trabalho de treinamento. Isso é útil durante o [novo treinamento de modelos em novos dados de grafos](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-model-retraining), bem como no [treinamento incremental nos mesmos dados de grafos](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental). Use um comando como este:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
"previousModelTrainingJobId" : "(the model-training job-id of a completed job)"
}'
```
É possível treinar sua própria implementação de modelos na infraestrutura de treinamento do Neptune ML fornecendo um objeto `customModelTrainingParameters`, como este:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
"modelName": "custom",
"customModelTrainingParameters" : {
"sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)",
"trainingEntryPointScript": "(your training script entry-point name in the Python module)",
"transformEntryPointScript": "(your transform script entry-point name in the Python module)"
}
}'
```
Consulte [O comando modeltraining](machine-learning-api-modeltraining.md) para obter mais informações, por exemplo, sobre como obter o status de um trabalho em execução, como interrompê-lo e como listar todos os trabalhos em execução. Consulte [Modelos personalizados no Neptune ML](machine-learning-custom-models.md) para obter informações sobre como implementar e usar um modelo personalizado.
**Topics**
+ [Modelos e treinamento de modelos no Amazon Neptune ML](machine-learning-models-and-training.md)
+ [Personalizar as configurações de hiperparâmetros do modelo no Neptune ML](machine-learning-customizing-hyperparams.md)
+ [Práticas recomendadas para treinamento de modelos](machine-learning-improve-model-performance.md)
# Modelos e treinamento de modelos no Amazon Neptune ML
O Neptune ML usa redes neurais para grafos (GNN) a fim de criar modelos para as várias tarefas de machine learning. Foi demonstrado que as redes neurais para grafos obtêm resultados de última geração para tarefas de machine learning para grafos e são excelentes para extrair padrões informativos de dados estruturados em grafos.
## Redes neurais para grafos (GNNs) no Neptune ML
As redes neurais para grafos (GNNs) pertencem a uma família de redes neurais que calculam representações de nós levando em consideração a estrutura e os atributos dos nós próximos. As GNNs complementam outros métodos tradicionais de machine learning e rede neural que não são adequados para dados de grafos.
As GNNs são usadas para resolver tarefas de machine learning, como classificação e regressão de nós (previsão de propriedades de nós) e classificação e regressão de bordas (previsão de propriedades de bordas) ou previsão de links (previsão se dois nós no grafo devem estar conectados ou não).
Em geral, o uso de uma GNN para uma tarefa de machine learning envolve duas fases:
+ Uma fase de codificação, em que s GNN calcula um vetor d-dimensional para cada nó no grafo. Esses vetores também são denominados *representações* ou *incorporações*.
+ Uma fase de decodificação, que faz previsões com base nas representações codificadas.
Para classificação e regressão de nós, as representações de nós são usadas diretamente para as tarefas de classificação e regressão. Para classificação e regressão de bordas, as representações dos nós incidentes em uma borda são usadas como entrada para a classificação ou a regressão. Para previsão de links, uma pontuação de probabilidade de borda é calculada usando um par de representações de nós e uma representação do tipo de borda.
A [Deep Graph Library (DGL)](https://www.dgl.ai/) viabiliza a definição e o treinamento eficientes de GNNs para essas tarefas.
Diferentes modelos de GNN são unificados sob a formulação da transmissão de mensagens. Nessa visualização, a representação de um nó em um grafo é calculada usando as representações dos vizinhos do nó (as mensagens), junto com a representação inicial do nó. No NeptuneML, a representação inicial de um nó é derivada dos atributos extraídos de suas propriedades do nó ou pode ser aprendida e depende da identidade do nó.
O Neptune ML também oferece a opção de concatenar atributos de nós e representações de nós que podem ser aprendidos para servir como representação do nó original.
Para as várias tarefas no Neptune ML envolvendo grafos com propriedades de nós, usamos a [Relational Graph Convolutional Network](https://arxiv.org/abs/1703.06103) (R-GCN) para realizar a fase de codificação. A R-GCN é uma arquitetura de GNN adequada para grafos com vários tipos de nós e bordas (conhecidos como grafos heterogêneos).
A rede R-GCN consiste em um número fixo de camadas, empilhadas uma após a outra. Cada camada da R-GCN usa seus parâmetros de modelo que podem ser aprendidos para agregar informações da vizinhança imediata de 1 salto de um nó. Como as camadas subsequentes usam as representações de saída da camada anterior como entrada, o raio da vizinhança do grafo que influencia a incorporação final de um nó depende do número de camadas (`num-layer`) da rede R-GCN.
Por exemplo, isso significa que uma rede de duas camadas usa informações de nós que estão a dois saltos de distância.
Para saber mais sobre GNNs, consulte [A Comprehensive Survey on Graph Neural Networks](https://arxiv.org/abs/1901.00596). Para obter mais informações sobre a Deep Graph Library (DGL), visite a [página da web](https://www.dgl.ai/) da DGL. Para ver um tutorial prático sobre como usar a DGL com GNNs, consulte [Learning graph neural networks with Deep Graph Library](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library).
## Treinar redes neurais para grafos
No machine learning, o processo de obter um modelo para aprender a fazer boas previsões para uma tarefa é chamado de treinamento de modelos. Em geral, isso é realizado especificando um objetivo específico a ser otimizado, bem como um algoritmo a ser usado para realizar essa otimização.
Esse processo também é empregado no treinamento de uma GNN para aprender boas representações para a tarefa posterior. Criamos uma função objetiva para essa tarefa que é minimizada durante o treinamento de modelos. Por exemplo, para classificação de nós, usamos [CrossEntropyLoss](https://pytorch.org/docs/stable/generated/torch.nn.CrossEntropyLoss.html) como o objetivo, o que penaliza erros de classificação, e para regressão de nós minimizamos o [MeanSquareError](https://pytorch.org/docs/stable/generated/torch.nn.MSELoss.html).
O objetivo geralmente é uma função de perda que pega as previsões do modelo para um ponto de dados específico e as compara ao valor verdadeiro básico desse ponto de dados. Ela exibe o valor da perda, que mostra o quão distantes estão as previsões do modelo. O objetivo do processo de treinamento é minimizar a perda e garantir que as previsões do modelo estejam próximas da verdade.
O algoritmo de otimização usado no machine learning para o processo de treinamento geralmente é uma variante do gradiente descendente. No Neptune ML, usamos [Adam](https://arxiv.org/pdf/1412.6980.pdf), que é um algoritmo para otimização baseada em gradiente de primeira ordem de funções objetivas estocásticas com base em estimativas adaptativas de momentos de ordem inferior.
Embora o processo de treinamento de modelos tente garantir que os parâmetros do modelo aprendido estejam próximos dos mínimos da função objetiva, o desempenho geral de um modelo também depende dos *hiperparâmetros* do modelo, que são configurações do modelo que não são aprendidas pelo algoritmo de treinamento. Por exemplo, a dimensionalidade da representação do nó aprendido, `num-hidden`, é um hiperparâmetro que afeta o desempenho do modelo. Portanto, é comum no machine learning realizar a otimização de hiperparâmetros (HPO) para escolher os hiperparâmetros adequados.
O Neptune ML usa uma tarefa de ajuste de hiperparâmetros do SageMaker AI para iniciar várias instâncias de treinamento de modelo com diferentes configurações de hiperparâmetros para tentar encontrar o melhor modelo para uma variedade de configurações de hiperparâmetros. Consulte [Personalizar as configurações de hiperparâmetros do modelo no Neptune ML](machine-learning-customizing-hyperparams.md).
## Modelos de incorporação de grafos de conhecimento no Neptune ML
Grafos de conhecimento (KGs) são grafos que codificam informações sobre diferentes entidades (nós) e suas relações (bordas). No Neptune ML, os modelos de incorporação de grafos de conhecimento são aplicados por padrão para realizar a previsão de links quando o grafo não contém propriedades de nós, somente relações com outros nós. Embora os modelos de R-GCN com incorporações que podem ser aprendidas também possam ser usados para esses grafos especificando o tipo de modelo como `"rgcn"`, os modelos de incorporação de grafos de conhecimento são mais simples e foram projetados para ser eficazes para aprender representações de grafos de conhecimento em grande escala.
Os modelos de incorporação de grafos de conhecimento são usados em uma tarefa de previsão de links para prever os nós ou relações que completam uma `(h, r, t)` tripla em que `h` é o nó de origem, `r` é o tipo de relação e `t` é o nó de destino.
Os modelos de incorporação de grafos de conhecimento implementados no Neptune ML são `distmult`, `transE` e `rotatE`. Para saber mais sobre os modelos de incorporação de grafos de conhecimento, consulte [DGL-KE](https://github.com/awslabs/dgl-ke).
## Treinar modelos personalizados no Neptune ML
O Neptune ML permite definir e implementar os próprios modelos personalizados, para cenários específicos. Consulte [Modelos personalizados no Neptune ML](machine-learning-custom-models.md) para obter informações sobre como implementar um modelo personalizado e como usar a infraestrutura do Neptune ML para treiná-lo.
# Personalizar as configurações de hiperparâmetros do modelo no Neptune ML
Quando você inicia um trabalho de treinamento de modelos do Neptune ML, o Neptune ML usa automaticamente as informações inferidas do trabalho de [processamento de dados](machine-learning-on-graphs-processing.md) anterior. Ele usa as informações para gerar intervalos de configuração de hiperparâmetros que são usados para criar um [trabalho de ajuste de hiperparâmetros de SageMaker IA](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-how-it-works.html) para treinar vários modelos para sua tarefa. Dessa forma, você não precisa especificar uma longa lista de valores de hiperparâmetros com os quais os modelos serão treinados. Em vez disso, os intervalos e os padrões dos hiperparâmetros do modelo são selecionados com base no tipo de tarefa, no tipo de grafo e nas configurações do trabalho de ajuste.
No entanto, você também pode substituir a configuração padrão de hiperparâmetros e fornecer hiperparâmetros personalizados modificando um arquivo de configuração JSON que o trabalho de processamento de dados gera.
Usando a [API modelTraining](machine-learning-api-modeltraining.md) do Neptune ML, é possível controlar várias configurações de trabalhos de ajuste de hiperparâmetros gerais, como `maxHPONumberOfTrainingJobs`, `maxHPOParallelTrainingJobs` e `trainingInstanceType`. Para um controle mais refinado sobre os hiperparâmetros do modelo, você pode personalizar o arquivo `model-HPO-configuration.json` que o trabalho de processamento de dados gera. O arquivo é salvo no local do Amazon S3 que você especificou para a saída do trabalho de processamento.
É possível baixar o arquivo, editá-lo para substituir as configurações padrão de hiperparâmetros e enviá-lo de volta para o mesmo local do Amazon S3. Não altere o nome do arquivo e siga estas instruções ao editar.
Como baixar o arquivo do Amazon S3:
```
aws s3 cp \
s3://(bucket name)/(path to output folder)/model-HPO-configuration.json \
./
```
Quando terminar de editar, faça upload do arquivo de volta para onde estava:
```
aws s3 cp \
model-HPO-configuration.json \
s3://(bucket name)/(path to output folder)/model-HPO-configuration.json
```
## Estrutura do arquivo `model-HPO-configuration.json`
O arquivo `model-HPO-configuration.json` especifica o modelo a ser treinado, o `task_type` de machine learning e os hiperparâmetros que devem ser variados ou fixos para as várias execuções de treinamento do modelo.
Os hiperparâmetros são categorizados como pertencentes a vários níveis, o que significa a precedência dada aos hiperparâmetros quando o trabalho de ajuste do hiperparâmetro é invocado:
+ Os hiperparâmetros de nível 1 têm a maior precedência. Se você definir `maxHPONumberOfTrainingJobs` como um valor menor que 10, somente os hiperparâmetros de nível 1 serão ajustados, e o restante assumirá seus valores padrão.
+ Os hiperparâmetros de nível 2 têm menor precedência; portanto, se você tiver mais de 10, mas menos de 50 trabalhos de treinamento no total para um trabalho de ajuste, os hiperparâmetros de nível 1 e nível 2 serão ajustados.
+ Os hiperparâmetros de nível 3 são ajustados junto com os níveis 1 e 2 somente se você tiver mais de 50 trabalhos de treinamento no total.
+ Por fim, os hiperparâmetros fixos não são ajustados e sempre assumem seus valores padrão.
### Exemplo de arquivo `model-HPO-configuration.json`
Veja a seguir um exemplo de arquivo `model-HPO-configuration.json`:
```
{
"models": [
{
"model": "rgcn",
"task_type": "node_class",
"eval_metric": {
"metric": "acc"
},
"eval_frequency": {
"type": "evaluate_every_epoch",
"value": 1
},
"1-tier-param": [
{
"param": "num-hidden",
"range": [16, 128],
"type": "int",
"inc_strategy": "power2"
},
{
"param": "num-epochs",
"range": [3,30],
"inc_strategy": "linear",
"inc_val": 1,
"type": "int",
"node_strategy": "perM"
},
{
"param": "lr",
"range": [0.001,0.01],
"type": "float",
"inc_strategy": "log"
}
],
"2-tier-param": [
{
"param": "dropout",
"range": [0.0,0.5],
"inc_strategy": "linear",
"type": "float",
"default": 0.3
},
{
"param": "layer-norm",
"type": "bool",
"default": true
}
],
"3-tier-param": [
{
"param": "batch-size",
"range": [128, 4096],
"inc_strategy": "power2",
"type": "int",
"default": 1024
},
{
"param": "fanout",
"type": "int",
"options": [[10, 30],[15, 30], [15, 30]],
"default": [10, 15, 15]
},
{
"param": "num-layer",
"range": [1, 3],
"inc_strategy": "linear",
"inc_val": 1,
"type": "int",
"default": 2
},
{
"param": "num-bases",
"range": [0, 8],
"inc_strategy": "linear",
"inc_val": 2,
"type": "int",
"default": 0
}
],
"fixed-param": [
{
"param": "concat-node-embed",
"type": "bool",
"default": true
},
{
"param": "use-self-loop",
"type": "bool",
"default": true
},
{
"param": "low-mem",
"type": "bool",
"default": true
},
{
"param": "l2norm",
"type": "float",
"default": 0
}
]
}
]
}
```
### Elementos de um arquivo `model-HPO-configuration.json`
O arquivo contém um objeto JSON com uma única matriz de nível superior chamada `models` que contém um único objeto de configuração de modelo. Ao personalizar o arquivo, assegure-se de que a matriz `models` tenha somente um objeto de configuração de modelo. Se seu arquivo contiver mais de um objeto de configuração de modelo, o trabalho de ajuste falhará com um aviso.
O objeto de configuração do modelo contém os seguintes elementos gerais:
+ **`model`**: (*string*) O tipo de modelo a ser treinado (**não modifique**). Os valores válidos são:
+ `"rgcn"`: é o padrão para tarefas de classificação e regressão de nós e para tarefas de previsão de links heterogêneos.
+ `"transe"`: é o padrão para as tarefas de previsão de links do KGE.
+ `"distmult"`: é um tipo de modelo alternativo para tarefas de previsão de links do KGE.
+ `"rotate"`: é um tipo de modelo alternativo para tarefas de previsão de links do KGE.
Como regra, não modifique diretamente o valor `model`, pois tipos de modelos diferentes geralmente têm hiperparâmetros aplicáveis substancialmente diferentes, o que pode gerar um erro de análise após o início do trabalho de treinamento.
Para alterar o tipo de modelo, use o parâmetro `modelName` na [API modelTraining](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job) em vez de alterá-lo no arquivo `model-HPO-configuration.json`.
Uma forma de alterar o tipo de modelo e fazer alterações detalhadas nos hiperparâmetros é copiar o modelo padrão de configuração do modelo no modelo que você deseja usar e colá-lo no arquivo `model-HPO-configuration.json`. Haverá uma pasta denominada `hpo-configuration-templates` no mesmo local do Amazon S3 que o arquivo `model-HPO-configuration.json` se o tipo de tarefa inferido for compatível com vários modelos. Essa pasta contém todas as configurações padrão de hiperparâmetros para os outros modelos aplicáveis à tarefa.
Por exemplo, se você quiser alterar as configurações de modelo e hiperparâmetros para uma tarefa de previsão de link `KGE` do modelo padrão `transe` para um modelo `distmult`, basta colar o conteúdo do arquivo `hpo-configuration-templates/distmult.json` no arquivo `model-HPO-configuration.json` e editar os hiperparâmetros conforme necessário.
**nota**
Se você definir o parâmetro `modelName` na API `modelTraining` e também alterar a especificação `model` e de hiperparâmetros no arquivo `model-HPO-configuration.json`, e elas forem diferentes, o valor `model` no arquivo `model-HPO-configuration.json` terá precedência, e o valor `modelName` será ignorado.
+ **`task_type`**: (*String*) O tipo de tarefa de machine learning inferido ou passado diretamente para o trabalho de processamento de dados (**não modifique**). Os valores válidos são:
+ `"node_class"`
+ `"node_regression"`
+ `"link_prediction"`
O trabalho de processamento de dados infere o tipo de tarefa examinando o conjunto de dados exportado e o arquivo de configuração do trabalho de treinamento gerado para conferir as propriedades do conjunto de dados.
Esse valor não deve ser alterado. Se você quiser treinar uma tarefa diferente, precisará [executar um novo trabalho de processamento de dados](machine-learning-on-graphs-processing.md). Se o valor `task_type` não for o esperado, confira as entradas do seu trabalho de processamento de dados para ter certeza de que estão corretas. Isso inclui parâmetros para a API `modelTraining`, bem como no arquivo de configuração do trabalho de treinamento gerado pelo processo de exportação de dados.
+ **`eval_metric`**: (*String*) a métrica de avaliação deve ser usada para avaliar o desempenho do modelo e selecionar o modelo com melhor desempenho em todas as execuções de HPO. Os valores válidos são:
+ `"acc"`: precisão de classificação padrão. É o padrão para tarefas de classificação de rótulo único, a menos que rótulos não equilibrados sejam encontrados durante o processamento de dados. Nesse caso, o padrão será `"F1"`.
+ `"acc_topk"`: o número de vezes que o rótulo correto está entre as principais previsões **`k`**. Também é possível definir o valor **`k`** transmitindo `topk` como uma chave extra.
+ `"F1"`: a [pontuação da F1](https://en.wikipedia.org/wiki/F-score).
+ `"mse"`: [métrica de erro quadrático médio](https://en.wikipedia.org/wiki/Mean_squared_error), para tarefas de regressão.
+ `"mrr"`: [métrica média de classificação recíproca](https://en.wikipedia.org/wiki/Mean_reciprocal_rank).
+ `"precision"`: a precisão do modelo, calculada como a razão entre os positivos verdadeiros e os positivos previstos: `= true-positives / (true-positives + false-positives)`.
+ `"recall"`: a chamada do modelo, calculada como a razão entre os positivos verdadeiros e os positivos reais: `= true-positives / (true-positives + false-negatives)`.
+ `"roc_auc"`: a área abaixo da [curva ROC](https://en.wikipedia.org/wiki/Receiver_operating_characteristic). Esse é o padrão para classificação com vários rótulos.
Por exemplo, para alterar a métrica para `F1`, altere o valor `eval_metric` da seguinte forma:
```
" eval_metric": {
"metric": "F1",
},
```
Ou para alterar a métrica para uma pontuação de precisão `topk`, você mudaria a `eval_metric` da seguinte forma:
```
"eval_metric": {
"metric": "acc_topk",
"topk": 2
},
```
+ **`eval_frequency`**: (*Objeto*) Especifica com que frequência durante o treinamento o desempenho do modelo no conjunto de validação deve ser conferido. Com base no desempenho da validação, a parada antecipada pode então ser iniciada e o melhor modelo pode ser salvo.
O objeto `eval_frequency` contém dois elementos, a saber, `"type"` e `"value"`. Por exemplo:
```
"eval_frequency": {
"type": "evaluate_every_pct",
"value": 0.1
},
```
Os valores `type` válidos são:
+ **`evaluate_every_pct`**: especifica a porcentagem de treinamento a ser concluído para cada avaliação.
Para `evaluate_every_pct`, o campo `"value"` contém um número de ponto flutuante entre zero e um que expressa essa porcentagem.
+ **`evaluate_every_batch`**: especifica o número de treinamento a ser concluído para cada avaliação.
Para `evaluate_every_batch`, o campo `"value"` contém um número inteiro que expressa essa contagem de lotes.
+ **`evaluate_every_epoch`**: especifica o número de épocas por avaliação, em que uma nova época começa à meia-noite.
Para `evaluate_every_epoch`, o campo `"value"` contém um número inteiro que expressa essa contagem de épocas.
A configuração padrão para `eval_frequency` é:
```
"eval_frequency": {
"type": "evaluate_every_epoch",
"value": 1
},
```
+ **`1-tier-param`**: (*Obrigatório*) Uma matriz de hiperparâmetros de nível 1.
Se não quiser ajustar nenhum hiperparâmetro, você poderá definir isso como uma matriz vazia. Isso não afeta o número total de trabalhos de treinamento lançados pelo trabalho de ajuste de hiperparâmetros de SageMaker IA. Significa apenas que todos os trabalhos de treinamento, se houver mais de 1, mas menos de 10, serão executados com o mesmo conjunto de hiperparâmetros.
Por outro lado, se você quiser tratar todos os seus hiperparâmetros ajustáveis com igual importância, poderá colocar todos os hiperparâmetros nessa matriz.
+ **`2-tier-param`**: (*obrigatório*) uma matriz de hiperparâmetros de nível 2.
Esses parâmetros serão ajustados somente se `maxHPONumberOfTrainingJobs` tiver um valor maior que 10. Caso contrário, eles serão fixados nos valores padrão.
Se você tiver um orçamento de treinamento de no máximo 10 trabalhos de treinamento ou não quiser hiperparâmetros de nível 2 por qualquer outro motivo, mas quiser ajustar todos os hiperparâmetros ajustáveis, defina isso como uma matriz vazia.
+ **`3-tier-param`**: (*obrigatório*) uma matriz de hiperparâmetros de nível 3.
Esses parâmetros serão ajustados somente se `maxHPONumberOfTrainingJobs` tiver um valor maior que 50. Caso contrário, eles serão fixados nos valores padrão.
Se não quiser ajustar nenhum hiperparâmetro de nível 3, você poderá definir isso como uma matriz vazia.
+ **`fixed-param`**: (*obrigatório*) uma matriz de hiperparâmetros fixos que usam apenas seus valores padrão e não variam em diferentes trabalhos de treinamento.
Se quiser variar todos os hiperparâmetros, você poderá definir isso como uma matriz vazia e definir o valor como `maxHPONumberOfTrainingJobs` grande o suficiente para variar todos os níveis ou tornar todos os hiperparâmetros de nível 1.
O objeto JSON que representa cada hiperparâmetro em `1-tier-param`, `2-tier-param`, `3-tier-param` e `fixed-param` contém os seguintes elementos:
+ **`param`**: (*string*) o nome do hiperparâmetro (**não altere**).
Veja a [lista de nomes de hiperparâmetros válidos no Neptune ML](#machine-learning-hyperparams-list).
+ **`type`**: (*string*) o tipo de hiperparâmetro (**não altere**).
Os tipos válidos são `bool`, `int` e `float`.
+ **`default`**: (*string*) o valor padrão para o hiperparâmetro.
Você pode definir um novo valor padrão.
Os hiperparâmetros ajustáveis também podem conter os seguintes elementos:
+ **`range`**: (*matriz*) o intervalo de um hiperparâmetro ajustável contínuo.
Deve ser uma matriz com dois valores, ou seja, o mínimo e o máximo do intervalo (`[min, max]`).
+ **`options`**: (*matriz*) as opções para um hiperparâmetro categórico ajustável.
Essa matriz deve conter todas as opções a serem consideradas:
```
"options" : [value1, value2, ... valuen]
```
+ **`inc_strategy`**: (*string*) o tipo de alteração incremental para intervalos contínuos de hiperparâmetros ajustáveis (**não altere**).
Os valores válidos são `log`, `linear` e `power2`. Aplica-se somente quando a chave de intervalo é definida.
Modificar isso pode resultar no não uso de todo o intervalo de seu hiperparâmetro para ajuste.
+ **`inc_val`** (*float*) a quantidade pela qual os incrementos sucessivos diferem para hiperparâmetros ajustáveis contínuos (**não altere**).
Aplica-se somente quando a chave de intervalo é definida.
Modificar isso pode resultar no não uso de todo o intervalo de seu hiperparâmetro para ajuste.
+ **`node_strategy`**: (*string*) indica que o intervalo efetivo desse hiperparâmetro deve mudar com base no número de nós no grafo (**não altere**).
Os valores válidos são `"perM"` (por milhão), `"per10M"` (por 10 milhões) e `"per100M"` (por 100 milhões).
Em vez de alterar esse valor, altere `range`.
+ **`edge_strategy`**: (*string*) indica que o intervalo efetivo desse hiperparâmetro deve mudar com base no número de bordas no grafo (**não altere**).
Os valores válidos são `"perM"` (por milhão), `"per10M"` (por 10 milhões) e `"per100M"` (por 100 milhões).
Em vez de alterar esse valor, altere `range`.
### Lista de todos os hiperparâmetros no Neptune ML
A lista a seguir contém todos os hiperparâmetros que podem ser definidos em qualquer lugar no Neptune ML, para qualquer tipo de modelo e tarefa. Como nem todos são aplicáveis a todos os tipos de modelo, é importante definir apenas hiperparâmetros no arquivo `model-HPO-configuration.json` que aparece para o modelo que você está usando.
+ **`batch-size`**: o tamanho do lote de nós-alvo usados em uma passagem direta. *Tipo*: `int`.
Definir isso como um valor muito maior pode causar problemas de memória para treinamento em instâncias de GPU.
+ **`concat-node-embed`**: indica se é necessário obter a representação inicial de um nó concatenando seus atributos processados com incorporações de nós iniciais que podem ser aprendidos a fim de aumentar a expressividade do modelo. *Tipo*: `bool`.
+ **`dropout`**: a probabilidade de abandono aplicada às camadas de abandono. *Tipo*: `float`.
+ **`edge-num-hidden`**: o tamanho da camada oculta ou o número de unidades do módulo de atributos de borda. Usado somente quando `use-edge-features` for definido como `True`. *Tipo*: flutuante.
+ **`enable-early-stop`**: alterna se deve ou não usar o atributo de parada antecipada. *Tipo*: `bool`. *Padrão*: `true`.
Use esse parâmetro booliano para desativar o atributo de parada antecipada.
+ **`fanout`**: o número de vizinhos para amostra para um nó-alvo durante a amostragem de vizinhos. *Tipo*: `int`.
Esse valor está fortemente acoplado a `num-layers` e deve estar sempre no mesmo nível de hiperparâmetros. Isso ocorre porque você pode especificar um fanout para cada camada potencial do GNN.
Como esse hiperparâmetro pode fazer com que o desempenho do modelo varie amplamente, ele deve ser corrigido ou definido como um hiperparâmetro de nível 2 ou nível 3. Definir isso como um valor grande pode causar problemas de memória para treinamento em instâncias de GPU.
+ **`gamma`**: o valor da margem na função de pontuação. *Tipo*: `float`.
Isso se aplica somente aos modelos de previsão de links `KGE`.
+ **`l2norm`**: o valor de redução de peso usado no otimizador que impõe uma penalidade de normalização L2 nos pesos. *Tipo*: `bool`.
+ **`layer-norm`**: indica se a normalização de camadas deve ser usada para modelos `rgcn`. *Tipo*: `bool`.
+ **`low-mem`**: indica se deve ser usada uma implementação de baixa memória da função de transmissão de mensagens de relação em detrimento da velocidade. *Tipo*: `bool`.
+ **`lr`**: a taxa de aprendizado. *Tipo*: `float`.
Isso deve ser definido como um hiperparâmetro de nível 1.
+ **`neg-share`**: na previsão de links, indica se as amostras de bordas positivas podem compartilhar amostras de bordas negativas. *Tipo*: `bool`.
+ **`num-bases`**: o número de bases para decomposição de bases em um modelo `rgcn`. Usar um valor de `num-bases` menor do que o número de tipos de borda no grafo atua como um regularizador para o modelo `rgcn`. *Tipo*: `int`.
+ **`num-epochs`**: o número de épocas de treinamento a serem executados. *Tipo*: `int`.
Época é uma passagem de treinamento completa pelo grafo.
+ **`num-hidden`**: o tamanho da camada oculta ou o número de unidades. *Tipo*: `int`.
Isso também define o tamanho inicial de incorporação para nós sem atributos.
Definir isso para um valor muito maior sem reduzir `batch-size` pode causar out-of-memory problemas de treinamento na instância da GPU.
+ **`num-layer`**: o número de camadas de GNN no modelo. *Tipo*: `int`.
Esse valor está fortemente acoplado ao parâmetro fanout e deve vir depois que o fanout é definido no mesmo nível de hiperparâmetros.
Como isso ode fazer com que o desempenho do modelo varie amplamente, ele deve ser corrigido ou definido como um hiperparâmetro de nível 2 ou nível 3.
+ **`num-negs`**: na previsão de links, o número de amostras negativas por amostra positiva. *Tipo*: `int`.
+ **`per-feat-name-embed`**: indica se cada atributo deve ser incorporado transformando-o de forma independente antes de combinar os atributos. *Tipo*: `bool`.
Quando definido como `true`, cada atributo por nó é transformado de forma independente em um tamanho de dimensão fixo antes que todos os atributos transformados do nó sejam concatenados e posteriormente transformados na dimensão `num_hidden`.
Quando definido como `false`, os atributos são concatenados sem nenhuma transformação específica do atributo.
+ **`regularization-coef`**: na previsão de links, o coeficiente de perda de regularização. *Tipo*: `float`.
+ **`rel-part`**: indica se a partição de relação deve ser usada para previsão de links `KGE`. *Tipo*: `bool`.
+ **`sparse-lr`**: a taxa de aprendizado para incorporações de nós que podem ser aprendidos. *Tipo*: `float`.
As incorporações de nós iniciais que podem ser aprendidos são usadas para nós sem atributos ou quando `concat-node-embed` está definido. Os parâmetros da camada de incorporação de nós esparsos que podem ser aprendidos são treinados usando um otimizador separado que pode ter uma taxa de aprendizado separada.
+ **`use-class-weight`**: indica se devem ser aplicados pesos de classe para tarefas de classificação não equilibradas. Se definido como `true`, as contagens de rótulos são usadas para definir um peso para cada rótulo de classe. *Tipo*: `bool`.
+ **`use-edge-features`**: indica se os atributos de borda devem ser usados durante a transmissão de mensagens. Se definido como `true`, um módulo de atributo de borda personalizado é adicionado à camada RGCN para tipos de borda que têm atributos. *Tipo*: `bool`.
+ **`use-self-loop`**: indica se deve incluir loops automáticos no treinamento de um modelo `rgcn`. *Tipo*: `bool`.
+ **`window-for-early-stop`**: controla a média do número das pontuações de validação mais recentes para decidir sobre uma parada antecipada. O padrão é 3. type=int. Consulte também [Interrupção antecipada do processo de treinamento de modelos no Neptune ML](machine-learning-improve-model-performance.md#machine-learning-model-training-early-stop). *Tipo*: `int`. *Padrão*: `3`.
Consulte .
## Personalizar hiperparâmetros no Neptune ML
Ao editar o arquivo `model-HPO-configuration.json`, os seguintes tipos de alteração a serem feitas são os mais comuns:
+ Edite os valores and/or máximos mínimos dos `range` hiperparâmetros.
+ Defina um hiperparâmetro como um valor fixo movendo-o para a seção `fixed-param` e definindo seu valor padrão para o valor fixo que você deseja que ele assuma.
+ Altere a prioridade de um hiperparâmetro colocando-o em um nível específico, editando seu intervalo e certificando-se de que seu valor padrão seja definido adequadamente.
# Práticas recomendadas para treinamento de modelos
Há procedimentos que você pode realizar para melhorar o desempenho dos modelos do Neptune ML.
## Escolher a propriedade correta do nó
Pode ser que nem todas as propriedades no grafo sejam significativas ou relevantes para as tarefas de machine learning. Todas as propriedades irrelevantes devem ser excluídas durante a exportação de dados.
Veja algumas práticas recomendadas:
+ Use especialistas no domínio para ajudar a avaliar a importância dos atributos e a viabilidade de usá-los para previsões.
+ Remova os atributos considerados redundantes ou irrelevantes para reduzir o ruído nos dados e as correlações sem importância.
+ Faça iterações à medida que constrói o modelo. Ajuste os atributos, as combinações de atributos e os objetivos de ajuste à medida que avança.
O [processamento de atributos](https://docs.aws.amazon.com/machine-learning/latest/dg/feature-processing.html) no Guia do desenvolvedor do Amazon Machine Learning apresenta diretrizes adicionais para o processamento de atributos relevantes para o Neptune ML.
## Lidar com pontos de dados atípicos
Valor atípico é um ponto de dados significativamente diferente dos dados restantes. Valores atípicos podem prejudicar ou induzir erros no processo de treinamento, ocasionando maior tempo de treinamento ou modelos menos precisos. A menos que sejam realmente importantes, você deve eliminar os valores atípicos antes de exportar os dados.
## Remover bordas e nós duplicados
Os grafos armazenados no Neptune podem ter bordas ou nós duplicados. Esses elementos redundantes introduzirão ruído no treinamento de modelos de ML. Elimine bordas ou nós duplicados antes de exportar os dados.
## Ajustar a estrutura do grafo
Quando o grafo é exportado, você pode alterar a forma como os atributos são processados e como o grafo é construído, para melhorar o desempenho do modelo.
Veja algumas práticas recomendadas:
+ Quando uma propriedade de borda tem o significado de categorias de bordas, em alguns casos vale a pena transformá-la em tipos de borda.
+ A política de normalização padrão usada para uma propriedade numérica é `min-max`, mas em alguns casos outras políticas de normalização funcionam melhor. É possível pré-processar a propriedade e alterar a política de normalização conforme explicado em [Elementos de um arquivo `model-HPO-configuration.json`](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements).
+ O processo de exportação gera automaticamente tipos de atributo com base nos tipos de propriedade. Por exemplo, ele trata as propriedades `String` como atributos categóricos e as propriedades `Float` e `Int` como atributos numéricos. Se necessário, você poderá modificar o tipo de atributo após a exportação (consulte [Elementos de um arquivo `model-HPO-configuration.json`](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements)).
## Ajustar os intervalos e padrões dos hiperparâmetros
A operação de processamento de dados infere intervalos de configuração de hiperparâmetros a partir do grafo. Se os intervalos e os padrões de hiperparâmetros do modelo gerado não funcionarem bem para os dados dos grafos, você poderá editar o arquivo de configuração do HPO para criar sua própria estratégia de ajuste de hiperparâmetros.
Veja algumas práticas recomendadas:
+ Quando o grafo fica grande, o tamanho padrão da dimensão oculta pode não ser grande o suficiente para conter todas as informações. É possível alterar o hiperparâmetro `num-hidden` para controlar o tamanho da dimensão oculta.
+ Para modelos de incorporação de grafos de conhecimento (KGE), convém alterar o modelo específico que está sendo usado de acordo com a estrutura do grafo e o orçamento.
Os modelos `TrainsE` têm dificuldade de lidar com relações um-para-muitos (1-N), muitos-para-um (N-1) e muitos-para-muitos (N-N). Os modelos `DistMult` têm dificuldade de lidar com relações simétricas. `RotatE` é bom em modelar todos os tipos de relações, mas é mais caro do que `TrainsE` e `DistMult` durante o treinamento.
+ Em alguns casos, quando tanto a identificação do nó quanto as informações do atributo do nó são importantes, você deve usar ``concat-node-embed`` para instruir o modelo Neptune ML a obter a representação inicial de um nó concatenando os atributos com suas incorporações iniciais.
+ Ao obter um desempenho razoavelmente bom em alguns hiperparâmetros, é possível ajustar o espaço de pesquisa de hiperparâmetros de acordo com esses resultados.
## Interrupção antecipada do processo de treinamento de modelos no Neptune ML
A interrupção antecipada pode reduzir significativamente o tempo de execução do treinamento de modelos e os custos associados sem degradar o desempenho do modelo. Também evita que o modelo se ajuste demais aos dados de treinamento.
A interrupção antecipada depende de medições regulares do desempenho do conjunto de validação. Inicialmente, o desempenho melhora à medida que o treinamento prossegue, mas quando o modelo começa a se ajustar demais, ele começa a declinar novamente. O atributo de interrupção antecipada identifica o ponto em que o modelo começa a se ajustar demais e interrompe o treinamento do modelo nesse ponto.
O Neptune ML monitora as chamadas da métrica de validação e compara a métrica de validação mais recente com a média das métricas de validação nas últimas **`n`** avaliações, em que **`n`** é um número definido usando o parâmetro `window-for-early-stop`. Assim que a métrica de validação for pior do que a média, o Neptune ML interromperá o treinamento do modelo e salvará o melhor modelo até o momento.
É possível controlar a interrupção antecipada usando os seguintes parâmetros:
+ **`window-for-early-stop`**: o valor desse parâmetro é um número inteiro que especifica a média do número de pontuações de validação recentes ao decidir sobre uma interrupção antecipada. O valor padrão é `3`.
+ **`enable-early-stop`**: use esse parâmetro booliano para desativar o atributo de interrupção antecipada. Por padrão, o valor é `true`.
## Interrupção antecipada do processo HPO no Neptune ML
O recurso de interrupção antecipada no Neptune ML também interrompe as tarefas de treinamento que não estão funcionando bem em comparação com outras tarefas de treinamento, usando o recurso de início a quente do HPO do SageMaker AI. Isso também pode reduzir custos e melhorar a qualidade do HPO.
Consulte [Run a warm start hyperparameter tuning job](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-warm-start.html) para obter uma descrição de como isso funciona.
O início a quente oferece a capacidade de transmitir informações aprendidas em trabalhos de treinamento anteriores para trabalhos de treinamento subsequentes e oferece dois benefícios distintos:
+ Primeiro, os resultados dos trabalhos de treinamento anteriores são usados para selecionar boas combinações de hiperparâmetros a serem pesquisados no novo trabalho de ajuste.
+ Segundo, permite a interrupção antecipada para acessar mais execuções do modelo, o que reduz o tempo de ajuste.
Esse atributo é habilitado automaticamente no Neptune ML e permite que você encontre um equilíbrio entre o tempo de treinamento e o desempenho do modelo. Se você estiver satisfeito com o desempenho do modelo atual, poderá usar esse modelo. Caso contrário, execute mais HPOs que são iniciados a quente com os resultados das execuções anteriores para descobrir um modelo melhor.
## Obter serviços de suporte profissional
A AWS oferece serviços de suporte profissional para ajudar você com problemas em machine learning em projetos do Neptune. Se tiver problemas, entre em contato com o [AWS Support](https://aws.amazon.com/premiumsupport/).
# Usar um modelo treinado para gerar novos artefatos de modelo
Usando o comando de transformação de modelos do Neptune ML, é possível calcular artefatos de modelo, como incorporações de nós em dados de grafos processados, usando parâmetros de modelo pré-treinados.
## Transformação de modelos para inferência incremental
No [fluxo de trabalho de inferência de modelos incrementais](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental), depois de processar os dados de grafos atualizados que você exportou do Neptune, é possível iniciar um trabalho de processamento de modelos usando um comando do curl (ou awscurl) como o seguinte:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"mlModelTrainingJobId": "(the ML model training job-id)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/"
}'
```
Depois, é possível transmitir o ID desse trabalho para a chamada da API create-endpoints a fim de criar um endpoint ou atualizar um existente com os novos artefatos do modelo gerados por esse trabalho. Isso permite que o endpoint novo ou atualizado forneça previsões de modelo para os dados de grafos atualizados.
## Transformação de modelos para qualquer trabalho de treinamento
Você também pode fornecer um parâmetro `trainingJobName` para gerar artefatos de modelo para qualquer uma das tarefas de treinamento do SageMaker AI iniciados durante o treinamento de modelos do Neptune ML. Como uma tarefa de treinamento de modelos do Neptune ML pode iniciar muitas tarefas de treinamento do SageMaker AI, isso oferece a flexibilidade de criar um endpoint de inferência com base em qualquer uma dessas tarefas de treinamento do SageMaker.
Por exemplo:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"trainingJobName" : "(name a completed SageMaker AI training job)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/"
}'
```
Se o trabalho de treinamento original foi para um modelo personalizado fornecido pelo usuário, você deverá incluir um objeto `customModelTransformParameters` ao invocar uma transformação de modelos. Consulte [Modelos personalizados no Neptune ML](machine-learning-custom-models.md) para obter informações sobre como implementar e usar um modelo personalizado.
**nota**
O comando `modeltransform` sempre executa a transformação de modelos na melhor tarefa de treinamento do SageMaker AI para esse treinamento.
Consulte [O comando modeltransform](machine-learning-api-modeltransform.md) para obter mais informações sobre trabalhos de treinamento de modelos.
# Artefatos produzidos pelo treinamento de modelos no Neptune ML
Após o treinamento de modelos, o Neptune ML usa os parâmetros de modelo mais bem treinados para gerar artefatos de modelo que são necessários para iniciar o endpoint de inferência e fornecer previsões do modelo. Esses artefatos são agrupados pela tarefa de treinamento e armazenados no local de saída do Amazon S3 da melhor tarefa de treinamento do SageMaker AI.
As seções a seguir descrevem o que está incluído nos artefatos do modelo para as várias tarefas e como o comando de transformação de modelos usa um modelo treinado preexistente para gerar artefatos mesmo em novos dados de grafos.
## Artefatos gerados para diferentes tarefas
O conteúdo dos artefatos do modelo gerados pelo processo de treinamento depende da tarefa de machine learning de destino:
****
+ **Classificação e regressão de nós**: para previsão de propriedades de nós, os artefatos incluem parâmetros do modelo, incorporações de nós do [codificador de GNN](machine-learning-models-and-training.md#machine-learning-gnns), previsões de modelo para nós no grafo de treinamento e alguns arquivos de configuração para o endpoint de inferência. Nas tarefas de classificação e regressão de nós, as previsões do modelo são pré-calculadas para os nós presentes durante o treinamento com o objetivo de reduzir a latência da consulta.
+ **Classificação e regressão de bordas**: para a previsão de propriedades da borda, os artefatos também incluem parâmetros do modelo e incorporações de nós. Os parâmetros do decodificador de modelos são especialmente importantes para inferência porque calculamos as previsões de classificação ou regressão de bordas aplicando o decodificador de modelos às incorporações do vértice de origem e de destino de uma borda.
+ **Previsão de links**: para previsão de links, além dos artefatos gerados para a previsão de propriedades de borda, o grafo de DGL também é incluído como um artefato porque a previsão de links requer o grafo de treinamento para realizar previsões. O objetivo da previsão de links é prever os vértices de destino que provavelmente se combinarão com um vértice de origem para formar uma borda de um tipo específico no grafo. Para fazer isso, a incorporação de nós do vértice de origem e uma representação aprendida para o tipo de borda são combinadas com as incorporações de nós de todos os vértices de destino possíveis a fim de produzir uma pontuação de probabilidade de borda para cada um dos vértices de destino. As pontuações são então classificadas para avaliar os possíveis vértices de destino e gerar os principais candidatos.
Para cada um dos tipos de tarefa, os pesos do modelo de rede neural para grafos da DGL são salvos no artefato do modelo. Isso permite que o Neptune ML calcule novas saídas do modelo à medida que o grafo muda (inferência *indutiva*), além de usar previsões e incorporações pré-calculadas (inferência *transdutiva*) para reduzir a latência.
## Gerar novos artefatos do modelo
Os artefatos do modelo gerados após o treinamento de modelos no Neptune ML estão diretamente vinculados ao processo de treinamento. Isso significa que as incorporações e as previsões pré-calculadas existem apenas para entidades que estavam no grafo de treinamento original. Embora o modo de inferência indutiva para endpoints do Neptune ML possa calcular previsões para novas entidades em tempo real, convém gerar previsões em lote em novas entidades sem consultar um endpoint.
Para obter previsões do modelo em lote para novas entidades adicionadas ao grafo, novos artefatos do modelo precisam ser recalculados para os novos dados de grafos. Isso é feito com o comando `modeltransform`. Use o comando `modeltransform` quando deseja apenas previsões em lote sem configurar um endpoint ou quando deseja que todas as previsões sejam geradas para que você possa gravá-las de volta no grafo.
Como o treinamento de modelos executa implicitamente uma transformação de modelos no final do processo de treinamento, os artefatos do modelo são sempre recalculados nos dados de grafos de treinamento por um trabalho de treinamento. No entanto, o comando `modeltransform` também pode calcular artefatos de modelo em dados de grafos que não foram usados para treinar um modelo. Para isso, os novos dados de grafos devem ser processados usando as mesmas codificações de atributos dos dados de grafos originais e devem seguir o mesmo esquema de grafo.
É possível fazer isso criando primeiro uma tarefa de processamento de dados que seja clone da tarefa de processamento de dados executada nos dados do grafo de treinamento original e executando-a nos novos dados de grafos (consulte [Processar dados de grafos atualizados para o Neptune ML](machine-learning-on-graphs-processing.md#machine-learning-on-graphs-processing-updated)). Depois, chame o comando `modeltransform` com o novo `dataProcessingJobId` e o antigo `modelTrainingJobId` para recalcular os artefatos do modelo nos dados de grafos atualizados.
Para a previsão da propriedade do nó, as incorporações e as previsões do nó são recalculadas nos novos dados de grafos, mesmo para os nós que estavam presentes no grafo de treinamento original.
Para previsão de propriedades de borda e de links, as incorporações de nós também são recalculadas e, da mesma forma, substituem todas as incorporações de nós existentes. Para recalcular as incorporações de nós, o Neptune ML aplica o codificador de GNN aprendido do modelo treinado anterior aos nós dos novos dados de grafos com seus novos atributos.
Para nós sem atributos, as representações iniciais aprendidas do treinamento do modelo original são reutilizadas. Para novos nós sem atributos e que não estavam presentes no grafo de treinamento original, o Neptune ML inicializa a representação como a média das representações iniciais aprendidas desse tipo de nó presentes no grafo de treinamento original. Isso poderá causar uma certa degradação do desempenho nas previsões do modelo se você tiver muitos nós novos sem atributos, pois todos eles serão inicializados com a incorporação inicial média desse tipo de nó.
Se o modelo for treinado com `concat-node-embed` definido como verdadeiro, as representações iniciais do nó serão criadas concatenando os atributos do nó com a representação inicial que pode ser aprendida. Assim, para o grafo atualizado, a representação inicial dos novos nós também usa a média das incorporações iniciais dos nós, concatenadas com os novos atributos dos nós.
Além disso, no momento, exclusões de nós não são compatíveis. Se os nós tiverem sido removidos no grafo atualizado, você precisará treinar novamente o modelo nos dados do grafo atualizado.
O novo cálculo dos artefatos do modelo reutiliza os parâmetros aprendidos do modelo em um novo grafo e só deve ser feito quando o novo grafo é muito semelhante ao grafo antigo. Se o novo grafo não for suficientemente semelhante, você precisará treinar novamente o modelo para obter um desempenho semelhante nos novos dados de grafos. O que constitui algo suficientemente semelhante depende da estrutura dos dados de grafos, mas, como regra, será necessário treinar novamente o modelo se os novos dados forem mais de 10 a 20% diferentes dos dados do grafo de treinamento original.
Para grafos em que todos os nós têm atributos, a extremidade superior do limite (20% diferente) se aplica, mas para grafos em que muitos nós não têm atributos e os novos nós adicionados ao grafo não têm propriedades, a extremidade inferior (10% diferente) pode até ser alta demais.
Consulte [O comando modeltransform](machine-learning-api-modeltransform.md) para obter mais informações sobre trabalhos de treinamento de modelos.
# Modelos personalizados no Neptune ML
**nota**
O suporte ao modelo personalizado do Neptune ML depende de uma versão mais antiga do Python 3. [Para criar e executar modelos GNN personalizados com up-to-date dependências, use GraphStorm on. SageMaker](https://graphstorm.readthedocs.io/en/v0.3.1/cli/model-training-inference/distributed/sagemaker.html)
No momento, a [inferência indutiva em tempo real](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference) não é compatível com modelos personalizados.
O Neptune ML permite definir as próprias implementações de modelos personalizados usando Python. É possível treinar e implantar modelos personalizados usando a infraestrutura do Neptune ML da mesma forma que é feito com os modelos integrados, e usá-los para obter previsões por meio de consultas de grafos.
Você pode começar a implementar um modelo personalizado em Python seguindo os [exemplos do kit de ferramentas do Neptune ML](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/) e usando os componentes do modelo fornecidos no kit de ferramentas do Neptune ML. As seções a seguir fornecem mais detalhes.
**Contents**
+ [Visão geral dos modelos personalizados no Neptune ML](machine-learning-custom-model-overview.md)
+ [Quando usar um modelo personalizado no Neptune ML](machine-learning-custom-model-overview.md#machine-learning-custom-models-when-to-use)
+ [Fluxo de trabalho para desenvolver e usar um modelo personalizado no Neptune ML](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow)
+ [Desenvolvimento de modelos personalizados no Neptune ML](machine-learning-custom-model-development.md)
+ [Desenvolvimento de scripts de treinamento de modelos personalizados no Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-training-script)
+ [Desenvolvimento de scripts de transformação de modelos personalizados no Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-transform-script)
+ [Arquivo `model-hpo-configuration.json` personalizado no Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-hpo-configuration-file)
+ [Teste local da implementação do modelo personalizado no Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-testing)
# Visão geral dos modelos personalizados no Neptune ML
## Quando usar um modelo personalizado no Neptune ML
Os modelos integrados do Neptune ML lidam com todas as tarefas padrão compatíveis com o Neptune ML, mas pode haver casos em que você queira ter um controle mais granular sobre o modelo para uma tarefa específica ou precise personalizar o processo de treinamento de modelos. Por exemplo, um modelo personalizado é apropriado nas seguintes situações:
+ Codificação de atributos de texto de modelos de texto muito grandes precisam ser executados na GPU.
+ Você deseja usar seu próprio modelo personalizado de rede neural para grafos (GNN) desenvolvido na Deep Graph Library (DGL).
+ Você deseja usar modelos tabulares ou modelos de conjunto para classificação e regressão de nós.
## Fluxo de trabalho para desenvolver e usar um modelo personalizado no Neptune ML
O suporte a modelos personalizados no Neptune ML foi projetado para se integrar perfeitamente aos fluxos de trabalho existentes do Neptune ML. Ele funciona executando código personalizado no módulo de origem na infraestrutura do Neptune ML para treinar o modelo. Assim como no caso de um modo integrado, o Neptune ML inicia automaticamente SageMaker um trabalho de ajuste de HyperParameter IA e seleciona o melhor modelo de acordo com a métrica de avaliação. Depois, ele usa a implementação fornecida no módulo de origem para gerar artefatos de modelo para implantação.
A exportação de dados, a configuração de treinamento e o pré-processamento de dados são os mesmos para modelos personalizados e incorporados.
Depois do pré-processamento de dados, é quando você pode desenvolver e testar de forma iterativa e interativa a implementação de modelos personalizados usando Python. Quando o modelo estiver pronto para produção, você poderá fazer o upload do módulo Python resultante para o Amazon S3 da seguinte forma:
```
aws s3 cp --recursive (source path to module) s3://(bucket name)/(destination path for your module)
```
Depois, é possível usar o fluxo de trabalho de dados [padrão](machine-learning-overview.md#machine-learning-overview-starting-workflow) normal ou [incremental](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental) para implantar o modelo na produção, com algumas diferenças.
Para treinamento de modelos usando um modelo personalizado, é necessário fornecer um objeto `customModelTrainingParameters` JSON à API de treinamento de modelos do Neptune ML para garantir que o código personalizado seja usado. Os campos no objeto `customModelTrainingParameters` são os seguintes:
+ **`sourceS3DirectoryPath`**: (*obrigatório*) o caminho para o local do Amazon S3 onde o módulo Python que implementa seu modelo está localizado. Isso deve apontar para uma localização válida existente do Amazon S3 que contenha, no mínimo, um script de treinamento, um script de transformação e um arquivo `model-hpo-configuration.json`.
+ **`trainingEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que executa o treinamento de modelos e usa hiperparâmetros como argumentos de linha de comando, incluindo hiperparâmetros fixos.
*Padrão*: `training.py`.
+ **`transformEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que deve ser executado após a identificação do melhor modelo da pesquisa de hiperparâmetros, para calcular os artefatos do modelo necessários para a implantação do modelo. Ele deve ser capaz de ser executado sem argumentos de linha de comando.
*Padrão*: `transform.py`.
Por exemplo:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
"modelName": "custom",
"customModelTrainingParameters" : {
"sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)",
"trainingEntryPointScript": "(your training script entry-point name in the Python module)",
"transformEntryPointScript": "(your transform script entry-point name in the Python module)"
}
}'
```
Da mesma forma, para habilitar uma transformação de modelos personalizados, você deve fornecer um objeto `customModelTransformParameters` JSON à API de transformação de modelos do Neptune ML, com valores de campo compatíveis com os parâmetros do modelo salvos do trabalho de treinamento. O objeto `customModelTransformParameters` contém os seguintes campos:
+ **`sourceS3DirectoryPath`**: (*obrigatório*) o caminho para o local do Amazon S3 onde o módulo Python que implementa seu modelo está localizado. Isso deve apontar para uma localização válida existente do Amazon S3 que contenha, no mínimo, um script de treinamento, um script de transformação e um arquivo `model-hpo-configuration.json`.
+ **`transformEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que deve ser executado após a identificação do melhor modelo da pesquisa de hiperparâmetros, para calcular os artefatos do modelo necessários para a implantação do modelo. Ele deve ser capaz de ser executado sem argumentos de linha de comando.
*Padrão*: `transform.py`.
Por exemplo:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"trainingJobName" : "(name of a completed SageMaker AI training job)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/"
"customModelTransformParameters" : {
"sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)",
"transformEntryPointScript": "(your transform script entry-point name in the Python module)"
}
}'
```
# Desenvolvimento de modelos personalizados no Neptune ML
Uma boa maneira de começar o desenvolvimento de modelos personalizados é seguir os [exemplos do kit de ferramentas do Neptune ML](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/introduction) para estruturar e escrever o módulo de treinamento. O kit de ferramentas do Neptune ML também implementa componentes do modelo de ML de grafo modularizado no [modelzoo](https://github.com/awslabs/neptuneml-toolkit/tree/main/src/neptuneml_toolkit/modelzoo) que você pode empilhar e usar para criar o modelo personalizado.
Além disso, o kit de ferramentas fornece funções de utilitário que ajudam a gerar os artefatos necessários durante o treinamento e a transformação de modelos. É possível importar esse pacote Python na implementação personalizada. Todas as funções ou os módulos fornecidos no kit de ferramentas também estão disponíveis no ambiente de treinamento do Neptune ML.
Se o módulo Python tiver dependências externas adicionais, você poderá incluir essas dependências adicionais criando um arquivo `requirements.txt` no diretório do módulo. Os pacotes listados no arquivo `requirements.txt` serão então instalados antes da execução do script de treinamento.
No mínimo, o módulo Python que implementa o modelo personalizado precisa conter o seguinte:
+ Um ponto de entrada do script de treinamento
+ Um ponto de entrada do script de transformação
+ Um arquivo `model-hpo-configuration.json`
## Desenvolvimento de scripts de treinamento de modelos personalizados no Neptune ML
O script de treinamento de modelos personalizados deve ser um script Python executável, como o exemplo [https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) do kit de ferramentas do Neptune ML. Ele deve aceitar nomes e valores de hiperparâmetros como argumentos de linha de comando. Durante o treinamento de modelos, os nomes dos hiperparâmetros são obtidos do arquivo `model-hpo-configuration.json`. Os valores dos hiperparâmetros estarão dentro do intervalo de hiperparâmetros válido se o hiperparâmetro for ajustável ou assumirão o valor padrão do hiperparâmetro se não for ajustável.
O script de treinamento é executado em uma instância de treinamento do SageMaker AI usando uma sintaxe como esta:
```
python3 (script entry point) --(1st parameter) (1st value) --(2nd parameter) (2nd value) (...)
```
Para todas as tarefas, o Neptune ML AutoTrainer envia vários parâmetros necessários ao script de treinamento, além dos hiperparâmetros especificados, e o script deve ser capaz de lidar com esses parâmetros adicionais para funcionar adequadamente.
Esses parâmetros adicionais necessários variam um pouco de acordo com a tarefa:
**Para classificação ou regressão de nós**
+ **`task`**: o tipo de tarefa usado internamente pelo Neptune ML. Para classificação de nós, é `node_class`, e para regressão de nós, é `node_regression`.
+ **`model`**: o nome do modelo usado internamente pelo Neptune ML, que é `custom` neste caso.
+ **`name`**: o nome da tarefa usada internamente pelo Neptune ML, que é `node_class-custom` para classificação de nós nesse caso, e `node_regression-custom` para regressão de nós.
+ **`target_ntype`**: o nome do tipo de nó para classificação ou regressão.
+ **`property`**: o nome da propriedade de nó para classificação ou regressão.
**Para previsão de links**
+ **`task`**: o tipo de tarefa usado internamente pelo Neptune ML. Para previsão de links, é `link_predict`.
+ **`model`**: o nome do modelo usado internamente pelo Neptune ML, que é `custom` neste caso.
+ **`name`**: o nome de tarefa usado internamente pelo Neptune ML, que é `link_predict-custom` nesse caso.
**Para classificação ou regressão de bordas**
+ **`task`**: o tipo de tarefa usado internamente pelo Neptune ML. Para classificação de bordas, é `edge_class`, e para regressão de bordas, é `edge_regression`.
+ **`model`**: o nome do modelo usado internamente pelo Neptune ML, que é `custom` neste caso.
+ **`name`**: o nome da tarefa usada internamente pelo Neptune ML, que é `edge_class-custom` para classificação de bordas nesse caso, e `edge_regression-custom` para regressão de bordas.
+ **`target_etype`**: o nome do tipo de borda para classificação ou regressão.
+ **`property`**: o nome da propriedade de borda para classificação ou regressão.
O script deve salvar os parâmetros do modelo, bem como quaisquer outros artefatos necessários ao final do treinamento.
É possível usar as funções do utilitário do kit de ferramentas do Neptune ML para determinar a localização dos dados de grafos processados, o local em que os parâmetros do modelo devem ser salvos e quais dispositivos de GPU estão disponíveis na instância de treinamento. Consulte o exemplo de script de treinamento [train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) para ver exemplos de como usar essas funções de utilitário.
## Desenvolvimento de scripts de transformação de modelos personalizados no Neptune ML
É necessário um script de transformação para aproveitar o [fluxo de trabalho incremental](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental) do Neptune ML para inferência de modelos em grafos em evolução sem treinar novamente o modelo. Mesmo que todos os artefatos necessários para a implantação do modelo sejam gerados pelo script de treinamento, você ainda precisará fornecer um script de transformação se quiser gerar modelos atualizados sem treinar novamente o modelo.
**nota**
No momento, a [inferência indutiva em tempo real](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference) não é compatível com modelos personalizados.
O script de transformação de modelos personalizados deve ser um script Python executável, como o exemplo de script [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) do kit de ferramentas do Neptune ML. Como esse script é invocado durante o treinamento de modelos sem argumentos de linha de comando, todos os argumentos de linha de comando aceitos pelo script devem ter padrões.
O script é executado em uma instância de treinamento do SageMaker AI com uma sintaxe como esta:
```
python3 (your transform script entry point)
```
O script de transformação precisará de várias informações, como:
+ A localização dos dados de grafos processados.
+ O local onde os parâmetros do modelo são salvos e onde os novos artefatos do modelo devem ser salvos.
+ Os dispositivos disponíveis na instância.
+ Os hiperparâmetros que geraram o melhor modelo.
Essas entradas são obtidas usando as funções de utilitário do Neptune ML que o script pode chamar. Veja o exemplo do script [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) do kit de ferramentas para ver exemplos de como fazer isso.
O script deve salvar as incorporações do nó, os mapeamentos de ID de nó e quaisquer outros artefatos necessários para a implantação do modelo em cada tarefa. Consulte a [documentação dos artefatos do modelo](machine-learning-model-artifacts.md) para obter mais informações sobre os artefatos do modelo necessários para diferentes tarefas do Neptune ML.
## Arquivo `model-hpo-configuration.json` personalizado no Neptune ML
O arquivo `model-hpo-configuration.json` define hiperparâmetros para o modelo personalizado. Ele está no mesmo [formato](machine-learning-customizing-hyperparams.md) que o arquivo `model-hpo-configuration.json` usado com os modelos integrados do Neptune ML e tem precedência sobre a versão gerada automaticamente pelo Neptune ML e carregada no local dos dados processados.
Ao adicionar um novo hiperparâmetro ao modelo, você também deve adicionar uma entrada para o hiperparâmetro nesse arquivo para que o hiperparâmetro seja transmitido ao script de treinamento.
Será necessário fornecer um intervalo para um hiperparâmetro se quiser que ele seja ajustável e defini-lo como parâmetro `tier-1`, `tier-2` ou `tier-3`. O hiperparâmetro será ajustado se o número total de trabalhos de treinamento configurados permitir o ajuste de hiperparâmetros em seu nível. Para um parâmetro não ajustável, é necessário fornecer um valor padrão e adicionar o hiperparâmetro à seção `fixed-param` do arquivo. Veja o [exemplo de arquivo `model-hpo-configuration.json`](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/model-hpo-configuration.json) do kit de ferramentas para ver um exemplo de como fazer isso.
Você também deve fornecer a definição de métrica que a tarefa de otimização de hiperparâmetros do SageMaker AI usará para avaliar os modelos candidatos treinados. Para fazer isso, adicione um objeto JSON `eval_metric` ao arquivo `model-hpo-configuration.json` da seguinte forma:
```
"eval_metric": {
"tuning_objective": {
"MetricName": "(metric_name)",
"Type": "Maximize"
},
"metric_definitions": [
{
"Name": "(metric_name)",
"Regex": "(metric regular expression)"
}
]
},
```
A matriz `metric_definitions` no objeto `eval_metric` lista objetos de definição de cada métrica que você deseja que o SageMaker AI extraia da instância de treinamento. Cada objeto de definição de métrica tem uma chave `Name` que permite fornecer um nome para a métrica (como “precisão”, “f1”, etc.). A chave `Regex` permite fornecer uma string de expressão regular que corresponda à forma como essa métrica específica é impressa nos logs de treinamento. Consulte a [página de ajuste de hiperparâmetro do SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-define-metrics.html) para obter mais detalhes sobre como definir métricas.
O objeto `tuning_objective` em `eval_metric` então permite especificar quais métricas em `metric_definitions` devem ser usadas como a métrica de avaliação que serve como métrica objetiva para otimização de hiperparâmetros. O valor para o `MetricName` deve corresponder ao valor de um `Name` em uma das definições em `metric_definitions`. O valor de `Type` deve ser “Maximizar” ou “Minimizar”, dependendo se a métrica deve ser interpretada como maior é melhor (como “precisão”) ou menos é melhor (como “erro quadrático médio”).
Erros nessa seção do arquivo `model-hpo-configuration.json` podem gerar falhas no trabalho da API de treinamento de modelos do Neptune ML, porque a tarefa de ajuste de hiperparâmetros do SageMaker AI não poderá selecionar o melhor modelo.
## Teste local da implementação do modelo personalizado no Neptune ML
É possível usar o ambiente Conda do kit de ferramentas do Neptune ML para executar o código localmente a fim de testar e validar o modelo. Se você estiver desenvolvendo em uma instância do Neptune Notebook, esse ambiente Conda será pré-instalado na instância de bloco de anotações do Neptune. Se você estiver desenvolvendo em uma instância diferente, precisará seguir as [instruções de configuração local](https://github.com/awslabs/neptuneml-toolkit#local-installation) no kit de ferramentas do Neptune ML.
O ambiente Conda reproduz com precisão o ambiente em que o modelo será executado quando você chamar a [API de treinamento de modelos](machine-learning-api-modeltraining.md). Todos os exemplos de script de treinamento e scripts de transformação permitem transmitir um sinalizador `--local` de linha de comando para executar os scripts em um ambiente local a fim de facilitar a depuração. Essa é uma prática recomendada ao desenvolver o próprio modelo, pois permite testar de forma interativa e iterativa a implementação do modelo. Durante o treinamento de modelos no ambiente de treinamento de produção do Neptune ML, esse parâmetro é omitido.
# Criar um endpoint de inferência para consulta
Um endpoint de inferência permite consultar um modelo específico que o processo de treinamento de modelos criou. O endpoint se conecta ao modelo de melhor desempenho de um tipo específico que o processo de treinamento conseguiu gerar. O endpoint então pode aceitar consultas do Gremlin do Neptune e gerar as previsões desse modelo para entradas nas consultas. Depois de criar um endpoint de referência, ele permanece ativo até a exclusão.
## Gerenciar endpoints de inferência para o Neptune ML
Depois de concluir o treinamento de modelos em dados que você exportou do Neptune, você poderá criar um endpoint de inferência usando um comando `curl` (ou `awscurl`) como o seguinte:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"mlModelTrainingJobId": "(the model-training job-id of a completed job)"
}'
```
Também é possível criar um endpoint de inferência a partir de um modelo criado por um trabalho de transformação de modelos concluído, da mesma forma:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"mlModelTransformJobId": "(the model-transform job-id of a completed job)"
}'
```
Os detalhes de como usar esses comandos são explicados em [O comando endpoints](machine-learning-api-endpoints.md), junto com informações sobre como obter o status de um endpoint, excluir um endpoint e listar todos os endpoints de inferência.
# Consultas de inferência no Neptune ML
É possível usar o Gremlin ou o SPARQL para consultar um endpoint de inferência do Neptune ML. No entanto, a [inferência indutiva em tempo real](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference) no momento só é aceita para consultas do Gremlin.
# Consultas de inferência do Gremlin no Neptune ML
Conforme descrito em [Capacidades do Neptune ML](machine-learning.md#machine-learning-capabilities), o Neptune ML é compatível com modelos de treinamento que podem realizar os seguintes tipos de tarefa de inferência:
+ **Classificação de nós**: prevê o atributo categórico de uma propriedade de vértice.
+ **Regressão de nós**: prevê uma propriedade numérica de um vértice.
+ **Classificação de bordas**: prevê o atributo categórico de uma propriedade de borda.
+ **Regressão de nós**: prevê uma propriedade numérica de uma borda.
+ **Previsão de links**: prevê nós de destino considerando-se um nó de origem e uma borda de saída, ou nós de origem considerando-se um nó de destino e uma borda de entrada.
[Podemos ilustrar essas diferentes tarefas com exemplos que usam o [conjunto de dados de MovieLens 100 mil](https://grouplens.org/datasets/movielens/100k/) fornecido pela Research. GroupLens ](https://grouplens.org/datasets/movielens/) Esse conjunto de dados consiste em filmes, usuários e avaliações dos filmes feitas pelos usuários, a partir das quais criamos um grafo de propriedades como este:
![\[Exemplo de gráfico de propriedades do filme usando o conjunto de MovieLens dados 100k\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/images/movie_property_graph_example.png)
**Classificação de nós**: no conjunto de dados acima, `Genre` é um tipo de vértice conectado ao tipo de vértice `Movie` por borda `included_in`. No entanto, se ajustarmos o conjunto de dados para tornar `Genre` um atributo [categórico](https://en.wikipedia.org/wiki/Categorical_variable) para o tipo de vértice `Movie`, o problema de inferir `Genre` para novos filmes adicionados ao nosso grafo de conhecimento poderá ser resolvido usando modelos de classificação de nós.
**Regressão de nós**: se considerarmos o tipo de vértice `Rating`, que tem propriedades, como `timestamp` e `score`, o problema de inferir o valor numérico `Score` para um `Rating` pode ser resolvido usando modelos de regressão de nós.
**Classificação de arestas**: Da mesma forma, para uma `Rated` aresta, se tivermos uma propriedade `Scale` que pode ter um dos valores,`Love`,,`Like`,`Dislike`,`Neutral`,`Hate`, então o problema de inferir a `Rated` aresta `Scale` para novos movies/ratings pode ser resolvido usando modelos de classificação de arestas.
**Regressão de bordas**: da mesma forma, para a mesma borda `Rated`, se tivermos uma propriedade `Score` que contém um valor numérico para a classificação, isso pode ser inferido a partir de modelos de regressão de bordas.
**Previsão de links**: problemas, por exemplo, encontrar os dez principais usuários com maior probabilidade de avaliar um determinado filme ou encontrar os dez melhores filmes que um determinado usuário tem maior probabilidade de avaliar se enquadram na previsão de links.
**nota**
Para casos de uso do Neptune ML, temos um conjunto muito rico de cadernos projetados para oferecer uma compreensão prática de cada caso de uso. Você pode criar esses notebooks junto com seu cluster Neptune ao usar o modelo Neptune ML para criar um cluster [Neptune CloudFormation ML](machine-learning-quick-start.md). Esses cadernos também estão disponíveis no [github](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning).
**Topics**
+ [Predicados do Neptune ML usados em consultas de inferência do Gremlin](machine-learning-gremlin-inference-query-predicates.md)
+ [Consultas de classificação de nós do Gremlin no Neptune ML](machine-learning-gremlin-vertex-classification-queries.md)
+ [Consultas de regressão de nós do Gremlin no Neptune ML](machine-learning-gremlin-vertex-regression-queries.md)
+ [Consultas de classificação de bordas do Gremlin no Neptune ML](machine-learning-gremlin-edge-classification-queries.md)
+ [Consultas de regressão de bordas do Gremlin no Neptune ML](machine-learning-gremlin-edge-regression.md)
+ [Consultas de previsão de links do Gremlin usando modelos de previsão de links no Neptune ML](machine-learning-gremlin-link-prediction-queries.md)
+ [Lista de exceções para consultas de inferência do Gremlin no Neptune ML](machine-learning-gremlin-exceptions.md)
# Predicados do Neptune ML usados em consultas de inferência do Gremlin
## `Neptune#ml.deterministic`
Esse predicado é uma opção para consultas de inferência indutiva, ou seja, para consultas que incluem o predicado [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference).
Ao usar a inferência indutiva, o mecanismo do Neptune cria o subgrafo apropriado para avaliar o modelo de GNN treinado, e os requisitos desse subgrafo dependem dos parâmetros do modelo final. Especificamente, o parâmetro `num-layer` determina o número de saltos transversais dos nós ou das bordas de destino, e o parâmetro `fanouts` especifica quantos vizinhos devem ser incluídos na amostra em cada salto (consulte os parâmetros do [HPO](machine-learning-customizing-hyperparams.md)).
Por padrão, as consultas de inferência indutiva são executadas no modo não determinístico, no qual o Neptune constrói a vizinhança aleatoriamente. Ao fazer previsões, essa amostragem normal de vizinhos aleatórios às vezes gera previsões diferentes.
Quando você inclui `Neptune#ml.deterministic` em uma consulta de inferência indutiva, o mecanismo do Neptune tenta realizar uma amostra de vizinhos de forma determinística para que várias invocações da mesma consulta retornem sempre os mesmos resultados. No entanto, não se pode garantir que os resultados sejam completamente determinísticos, pois as alterações no grafo e nos artefatos subjacentes dos sistemas distribuídos ainda podem introduzir flutuações.
Você inclui o predicado `Neptune#ml.deterministic` em uma consulta como esta:
```
.with("Neptune#ml.deterministic")
```
Se o predicado `Neptune#ml.deterministic` for incluído em uma consulta que também não inclua `Neptune#ml.inductiveInference`, ele será simplesmente ignorado.
## `Neptune#ml.disableInductiveInferenceMetadataCache`
Esse predicado é uma opção para consultas de inferência indutiva, ou seja, para consultas que incluem o predicado [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference).
Para consultas de inferência indutiva, o Neptune usa um arquivo de metadados armazenado no Amazon S3 para decidir o número de saltos e o fanout ao construir a vizinhança. O Neptune normalmente armazena em cache esses metadados do modelo para evitar a busca repetida do arquivo no Amazon S3. O armazenamento em cache pode ser desativado incluindo o predicado `Neptune#ml.disableInductiveInferenceMetadataCache` na consulta. Embora possa ser mais lento para o Neptune buscar os metadados diretamente do Amazon S3, isso é útil SageMaker quando o endpoint de IA é atualizado após um novo treinamento ou transformação e o cache está obsoleto.
Você inclui o predicado `Neptune#ml.disableInductiveInferenceMetadataCache` em uma consulta como esta:
```
.with("Neptune#ml.disableInductiveInferenceMetadataCache")
```
Veja um exemplo de consulta em um caderno Jupyter:
```
%%gremlin
g.with("Neptune#ml.endpoint", "ep1")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.with("Neptune#ml.disableInductiveInferenceMetadataCache")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
## `Neptune#ml.endpoint`
O predicado `Neptune#ml.endpoint` é usado em uma etapa `with()` para especificar o endpoint de inferência, se necessário:
```
.with("Neptune#ml.endpoint", "the model's SageMaker AI inference endpoint")
```
Você pode identificar o endpoint pelo `id` ou pelo URL. Por exemplo:
```
.with( "Neptune#ml.endpoint", "node-classification-movie-lens-endpoint" )
```
Ou:
```
.with( "Neptune#ml.endpoint", "https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/node-classification-movie-lens-endpoint/invocations" )
```
**nota**
Se você [definir o parâmetro `neptune_ml_endpoint`](machine-learning-cluster-setup.md#machine-learning-set-inference-endpoint-cluster-parameter) no grupo de parâmetros do cluster de banco de dados do Neptune como o URL ou o `id` do endpoint, não precisará incluir o predicado `Neptune#ml.endpoint` em cada consulta.
## `Neptune#ml.iamRoleArn`
`Neptune#ml.iamRoleArn`é usado em uma `with()` etapa para especificar o ARN da função IAM de execução da SageMaker IA, se necessário:
```
.with("Neptune#ml.iamRoleArn", "the ARN for the SageMaker AI execution IAM role")
```
Para obter informações sobre como criar a função IAM de execução de SageMaker IA, consulte[Crie um NeptuneSageMaker IAMRole papel personalizado](machine-learning-manual-setup.md#ml-manual-setup-sm-role).
**nota**
Se você [definir o `neptune_ml_iam_role` parâmetro](machine-learning-cluster-setup.md#machine-learning-enabling-create-param-group) no grupo de parâmetros do cluster do Neptune DB como o ARN da SageMaker sua função IAM de execução de IA, não precisará incluir `Neptune#ml.iamRoleArn` o predicado em cada consulta.
## Neptune\$1ml.inductiveInference
A inferência transdutiva é habilitada por padrão no Gremlin. Para fazer uma consulta de [inferência indutiva em tempo real](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference), inclua o predicado `Neptune#ml.inductiveInference` desta forma:
```
.with("Neptune#ml.inductiveInference")
```
Se seu grafo for dinâmico, a inferência indutiva geralmente será a melhor escolha, mas se seu grafo for estático, a inferência transdutiva será mais rápida e eficiente.
## `Neptune#ml.limit`
Opcionalmente, o predicado `Neptune#ml.limit` limita o número de resultados gerados por entidade:
```
.with( "Neptune#ml.limit", 2 )
```
Por padrão, o limite é 1 e o número máximo que pode ser definido é 100.
## `Neptune#ml.threshold`
Opcionalmente, o predicado `Neptune#ml.threshold` estabelece um limite de corte para as pontuações dos resultados:
```
.with( "Neptune#ml.threshold", 0.5D )
```
Isso permite que você descarte todos os resultados com pontuações abaixo do limite especificado.
## `Neptune#ml.classification`
O `Neptune#ml.classification` predicado é anexado à `properties()` etapa para estabelecer que as propriedades precisam ser obtidas do endpoint de SageMaker IA do modelo de classificação de nós:
```
.properties( "property key of the node classification model" ).with( "Neptune#ml.classification" )
```
## `Neptune#ml.regression`
O `Neptune#ml.regression` predicado é anexado à `properties()` etapa para estabelecer que as propriedades precisam ser obtidas do endpoint de SageMaker IA do modelo de regressão do nó:
```
.properties( "property key of the node regression model" ).with( "Neptune#ml.regression" )
```
## `Neptune#ml.prediction`
O predicado `Neptune#ml.prediction` é anexado às etapas `in()` e `out()` para estabelecer que se trata de uma consulta de previsão de links:
```
.in("edge label of the link prediction model").with("Neptune#ml.prediction").hasLabel("target node label")
```
## `Neptune#ml.score`
O predicado `Neptune#ml.score` é usado em consultas de classificação de nós ou bordas do Gremlin para obter uma pontuação de confiança de machine learning. O predicado `Neptune#ml.score` deve ser transmitido junto com o predicado da consulta na etapa `properties()` para obter uma pontuação de confiança de ML para consultas de classificação de nós ou bordas.
É possível encontrar um exemplo de classificação de nós com [outros exemplos de classificação de nós](machine-learning-gremlin-vertex-classification-queries.md#machine-learning-gremlin-node-class-other-queries) e um exemplo de classificação de bordas na [seção de classificação de bordas](machine-learning-gremlin-edge-classification-queries.md).
# Consultas de classificação de nós do Gremlin no Neptune ML
Para consultas de classificação de nós do Gremlin no Neptune ML:
+ O modelo é treinado em uma propriedade dos vértices. O conjunto de valores exclusivos dessa propriedade é chamado de conjunto de classes de nós ou, simplesmente, classes.
+ A classe do nó ou o valor da propriedade categórica da propriedade de um vértice pode ser inferido do modelo de classificação de nós. Isso é útil quando essa propriedade ainda não está anexada ao vértice.
+ Para buscar uma ou mais classes de um modelo de classificação de nós, você precisa usar a etapa `with()` com o predicado `Neptune#ml.classification` para configurar a etapa `properties()`. O formato de saída é semelhante ao esperado se essas fossem propriedades de vértice.
**nota**
A classificação de nós só funciona com valores de propriedades de string. Isso significa que valores de propriedades numéricas, como `0` ou `1`, não são compatíveis, embora a string seja equivalente a `"0"` e `"1"`. Da mesma forma, os valores de propriedade booliana `true` e `false` não funcionam, mas `"true"` e `"false"` funcionam.
Veja a seguir um exemplo de consulta de classificação de nós:
```
g.with( "Neptune#ml.endpoint","node-classification-movie-lens-endpoint" )
.with( "Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role" )
.with( "Neptune#ml.limit", 2 )
.with( "Neptune#ml.threshold", 0.5D )
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
```
O resultado dessa consulta seria algo semelhante ao seguinte:
```
==>vp[genre->Action]
==>vp[genre->Crime]
==>vp[genre->Comedy]
```
Na consulta acima, as etapas `V()` e `properties()` são usadas da seguinte forma:
A etapa `V()` contém o conjunto de vértices para os quais você deseja buscar as classes do modelo de classificação de nós:
```
.V( "movie_1", "movie_2", "movie_3" )
```
A etapa `properties()` contém a chave na qual o modelo foi treinado e tem `.with("Neptune#ml.classification")` para indicar que se trata de uma consulta de inferência de ML de classificação de nós.
Atualmente, não são aceitas várias chaves de propriedade em uma etapa `properties().with("Neptune#ml.classification")`. Por exemplo, a seguinte consulta gera uma exceção:
```
g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre", "other_label").with("Neptune#ml.classification")
```
Para ver a mensagem de erro específica, consulte a [lista de exceções do Neptune ML](machine-learning-gremlin-exceptions.md).
Uma etapa `properties().with("Neptune#ml.classification")` pode ser usada em combinação com qualquer uma das seguintes etapas:
+ `value()`
+ `value().is()`
+ `hasValue()`
+ `has(value,"")`
+ `key()`
+ `key().is()`
+ `hasKey()`
+ `has(key,"")`
+ `path()`
## Outras consultas de classificação de nós
Se o endpoint de inferência e o perfil do IAM correspondente tiverem sido salvos no seu grupo de parâmetros do cluster de banco de dados, uma consulta de classificação de nós poderá ser tão simples quanto esta:
```
g.V("movie_1", "movie_2", "movie_3").properties("genre").with("Neptune#ml.classification")
```
Você pode misturar propriedades e classes de vértices em uma consulta usando a etapa `union()`:
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.union(
properties("genre").with("Neptune#ml.classification"),
properties("genre")
)
```
Também é possível fazer uma consulta ilimitada, como esta:
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V()
.properties("genre").with("Neptune#ml.classification")
```
Você pode recuperar as classes de nós junto com os vértices usando a etapa `select()` junto com a etapa `as()`:
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" ).as("vertex")
.properties("genre").with("Neptune#ml.classification").as("properties")
.select("vertex","properties")
```
Também é possível filtrar por classes de nós, conforme ilustrado nestes exemplos:
```
g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, "Horror")
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, P.eq("Action"))
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, P.within("Action", "Horror"))
```
Você pode obter uma pontuação de confiança na classificação de nós usando o predicado `Neptune#ml.score`:
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre", "Neptune#ml.score").with("Neptune#ml.classification")
```
A resposta seria semelhante a esta:
```
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.01234567]
==>vp[genre->Crime]
==>vp[Neptune#ml.score->0.543210]
==>vp[genre->Comedy]
==>vp[Neptune#ml.score->0.10101]
```
## Usar inferência indutiva em uma consulta de classificação de nós
Suponha que você adicione um novo nó a um grafo existente, em um caderno Jupyter, da seguinte forma:
```
%%gremlin
g.addV('label1').property(id,'101').as('newV')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV')
```
Depois, você poderia usar uma consulta de inferência indutiva para obter um gênero e uma pontuação de confiança que refletissem o novo nó:
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("genre", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
```
No entanto, se você executou a consulta várias vezes, poderá obter resultados um pouco diferentes:
```
# First time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.21365921]
```
Você pode tornar a mesma consulta determinística:
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("genre", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
Nesse caso, os resultados seriam praticamente os mesmos todas as vezes:
```
# First time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
```
# Consultas de regressão de nós do Gremlin no Neptune ML
A regressão de nós é semelhante à classificação de nós, exceto que o valor inferido do modelo de regressão para cada nó é numérico. É possível usar as mesmas consultas do Gremlin para regressão e classificação de nós, exceto pelas seguintes diferenças:
+ Novamente, no Neptune ML, os nós se referem a vértices.
+ A etapa `properties()` assume a forma `properties().with("Neptune#ml.regression")` em vez de `properties().with("Neptune#ml.classification")`.
+ Os predicados `"Neptune#ml.limit` e `"Neptune#ml.threshold"` não são aplicáveis.
+ Ao filtrar o valor, você precisa especificar um valor numérico.
Veja a seguir um exemplo de consulta de classificação de vértices:
```
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
```
Você pode filtrar o valor inferido usando um modelo de regressão, conforme ilustrado nos seguintes exemplos:
```
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
.value().is(P.gte(1600000))
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
.hasValue(P.lte(1600000D))
```
## Usar inferência indutiva em uma consulta de regressão de nós
Suponha que você adicione um novo nó a um grafo existente, em um caderno Jupyter, da seguinte forma:
```
%%gremlin
g.addV('label1').property(id,'101').as('newV')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV')
```
Depois, você pode usar uma consulta de inferência indutiva para obter uma classificação que leve em conta o novo nó:
```
%%gremlin
g.with("Neptune#ml.endpoint", "nr-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
Como a consulta não é determinística, ela poderá gerar resultados um pouco diferentes se você a executar várias vezes, com base na vizinhança:
```
# First time
==>vp[rating->9.1]
# Second time
==>vp[rating->8.9]
```
Se precisar de resultados mais consistentes, você poderá tornar a consulta determinística:
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
Agora, os resultados serão praticamente os mesmos todas as vezes:
```
# First time
==>vp[rating->9.1]
# Second time
==>vp[rating->9.1]
```
# Consultas de classificação de bordas do Gremlin no Neptune ML
Para consultas de classificação de bordas do Gremlin no Neptune ML:
+ O modelo é treinado em uma propriedade das bordas. O conjunto de valores exclusivos dessa propriedade é chamado de conjunto de classes.
+ O valor da classe ou da propriedade categórica de uma borda pode ser inferido do modelo de classificação de bordas, o que é útil quando essa propriedade ainda não está anexada à borda.
+ Para buscar uma ou mais classes de um modelo de classificação de bordas, é necessário usar a etapa `with()` com o predicado, `"Neptune#ml.classification"` para configurar a etapa `properties()`. O formato de saída é semelhante ao esperado se essas fossem propriedades de borda.
**nota**
A classificação de bordas só funciona com valores de propriedades de string. Isso significa que valores de propriedades numéricas, como `0` ou `1`, não são compatíveis, embora a string seja equivalente a `"0"` e `"1"`. Da mesma forma, os valores de propriedade booliana `true` e `false` não funcionam, mas `"true"` e `"false"` funcionam.
Aqui está um exemplo de consulta de classificação de bordas que solicita uma pontuação de confiança usando o predicado `Neptune#ml.score`:
```
g.with("Neptune#ml.endpoint","edge-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by", "Neptune#ml.score").with("Neptune#ml.classification")
```
A resposta seria semelhante a esta:
```
==>p[knows_by->"Family"]
==>p[Neptune#ml.score->0.01234567]
==>p[knows_by->"Friends"]
==>p[Neptune#ml.score->0.543210]
==>p[knows_by->"Colleagues"]
==>p[Neptune#ml.score->0.10101]
```
## Sintaxe de uma consulta de classificação de bordas do Gremlin
Para um grafo simples em que `User` é o nó principal e final e `Relationship` é a borda que os conecta, um exemplo de consulta de classificação de bordas é:
```
g.with("Neptune#ml.endpoint","edge-classification-social-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by").with("Neptune#ml.classification")
```
O resultado dessa consulta seria algo semelhante ao seguinte:
```
==>p[knows_by->"Family"]
==>p[knows_by->"Friends"]
==>p[knows_by->"Colleagues"]
```
Na consulta acima, as etapas `E()` e `properties()` são usadas da seguinte forma:
+ A etapa `E()` contém o conjunto de bordas para os quais você deseja buscar as classes do modelo de classificação de bordas:
```
.E("relationship_1","relationship_2","relationship_3")
```
+ A etapa `properties()` contém a chave na qual o modelo foi treinado e tem `.with("Neptune#ml.classification")` para indicar que se trata de uma consulta de inferência de ML de classificação de bordas.
Atualmente, não são aceitas várias chaves de propriedade em uma etapa `properties().with("Neptune#ml.classification")`. Por exemplo, a consulta a seguir ocasiona o lançamento de uma exceção:
```
g.with("Neptune#ml.endpoint","edge-classification-social-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by", "other_label").with("Neptune#ml.classification")
```
Sobre mensagens de erro específicas, consulte [Lista de exceções para consultas de inferência do Gremlin no Neptune ML](machine-learning-gremlin-exceptions.md).
Uma etapa `properties().with("Neptune#ml.classification")` pode ser usada em combinação com qualquer uma das seguintes etapas:
+ `value()`
+ `value().is()`
+ `hasValue()`
+ `has(value,"")`
+ `key()`
+ `key().is()`
+ `hasKey()`
+ `has(key,"")`
+ `path()`
## Usar inferência indutiva em uma consulta de classificação de bordas
Suponha que você adicione uma nova borda a um grafo existente, em um caderno Jupyter, da seguinte forma:
```
%%gremlin
g.V('1').as('fromV')
.V('2').as('toV')
.addE('eLabel1').from('fromV').to('toV').property(id, 'e101')
```
Depois, você poderia usar uma consulta de inferência indutiva para obter uma escala que levasse em conta a nova borda:
```
%%gremlin
g.with("Neptune#ml.endpoint", "ec-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("scale", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
```
Como a consulta não é determinística, os resultados seriam um pouco diferentes se você a executasse várias vezes, com base na vizinhança aleatória:
```
# First time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.21365921]
```
Se precisar de resultados mais consistentes, você poderá tornar a consulta determinística:
```
%%gremlin
g.with("Neptune#ml.endpoint", "ec-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("scale", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
Agora, os resultados serão mais ou menos os mesmos toda vez que você executar a consulta:
```
# First time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
```
# Consultas de regressão de bordas do Gremlin no Neptune ML
A regressão de bordas é semelhante à classificação de bordas, exceto que o valor inferido do modelo de ML é numérico. Para regressão de bordas, o Neptune ML é compatível com as mesmas consultas de classificação.
Os principais pontos a serem observados são:
+ Você precisa usar o predicado de ML `"Neptune#ml.regression"` para configurar a etapa `properties()` para esse caso de uso.
+ Os predicados `"Neptune#ml.limit"` e `"Neptune#ml.threshold"` não são aplicáveis nesse caso de uso.
+ Para filtrar o valor, você precisa especificar o valor como numérico.
## Sintaxe de uma consulta de regressão de bordas do Gremlin
Para um grafo simples em que `User` está o nó principal, `Movie` o nó final e `Rated` é a borda que os conecta, aqui está um exemplo de consulta de regressão de bordas que encontra o valor da classificação numérica, chamado de pontuação aqui, da borda `Rated`:
```
g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("rating_1","rating_2","rating_3")
.properties("score").with("Neptune#ml.regression")
```
Também é possível filtrar por um valor inferido do modelo de regressão de ML. Para as bordas `Rated` existentes (de `User` a `Movie`) identificadas por `"rating_1"`, `"rating_2"` e `"rating_3"`, em que a propriedade de borda `Score` não está presente para essas classificações, é possível usar uma consulta como a seguinte para inferir `Score` para as bordas em que ela é maior ou igual a 9:
```
g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("rating_1","rating_2","rating_3")
.properties("score").with("Neptune#ml.regression")
.value().is(P.gte(9))
```
## Usar inferência indutiva em uma consulta de regressão de bordas
Suponha que você adicione uma nova borda a um grafo existente, em um caderno Jupyter, da seguinte forma:
```
%%gremlin
g.V('1').as('fromV')
.V('2').as('toV')
.addE('eLabel1').from('fromV').to('toV').property(id, 'e101')
```
Depois, você pode usar uma consulta de inferência indutiva para obter uma pontuação que leve em conta a nova borda:
```
%%gremlin
g.with("Neptune#ml.endpoint", "er-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("score")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
Como a consulta não é determinística, os resultados seriam um pouco diferentes se você a executasse várias vezes, com base na vizinhança aleatória:
```
# First time
==>ep[score->96]
# Second time
==>ep[score->91]
```
Se precisar de resultados mais consistentes, você poderá tornar a consulta determinística:
```
%%gremlin
g.with("Neptune#ml.endpoint", "er-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("score")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
Agora, os resultados serão mais ou menos os mesmos toda vez que você executar a consulta:
```
# First time
==>ep[score->96]
# Second time
==>ep[score->96]
```
# Consultas de previsão de links do Gremlin usando modelos de previsão de links no Neptune ML
Os modelos de previsão de links podem resolver problemas, como os seguintes:
+ **Previsão do nó principal**: considerando um tipo de vértice e borda, a quais vértices esse vértice provavelmente se vinculará?
+ **Previsão do nó final**: considerando um rótulo de vértice e borda, a quais vértices esse vértice provavelmente se vinculará?
**nota**
A previsão de borda ainda não é aceita no Neptune ML.
Para os exemplos abaixo, considere um grafo simples com os vértices `User` e `Movie` que estão vinculados pela borda `Rated`.
Aqui está um exemplo de consulta de previsão do nó principal, usada para prever os cinco principais usuários com maior probabilidade de avaliar os filmes, `"movie_1"`, `"movie_2"` e `"movie_3"`.
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.with("Neptune#ml.limit", 5)
.V("movie_1", "movie_2", "movie_3")
.in("rated").with("Neptune#ml.prediction").hasLabel("user")
```
Aqui está uma similar para previsão de nó final, usada para prever os cinco principais filmes que o usuário `"user_1"` provavelmente avaliará:
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie")
```
Tanto o rótulo da borda quanto o rótulo do vértice previsto são obrigatórios. Se um deles for omitido, uma exceção será lançada. Por exemplo, a seguinte consulta sem um rótulo de vértice previsto gera uma exceção:
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction")
```
Da mesma forma, a seguinte consulta sem um rótulo de borda gera uma exceção:
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out().with("Neptune#ml.prediction").hasLabel("movie")
```
Para ver a mensagem de erro específica, consulte a [lista de exceções do Neptune ML](machine-learning-gremlin-exceptions.md).
## Outras consultas de previsão de links
Você pode usar a etapa `select()` com a etapa `as(`) para gerar os vértices previstos junto com os vértices de entrada:
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1").as("source")
.in("rated").with("Neptune#ml.prediction").hasLabel("user").as("target")
.select("source","target")
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1").as("source")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie").as("target")
.select("source","target")
```
É possível fazer consultas ilimitadas, como estas:
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie")
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1")
.in("rated").with("Neptune#ml.prediction").hasLabel("user")
```
## Usar inferência indutiva em uma consulta de previsão de links
Suponha que você adicione um novo nó a um grafo existente, em um caderno Jupyter, da seguinte forma:
```
%%gremlin
g.addV('label1').property(id,'101').as('newV1')
.addV('label2').property(id,'102').as('newV2')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV1').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV2')
```
Você pode então usar uma consulta de inferência indutiva para prever o nó principal, levando em consideração o novo nó:
```
%%gremlin
g.with("Neptune#ml.endpoint", "lp-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').out("eLabel1")
.with("Neptune#ml.prediction")
.with("Neptune#ml.inductiveInference")
.hasLabel("label2")
```
Resultado:
```
==>V[2]
```
Da mesma forma, você pode usar uma consulta de inferência indutiva para prever o nó final, levando em consideração o novo nó:
```
%%gremlin
g.with("Neptune#ml.endpoint", "lp-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('102').in("eLabel2")
.with("Neptune#ml.prediction")
.with("Neptune#ml.inductiveInference")
.hasLabel("label1")
```
Resultado:
```
==>V[1]
```
# Lista de exceções para consultas de inferência do Gremlin no Neptune ML
Essa é uma lista abrangente de exceções que podem ocorrer ao executar consultas de inferência do Neptune ML Gremlin. Essas exceções abrangem uma série de problemas, desde problemas com o endpoint ou perfil do IAM especificado até etapas incompatíveis do Gremlin e limitações no número de consultas de inferência de ML por consulta. Cada entrada inclui uma mensagem detalhada descrevendo o problema.
+ **`BadRequestException`**: as credenciais do perfil fornecido não podem ser carregadas.
*Mensagem*: `Unable to load credentials for role: the specified IAM Role ARN.`
+ **`BadRequestException`**— A função do IAM especificada não está autorizada a invocar o endpoint de SageMaker IA.
*Mensagem*: `User: the specified IAM Role ARN is not authorized to perform: sagemaker:InvokeEndpoint on resource: the specified endpoint.`
+ **`BadRequestException`**: o endpoint especificado não existe.
*Mensagem*: `Endpoint the specified endpoint not found.`
+ **`InternalFailureException`**: não é possível obter metadados de inferência indutiva em tempo real do Neptune ML do Amazon S3.
*Mensagem*: `Unable to fetch Neptune ML - Real-Time Inductive Inference metadata from S3. Check the permissions of the S3 bucket or if the Neptune instance can connect to S3.`
+ **`InternalFailureException`**: o Neptune ML não consegue encontrar o arquivo de metadados para inferência indutiva em tempo real no Amazon S3.
*Mensagem*: `Neptune ML cannot find the metadata file for Real-Time Inductive Inference in S3.`
+ **`InvalidParameterException`**: o endpoint especificado não é sintaticamente válido.
*Mensagem*: `Invalid endpoint provided for external service query.`
+ **`InvalidParameterException`**— O ARN da função IAM de SageMaker execução especificada não é sintaticamente válido.
*Mensagem*: `Invalid IAM role ARN provided for external service query.`
+ **`InvalidParameterException`**: várias chaves de propriedade são especificadas na etapa `properties()` de uma consulta.
*Mensagem*: `ML inference queries are currently supported for one property key.`
+ **`InvalidParameterException`**: vários rótulos de borda são especificados em uma consulta.
*Mensagem*: `ML inference are currently supported only with one edge label.`
+ **`InvalidParameterException`**: várias restrições de rótulos de vértice são especificadas em uma consulta.
*Mensagem*: `ML inference are currently supported only with one vertex label constraint.`
+ **`InvalidParameterException`**: os predicados `Neptune#ml.classification` e `Neptune#ml.regression` estão presentes na mesma consulta.
*Mensagem*: `Both regression and classification ML predicates cannot be specified in the query.`
+ **`InvalidParameterException`**: mais de um rótulo de borda foi especificado na etapa `in()` ou `out()` em uma consulta de previsão de links.
*Mensagem*: `ML inference are currently supported only with one edge label.`
+ **`InvalidParameterException`**: mais de uma chave de propriedade foi especificada com Neptune\$1ml.score.
*Mensagem*: `Neptune ML inference queries are currently supported for one property key and one Neptune#ml.score property key.`
+ **`MissingParameterException`**: o endpoint não foi especificado na consulta nem como um parâmetro de cluster de banco de dados.
*Mensagem*: `No endpoint provided for external service query.`
+ **``MissingParameterException**— A função IAM de execução da SageMaker IA não foi especificada na consulta ou como um parâmetro de cluster de banco de dados.
*Mensagem*: `No IAM role ARN provided for external service query.`
+ **`MissingParameterException`**: a chave da propriedade está ausente na etapa `properties()` de uma consulta.
*Mensagem*: `Property key needs to be specified using properties() step for ML inference queries.`
+ **`MissingParameterException`**: nenhum rótulo de borda foi especificado na etapa `in()` ou `out()` em uma consulta de previsão de links.
*Mensagem*: `Edge label needs to be specified while using in() or out() step for ML inference queries.`
+ **`MissingParameterException`**: nenhuma chave de propriedade foi especificada com Neptune\$1ml.score.
*Mensagem*: `Property key needs to be specified along with Neptune#ml.score property key while using the properties() step for Neptune ML inference queries.`
+ **`UnsupportedOperationException`**: a etapa `both()` é usada em uma consulta de previsão de links.
*Mensagem*: `ML inference queries are currently not supported with both() step.`
+ **`UnsupportedOperationException`**: nenhum rótulo de vértice previsto foi especificado na etapa `has()` com a etapa `in()` ou `out()` em uma consulta de previsão de links.
*Mensagem*: `Predicted vertex label needs to be specified using has() step for ML inference queries.`
+ **`UnsupportedOperationException`**: no momento, as consultas de inferência indutiva de ML do Gremlin não são compatíveis com etapas não otimizadas.
*Mensagem*: `Neptune ML - Real-Time Inductive Inference queries are currently not supported with Gremlin steps which are not optimized for Neptune. Check the Neptune User Guide for a list of Neptune-optimized steps.`
+ **`UnsupportedOperationException`**: no momento, as consultas de inferência do Neptune ML não são aceitas em uma etapa `repeat`.
*Mensagem*: `Neptune ML inference queries are currently not supported inside a repeat step.`
+ **`UnsupportedOperationException`**: no momento, não há compatibilidade com mais de uma consulta de inferência do Neptune ML por consulta do Gremlin.
*Mensagem*: `Neptune ML inference queries are currently supported only with one ML inference query per gremlin query.`
# Consultas de inferência do SPARQL no Neptune ML
O Neptune ML associa o grafo do RDF a um grafo de propriedades para modelar a tarefa de ML. No momento, ele é compatível com os seguintes casos de uso:
+ **Classificação de objetos**: prevê o atributo categórico de um objeto.
+ **Regressão de objetos**: prevê uma propriedade numérica de um objeto.
+ **Previsão de objetos**: prevê um objeto considerando-se um assunto e um relacionamento.
+ **Previsão de assunto**: prevê um assunto considerando-se um objeto e um relacionamento.
**nota**
O Neptune ML não é compatível com casos de uso de classificação e regressão de assuntos com SPARQL.
# Predicados do Neptune ML usados em consultas de inferência do SPARQL
Os seguintes predicados são usados com inferência do SPARQL:
## Predicado `neptune-ml:timeout`
Especifica o tempo limite para conexão com o servidor remoto. Não deve ser confundido com o tempo limite da solicitação de consulta, que é o tempo máximo que o servidor pode levar para atender a uma solicitação.
Observe que, se o tempo limite da consulta ocorrer antes do tempo limite do serviço especificado pelo predicado `neptune-ml:timeout`, a conexão do serviço também será cancelada.
## Predicado `neptune-ml:outputClass`
O predicado `neptune-ml:outputClass` só é usado para definir a classe do objeto previsto para previsão de objetos ou do assunto previsto para a previsão do assunto.
## Predicado `neptune-ml:outputScore`
O predicado `neptune-ml:outputScore` é um número positivo que representa a probabilidade de que a saída de um modelo de machine learning esteja correta.
## Predicado `neptune-ml:modelType`
O predicado `neptune-ml:modelType` especifica o tipo de modelo de machine learning que está sendo treinado:
+ `OBJECT_CLASSIFICATION`
+ `OBJECT_REGRESSION`
+ `OBJECT_PREDICTION`
+ `SUBJECT_PREDICTION`
## Predicado `neptune-ml:input`
O predicado `neptune-ml:input` se refere à lista de URIs usados como entradas para o Neptune ML.
## Predicado `neptune-ml:output`
O predicado `neptune-ml:output` se refere à lista de conjuntos de vinculação em que o Neptune ML gera resultados.
## Predicado `neptune-ml:predicate`
O predicado `neptune-ml:predicate` é usado de forma diferente dependendo da tarefa que estiver sendo realizada:
+ Para **previsão de objetos ou assuntos**: define o tipo de predicado (o tipo de borda ou de relacionamento).
+ Para **classificação e regressão de objetos**: define o literal (propriedade) que queremos prever.
## Predicado `neptune-ml:batchSize`
O `neptune-ml:batchSize` especifica o tamanho da entrada para a chamada de serviço remoto.
# Exemplos de classificação de objetos do SPARQL
Para classificação de objetos do SPARQL no Neptune ML, o modelo é treinado em um dos valores de predicados. Isso é útil quando esse predicado ainda não está presente em um assunto específico.
Somente valores de predicados categóricos podem ser inferidos usando o modelo de classificação de objetos.
A seguinte consulta busca prever o valor do predicado para todas as entradas do tipo `foaf:Person`:
```
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:modelType 'OBJECT_CLASSIFICATION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output .
}
}
```
Essa consulta pode ser personalizada da seguinte forma:
```
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:endpoint 'node-prediction-account-balance-endpoint' ;
neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ;
neptune-ml:batchSize "40"^^xsd:integer ;
neptune-ml:timeout "1000"^^xsd:integer ;
neptune-ml:modelType 'OBJECT_CLASSIFICATION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output .
}
}
```
# Exemplos de regressão de objetos do SPARQL
A regressão de objetos é semelhante à classificação de objetos, exceto por um valor de predicado numérico inferido do modelo de regressão para cada nó. É possível usar as mesmas consultas do SPARQL para regressão de objetos e para classificação de objetos, com a exceção de que os predicados `the Neptune#ml.limit` e `Neptune#ml.threshold` não são aplicáveis.
A seguinte consulta busca prever o valor do predicado para todas as entradas do tipo `foaf:Person`:
```
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:modelType 'OBJECT_REGRESSION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output .
}
}
```
Essa consulta pode ser personalizada da seguinte forma:
```
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:endpoint 'node-prediction-account-balance-endpoint' ;
neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ;
neptune-ml:batchSize "40"^^xsd:integer ;
neptune-ml:timeout "1000"^^xsd:integer ;
neptune-ml:modelType 'OBJECT_REGRESSION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output .
}
}
```
# Exemplo de previsão de objetos do SPARQL
A *previsão de objetos* prevê o valor do objeto para um assunto e um predicado específicos.
A seguinte consulta de previsão de objetos busca prever de qual filme a entrada do tipo `foaf:Person` gostaria:
```
?x a foaf:Person .
?x ?m .
?m a .
## Query
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:modelType 'OBJECT_PREDICTION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output ;
neptune-ml:outputClass .
}
}
```
A consulta em si pode ser personalizada da seguinte forma:
```
SELECT * WHERE { ?input a foaf:Person .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:endpoint 'node-prediction-user-movie-prediction-endpoint' ;
neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ;
neptune-ml:limit "5"^^xsd:integer ;
neptune-ml:batchSize "40"^^xsd:integer ;
neptune-ml:threshold "0.1"^^xsd:double ;
neptune-ml:timeout "1000"^^xsd:integer ;
neptune-ml:outputScore ?score ;
neptune-ml:modelType 'OBJECT_PREDICTION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output ;
neptune-ml:outputClass .
}
}
```
# Exemplo de previsão de assuntos do SPARQL
A *previsão de assuntos* prevê o assunto considerando-se um predicado e um objeto.
Por exemplo, a seguinte consulta prevê quem (do tipo `foaf:User`) assistirá a determinado filme:
```
SELECT * WHERE { ?input (a foaf:Movie) .
SERVICE neptune-ml:inference {
neptune-ml:config neptune-ml:modelType 'SUBJECT_PREDICTION' ;
neptune-ml:input ?input ;
neptune-ml:predicate ;
neptune-ml:output ?output ;
neptune-ml:outputClass ; }
}
```
# Lista de exceções para consultas de inferência do SPARQL no Neptune ML
****
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects at least 1 value for the parameter (parameter name), found zero.`
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects at most 1 value for the parameter (parameter name), found (a number) values.`
+ **`BadRequestException`**: *mensagem*: `Invalid predicate (predicate name) provided for external service http://aws.amazon.com/neptune/vocab/v01/services/ml#inference query.`
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the predicate (predicate name) to be defined`.
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the value of (parameter) (parameter name) to be a variable, found: (type)"`
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the input (parameter name) to be a constant, found: (type)`.
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference is expected to return only 1 value`.
+ **`BadRequestException`**: *mensagem*: `"The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference only allows StatementPatternNodes`.
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference does not allow the predicate (predicate name)`.
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference predicates cannot be variables, found: (type)`.
+ **`BadRequestException`**: *mensagem*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference predicates are expected to be part of the namespace (namespace name), found: (namespace name)`.
# Referência da API de gerenciamento do Neptune ML
**Contents**
+ [O comando de processamento de dados](machine-learning-api-dataprocessing.md)
+ [Criar um trabalho de processamento de dados](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-create-job)
+ [Obter o status do trabalho](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-get-job-status)
+ [Interromper um trabalho](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-stop-job)
+ [Listar trabalhos](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-list-jobs)
+ [O comando modeltraining](machine-learning-api-modeltraining.md)
+ [Criar um trabalho de treinamento de modelos](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job)
+ [Obter o status do trabalho](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-get-job-status)
+ [Interromper um trabalho](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-stop-job)
+ [Listar trabalhos](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-list-jobs)
+ [O comando modeltransform](machine-learning-api-modeltransform.md)
+ [Criar um trabalho de transformação de modelos](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-create-job)
+ [Obter o status do trabalho](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-get-job-status)
+ [Interromper um trabalho](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-stop-job)
+ [Listar trabalhos](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-list-jobs)
+ [O comando endpoints](machine-learning-api-endpoints.md)
+ [Criar um endpoint de inferência](machine-learning-api-endpoints.md#machine-learning-api-endpoints-create-job)
+ [Obter o status do endpoint](machine-learning-api-endpoints.md#machine-learning-api-endpoints-get-endpoint-status)
+ [Excluir um endpoint](machine-learning-api-endpoints.md#machine-learning-api-endpoints-delete-endpoint)
+ [Listar endpoints de inferência](machine-learning-api-endpoints.md#machine-learning-api-endpoints-list-endpoints)
+ [Exceções](machine-learning-api-exceptions.md)
# Processamento de dados usando o comando `dataprocessing`
Use o comando `dataprocessing` do Neptune ML para criar um trabalho de processamento de dados, conferir o status, interrompê-lo ou listar todos os trabalhos ativos de processamento de dados.
## Criar um trabalho de processamento de dados usando o comando `dataprocessing` do Neptune ML
Um comando `dataprocessing` típico do Neptune ML para criar um trabalho tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/dataprocessing \
-H 'Content-Type: application/json' \
-d '{
"inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)",
"id" : "(a job ID for the new job)",
"processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)"
}'
```
Um comando para iniciar o reprocessamento incremental tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/dataprocessing \
-H 'Content-Type: application/json' \
-d '{
"inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)",
"id" : "(a job ID for this job)",
"processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)"
"previousDataProcessingJobId" : "(the job ID of a previously completed job to update)"
}'
```
**Parâmetros para criação de trabalhos `dataprocessing`**
+ **`id`**: (*opcional*) um identificador exclusivo do novo trabalho.
*Tipo*: string. *Padrão*: um UUID gerado automaticamente.
+ **`previousDataProcessingJobId`**: (*opcional*) o ID de um trabalho de processamento de dados concluído executado em uma versão anterior dos dados.
*Tipo*: string. *Padrão*: *nenhum*.
*Observação*: use para processamento incremental de dados, para atualizar o modelo quando os dados do grafo forem alterados (mas não quando os dados forem excluídos).
+ **`inputDataS3Location`**— (*Obrigatório*) O URI do local do Amazon S3 em que você deseja que a SageMaker IA baixe os dados necessários para executar o trabalho de processamento de dados.
*Tipo*: string.
+ **`processedDataS3Location`**— (*Obrigatório*) O URI do local do Amazon S3 em que você deseja que a SageMaker IA salve os resultados de um trabalho de processamento de dados.
*Tipo*: string.
+ **`sagemakerIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM para execução de SageMaker IA.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`neptuneIamRoleArn`**— (*Opcional*) O nome de recurso da Amazon (ARN) de uma função do IAM que a SageMaker IA pode assumir para realizar tarefas em seu nome.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`processingInstanceType`**: (*opcional*) o tipo de instância de ML usada durante o processamento de dados. A memória deve ser grande o suficiente para armazenar o conjunto de dados processado.
*Tipo*: string. *Padrão*: o menor tipo `ml.r5` cuja memória é dez vezes maior que o tamanho dos dados de grafos exportados no disco.
*Observação*: o Neptune ML pode selecionar o tipo de instância automaticamente. Consulte [Selecionar uma instância para processamento de dados](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size).
+ **`processingInstanceVolumeSizeInGB`**: (*opcional*) o tamanho do volume do disco da instância de processamento. Tanto os dados de entrada quanto os dados processados são armazenados em disco, portanto, o tamanho do volume deve ser grande o suficiente para conter os dois conjuntos de dados.
*Tipo*: número inteiro. *Padrão*: `0`.
*Observação*: se não for especificado ou for 0, o Neptune ML escolherá o tamanho do volume automaticamente com base no tamanho dos dados.
+ **`processingTimeOutInSeconds`**: (*opcional*) tempo limite em segundos do trabalho de processamento de dados.
*Tipo*: número inteiro. *Padrão*: `86,400` (um dia).
+ **`modelType`**: (*opcional*) um dos dois tipos de modelo que o Neptune ML aceita no momento: modelos de grafos heterogêneos (`heterogeneous`) e grafo de conhecimento (`kge`).
*Tipo*: string. *Padrão*: *nenhum*.
*Observação*: se não for especificado, o Neptune ML escolherá o tipo de modelo automaticamente com base nos dados.
+ **`configFileName`**: (*opcional*) um arquivo de especificação de dados que descreve como carregar os dados de grafos exportados para treinamento. O arquivo é gerado automaticamente pelo kit de ferramentas de exportação do Neptune.
*Tipo*: string. *Padrão*: `training-data-configuration.json`.
+ **`subnets`**— (*Opcional*) A IDs das sub-redes na VPC Neptune.
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`securityGroupIds`**— (*Opcional*) O grupo de segurança da VPC. IDs
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`volumeEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar dados no volume de armazenamento anexado às instâncias de computação de ML que executam o trabalho de processamento.
*Tipo*: string *Padrão*: *nenhum*.
+ **`enableInterContainerTrafficEncryption`**: (*opcional*) habilite ou desabilite a criptografia de tráfego entre contêineres em trabalhos de treinamento ou ajuste de hiperparâmetros.
*Tipo*: booliano. *Padrão*: *verdadeiro*.
**nota**
O parâmetro `enableInterContainerTrafficEncryption` só está disponível na [versão 1.2.0.2.R3 do mecanismo](engine-releases-1.2.0.2.R3.md).
+ **`s3OutputEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar a saída do trabalho de treinamento.
*Tipo*: string *Padrão*: *nenhum*.
## Obter o status de um trabalho de processamento de dados usando o comando `dataprocessing` do Neptune ML
Um exemplo de comando `dataprocessing` do Neptune ML para o status de um trabalho tem a seguinte aparência:
```
curl -s \
"https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)" \
| python -m json.tool
```
**Parâmetros para o status do trabalho `dataprocessing`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de processamento de dados.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
## Interromper um trabalho de processamento de dados usando o comando `dataprocessing` do Neptune ML
Um exemplo de comando `dataprocessing` do Neptune ML para interromper um trabalho tem a seguinte aparência:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)"
```
Ou esta:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)?clean=true"
```
**Parâmetros para um trabalho de interrupção `dataprocessing`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de processamento de dados.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`clean`**: (*opcional*) esse sinalizador especifica que todos os artefatos do Amazon S3 devem ser excluídos quando o trabalho é interrompido.
*Tipo*: booliano. *Padrão*: `FALSE`.
## Listar trabalhos de processamento de dados ativos usando o comando `dataprocessing` do Neptune ML
Um exemplo de comando `dataprocessing` do Neptune ML para listar trabalhos ativos tem a seguinte aparência:
```
curl -s "https://(your Neptune endpoint)/ml/dataprocessing"
```
Ou esta:
```
curl -s "https://(your Neptune endpoint)/ml/dataprocessing?maxItems=3"
```
**Parâmetros para trabalhos de lista `dataprocessing`**
+ **`maxItems`**: (*opcional*) o número máximo de itens a serem gerados.
*Tipo*: número inteiro. *Padrão*: `10`. *Valor máximo permitido*: `1024`.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
# Treinamento de modelos usando o comando `modeltraining`
Use o comando `modeltraining` do Neptune ML para criar um trabalho de treinamento de modelos, conferir o status, interrompê-lo ou listar todos os trabalhos ativos de treinamento de modelos.
## Criar um trabalho de treinamento de modelos usando o comando `modeltraining` do Neptune ML
Um comando `modeltraining` do Neptune ML para criar um trabalho tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
}'
```
Um comando `modeltraining` do Neptune ML para criar um trabalho de atualização para treinamento incremental de modelos tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
"previousModelTrainingJobId" : "(the job ID of a completed model-training job to update)",
}'
```
Um comando `modeltraining` do Neptune ML para criar um trabalho com a implementação de modelos personalizados fornecidos pelo usuário tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltraining
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"dataProcessingJobId" : "(the data-processing job-id of a completed job)",
"trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer"
"modelName": "custom",
"customModelTrainingParameters" : {
"sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)",
"trainingEntryPointScript": "(your training script entry-point name in the Python module)",
"transformEntryPointScript": "(your transform script entry-point name in the Python module)"
}
}'
```
**Parâmetros para criação de trabalhos `modeltraining`**
+ **`id`**: (*opcional*) um identificador exclusivo do novo trabalho.
*Tipo*: string. *Padrão*: um UUID gerado automaticamente.
+ **`dataProcessingJobId`**: (*obrigatório*) o ID do trabalho de processamento de dados concluído que criou os dados com os quais o treinamento funcionará.
*Tipo*: string
+ **`trainModelS3Location`**: (*obrigatório*) o local no Amazon S3 onde os artefatos do modelo devem ser armazenados.
*Tipo*: string
+ **`previousModelTrainingJobId`**: (*opcional*) o ID de um trabalho de treinamento de modelos concluído que você deseja atualizar de modo incremental com base nos dados atualizados.
*Tipo*: string *Padrão*: *nenhum*.
+ **`sagemakerIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM para execução de SageMaker IA.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`modelName`**: (*opcional*) o tipo de modelo para treinamento. Por padrão, o modelo de ML é automaticamente baseado no `modelType` usado no processamento de dados, mas você pode especificar um tipo de modelo diferente aqui.
*Tipo*: string. *Padrão*: `rgcn` para grafos heterogêneos e `kge` para grafos de conhecimento. *Valores válidos*: para grafos heterogêneos: `rgcn`. Para grafos `kge`:`transe`, `distmult` ou `rotate`. Para uma implementação de modelos personalizados: `custom`.
+ **`baseProcessingInstanceType`**: (*opcional*) o tipo de instância de ML usada na preparação e gerenciamento do treinamento de modelos de ML.
*Tipo*: string *Observação*: é uma instância de CPU escolhida com base nos requisitos de memória para processar os dados e o modelo de treinamento. Consulte [Selecionar uma instância para treinamento e transformação de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size).
+ **`trainingInstanceType`**: (*opcional*) o tipo de instância de ML usada para treinamento de modelos. Todos os modelos do Neptune ML são compatíveis com o treinamento de CPU, GPU e multiGPU.
*Tipo*: string *Padrão*: `ml.p3.2xlarge`.
*Observação*: a escolha do tipo de instância certo para treinamento depende do tipo de tarefa, do tamanho do grafo e do orçamento. Consulte [Selecionar uma instância para treinamento e transformação de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size).
+ **`trainingInstanceVolumeSizeInGB`**: (*opcional*) o tamanho do volume do disco da instância de treinamento. Tanto os dados de entrada quanto o modelo de saída são armazenados em disco, portanto, o tamanho do volume deve ser grande o suficiente para conter os dois conjuntos de dados.
*Tipo*: número inteiro. *Padrão*: `0`.
*Observação*: se não for especificado ou for 0, o Neptune ML selecionará um tamanho de volume de disco com base na recomendação gerada na etapa de processamento de dados. Consulte [Selecionar uma instância para treinamento e transformação de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size).
+ **`trainingTimeOutInSeconds`**: (*opcional*) tempo limite em segundos para o trabalho de treinamento.
*Tipo*: número inteiro. *Padrão*: `86,400` (um dia).
+ **`maxHPONumberOfTrainingJobs`**: número total máximo de trabalhos de treinamento a serem iniciados para o trabalho de ajuste de hiperparâmetros.
*Tipo*: número inteiro. *Padrão*: `2`.
*Observação*: o Neptune ML ajusta automaticamente os hiperparâmetros do modelo de machine learning. Para obter um modelo com bom desempenho, use pelo menos dez trabalhos (em outras palavras, defina `maxHPONumberOfTrainingJobs` como dez). Em geral, quanto mais ajustes forem executados, melhores serão os resultados.
+ **`maxHPOParallelTrainingJobs`**: número máximo de trabalhos de treinamento paralelos a serem iniciados para o trabalho de ajuste de hiperparâmetros.
*Tipo*: número inteiro. *Padrão*: `2`.
*Observação*: o número de trabalhos paralelos que você pode executar é limitado pelos recursos disponíveis na instância de treinamento.
+ **`subnets`**— (*Opcional*) A IDs das sub-redes na VPC Neptune.
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`securityGroupIds`**— (*Opcional*) O grupo de segurança da VPC. IDs
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`volumeEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar dados no volume de armazenamento anexado às instâncias de computação de ML que executam o trabalho de treinamento.
*Tipo*: string *Padrão*: *nenhum*.
+ **`s3OutputEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar a saída da tarefa de processamento.
*Tipo*: string *Padrão*: *nenhum*.
+ **`enableInterContainerTrafficEncryption`**: (*opcional*) habilite ou desabilite a criptografia de tráfego entre contêineres em trabalhos de treinamento ou ajuste de hiperparâmetros.
*Tipo*: booliano. *Padrão*: *verdadeiro*.
**nota**
O parâmetro `enableInterContainerTrafficEncryption` só está disponível na [versão 1.2.0.2.R3 do mecanismo](engine-releases-1.2.0.2.R3.md).
+ **`enableManagedSpotTraining`**: (*opcional*) otimiza o custo de treinamento de modelos de machine learning usando instâncias spot do Amazon Elastic Compute Cloud. Para obter mais informações, consulte [Managed Spot Training na Amazon SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/model-managed-spot-training.html).
*Tipo*: booliano. *Padrão*: *falso*.
+ **`customModelTrainingParameters`**: (*opcional*) a configuração para treinamento de modelos personalizados. Trata-se de um objeto JSON com os seguintes campos:
+ **`sourceS3DirectoryPath`**: (*obrigatório*) o caminho para o local do Amazon S3 onde o módulo Python que implementa seu modelo está localizado. Isso deve apontar para uma localização válida existente do Amazon S3 que contenha, no mínimo, um script de treinamento, um script de transformação e um arquivo `model-hpo-configuration.json`.
+ **`trainingEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que executa o treinamento de modelos e usa hiperparâmetros como argumentos de linha de comando, incluindo hiperparâmetros fixos.
*Padrão*: `training.py`.
+ **`transformEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que deve ser executado após a identificação do melhor modelo da pesquisa de hiperparâmetros, para calcular os artefatos do modelo necessários para a implantação do modelo. Ele deve ser capaz de ser executado sem argumentos de linha de comando.
*Padrão*: `transform.py`.
+ **`maxWaitTime`**: (*opcional*) o tempo máximo de espera, em segundos, ao realizar o treinamento de modelos usando instâncias spot. Deve ser maior que `trainingTimeOutInSeconds`.
*Tipo*: número inteiro.
## Obter o status de um trabalho de treinamento de modelos usando o comando `modeltraining` do Neptune ML
Um exemplo de comando `modeltraining` do Neptune ML para o status de um trabalho tem a seguinte aparência:
```
curl -s \
"https://(your Neptune endpoint)/ml/modeltraining/(the job ID)" \
| python -m json.tool
```
**Parâmetros para o status do trabalho `modeltraining`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de treinamento de modelos.
*Tipo*: string
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
## Interromper um trabalho de treinamento de modelos usando o comando `modeltraining` do Neptune ML
Um exemplo de comando `modeltraining` do Neptune ML para interromper um trabalho tem a seguinte aparência:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)"
```
Ou esta:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)?clean=true"
```
**Parâmetros para um trabalho de interrupção `modeltraining`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de treinamento de modelos.
*Tipo*: string
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`clean`**: (*opcional*) esse sinalizador especifica que todos os artefatos do Amazon S3 devem ser excluídos quando o trabalho é interrompido.
*Tipo*: booliano. *Padrão*: `FALSE`.
## Listar trabalhos de treinamento de modelos usando o comando `modeltraining` do Neptune ML
Um exemplo de comando `modeltraining` do Neptune ML para listar trabalhos ativos tem a seguinte aparência:
```
curl -s "https://(your Neptune endpoint)/ml/modeltraining" | python -m json.tool
```
Ou esta:
```
curl -s "https://(your Neptune endpoint)/ml/modeltraining?maxItems=3" | python -m json.tool
```
**Parâmetros para trabalhos de lista `modeltraining`**
+ **`maxItems`**: (*opcional*) o número máximo de itens a serem gerados.
*Tipo*: número inteiro. *Padrão*: `10`. *Valor máximo permitido*: `1024`.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
# Transformação de modelos usando o comando `modeltransform`
Use o comando `modeltransform` do Neptune ML para criar um trabalho de transformação de modelos, conferir o status, interrompê-lo ou listar todos os trabalhos ativos de transformação de modelos.
## Criar um trabalho de transformação de modelos usando o comando `modeltransform` do Neptune ML
Um comando `modeltransform` do Neptune ML para criar um trabalho de transformação incremental, sem novo treinamento de modelos, tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-transform job ID)",
"dataProcessingJobId" : "(the job-id of a completed data-processing job)",
"mlModelTrainingJobId" : "(the job-id of a completed model-training job)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform"
}'
```
Um comando do Neptune `modeltransform` ML para criar um trabalho a partir de um trabalho de treinamento de IA SageMaker concluído tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-transform job ID)",
"trainingJobName" : "(name of a completed SageMaker AI training job)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform",
"baseProcessingInstanceType" : ""
}'
```
Um comando `modeltransform` do Neptune ML para criar um trabalho que use uma implementação de modelos personalizados tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/modeltransform
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique model-training job ID)",
"trainingJobName" : "(name of a completed SageMaker AI training job)",
"modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/"
"customModelTransformParameters" : {
"sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)",
"transformEntryPointScript": "(your transform script entry-point name in the Python module)"
}
}'
```
**Parâmetros para criação de trabalhos `modeltransform`**
+ **`id`**: (*opcional*) um identificador exclusivo do novo trabalho.
*Tipo*: string. *Padrão*: um UUID gerado automaticamente.
+ **`dataProcessingJobId`**: o ID de um trabalho de processamento de dados concluído.
*Tipo*: string.
*Observação*: você deve incluir `dataProcessingJobId`, `mlModelTrainingJobId`, ou `trainingJobName`.
+ **`mlModelTrainingJobId`**: o ID de um trabalho de treinamento de modelos concluído.
*Tipo*: string.
*Observação*: você deve incluir `dataProcessingJobId`, `mlModelTrainingJobId` ou `trainingJobName`.
+ **`trainingJobName`**— O nome de um trabalho de treinamento de SageMaker IA concluído.
*Tipo*: string.
*Observação*: você deve incluir os parâmetros `dataProcessingJobId` e `mlModelTrainingJobId` ou `trainingJobName`.
+ **`sagemakerIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM para execução de SageMaker IA.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`customModelTransformParameters `**: (*opcional*) informações de configuração para uma transformação de modelos usando um modelo personalizado. O objeto `customModelTransformParameters` contém os seguintes campos, que devem ter valores compatíveis com os parâmetros do modelo salvos do trabalho de treinamento:
+ **`sourceS3DirectoryPath`**: (*obrigatório*) o caminho para o local do Amazon S3 onde o módulo Python que implementa seu modelo está localizado. Isso deve apontar para uma localização válida existente do Amazon S3 que contenha, no mínimo, um script de treinamento, um script de transformação e um arquivo `model-hpo-configuration.json`.
+ **`transformEntryPointScript`**: (*opcional*) o nome do ponto de entrada no módulo de um script que deve ser executado após a identificação do melhor modelo da pesquisa de hiperparâmetros, para calcular os artefatos do modelo necessários para a implantação do modelo. Ele deve ser capaz de ser executado sem argumentos de linha de comando.
*Padrão*: `transform.py`.
+ **`baseProcessingInstanceType`**: (*opcional*) o tipo de instância de ML usada na preparação e gerenciamento do treinamento de modelos de ML.
*Tipo*: string. *Observação*: é uma instância de CPU escolhida com base nos requisitos de memória para processar os dados e o modelo de transformação. Consulte [Selecionar uma instância para treinamento e transformação de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size).
+ **`baseProcessingInstanceVolumeSizeInGB`**: (*opcional*) o tamanho do volume do disco da instância de treinamento. Tanto os dados de entrada quanto o modelo de saída são armazenados em disco, portanto, o tamanho do volume deve ser grande o suficiente para conter os dois conjuntos de dados.
*Tipo*: número inteiro. *Padrão*: `0`.
*Observação*: se não for especificado ou for 0, o Neptune ML selecionará um tamanho de volume de disco com base na recomendação gerada na etapa de processamento de dados. Consulte [Selecionar uma instância para treinamento e transformação de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size).
+ **`subnets`**— (*Opcional*) A IDs das sub-redes na VPC Neptune.
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`securityGroupIds`**— (*Opcional*) O grupo de segurança da VPC. IDs
*Tipo*: lista de strings. *Padrão*: *nenhum*.
+ **`volumeEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar dados no volume de armazenamento anexado às instâncias de computação de ML que executam a tarefa de transformação.
*Tipo*: string *Padrão*: *nenhum*.
+ **`enableInterContainerTrafficEncryption`**: (*opcional*) habilite ou desabilite a criptografia de tráfego entre contêineres em trabalhos de treinamento ou ajuste de hiperparâmetros.
*Tipo*: booliano. *Padrão*: *verdadeiro*.
**nota**
O parâmetro `enableInterContainerTrafficEncryption` só está disponível na [versão 1.2.0.2.R3 do mecanismo](engine-releases-1.2.0.2.R3.md).
+ **`s3OutputEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar a saída da tarefa de processamento.
*Tipo*: string *Padrão*: *nenhum*.
## Obter o status de um trabalho de transformação de modelos usando o comando `modeltransform` do Neptune ML
Um exemplo de comando `modeltransform` do Neptune ML para o status de um trabalho tem a seguinte aparência:
```
curl -s \
"https://(your Neptune endpoint)/ml/modeltransform/(the job ID)" \
| python -m json.tool
```
**Parâmetros para o status do trabalho `modeltransform`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de transformação de modelos.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
## Interromper um trabalho de transformação de modelos usando o comando `modeltransform` do Neptune ML
Um exemplo de comando `modeltransform` do Neptune ML para interromper um trabalho tem a seguinte aparência:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)"
```
Ou esta:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)?clean=true"
```
**Parâmetros para um trabalho de interrupção `modeltransform`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do trabalho de transformação de modelos.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
+ **`clean`**: (*opcional*) esse sinalizador especifica que todos os artefatos do Amazon S3 devem ser excluídos quando o trabalho é interrompido.
*Tipo*: booliano. *Padrão*: `FALSE`.
## Listar trabalhos ativos de transformação de modelos usando o comando `modeltransform` do Neptune ML
Um exemplo de comando `modeltransform` do Neptune ML para listar trabalhos ativos tem a seguinte aparência:
```
curl -s "https://(your Neptune endpoint)/ml/modeltransform" | python -m json.tool
```
Ou esta:
```
curl -s "https://(your Neptune endpoint)/ml/modeltransform?maxItems=3" | python -m json.tool
```
**Parâmetros para trabalhos de lista `modeltransform`**
+ **`maxItems`**: (*opcional*) o número máximo de itens a serem gerados.
*Tipo*: número inteiro. *Padrão*: `10`. *Valor máximo permitido*: `1024`.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou ocorrerá um erro.
# Gerenciar endpoints de inferência usando o comando `endpoints`
Use o comando `endpoints` do Neptune ML para criar um endpoint de inferência, conferir o status, excluí-lo ou listar endpoints de inferência existentes.
## Criar um endpoint de inferência usando o comando `endpoints` do Neptune ML
Um comando `endpoints` do Neptune ML para criar um endpoint de inferência a partir de um modelo criado por um trabalho de treinamento tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"mlModelTrainingJobId": "(the model-training job-id of a completed job)"
}'
```
Um comando `endpoints` do Neptune ML para atualizar um endpoint de inferência existente a partir de um modelo criado por um trabalho de treinamento tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"update" : "true",
"mlModelTrainingJobId": "(the model-training job-id of a completed job)"
}'
```
Um comando `endpoints` do Neptune ML para criar um endpoint de inferência a partir de um modelo criado por um trabalho de transformação de modelos tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"mlModelTransformJobId": "(the model-training job-id of a completed job)"
}'
```
Um comando `endpoints` do Neptune ML para atualizar um endpoint de inferência existente a partir de um modelo criado por um trabalho de transformação de modelos tem a seguinte aparência:
```
curl \
-X POST https://(your Neptune endpoint)/ml/endpoints
-H 'Content-Type: application/json' \
-d '{
"id" : "(a unique ID for the new endpoint)",
"update" : "true",
"mlModelTransformJobId": "(the model-training job-id of a completed job)"
}'
```
**Parâmetros para criação de endpoints de inferência `endpoints`**
+ **`id`**: (*opcional*) um identificador exclusivo para o novo endpoint de inferência.
*Tipo*: string. *Padrão*: um nome com carimbo de data e hora gerado automaticamente.
+ **`mlModelTrainingJobId`**: o ID do trabalho de treinamento de modelos concluído que criou o modelo para o qual o endpoint de inferência apontará.
*Tipo*: string.
*Observação*: é necessário fornecer o `mlModelTrainingJobId` ou o `mlModelTransformJobId`.
+ **`mlModelTransformJobId`**: o ID do trabalho de transformação de modelos concluído.
*Tipo*: string.
*Observação*: é necessário fornecer o `mlModelTrainingJobId` ou o `mlModelTransformJobId`.
+ **`update`**: (*opcional*) se presente, esse parâmetro indica que se trata de uma solicitação de atualização.
*Tipo*: booliano. *Padrão*: `false`
*Observação*: é necessário fornecer o `mlModelTrainingJobId` ou o `mlModelTransformJobId`.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou será lançado um erro.
+ **`modelName`**: (*opcional*) o tipo de modelo para treinamento. Por padrão, o modelo de ML é automaticamente baseado no `modelType` usado no processamento de dados, mas você pode especificar um tipo de modelo diferente aqui.
*Tipo*: string. *Padrão*: `rgcn` para grafos heterogêneos e `kge` para grafos de conhecimento. *Valores válidos*: para grafos heterogêneos: `rgcn`. Para grafos de conhecimento:`kge`, `transe`, `distmult` ou `rotate`.
+ **`instanceType`**: (*opcional*) o tipo de instância de ML usada para serviços on-line.
*Tipo*: string. *Padrão*: `ml.m5.xlarge`.
*Observação*: selecionar a instância de ML para um endpoint de inferência depende do tipo de tarefa, do tamanho do grafo e do orçamento. Consulte [Selecionar uma instância para um endpoint de inferência](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size).
+ **`instanceCount`**: (*opcional*) o número mínimo de instâncias do Amazon EC2 a serem implantadas em um endpoint para previsão.
*Tipo*: número inteiro. *Padrão*: `1`.
+ **`volumeEncryptionKMSKey`**— (*Opcional*) A chave AWS Key Management Service (AWS KMS) que a SageMaker IA usa para criptografar dados no volume de armazenamento anexado às instâncias de computação de ML que executam os endpoints.
*Tipo*: string *Padrão*: *nenhum*.
## Obter o status de um endpoint de inferência usando o comando `endpoints` do Neptune ML
Um exemplo de comando `endpoints` do Neptune ML para o status de um endpoint de instância tem a seguinte aparência:
```
curl -s \
"https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)" \
| python -m json.tool
```
**Parâmetros para o status do endpoint da instância `endpoints`**
+ **`id`**: (*obrigatório*) o identificador exclusivo do endpoint de inferência.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou será lançado um erro.
## Excluir um endpoint de instância usando o comando `endpoints` do Neptune ML
Um exemplo de comando `endpoints` do Neptune ML para exclusão de um endpoint de instância tem a seguinte aparência:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)"
```
Ou esta:
```
curl -s \
-X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)?clean=true"
```
**Parâmetros para exclusão `endpoints` de um endpoint de inferência**
+ **`id`**: (*obrigatório*) o identificador exclusivo do endpoint de inferência.
*Tipo*: string.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou será lançado um erro.
+ **`clean`**: (*opcional*) indica que todos os artefatos relacionados a esse endpoint também devem ser excluídos.
*Tipo*: booliano. *Padrão*: `FALSE`.
## Listar endpoints de inferência usando o comando `endpoints` do Neptune ML
Um comando `endpoints` do Neptune ML para listar endpoints de inferência tem a seguinte aparência:
```
curl -s "https://(your Neptune endpoint)/ml/endpoints" \
| python -m json.tool
```
Ou esta:
```
curl -s "https://(your Neptune endpoint)/ml/endpoints?maxItems=3" \
| python -m json.tool
```
**Parâmetros para listar endpoints de inferência `dataprocessing`**
+ **`maxItems`**: (*opcional*) o número máximo de itens a serem gerados.
*Tipo*: número inteiro. *Padrão*: `10`. *Valor máximo permitido*: `1024`.
+ **`neptuneIamRoleArn`**— (*Opcional*) O ARN de uma função do IAM que fornece ao Neptune acesso aos recursos de IA e SageMaker Amazon S3.
*Tipo*: string. *Observação*: deve estar listado no grupo de parâmetros do cluster de banco de dados ou será lançado um erro.
# Erros e exceções da API de gerenciamento do Neptune ML
Todas as exceções da API de gerenciamento do Neptune ML exibem um código HTTP 400. Depois de receber qualquer uma dessas exceções, o comando que gerou a exceção não deve ser repetido.
****
+ **`MissingParameterException`**: mensagem de erro:
`Required credentials are missing. Please add IAM role to the cluster or pass as a parameter to this request.`
+ **`InvalidParameterException`**: mensagens de erro:
+ `Invalid ML instance type.`
+ `Invalid ID provided. ID can be 1-48 alphanumeric characters.`
+ `Invalid ID provided. Must contain only letters, digits, or hyphens.`
+ `Invalid ID provided. Please check whether a resource with the given ID exists.`
+ `Another resource with same ID already exists. Please use a new ID.`
+ `Failed to stop the job because it has already completed or failed.`
+ **`BadRequestException`**: mensagens de erro:
+ `Invalid S3 URL or incorrect S3 permissions. Please check your S3 configuration.`
+ `Provided ModelTraining job has not completed.`
+ `Provided SageMaker AI Training job has not completed.`
+ `Provided MLDataProcessing job is not completed.`
+ `Provided MLModelTraining job doesn't exist.`
+ `Provided ModelTransformJob doesn't exist.`
+ `Unable to find SageMaker AI resource. Please check your input.`
# Limites do Neptune ML
+ Os tipos de inferência atualmente compatíveis são classificação de nós, regressão de nós, classificação de bordas, regressão de bordas e previsão de links (consulte [Capacidades do Neptune ML](machine-learning.md#machine-learning-capabilities)).
+ O tamanho máximo do grafo que o Neptune ML pode aceitar depende da quantidade de memória e armazenamento necessários durante a [preparação dos dados](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size), o [treinamento de modelos](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size) e a [inferência](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size).
+ O tamanho máximo da memória de uma instância de processamento de dados do SageMaker AI é 768 GB. Como resultado, a fase de processamento de dados falhará se precisar de mais de 768 GB de memória.
+ O tamanho máximo da memória de uma instância de treinamento do SageMaker AI é 732 GB. Como resultado, a fase de treinamento falhará se precisar de mais de 732 GB de memória.
+ O tamanho máximo de uma carga útil de inferência para um endpoint do SageMaker AI é 6 MiB. Como resultado, a inferência indutiva falhará se a carga útil do subgrafo exceder esse tamanho.
+ Atualmente, o Neptune ML está disponível somente em regiões nas quais o Neptune e os outros serviços dos quais ele depende (como o AWS Lambda, o Amazon API Gateway e o Amazon SageMaker AI) são todos compatíveis.
Há diferenças na China (Pequim) e na China (Ningxia) relacionadas ao uso padrão da autenticação do IAM, conforme [explicado aqui](https://docs.amazonaws.cn/en_us/aws/latest/userguide/api-gateway.html#feature-diff) além de outras diferenças.
+ No momento, os endpoints de inferência de previsão de links lançados pelo Neptune ML só podem prever possíveis links com nós que estavam presentes no grafo durante o treinamento.
Por exemplo, considere um grafo com vértices `User` e `Movie` e bordas `Rated`. Usando um modelo de recomendação de previsão de links do Neptune ML correspondente, é possível adicionar um novo usuário ao grafo e fazer com que o modelo preveja filmes para ele, mas o modelo só pode recomendar filmes que estavam presentes durante o treinamento de modelos. Embora a incorporação de nós `User` seja calculada em tempo real usando o subgrafo local e o modelo de GNN e, portanto, possa mudar com o tempo à medida que os usuários avaliam os filmes, ela é comparada às incorporações de filmes estáticas pré-calculadas para a recomendação final.
+ Os modelos KGE compatíveis com o Neptune ML funcionam apenas para tarefas de previsão de links, e as representações são específicas de vértices e tipos de borda presentes no grafo durante o treinamento. Isso significa que todos os vértices e os tipos de borda mencionados em uma consulta de inferência devem estar presentes no grafo durante o treinamento. As previsões para novos tipos de borda ou vértices não podem ser feitas sem treinar novamente o modelo.
## Limitações de recursos do SageMaker AI
Dependendo das atividades e do uso de recursos ao longo do tempo, é possível encontrar mensagens de erro dizendo que [você excedeu sua cota](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html) ([ResourceLimitExceeded](https://repost.aws/knowledge-center/sagemaker-resource-limit-exceeded-error)). É necessário aumentar a escala verticalmente dos recursos do SageMaker AI. Siga as etapas no procedimento [Solicitar um aumento da cota de serviço para recursos do SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html#service-limit-increase-request-procedure) nesta página para solicitar aumento da cota ao AWS Support.
Os nomes dos recursos do SageMaker AI correspondem às fases do Neptune ML da seguinte forma:
+ O `ProcessingJob` do SageMaker AI é usado por tarefas de processamento de dados, treinamento e transformação de modelos do Neptune.
+ O `HyperParameterTuningJob` do SageMaker AI é usado por tarefas de treinamento de modelos do Neptune.
+ O `TrainingJob` do SageMaker AI é usado por tarefas de treinamento de modelos do Neptune.
+ O `Endpoint` do SageMaker AI é usado por endpoints de inferência do Neptune.