Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Amazon Neptune ML per machine learning sui grafi Spesso in grandi set di dati connessi sono presenti informazioni preziose difficili da estrarre usando query basate solo sull'intuito umano. Le tecniche di machine learning (ML) consentono di trovare correlazioni nascoste nei grafi con miliardi di relazioni. Queste correlazioni possono essere utili per suggerire prodotti, prevedere l'affidabilità creditizia, identificare frodi e molte altre attività. La funzionalità Neptune ML consente di creare e addestrare modelli di machine learning utili su grafi di grandi dimensioni in poche ore anziché in settimane. [A tal fine, Neptune ML utilizza la tecnologia Graph Neural Network (GNN) basata su [ SageMaker Amazon](https://aws.amazon.com/sagemaker/) AI [e Deep Graph Library (DGL) (](https://www.dgl.ai/)che è open source).](https://github.com/dmlc/dgl/) Le reti neurali a grafo sono un campo emergente nell'intelligenza artificiale (vedi, ad esempio, [A Comprehensive Survey on Graph Neural Networks](https://arxiv.org/abs/1901.00596)). [Per un tutorial pratico sull'utilizzo GNNs con DGL, consulta Apprendimento delle reti neurali a grafi con Deep Graph Library.](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library) **Nota** I vertici del grafo nei modelli Neptune ML sono identificati come "nodi". Ad esempio, la classificazione dei vertici utilizza un modello di machine learning per la classificazione dei nodi e la regressione dei vertici utilizza un modello di regressione dei nodi. ## Cosa può fare Neptune ML Neptune supporta sia l'inferenza trasduttiva, che restituisce previsioni precalcolate al momento dell'addestramento, sulla base dei dati del grafo in quel momento, sia l'inferenza induttiva, che restituisce l'elaborazione dei dati e la valutazione del modello in tempo reale, sulla base dei dati correnti. Per informazioni, consulta [Differenza tra inferenza induttiva e trasduttiva](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference). Neptune ML può addestrare modelli di machine learning per supportare cinque diverse categorie di inferenza: **Tipi di attività di inferenza attualmente supportati da Neptune ML** + **Classificazione dei nodi**: previsione della funzionalità categoriale di una proprietà del vertice. Ad esempio, per il film *Le ali della libertà*, Neptune ML può prevedere la sua proprietà `genre` come `story` da un set di candidati di `[story, crime, action, fantasy, drama, family, ...]`. Esistono due tipi di attività di classificazione dei nodi: + **Classificazione a classe singola**: in questo tipo di attività, ogni nodo ha una sola funzionalità di destinazione. Ad esempio, la proprietà `Place_of_birth` di `Alan Turing` ha il valore `UK`. + **Classificazione multi-classe**: in questo tipo di attività, ogni nodo può avere più di una funzionalità di destinazione. Ad esempio, la proprietà `genre` del film *Il Padrino* ha i valori `crime` e `story`. + **Regressione dei nodi**: previsione di una proprietà numerica di un vertice. Ad esempio, per il film *Avengers: Endgame,* Neptune ML può prevedere che la proprietà `popularity` abbia un valore di `5.0`. + **Classificazione degli archi**: previsione della funzionalità categoriale di una proprietà dell'arco. Esistono due tipi di attività di classificazione degli archi: + **Classificazione a classe singola**: in questo tipo di attività, ogni arco ha una sola funzionalità di destinazione. Ad esempio, un arco delle valutazioni tra un utente e un film potrebbe avere la proprietà `liked`, con un valore "Sì" o "No". + **Classificazione multi-classe**: in questo tipo di attività, ogni arco può avere più di una funzionalità di destinazione. Ad esempio, un arco delle valutazioni tra un utente e un film potrebbe avere più valori per il tag della proprietà come "Divertente" "Commovente", "Agghiacciante" e così via. + **Regressione degli archi**: previsione di una proprietà numerica di un arco. Ad esempio, un arco delle valutazioni tra un utente e un film potrebbe avere la proprietà numerica `score`, per la quale Neptune ML potrebbe prevedere un valore dato un utente e un film. + **Previsione dei collegamenti**: previsione dei nodi di destinazione più probabili per un nodo di origine e un arco in uscita specifici oppure i nodi di origine più probabili per un nodo di destinazione e un arco in entrata specificati. Ad esempio, con un grafo della conoscenza per farmaco-malattia, dato `Aspirin` come nodo di origine e `treats` come arco in uscita, Neptune ML può prevedere i nodi di destinazione più pertinenti come `heart disease`, `fever` e così via. Oppure, con il grafo della conoscenza Wikimedia, dato `President-of` come arco o relazione e `United-States` come nodo di destinazione, Neptune ML può prevedere i presidenti più pertinenti come `George Washington`, `Abraham Lincoln`, `Franklin D. Roosevelt` e così via. **Nota** La classificazione dei nodi e la classificazione degli archi supportano solo valori stringa. Ciò significa che i valori delle proprietà numeriche come `0` o `1` non sono supportati, sebbene gli equivalenti stringa `"0"` e `"1"` lo siano. Allo stesso modo, i valori delle proprietà booleane `true` e `false` non sono supportati, ma `"true"` e `"false"` funzionano. Con Neptune ML, puoi utilizzare modelli di machine learning che rientrano in due categorie generali: **Tipi di modelli di machine learning attualmente supportati da Neptune ML** + **Modelli Graph Neural Network (GNN)** — Questi includono [Relational Graph Convolutional Networks (](https://arxiv.org/abs/1703.06103)R-). GCNs I modelli GNN funzionano per tutti e tre i tipi di attività descritti in precedenza. + **Modelli di incorporamento dei grafi della conoscenza (KGE)**: includono i modelli `TransE`, `DistMult` e `RotatE`. Funzionano solo per la previsione dei collegamenti. **Modelli definiti dall'utente**: Neptune ML consente inoltre di fornire l'implementazione di un modello personalizzato per tutti i tipi di attività sopra elencati. Puoi utilizzare il kit di strumenti per [Neptune ML](https://github.com/awslabs/neptuneml-toolkit) per sviluppare e testare l'implementazione del modello personalizzato basato su Python prima di utilizzare l'API di addestramento Neptune ML con il modello. Consulta [Modelli personalizzati in Neptune ML.](machine-learning-custom-models.md) per informazioni dettagliate su come strutturare e organizzare l'implementazione affinché sia compatibile con l'infrastruttura di addestramento di Neptune ML. # Configurazione di Neptune ML Il modo più semplice per iniziare a usare Neptune ML è [usare CloudFormation il modello di](machine-learning-quick-start.md) avvio rapido. Questo modello installa tutti i componenti necessari, tra cui un nuovo cluster database Neptune, tutti i ruoli IAM necessari e un nuovo notebook per grafi Neptune per semplificare l'utilizzo di Neptune ML. Puoi anche installare Neptune ML manualmente, come spiegato in [Configurazione di Neptune ML senza utilizzare il modello di avvio rapido CloudFormation](machine-learning-manual-setup.md). # Utilizzo del modello Neptune AWS CloudFormation ML per iniziare rapidamente in un nuovo cluster DB Il modo più semplice per iniziare a usare Neptune ML è usare CloudFormation il modello di avvio rapido. Questo modello installa tutti i componenti necessari, tra cui un nuovo cluster database Neptune, tutti i ruoli IAM necessari e un nuovo notebook per grafi Neptune per semplificare l'utilizzo di Neptune ML. **Per creare lo stack di avvio rapido di Neptune ML** 1. Per avviare lo CloudFormation stack sulla CloudFormation console, scegli uno dei pulsanti **Launch Stack nella tabella seguente**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/neptune/latest/userguide/machine-learning-quick-start.html) 1. Nella pagina **Select Template (Seleziona modello)**, selezionare **Next (Avanti)**. 1. Nella pagina **Specify Details (Specifica dettagli)**, selezionare **Next (Avanti)**. 1. Nella pagina **Opzioni**, scegli **Avanti**. 1. Nella pagina **Rivedi** sono presenti due caselle di controllo da selezionare: + Il primo riconosce che AWS CloudFormation potrebbe creare risorse IAM con nomi personalizzati. + Il secondo riconosce che AWS CloudFormation potrebbe richiedere la `CAPABILITY_AUTO_EXPAND` funzionalità per il nuovo stack. `CAPABILITY_AUTO_EXPAND`consente esplicitamente di CloudFormation espandere automaticamente le macro durante la creazione dello stack, senza previa revisione. Spesso i clienti creano un set di modifiche da un modello elaborato per consentire la revisione delle modifiche apportate dalle macro prima dell'effettiva creazione dello stack. Per ulteriori informazioni, consulta l'API CloudFormation [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html). Quindi, scegli **Crea**. Il modello di avvio rapido crea e imposta quanto segue: + Un cluster database Neptune. + I ruoli IAM necessari (e li associa). + Il gruppo di EC2 sicurezza Amazon necessario. + Gli endpoint SageMaker AI VPC necessari. + Un gruppo di parametri del cluster database per Neptune ML. + I parametri necessari in tale gruppo di parametri. + Un notebook SageMaker AI con esempi di notebook precompilati per Neptune ML. Tieni presente che non tutte le dimensioni delle istanze sono disponibili in ogni regione, quindi devi assicurarti che la dimensione dell'istanza notebook selezionata sia supportata dalla tua regione. + Il servizio Neptune-Export. Quando lo stack di avvio rapido è pronto, vai al notebook SageMaker AI creato dal modello e dai un'occhiata agli esempi precompilati. Ti aiuteranno a scaricare set di dati di esempio da utilizzare per sperimentare le funzionalità di Neptune ML. Possono anche farti risparmiare molto tempo durante l'utilizzo di Neptune ML. Ad esempio, guarda il comando magic di riga [%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml) e il comando magic di cella [%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml) supportati da questi notebook. Puoi anche usare il seguente AWS CLI comando per eseguire il modello di avvio rapido: 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) ``` # Configurazione di Neptune ML senza utilizzare il modello di avvio rapido CloudFormation Questa guida fornisce step-by-step istruzioni per configurare Amazon Neptune ML senza utilizzare AWS CloudFormation il modello di avvio rapido. Presuppone che tu abbia già un cluster Neptune DB funzionante e copre la configurazione necessaria, inclusa l'installazione del servizio Neptune-Export, la creazione di ruoli IAM personalizzati e la configurazione del cluster DB per abilitare Neptune ML. La guida spiega anche come creare due endpoint SageMaker AI nel tuo VPC Neptune per consentire al motore Neptune di accedere alla gestione dell'IA necessaria. SageMaker APIs Seguendo queste istruzioni, puoi configurare Neptune ML sulla tua infrastruttura Neptune esistente senza fare affidamento sul modello. CloudFormation ## Inizia con un cluster database Neptune funzionante Se non utilizzi il modello di CloudFormation avvio rapido per configurare Neptune ML, avrai bisogno di un cluster Neptune DB esistente con cui lavorare. Se lo desideri, puoi usarne uno che hai già o clonarne uno che usi già oppure puoi crearne uno nuovo (consulta [Crea un cluster Neptune](get-started-create-cluster.md)). ## Installazione del servizio Neptune-Export Se non hai ancora provveduto, installa il servizio Neptune-Export, come spiegato in [Utilizzo del servizio Neptune-Export per esportare i dati di Neptune](export-service.md). Aggiungi una regola in entrata al gruppo di sicurezza `NeptuneExportSecurityGroup` creato dal programma di installazione, con le seguenti impostazioni: + *Tipo:* `Custom TCP` + *Protocol (Protocollo)*: `TCP` + *Intervallo porte*: `80 - 443` + *Origine*: *(Neptune DB cluster security group ID)* ## Crea un ruolo S3 IAM personalizzato NeptuneLoadFrom Se ancora non hai provveduto, crea un ruolo IAM `NeptuneLoadFromS3` personalizzato, come spiegato in [Creazione di un ruolo IAM per l'accesso ad Amazon S3](bulk-load-tutorial-IAM-CreateRole.md). ## Crea un ruolo personalizzato NeptuneSageMaker IAMRole Utilizza la [console IAM](https://console.aws.amazon.com/iam/) per creare un ruolo `NeptuneSageMakerIAMRole` personalizzato, usando la seguente policy: ------ #### [ 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" } ] } ``` ------ Durante la creazione di questo ruolo, modifica la relazione di trust affinché corrisponda a quella seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "ec2.amazonaws.com", "rds.amazonaws.com", "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ Infine, copia il nome ARN assegnato a questo nuovo ruolo `NeptuneSageMakerIAMRole`. **Importante** Assicurati che le autorizzazioni Amazon S3 indicate in `NeptuneSageMakerIAMRole` corrispondano a quelle precedenti. Il nome ARN universale, `arn:aws:s3:::*`, è usato per la risorsa Amazon S3 nella policy precedente. Se per qualche motivo non è possibile utilizzare il nome ARN universale, è necessario aggiungere `arn:aws:s3:::graphlytics*` e il nome ARN di qualsiasi altra risorsa Amazon S3 del cliente che i comandi Neptune ML utilizzeranno nella sezione delle risorse. ## Configurazione del cluster database per abilitare Neptune ML **Per configurare il cluster database per Neptune ML** 1. Nella [console Neptune](https://console.aws.amazon.com/neptune) passa a **Gruppi di parametri** e quindi al gruppo di parametri del cluster database associato al cluster database che intendi usare. Imposta il parametro `neptune_ml_iam_role` sul nome ARN assegnato al ruolo `NeptuneSageMakerIAMRole` appena creato. 1. Passa a Database, quindi seleziona il cluster database che utilizzerai per Neptune ML. Seleziona **Azioni**, quindi **Gestisci ruoli IAM**. 1. Nella pagina **Gestisci ruoli IAM** seleziona **Aggiungi ruolo** e aggiungi `NeptuneSageMakerIAMRole`. Aggiungi quindi il ruolo `NeptuneLoadFromS3`. 1. Riavvia l'istanza di scrittura del cluster database. ## Crea due endpoint SageMaker AI nel tuo VPC Neptune Infine, per consentire al motore Neptune di accedere alla APIs gestione dell'IA SageMaker necessaria, devi creare SageMaker due endpoint AI nel tuo VPC Neptune, come spiegato in. [Crea due endpoint per l' SageMaker IA nel tuo VPC Neptune](machine-learning-cluster-setup.md#machine-learning-sm-endpoints) # Configurazione manuale di un notebook Neptune per Neptune ML I notebook SageMaker Neptune AI sono precaricati con una varietà di notebook di esempio per Neptune ML. [È possibile visualizzare in anteprima questi esempi nel repository open source Graph-Notebook. GitHub ](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning) Puoi usare uno dei notebook Neptune esistenti o, se preferisci, puoi crearne uno personalizzato, seguendo le istruzioni riportate in [Utilizzo Neptune Workbench per ospitare i notebook Neptune](graph-notebooks.md#graph-notebooks-workbench). Puoi anche configurare un notebook Neptune predefinito da utilizzare con Neptune ML seguendo questa procedura: **Modifica di un notebook per Neptune ML** 1. Apri la console Amazon SageMaker AI all'indirizzo [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/). 1. Nel riquadro di navigazione a sinistra scegli **Notebook**, quindi **Istanze notebook**. Cerca il nome del notebook Neptune da usare per Neptune ML e selezionalo per accedere alla pagina dei dettagli. 1. Se l'istanza notebook è in esecuzione, seleziona il pulsante **Arresta** in alto a destra nella pagina dei dettagli del notebook. 1. In **Impostazioni dell'istanza Notebook**, in **Configurazione del ciclo di vita** seleziona il collegamento per aprire la pagina relativa al ciclo di vita del notebook. 1. Seleziona **Modifica** in alto a destra, quindi fai clic su **Continua**. 1. Nella scheda **Avvia notebook** modifica lo script per includere comandi di esportazione aggiuntivi e per compilare i campi per il ruolo IAM di Neptune ML e l'URI del servizio di esportazione. L'aspetto sarà simile al seguente a seconda della shell (interprete di comandi): ``` 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. Selezionare **Update (Aggiorna)**. 1. Torna alla pagina dell'istanza notebook. In **Autorizzazioni e crittografia** è disponibile un campo per **ARN del ruolo IAM**. Seleziona il collegamento in questo campo per passare al ruolo IAM con cui viene eseguita questa istanza notebook. 1. Crea una nuova policy inline come questa: ------ #### [ 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. Salva questa nuova policy e collegala al ruolo IAM nel passaggio 8. 1. Seleziona **Start** in alto a destra nella pagina dei dettagli dell'istanza di SageMaker AI Notebook per avviare l'istanza Notebook. # Utilizzo di AWS CLI per configurare Neptune ML su un cluster DB Oltre al modello di CloudFormation avvio rapido e al Console di gestione AWS, puoi anche configurare Neptune ML utilizzando il. AWS CLI ## Scegli un gruppo di parametri del cluster database per il nuovo cluster Neptune ML I seguenti AWS CLI comandi creano un nuovo gruppo di parametri del cluster DB e lo configurano per funzionare con Neptune ML: **Per creare e configurare un gruppo di parametri del cluster database per Neptune ML** 1. Crea un nuovo gruppo di parametri del cluster database: ``` 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. Crea un parametro del cluster `neptune_ml_iam_role` DB impostato sull'ARN del `SageMakerExcecutionIAMRole` tuo cluster DB da utilizzare mentre chiami l' SageMaker IA per creare lavori e ottenere previsioni dai modelli ML ospitati: ``` 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) ``` L'impostazione di questo parametro consente a Neptune di SageMaker accedere all'IA senza che tu debba passare il ruolo ad ogni chiamata. Per informazioni su come creare il ruolo `SageMakerExcecutionIAMRole`, consulta [Crea un ruolo personalizzato NeptuneSageMaker IAMRole](machine-learning-manual-setup.md#ml-manual-setup-sm-role). 1. Infine, usa `describe-db-cluster-parameters` per verificare che tutti i parametri nel nuovo gruppo di parametri del cluster database siano impostati come desiderato: ``` 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) ``` ## Collegamento del nuovo gruppo di parametri del cluster database al cluster database verrà usato con Neptune ML Ora puoi collegare il nuovo gruppo di parametri del cluster database appena creato a un cluster database esistente utilizzando il seguente 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) ``` Per rendere effettivi tutti i parametri, puoi quindi riavviare il cluster database: ``` 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) ``` In alternativa se stai creando un nuovo cluster database da utilizzare con Neptune ML, puoi usare il seguente comando per creare il cluster con il nuovo gruppo di parametri collegato, quindi creare una nuova istanza primaria (scrittura): ``` 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) ``` ## Collegalo `NeptuneSageMakerIAMRole` al tuo cluster DB in modo che possa accedere alle SageMaker risorse AI e Amazon S3 Infine, segui le istruzioni [Crea un ruolo personalizzato NeptuneSageMaker IAMRole](machine-learning-manual-setup.md#ml-manual-setup-sm-role) per creare un ruolo IAM che consenta al tuo cluster DB di comunicare con SageMaker AI e Amazon S3. Quindi, usa il seguente comando per associare il ruolo `NeptuneSageMakerIAMRole` che hai creato al cluster database: ``` 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) ``` ## Crea due endpoint per l' SageMaker IA nel tuo VPC Neptune Neptune ML necessita di SageMaker due endpoint AI nel VPC del cluster Neptune DB: + `com.amazonaws.(AWS region, like us-east-1).sagemaker.runtime` + `com.amazonaws.(AWS region, like us-east-1).sagemaker.api` Se non hai utilizzato il CloudFormation modello di avvio rapido, che li crea automaticamente per te, puoi utilizzare i seguenti comandi per crearli: AWS CLI Questo crea l'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 questo crea l'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 ``` Per creare questi endpoint puoi anche utilizzare la [console VPC](https://console.aws.amazon.com/vpc/). Consulta [Chiamate di previsione sicure in Amazon SageMaker con AWS PrivateLink](https://aws.amazon.com/blogs/machine-learning/secure-prediction-calls-in-amazon-sagemaker-with-aws-privatelink/) e [Protezione di tutte le chiamate SageMaker API Amazon](https://aws.amazon.com/blogs/machine-learning/securing-all-amazon-sagemaker-api-calls-with-aws-privatelink/) con. AWS PrivateLink ## Crea un parametro di endpoint di inferenza SageMaker AI nel gruppo di parametri del cluster DB Per evitare di dover specificare l'endpoint di inferenza SageMaker AI del modello che stai utilizzando in ogni query che gli fai, crea un parametro del cluster DB denominato `neptune_ml_endpoint` nel gruppo di parametri del cluster DB per Neptune ML. Imposta il parametro sull'`id` dell'endpoint dell'istanza in questione. A tale scopo, è possibile utilizzare il seguente AWS CLI comando: ``` 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) ``` # Panoramica dell'utilizzo della funzionalità Neptune ML La funzionalità Neptune ML di Amazon Neptune offre un flusso di lavoro semplificato per sfruttare i modelli di machine learning all'interno di un database grafico. Il processo prevede diversi passaggi chiave: esportazione dei dati da Neptune in formato CSV, preelaborazione dei dati per prepararli all'addestramento del modello, addestramento del modello di machine learning utilizzando SageMaker Amazon AI, creazione di un endpoint di inferenza per fornire previsioni e quindi interrogare il modello direttamente dalle query Gremlin. L'ambiente di lavoro Neptune fornisce comodi comandi di linea e di magia cellulare per aiutare a gestire e automatizzare questi passaggi. Integrando le funzionalità di machine learning direttamente nel database dei grafici, Neptune ML consente agli utenti di ricavare informazioni preziose e fare previsioni utilizzando i ricchi dati relazionali archiviati nel grafico di Neptune. ## Avvio del flusso di lavoro per l'utilizzo di Neptune ML Per iniziare a usare la funzionalità Neptune ML in Amazon Neptune sono in genere necessari i cinque passaggi seguenti: ![\[Diagramma del flusso di lavoro di Neptune ML\]](http://docs.aws.amazon.com/it_it/neptune/latest/userguide/images/neptune-ML-workflow.png) 1. **Esportazione e configurazione dei dati**: la fase di esportazione dei dati utilizza il servizio Neptune-Export o lo strumento da riga di comando `neptune-export` per esportare i dati da Neptune ad Amazon Simple Storage Service (Amazon S3) in formato CSV. Contemporaneamente viene generato automaticamente un file di configurazione denominato `training-data-configuration.json`, che specifica come è possibile caricare i dati esportati in un grafo addestrabile. 1. **Pre-elaborazione dei dati**: in questo passaggio, il set di dati esportato viene pre-elaborato utilizzando le tecniche standard per prepararlo all'addestramento del modello. È possibile eseguire la normalizzazione delle funzionalità per i dati numerici e codificare le funzionalità del testo con `word2vec`. Alla fine di questo passaggio, viene generato un grafo DGL (Deep Graph library) dal set di dati esportato che verrà usato per il passaggio di addestramento del modello. Questo passaggio viene implementato utilizzando un processo di elaborazione SageMaker AI nel tuo account e i dati risultanti vengono archiviati in una posizione Amazon S3 che hai specificato. 1. **Addestramento del modello**: il passaggio di addestramento del modello addestra il modello di machine learning che verrà utilizzato per le previsioni. L'addestramento del modello viene svolto in due fasi: + La prima fase utilizza un processo di elaborazione SageMaker AI per generare un set di configurazione della strategia di addestramento del modello che specifica il tipo di modello e gli intervalli di iperparametri del modello che verranno utilizzati per l'addestramento del modello. + La seconda fase utilizza quindi un lavoro di ottimizzazione del modello SageMaker AI per provare diverse configurazioni di iperparametri e selezionare il processo di formazione che ha prodotto il modello con le migliori prestazioni. Il processo di ottimizzazione esegue un numero prestabilito di prove del processo di addestramento del modello sui dati elaborati. Al termine di questa fase, i parametri del modello addestrato del miglior processo di addestramento vengono utilizzati per generare gli artefatti del modello per l'inferenza. 1. **Crea un endpoint di inferenza in Amazon SageMaker AI**: l'endpoint di inferenza è un'istanza di endpoint SageMaker AI che viene lanciata con gli artefatti del modello prodotti dal miglior processo di formazione. Ogni modello è legato a un singolo endpoint. L'endpoint può accettare le richieste in entrata dal database a grafo e restituire le previsioni del modello per gli input nelle richieste. Dopo aver creato l'endpoint, questo rimane attivo finché non viene eliminato. 1. **Esecuzione di query sul modello di machine learning con Gremlin**: puoi utilizzare le estensioni del linguaggio di query Gremlin per eseguire query sulle previsioni dall'endpoint di inferenza. **Nota** [Neptune Workbench](graph-notebooks.md#graph-notebooks-workbench) contiene un comando magic di riga e un comando magic di cella che ti permettono di risparmiare molto tempo nella gestione di questi passaggi, ad esempio: [%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml) [%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml) # Generazione di previsioni basate sui dati dei grafi in evoluzione Con un grafo in continua evoluzione, potrebbe essere necessario creare periodicamente nuove previsioni in batch utilizzando dati aggiornati. L'esecuzione di query su previsioni precalcolate (inferenza trasduttiva) può essere significativamente più veloce rispetto alla generazione immediata di nuove previsioni basate sui dati più recenti (inferenza induttiva). Entrambi gli approcci sono validi, a seconda della rapidità con cui cambiano i dati e dei requisiti in termini di prestazioni. ## Differenza tra inferenza induttiva e trasduttiva Quando esegue l'inferenza trasduttiva, Neptune cerca e restituisce previsioni precalcolate al momento dell'addestramento. Quando esegue l'inferenza induttiva, Neptune costruisce il sottografo pertinente e ne recupera le proprietà. Il modello GNN DGL applica quindi l'elaborazione dei dati e la valutazione del modello in tempo reale. L'inferenza induttiva può quindi generare previsioni che coinvolgono nodi e archi che non erano presenti al momento dell'addestramento e che riflettono lo stato attuale del grafo. Ciò determina, tuttavia, una maggiore latenza. Se il grafo è dinamico, è consigliabile utilizzare l'inferenza induttiva per essere sicuri di tenere conto dei dati più recenti, ma se il grafo è statico, l'inferenza trasduttiva è più veloce ed efficiente. Per impostazione predefinita, l'inferenza induttiva è disabilitata. È possibile abilitarla per eseguire una query utilizzando il predicato [Neptune\$1ml.inductiveInference](machine-learning-gremlin-inference-query-predicates.md#machine-learning-gremlin-inference-neptune-ml-inductiveInference) Gremlin nella query come indicato di seguito: ``` .with( "Neptune#ml.inductiveInference") ``` # Flussi di lavoro trasduttivi incrementali Mentre per aggiornare gli artefatti del modello è sufficiente eseguire nuovamente i passaggi da uno a tre (dall'**esportazione e configurazione dei dati** alla **trasformazione del modello**), Neptune ML supporta modi più semplici per aggiornare le previsioni di ML in batch utilizzando nuovi dati. Uno prevede l'utilizzo di un [flusso di lavoro basato su modello incrementale](#machine-learning-overview-incremental) e un altro prevede l'utilizzo del [riaddestramento del modello con un avvio a caldo](#machine-learning-overview-model-retraining). ## Flusso di lavoro basato su modello incrementale In questo flusso di lavoro, si aggiornano le previsioni di ML senza riaddestrare il modello ML. **Nota** È possibile farlo solo quando i dati del grafo sono stati aggiornati con nuovi nodi e/o archi. Non funzionerà quando i nodi vengono rimossi. 1. **Esportazione e configurazione dei dati**: questo passaggio è uguale a quello del flusso di lavoro principale. 1. **Pre-elaborazione incrementale dei dati**: questo passaggio è simile al passaggio di pre-elaborazione dei dati nel flusso di lavoro principale, ma utilizza la stessa configurazione di elaborazione utilizzata in precedenza, che corrisponde a un modello addestrato specifico. 1. **Trasformazione del modello**: anziché un passaggio di addestramento del modello, questo passaggio di trasformazione del modello recupera il modello addestrato dal flusso di lavoro principale e dai risultati del passaggio di pre-elaborazione incrementale dei dati e genera nuovi artefatti del modello da utilizzare per l'inferenza. La fase di trasformazione del modello avvia un processo di elaborazione SageMaker AI per eseguire il calcolo che genera gli artefatti del modello aggiornati. 1. **Aggiornamento dell'endpoint di inferenza di Amazon SageMaker AI**: facoltativamente, se disponi di un endpoint di inferenza esistente, questo passaggio aggiorna l'endpoint con i nuovi artefatti del modello generati dalla fase di trasformazione del modello. In alternativa, puoi anche creare un nuovo endpoint di inferenza con i nuovi artefatti del modello. ## Riaddestramento del modello con avvio a caldo Utilizzando questo flusso di lavoro, puoi addestrare e implementare un nuovo modello di machine learning per generare previsioni utilizzando i dati del grafo incrementale, ma partire da un modello esistente generato tramite il flusso di lavoro principale: 1. **Esportazione e configurazione dei dati**: questo passaggio è uguale a quello del flusso di lavoro principale. 1. **Pre-elaborazione incrementale dei dati**: questo passaggio è uguale a quello del flusso di lavoro di inferenza del modello incrementale. I nuovi dati del grafo devono essere elaborati con lo stesso metodo di elaborazione usato in precedenza per l'addestramento del modello. 1. **Addestramento dei modelli con avvio a caldo**: l'addestramento dei modelli è simile a quello che avviene nel flusso di lavoro principale, ma è possibile accelerare la ricerca degli iperparametri del modello sfruttando le informazioni dell'attività di addestramento del modello precedente. 1. **Aggiorna l'endpoint di inferenza Amazon SageMaker AI**: questo passaggio è lo stesso del flusso di lavoro di inferenza del modello incrementale. # Flussi di lavoro per modelli personalizzati in Neptune ML Neptune ML consente di implementare, addestrare e distribuire modelli personalizzati per qualsiasi attività supportata da Neptune ML. Il flusso di lavoro per lo sviluppo e l'implementazione di un modello personalizzato è essenzialmente lo stesso di quello dei modelli predefiniti, con alcune differenze, come spiegato in [Flusso di lavoro per i modelli personalizzati](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow). # Selezione delle istanze per le fasi di Neptune ML Le diverse fasi dell'elaborazione di Neptune ML utilizzano SageMaker diverse istanze di intelligenza artificiale. In questa sezione viene illustrato come scegliere il tipo di istanza corretto per ogni fase. Puoi trovare informazioni sui tipi di istanze SageMaker AI e sui prezzi su [Amazon SageMaker Pricing](https://aws.amazon.com/sagemaker/pricing/). ## Selezione di un'istanza per l'elaborazione dei dati La fase di [elaborazione dei dati SageMaker ](machine-learning-on-graphs-processing.md) AI richiede un'[istanza di elaborazione](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) con memoria e storage su disco sufficienti per i dati di input, intermedi e output. La quantità specifica di memoria e spazio di archiviazione su disco necessaria dipende dalle caratteristiche del grafo Neptune ML e dalle relative funzionalità esportate. Per impostazione predefinita, Neptune ML sceglie l'istanza `ml.r5` più piccola, la cui memoria è dieci volte più grande delle dimensioni dei dati del grafo esportati su disco. ## Selezione di un'istanza per l'addestramento e la trasformazione del modello La scelta del tipo di istanza corretto per [l'addestramento del modello](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html) o la [trasformazione del modello](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-batch.html) dipende dal tipo di attività, dalle dimensioni del grafo e dai requisiti dei tempi di risposta. Le istanze GPU offrono le prestazioni migliori. In genere è consigliabile usare le istanze seriali `p3` e `g4dn`. Puoi anche usare le istanze `p2` o `p4d`. Per impostazione predefinita, Neptune ML sceglie l'istanza GPU più piccola con più memoria di quella richiesta dall'addestramento e dalla trasformazione del modello. Puoi trovare la selezione nel file `train_instance_recommendation.json`, nella posizione di output dell'elaborazione dati di Amazon S3. Ecco un esempio del contenuto di un file `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)" } ``` ## Selezione di un'istanza per un endpoint di inferenza La selezione del tipo di istanza corretto per un [endpoint di inferenza](machine-learning-on-graphs-inference-endpoint.md) dipende dal tipo di attività, dalle dimensioni del grafo e dal budget. Per impostazione predefinita, Neptune ML sceglie l'istanza `ml.m5d` più piccola con più memoria di quella richiesta dall'endpoint di inferenza. **Nota** Se sono necessari più di 384 GB di memoria, Neptune ML utilizza un'istanza `ml.r5d.24xlarge`. Puoi vedere il tipo di istanza consigliato da Neptune ML nel file `infer_instance_recommendation.json` disponibile nella posizione Amazon S3 in uso per l'addestramento del modello. Ecco un esempio del contenuto del file: ``` { "instance" : "(the recommended instance type for an inference endpoint)", "disk_size" : "(the estimated disk space required)", "mem_size" : "(the estimated memory required)" } ``` # Utilizzo dello strumento neptune-export o del servizio Neptune-Export per esportare dati da Neptune for Neptune ML Neptune ML richiede di fornire i dati di addestramento per [Deep Graph Library (DGL)](https://www.dgl.ai/) per la creazione e la valutazione dei modelli. È possibile esportare dati da Neptune utilizzando il [servizio Neptune-Export](export-service.md) o l'[utilità `neptune-export`](export-utility.md). Sia il servizio che lo strumento da riga di comando pubblicano i dati su Amazon Simple Storage Service (Amazon S3) in formato CSV e crittografati tramite la crittografia lato server di Amazon S3 (`SSE-S3`). Per informazioni, consulta [File esportati da Neptune-Export e `neptune-export`](exported-files.md). Inoltre, quando si configura un'esportazione dei dati di addestramento per Neptune ML, il processo di esportazione crea e pubblica un file di configurazione crittografato per l'addestramento del modello insieme ai dati esportati. Per impostazione predefinita, questo file è denominato `training-data-configuration.json`. # Esempi di utilizzo del servizio Neptune-Export per esportare i dati di addestramento per Neptune ML Questa richiesta esporta i dati di addestramento del grafo delle proprietà per un'attività di classificazione dei nodi: ``` 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" } ] } } }' ``` Questa richiesta esporta i dati di addestramento RDF per un'attività di classificazione dei nodi: ``` 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" } ] } } }' ``` # Campi da impostare nell'oggetto params durante l'esportazione dei dati di addestramento L'oggetto `params` in una richiesta di esportazione può contenere vari campi, come descritto nella [documentazione di `params`](export-params-fields.md). I campi seguenti sono quelli più importanti per l'esportazione dei dati di addestramento di machine learning: **** + **`endpoint`**: usa `endpoint` per specificare un endpoint di un'istanza Neptune nel cluster database su cui il processo di esportazione può eseguire query per estrarre i dati. + **`profile`**: il campo `profile` nell'oggetto `params` deve essere impostato su **`neptune-ml`**. In questo modo, il processo di esportazione formatta i dati esportati nel modo appropriato per l'addestramento del modello Neptune ML, in formato CSV per i dati dei grafi di proprietà o come N-Triple per i dati RDF. Inoltre, crea e scrive un file `training-data-configuration.json` nella stessa posizione Amazon S3 dei dati di addestramento esportati. + **`cloneCluster`**: se impostato su `true`, il processo di esportazione clona il cluster database, esporta dal clone e quindi elimina il clone al termine dell'operazione. + **`useIamAuth`**: se nel cluster database è abilitata l'[autenticazione IAM](iam-auth-enable.md), è necessario includere questo campo impostato su `true`. Il processo di esportazione offre anche diversi modi per filtrare i dati esportati (vedi [questi esempi](export-filtering-examples.md)). # Utilizzo dell'oggetto AdditionalParams per ottimizzare l'esportazione di informazioni sull'addestramento dei modelli L'oggetto `additionalParams` contiene campi che è possibile utilizzare per specificare le etichette e le funzionalità delle classi di machine learning ai fini dell'addestramento e fornire supporto durante la creazione di un file di configurazione dei dati di addestramento. Il processo di esportazione non può dedurre automaticamente le proprietà dei nodi e degli archi che costituiscono le etichette delle classi di machine learning da usare come esempi ai fini dell'addestramento. Inoltre, non è in grado di dedurre automaticamente la migliore codifica delle funzionalità per le proprietà numeriche, categoriali e di testo, quindi è necessario fornire suggerimenti utilizzando i campi nell'oggetto `additionalParams` per specificare questi dettagli o per sovrascrivere la codifica predefinita. Per i dati dei grafi di proprietà, la struttura di primo livello di `additionalParams` in una richiesta di esportazione avrà un aspetto simile al seguente: ``` { "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) ] } } } ``` Per i dati RDF, la struttura di primo livello avrà un aspetto simile al seguente: ``` { "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) ] } } } ``` Puoi anche fornire più configurazioni di esportazione, utilizzando il 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) ] } ] } } } ``` # Elementi di primo livello nel campo neptune\$1ml di AdditionalParams ## L'elemento version in neptune\$1ml Specifica la versione della configurazione dei dati di addestramento da generare. (*Facoltativo*), *Tipo*: stringa, *Impostazione predefinita*: "v2.0". Se includi `version`, deve essere impostato su `v2.0`. ## Il campo jobs in neptune\$1ml Contiene un array di oggetti di configurazione dei dati di addestramento, ognuno dei quali definisce un processo di elaborazione dei dati e contiene: + **`name`**: nome della configurazione dei dati di addestramento da creare. Ad esempio, una configurazione dei dati di addestramento con il nome "job-number-1" genera un file di configurazione dei dati di addestramento denominato `job-number-1.json`. + **`targets`**: array JSON di destinazioni di etichette delle classi dei nodi e degli archi che rappresentano le etichette delle classi di machine learning ai fini dell'addestramento. Per informazioni, consulta [Il campo targets in un oggetto neptune\$1ml](machine-learning-neptune_ml-targets.md). + **`features`**: array JSON di funzionalità delle proprietà dei nodi. Per informazioni, consulta [Il campo delle caratteristiche in neptune\$1ml](machine-learning-neptune_ml-features.md). # Il campo targets in un oggetto neptune\$1ml Il campo `targets` in una configurazione di esportazione dei dati di addestramento JSON contiene un array di oggetti di destinazione che specificano un'attività di addestramento e le etichette della classe machine-learning per l'addestramento di questa attività. Il contenuto degli oggetti di destinazione varia a seconda che l'addestramento venga eseguito su dati del grafo delle proprietà o su dati RDF. Per le attività di classificazione e regressione dei nodi del grafo delle proprietà, gli oggetti di destinazione nell'array avranno l'aspetto seguente: ``` { "node": "(node property-graph label)", "property": "(property name)", "type" : "(used to specify classification or regression)", "split_rate": [0.8,0.2,0.0], "separator": "," } ``` Per le attività di classificazione, regressione o previsione dei collegamenti degli archi del grafo delle proprietà, gli oggetti di destinazione nell'array avranno l'aspetto seguente: ``` { "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": "," } ``` Per le attività di classificazione e regressione RDF, gli oggetti di destinazione nell'array avranno l'aspetto seguente: ``` { "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] } ``` Per le attività di previsione dei collegamenti RDF, gli oggetti di destinazione nell'array avranno l'aspetto seguente: ``` { "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] } ``` Gli oggetti di destinazione possono contenere i seguenti campi: **Contents** + [Campi di destinazione del grafo delle proprietà](#machine-learning-property-graph-neptune_ml-targets) + [nodo](#machine-learning-property-graph-neptune_ml-targets-node) + [edge](#machine-learning-property-graph-neptune_ml-targets-edge) + [property](#machine-learning-property-graph-neptune_ml-targets-property) + [tipo](#machine-learning-property-graph-neptune_ml-targets-type) + [split\$1rate](#machine-learning-property-graph-neptune_ml-targets-split_rate) + [separator](#machine-learning-property-graph-neptune_ml-targets-separator) + [Campi di destinazione RDF](#machine-learning-RDF-neptune_ml-targets) + [nodo](#machine-learning-RDF-neptune_ml-targets-node) + [subject](#machine-learning-RDF-neptune_ml-targets-subject) + [predicate](#machine-learning-RDF-neptune_ml-targets-predicate) + [oggetto](#machine-learning-RDF-neptune_ml-targets-object) + [tipo](#machine-learning-RDF-neptune_ml-targets-type) + [split\$1rate](#machine-learning-RDF-neptune_ml-targets-split_rate) ## Campi in un oggetto di destinazione del grafo delle proprietà ### Il campo nodo (vertice) in un oggetto bersaglio Etichetta del grafo delle proprietà di un nodo di destinazione (vertice). Un oggetto di destinazione deve contenere un elemento `node` o un elemento `edge`, ma non entrambi. Un oggetto `node` accetta un singolo valore, come questo: ``` "node": "Movie" ``` Oppure, nel caso di un vertice con più etichette, può accettare un array di valori, come questo: ``` "node": ["Content", "Movie"] ``` ### Il campo del bordo in un oggetto bersaglio del grafico delle proprietà Specifica un arco di destinazione mediante le etichette del nodo iniziale, la propria etichetta e le etichette del nodo finale. Un oggetto di destinazione deve contenere un elemento `edge` o un elemento `node`, ma non entrambi. Il valore di un campo `edge` è un array JSON di tre stringhe che rappresentano le etichette del grafo delle proprietà del nodo iniziale, l'etichetta del grafo delle proprietà dell'arco stesso e le etichette del grafo delle proprietà del nodo finale, in questo modo: ``` "edge": ["Person_A", "knows", "Person_B"] ``` Se il nodo and/or finale del nodo iniziale ha più etichette, racchiudile in un array, in questo modo: ``` "edge": [ ["Admin", Person_A"], "knows", ["Admin", "Person_B"] ] ``` ### Il campo delle proprietà in un oggetto target del grafo delle proprietà Specifica una proprietà del vertice o dell'arco di destinazione, in questo modo: ``` "property" : "rating" ``` Questo campo è obbligatorio, tranne quando l'attività di destinazione è la previsione dei collegamenti. ### Il campo di tipo in un oggetto di destinazione del grafico delle proprietà Indica il tipo di attività di destinazione da eseguire su `node` o `edge`, in questo modo: ``` "type" : "regression" ``` I tipi di attività supportati per i nodi sono: + `classification` + `regression` I tipi di attività supportati per gli archi sono: + `classification` + `regression` + `link_prediction` Questo campo è obbligatorio. ### Il campo split\$1rate in un oggetto target del grafo delle proprietà (*Facoltativo*): una stima delle proporzioni di nodi o archi che verranno utilizzate rispettivamente nelle fasi di addestramento, convalida e test. Queste proporzioni sono rappresentate da un array JSON di tre numeri compresi tra zero e uno che si sommano a uno: ``` "split_rate": [0.7, 0.1, 0.2] ``` Se non si fornisce il `split_rate` campo opzionale, il valore stimato predefinito è `[0.9, 0.1, 0.0]` per le attività di classificazione e regressione e per le attività di previsione dei collegamenti. `[0.9,0.05, 0.05]` ### Il campo separatore in un oggetto di destinazione del grafico delle proprietà (*Facoltativo*): utilizzato con un'attività di classificazione. Il campo `separator` specifica un carattere utilizzato per suddividere il valore di una proprietà di destinazione in più valori categoriali quando viene utilizzato per archiviare più valori di categoria in una stringa. Esempio: ``` "separator": "|" ``` La presenza di un campo `separator` indica che l'attività è un'attività di classificazione con più destinazioni. ## Campi in un oggetto di destinazione RDF ### Il campo del nodo in un oggetto target RDF Definisce il tipo di nodo dei nodi di destinazione. Utilizzato con attività di classificazione dei nodi o attività di regressione dei nodi. Il tipo di nodo di un nodo in RDF è definito da: ``` node_id, , node_type ``` Un oggetto `node` RDF accetta solo un singolo valore, come questo: ``` "node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie" ``` ### Il campo oggetto in un oggetto target RDF Per le attività di previsione dei collegamenti, `subject` definisce il tipo di nodo di origine degli archi di destinazione. ``` "subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director" ``` **Nota** Per le attività di previsione dei collegamenti, `subject` deve essere utilizzato insieme a `predicate` e `object`. Se uno di questi tre elementi non viene specificato, tutti gli archi vengono considerati come destinazione dell'addestramento. ### Il campo del predicato in un oggetto target RDF Per le attività di classificazione e regressione dei nodi, `predicate` definisce quali dati letterali vengono utilizzati come funzionalità del nodo di destinazione di un nodo di destinazione. ``` "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre" ``` **Nota** Se i nodi di destinazione hanno un solo predicato che definisce la funzionalità del nodo di destinazione, il campo `predicate` può essere omesso. Per le attività di previsione dei collegamenti, `predicate` definisce il tipo di nodo di relazione degli archi di destinazione. ``` "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/direct" ``` **Nota** Per le attività di previsione dei collegamenti, `predicate` deve essere utilizzato insieme a `subject` e `object`. Se uno di questi tre elementi non viene specificato, tutti gli archi vengono considerati come destinazione dell'addestramento. ### Il campo oggetto in un oggetto target RDF Per le attività di previsione dei collegamenti, `object` definisce il tipo di nodo di destinazione degli archi di destinazione: ``` "object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie" ``` **Nota** Per le attività di previsione dei collegamenti, `object` deve essere utilizzato insieme a `subject` e `predicate`. Se uno di questi tre elementi non viene specificato, tutti gli archi vengono considerati come destinazione dell'addestramento. ### Il campo di tipo in un oggetto di destinazione RDF Indica il tipo di attività di destinazione da eseguire, in questo modo: ``` "type" : "regression" ``` I tipi di attività supportati per i dati RDF sono: + `link_prediction` + `classification` + `regression` Questo campo è obbligatorio. ### Campo `split_rate` in un oggetto di destinazione del grafo delle proprietà (*Facoltativo*): una stima delle proporzioni di nodi o archi che verranno utilizzate rispettivamente nelle fasi di addestramento, convalida e test. Queste proporzioni sono rappresentate da un array JSON di tre numeri compresi tra zero e uno che si sommano a uno: ``` "split_rate": [0.7, 0.1, 0.2] ``` Se non si specifica il campo `split_rate` facoltativo, il valore stimato predefinito è `[0.9, 0.1, 0.0]`. # Il campo delle caratteristiche in neptune\$1ml I valori delle proprietà e i valori letterali RDF sono disponibili in formati e tipi di dati diversi. Per ottenere prestazioni ottimali nel machine learning, è essenziale convertire tali valori in codifiche numeriche note come *funzionalità*. Neptune ML esegue l'estrazione e la codifica delle funzionalità come parte dei passaggi di esportazione ed elaborazione dei dati, come descritto in [Codifica delle funzionalità in Neptune ML](machine-learning-feature-encoding.md). Per i set di dati con grafi di proprietà, il processo di esportazione deduce automaticamente le funzionalità `auto` delle proprietà stringa e delle proprietà numeriche contenenti più valori. Per le proprietà numeriche contenenti valori singoli, deduce funzionalità `numerical`. Per le proprietà data deduce funzionalità `datetime`. Se desideri sovrascrivere una specifica di funzionalità dedotta automaticamente o aggiungere una specifica numerica del bucket, TF-IDF o SBERT per una proprietà FastText, puoi controllare la codifica della funzionalità utilizzando il campo features. **Nota** È possibile utilizzare il campo `features` solo per controllare le specifiche delle funzionalità per i dati dei grafi di proprietà, non per i dati RDF. Per il testo in formato libero, Neptune ML può utilizzare diversi modelli per convertire la sequenza di token in un valore della proprietà stringa in un vettore di valori reali a dimensione fissa: + [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features): usa la codifica [fastText](https://fasttext.cc/). Si tratta della codifica consigliata per le funzionalità che utilizzano una e solo una delle cinque lingue supportate da fastText. + [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-sbert-features): usa i modelli di codifica [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). Si tratta della codifica consigliata per il testo non supportato da `text_fasttext`. + [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features): usa gli algoritmi [Word2Vec](https://wikipedia.org/wiki/Word2vec) originariamente pubblicati da [Google](https://code.google.com/archive/p/word2vec/) per codificare il testo. Word2Vec supporta solo la lingua inglese. + [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features): usa un vettorizzatore TF-IDF ([Term Frequency—Inverse Document Frequency](https://wikipedia.org/wiki/Tf-idf)) per la codifica del testo. La codifica TF-IDF supporta funzionalità statistiche non supportate da altre codifiche. Il campo `features` contiene un array JSON di funzionalità delle proprietà dei nodi. Gli oggetti nell'array possono contenere i seguenti campi: **Contents** + [nodo](#machine-learning-neptune_ml-features-node) + [edge](#machine-learning-neptune_ml-features-edge) + [property](#machine-learning-neptune_ml-features-property) + [tipo](#machine-learning-neptune_ml-feature-types) + [norm](#machine-learning-neptune_ml-features-norm) + [linguaggio](#machine-learning-neptune_ml-features-language) + [max\$1length](#machine-learning-neptune_ml-features-max_length) + [separator](#machine-learning-neptune_ml-features-separator) + [range](#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) + [imputer](#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) ## Il campo del nodo nelle funzionalità Il campo `node` specifica l'etichetta del grafo delle proprietà di un vertice della funzionalità. Esempio: ``` "node": "Person" ``` Se un vertice ha più etichette, racchiudile in un array. Esempio: ``` "node": ["Admin", "Person"] ``` ## Il campo edge nelle feature Il campo `edge` specifica il tipo di arco di un arco della funzionalità. Un tipo di arco è costituito da un array contenente le etichette del grafo delle proprietà del vertice di origine, l'etichetta del grafo delle proprietà dell'arco e le etichette del grafo delle proprietà del vertice di destinazione. È necessario fornire tutti e tre i valori quando si specifica una funzionalità dell'arco. Esempio: ``` "edge": ["User", "reviewed", "Movie"] ``` Se un vertice di origine o di destinazione di un tipo di arco ha più etichette, racchiudile in un altro array. Esempio: ``` "edge": [["Admin", "Person"]. "edited", "Post"] ``` ## Il campo della proprietà nelle funzionalità Usa il parametro property per specificare una proprietà del vertice identificato dal parametro `node`. Esempio: ``` "property" : "age" ``` ## Valori possibili del campo di tipo per le funzionalità Il parametro `type` specifica il tipo di funzionalità da definire. Esempio: ``` "type": "bucket_numerical" ``` **Valori possibili del parametro `type`** + **`"auto"`**: specifica che Neptune ML deve rilevare automaticamente il tipo di proprietà e applicare una codifica delle funzionalità appropriata. Una funzionalità `auto` può anche avere un campo `separator` facoltativo. Per informazioni, consulta [Codifica delle funzionalità auto in Neptune ML](machine-learning-feature-encoding.md#machine-learning-auto-encoding). + **`"category"`**: questa codifica della funzionalità rappresenta il valore di una proprietà come una di varie categorie. In altre parole, la funzionalità può accettare uno o più valori discreti. Una funzionalità `category` può anche avere un campo `separator` facoltativo. Per informazioni, consulta [Funzionalità categoriali in Neptune ML](machine-learning-feature-encoding.md#machine-learning-categorical-features). + **`"numerical"`**: questa codifica di funzionalità rappresenta i valori delle proprietà numeriche come numeri in un intervallo continuo in cui "maggiore di" e "minore di" hanno un significato. Una funzionalità `numerical` può anche avere campi `norm`, `imputer` e `separator`. Per informazioni, consulta [Funzionalità numeriche in Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features). + **`"bucket_numerical"`**: questa codifica della funzionalità divide i valori delle proprietà numeriche in un set di *bucket* o categorie. Ad esempio, puoi codificare l'età delle persone in 4 bucket: bambini (0-20), giovani adulti (20-40), persone di mezza età (40-60 anni) e anziani (dai 60 anni in su). Una `bucket_numerical` funzionalità richiede un `bucket_cnt` campo `range` e può facoltativamente includere anche un `imputer` and/or `slide_window_size` campo. Per informazioni, consulta [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). + **`"datetime"`**: questa codifica di funzionalità rappresenta il valore di una proprietà datetime come array di queste funzionalità categoriali: anno, mese, giorno della settimana e ora. Una o più di queste quattro categorie possono essere eliminate utilizzando il parametro `datetime_parts`. Per informazioni, consulta [Funzionalità datetime in Neptune ML](machine-learning-feature-encoding.md#machine-learning-datetime-features). + **`"text_fasttext"`**: questa codifica di funzionalità converte i valori delle proprietà costituiti da frasi o testo in formato libero in vettori numerici usando modelli [fastText](https://fasttext.cc/). Supporta cinque lingue, ovvero inglese (`en`), cinese (`zh`), hindi (`hi`), spagnolo (`es`) e francese (`fr`). Per i valori delle proprietà di testo in ognuna di queste cinque lingue, `text_fasttext` è la codifica consigliata. Tuttavia, non è in grado di gestire i casi in cui la stessa frase contiene parole in più di una lingua. Per lingue diverse da quelle supportate da fastText, usa la codifica `text_sbert`. Se sono presenti molte stringhe di testo con valori delle proprietà più lunghe, ad esempio, di 120 token, usa il campo `max_length` per limitare il numero di token in ogni stringa codificata tramite `"text_fasttext"`. Per informazioni, consulta [Codifica *fastText* dei valori delle proprietà di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-fasttext-features). + **`"text_sbert"`**: questa codifica converte i valori delle proprietà del testo in vettori numerici utilizzando i modelli [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). Neptune supporta due metodi SBERT, ovvero `text_sbert128`, che è il metodo predefinito se si specifica solo `text_sbert` e `text_sbert512`. La differenza tra i due sta nel numero massimo di token che vengono codificati in una proprietà del testo. La codifica `text_sbert128` codifica solo i primi 128 token, mentre `text_sbert512` codifica fino a 512 token. Di conseguenza, l'utilizzo di `text_sbert512` può richiedere tempi di elaborazione superiori rispetto a `text_sbert128`. Entrambi i metodi sono più lenti di `text_fasttext`. I metodi `text_sbert*` supportano molte lingue e possono codificare una frase che contiene più di una lingua. Per informazioni, consulta [Codifica Sentence BERT (SBERT) delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-sbert-features). + **`"text_word2vec"`**: questa codifica converte i valori delle proprietà del testo in vettori numerici utilizzando gli algoritmi [Word2Vec](https://wikipedia.org/wiki/Word2vec). Supporta solo la lingua inglese. Per informazioni, consulta [Codifica Word2Vec delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-word2vec-features). + **`"text_tfidf"`**: questa codifica converte i valori delle proprietà del testo in vettori numerici utilizzando un vettorizzatore TF-IDF ([Term Frequency—Inverse Document Frequency](https://wikipedia.org/wiki/Tf-idf)). È possibile definire i parametri della codifica di una funzionalità `text_tfidf` utilizzando il campo `ngram_range`, il campo `min_df` e il campo `max_features`. Per informazioni, consulta [Codifica TF-IDF delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features). + **`"none"`**: usando il tipo `none` non avviene alcuna codifica delle funzionalità. I valori della proprietà non elaborati vengono invece analizzati e salvati. Usa `none` solo se intendi eseguire una codifica personalizzata delle funzionalità come parte dell'addestramento personalizzato del modello. ## Il campo della norma Questo campo è obbligatorio per le funzioni numeriche. Specifica un metodo di normalizzazione da utilizzare sui valori numerici: ``` "norm": "min-max" ``` Sono supportati i seguenti metodi di normalizzazione: + **"min-max"**: normalizza ogni valore sottraendo da esso il valore minimo e poi dividendolo per la differenza tra il valore massimo e il valore minimo. + **"standard"**: normalizza ogni valore dividendolo per la somma di tutti i valori. + **"none"**: non normalizza i valori numerici durante la codifica. Per informazioni, consulta [Funzionalità numeriche in Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features). ## Il campo della lingua Il campo della lingua specifica la lingua utilizzata nei valori delle proprietà del testo. Il suo utilizzo dipende dal metodo di codifica del testo: + Per la codifica [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) questo campo è obbligatorio e deve specificare una delle seguenti lingue: + `en`   (inglese) + `zh`   (cinese) + `hi`   (hindi) + `es`   (spagnolo) + `fr`   (francese) + Per la codifica [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) questo campo non viene utilizzato, poiché la codifica SBERT è multilingue. + Per la codifica [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) questo campo è facoltativo, poiché `text_word2vec` supporta solo la lingua inglese. Se presente, deve specificare il nome del modello linguistico inglese: ``` "language" : "en_core_web_lg" ``` + Per la codifica [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) questo campo non viene utilizzato. ## Il campo max\$1length Il campo `max_length` è facoltativo per le funzionalità `text_fasttext`, in quanto specifica il numero massimo di token in una funzionalità di testo di input che verranno codificati. Il testo di input più lungo di `max_length` viene troncato. Ad esempio, l'impostazione di max\$1length su 128 indica che tutti i token successivi al 128° in una sequenza di testo verranno ignorati: ``` "max_length": 128 ``` ## Il campo separatore Questo campo viene utilizzato facoltativamente con le funzionalità `category`, `numerical` e `auto`. Specifica un carattere che può essere utilizzato per suddividere il valore di una proprietà in più valori categoriali o valori numerici: ``` "separator": ";" ``` Utilizza il campo `separator` solo quando la proprietà archivia più valori delimitati in una singola stringa, ad esempio `"Actor;Director"` o `"0.1;0.2"`. Consulta le sezioni [Funzionalità categoriali](machine-learning-feature-encoding.md#machine-learning-categorical-features), [Funzionalità numeriche](machine-learning-feature-encoding.md#machine-learning-numerical-features) e [Codifica auto](machine-learning-feature-encoding.md#machine-learning-auto-encoding). ## Il campo dell'intervallo Questo campo è obbligatorio per le funzionalità `bucket_numerical`. Specifica l'intervallo di valori numerici che devono essere suddivisi in bucket, nel formato: `[lower-bound, upper-bound]`. ``` "range" : [20, 100] ``` Se il valore di una proprietà è minore del limite inferiore, viene assegnato al primo bucket o, se è maggiore del limite superiore, viene assegnato all'ultimo bucket. Per informazioni, consulta [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). ## Il campo bucket\$1cnt Questo campo è obbligatorio per le funzionalità `bucket_numerical`. Specifica il numero di bucket in cui deve essere suddiviso l'intervallo numerico definito dal parametro `range`: ``` "bucket_cnt": 10 ``` Per informazioni, consulta [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). ## Il campo slide\$1window\$1size Questo campo viene usato facoltativamente con le funzionalità `bucket_numerical` per assegnare valori a più di un bucket: ``` "slide_window_size": 5 ``` Per le finestre scorrevoli, Neptune ML prende le dimensioni della finestra **`s`** e trasforma ogni valore **`v`** numerico di una proprietà in un intervallo da ` v - s/2 ` a ` v + s/2 `. Il valore viene quindi assegnato a ogni bucket a cui si sovrappone l'intervallo. Per informazioni, consulta [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). ## Il campo dell'imputer Questo campo viene utilizzato facoltativamente con le funzionalità `numerical` e `bucket_numerical` per fornire una tecnica di imputazione per inserire i valori mancanti: ``` "imputer": "mean" ``` Le tecniche di imputazione supportate sono: + `"mean"` + `"median"` + `"most-frequent"` Se non si include il parametro imputer, la pre-elaborazione dei dati si interrompe e termina quando viene rilevato un valore mancante. Consulta [Funzionalità numeriche in Neptune ML](machine-learning-feature-encoding.md#machine-learning-numerical-features) e [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). ## Il campo max\$1features Questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare il numero massimo di termini da codificare: ``` "max_features": 100 ``` Se viene ad esempio impostato su 100, il vettorizzatore TF-IDF codificherà solo i 100 termini più comuni. Il valore predefinito, se si include `max_features`, è 5.000. Per informazioni, consulta [Codifica TF-IDF delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features). ## Il campo min\$1df Questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare la frequenza minima nel documento dei termini da codificare: ``` "min_df": 5 ``` Se viene ad esempio impostato su 5, indica che un termine deve comparire in almeno 5 valori di proprietà diversi per poter essere codificato. Il valore predefinito, se non si include il parametro `min_df` è `2`. Per informazioni, consulta [Codifica TF-IDF delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features). ## Il campo ngram\$1range Questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare le dimensioni delle sequenze di parole o token da considerare come potenziali termini individuali da codificare: ``` "ngram_range": [2, 4] ``` Il valore `[2, 4]` specifica che le sequenze di 2, 3 e 4 parole devono essere considerate come potenziali termini individuali. L'impostazione predefinita, se non si imposta `ngram_range` in modo esplicito è `[1, 1]`, ovvero solo singole parole o token vengono considerati come termini da codificare. Per informazioni, consulta [Codifica TF-IDF delle funzionalità di testo in Neptune ML](machine-learning-feature-encoding.md#machine-learning-tfidf-features). ## Il campo datetime\$1parts Questo campo viene utilizzato facoltativamente dalle funzionalità `datetime` per specificare quali parti del valore datetime codificare in modo categoriale: ``` "datetime_parts": ["weekday", "hour"] ``` Se non si include `datetime_parts`, per impostazione predefinita Neptune ML codifica le parti relative all'anno, al mese, al giorno della settimana e all'ora del valore datetime. Il valore `["weekday", "hour"]` indica che solo i valori di data/ora del giorno della settimana e dell'ora devono essere codificati in modo categoriale nella funzionalità. Se una delle parti non ha più di un valore univoco nel set di addestramento, non viene codificata. Per informazioni, consulta [Funzionalità datetime in Neptune ML](machine-learning-feature-encoding.md#machine-learning-datetime-features). # Esempi di utilizzo dei parametri all'interno di AdditionalParams per l'ottimizzazione della configurazione di addestramento del modello I seguenti esempi dimostrano come utilizzare la funzionalità «AdditionalParams» nei modelli di dati Property-Graph e RDF per configurare vari aspetti del processo di addestramento del modello per un'applicazione Neptune ML. Gli esempi coprono un'ampia gamma di funzionalità, tra cui la specifica delle velocità di suddivisione predefinite per training/validation/test i dati, la definizione di attività di classificazione dei nodi, regressione e previsione dei collegamenti, nonché la configurazione di diversi tipi di funzionalità come bucket numerici, incorporamenti di testo, datetime e dati categorici. Queste configurazioni dettagliate consentono di personalizzare la pipeline di machine learning in base ai requisiti specifici di dati e modellazione, sfruttando tutto il potenziale delle funzionalità di Neptune ML. **Contents** + [Esempi di grafici di proprietà che utilizzano AdditionalParams](#machine-learning-property-graph-additionalParams-examples) + [Definizione di un coefficiente di divisione per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-default-split-rate-example) + [Definizione di un'attività di classificazione dei nodi per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-node-classification-example) + [Definizione di un'attività di classificazione dei nodi multi-classe per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-multi-class-example) + [Definizione di un'attività di regressione dei nodi per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-node-regression-example) + [Definizione di un'attività di classificazione degli archi per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-edge-classification-example) + [Definizione di un'attività di classificazione degli archi multi-classe per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-multi-edge-classification-example) + [Definizione di un'attività di regressione degli archi per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-edge-regression-example) + [Definizione di un'attività di previsione dei collegamenti per la configurazione dell'addestramento dei modelli](#machine-learning-property-graph-additionalParams-link-prediction-example) + [Definizione di una funzionalità bucket numerico](#machine-learning-property-graph-additionalParams-numeric-bucket-example) + [Definizione di una funzionalità `Word2Vec`](#machine-learning-property-graph-additionalParams-word2vec-example) + [Definizione di una funzionalità `FastText`](#machine-learning-property-graph-additionalParams-fasttext-example) + [Definizione di una funzionalità `Sentence BERT`](#machine-learning-property-graph-additionalParams-sbert-example) + [Definizione di una funzionalità `TF-IDF`](#machine-learning-property-graph-additionalParams-tf-idf-example) + [Definizione di una funzionalità `datetime`](#machine-learning-property-graph-additionalParams-datetime-example) + [Definizione di una funzionalità `category`](#machine-learning-property-graph-additionalParams-category-example) + [Definizione di una funzionalità `numerical`](#machine-learning-property-graph-additionalParams-numerical-example) + [Definizione di una funzionalità `auto`](#machine-learning-property-graph-additionalParams-auto-example) + [Esempi di grafi RDF con `additionalParams`](#machine-learning-RDF-additionalParams-examples) + [Definizione di un coefficiente di divisione per la configurazione dell'addestramento dei modelli](#machine-learning-RDF-additionalParams-default-split-rate-example) + [Definizione di un'attività di classificazione dei nodi per la configurazione dell'addestramento dei modelli](#machine-learning-RDF-additionalParams-node-classification-example) + [Definizione di un'attività di regressione dei nodi per la configurazione dell'addestramento dei modelli](#machine-learning-RDF-additionalParams-node-regression-example) + [Definizione di un'attività di previsione dei collegamenti per archi particolari](#machine-learning-RDF-additionalParams-link-prediction-example) + [Definizione di un'attività di previsione dei collegamenti per tutti gli archi](#machine-learning-RDF-additionalParams-link-prediction-example) ## Esempi di grafici di proprietà che utilizzano AdditionalParams ### Definizione di un coefficiente di divisione per la configurazione dell'addestramento dei modelli Nell'esempio seguente, il parametro `split_rate` imposta il coefficiente di divisione predefinito per l'addestramento dei modelli. Se non viene specificato alcun coefficiente di divisione predefinito, l'addestramento utilizza un valore di [0,9, 0,1, 0,0]. È possibile sovrascrivere il valore predefinito per ogni destinazione specificando un valore `split_rate` per ogni destinazione. Nell'esempio seguente il campo `default split_rate` indica che occorre usare un coefficiente di divisione di `[0.7,0.1,0.2]`, a meno che non venga sovrascritto per ogni singola destinazione:" ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "split_rate": [0.7,0.1,0.2], "targets": [ (...) ], "features": [ (...) ] } } ``` ### Definizione di un'attività di classificazione dei nodi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà del nodo contenente esempi etichettati ai fini dell'addestramento, aggiungi un elemento di classificazione dei nodi all'array `targets`, usando `"type" : "classification"`. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. Nell'esempio seguente la destinazione `node` indica che la proprietà `genre` di ogni nodo `Movie` deve essere trattata come un'etichetta della classe nodo. Il valore `split_rate` sovrascrive il coefficiente di divisione predefinito: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "genre", "type": "classification", "split_rate": [0.7,0.1,0.2] } ], "features": [ (...) ] } } ``` ### Definizione di un'attività di classificazione dei nodi multi-classe per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà del nodo contenente più esempi etichettati ai fini dell'addestramento, aggiungi un elemento di classificazione dei nodi all'array targets usando `"type" : "classification"` e `separator` per specificare un carattere da usare per dividere un valore della proprietà di destinazione in più valori categoriali. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. Nell'esempio seguente la destinazione `node` indica che la proprietà `genre` di ogni nodo `Movie` deve essere trattata come un'etichetta della classe nodo. Il campo `separator` indica che ogni proprietà di genere contiene più valori separati da punto e virgola: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "genre", "type": "classification", "separator": ";" } ], "features": [ (...) ] } } ``` ### Definizione di un'attività di regressione dei nodi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà del nodo contenente le regressioni etichettate ai fini dell'addestramento, aggiungi un elemento di regressione dei nodi all'array targets usando `"type" : "regression"`. Aggiungi un campo split\$1rate per sovrascrivere il coefficiente di divisione predefinito. La destinazione `node` seguente indica che la proprietà `rating` di ogni nodo `Movie` deve essere trattata come un'etichetta di regressione del nodo. ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "rating", "type" : "regression", "split_rate": [0.7,0.1,0.2] } ], "features": [ ... ] } } ``` ### Definizione di un'attività di classificazione degli archi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà dell'arco contenente esempi etichettati ai fini dell'addestramento, aggiungi un elemento arco all'array `targets`, usando `"type" : "regression"`. Aggiungi un campo split\$1rate per sovrascrivere il coefficiente di divisione predefinito. La destinazione `edge` seguente indica che la proprietà `metAtLocation` di ogni arco `knows` deve essere trattata come un'etichetta della classe arco: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "knows", "Person"], "property": "metAtLocation", "type": "classification" } ], "features": [ (...) ] } } ``` ### Definizione di un'attività di classificazione degli archi multi-classe per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà dell'arco contenente più esempi etichettati ai fini dell'addestramento, aggiungi un elemento edge all'array `targets` usando `"type" : "classification"` e un campo `separator` per specificare un carattere da usare per dividere un valore della proprietà di destinazione in più valori categoriali. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. La destinazione `edge` seguente indica che la proprietà `sentiment` di ogni arco `repliedTo` deve essere trattata come un'etichetta della classe arco. Il campo separatore indica che ogni proprietà sentiment contiene più valori separati da virgole: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "repliedTo", "Message"], "property": "sentiment", "type": "classification", "separator": "," } ], "features": [ (...) ] } } ``` ### Definizione di un'attività di regressione degli archi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà dell'arco contenente esempi di regressione etichettati ai fini dell'addestramento, aggiungi un elemento `edge` all'array `targets`, usando `"type" : "regression"`. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. La destinazione `edge` seguente indica che la proprietà `rating` di ogni arco `reviewed` deve essere trattata come regressione degli archi: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "reviewed", "Movie"], "property": "rating", "type" : "regression" } ], "features": [ (...) ] } } ``` ### Definizione di un'attività di previsione dei collegamenti per la configurazione dell'addestramento dei modelli Per indicare gli archi da usare ai fini dell'addestramento delle previsioni dei collegamenti, aggiungi un elemento edge all'array targets usando `"type" : "link_prediction"`. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. La destinazione `edge` seguente indica che è necessario usare gli archi `cites` per la previsione dei collegamenti: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Article", "cites", "Article"], "type" : "link_prediction" } ], "features": [ (...) ] } } ``` ### Definizione di una funzionalità bucket numerico È possibile specificare una funzionalità dati numerici per una proprietà del nodo aggiungendo `"type": "bucket_numerical"` all'array `features`. La funzionalità `node` seguente indica che la proprietà `age` di ogni nodo `Person` deve essere trattata come una funzionalità bucket numerico: ``` "additionalParams": { "neptune_ml": { "targets": [ ... ], "features": [ { "node": "Person", "property": "age", "type": "bucket_numerical", "range": [1, 100], "bucket_cnt": 5, "slide_window_size": 3, "imputer": "median" } ] } } ``` ### Definizione di una funzionalità `Word2Vec` È possibile specificare una funzionalità `Word2Vec` per una proprietà del nodo aggiungendo `"type": "text_word2vec"` all'array `features`. La funzionalità `node` seguente indica che la proprietà `description` di ogni nodo `Movie` deve essere trattata come una funzionalità `Word2Vec`: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_word2vec", "language": "en_core_web_lg" } ] } } ``` ### Definizione di una funzionalità `FastText` È possibile specificare una funzionalità `FastText` per una proprietà del nodo aggiungendo `"type": "text_fasttext"` all'array `features`. Il campo `language` è obbligatorio e deve specificare uno dei codici di lingua seguenti: + `en`   (inglese) + `zh`   (cinese) + `hi`   (hindi) + `es`   (spagnolo) + `fr`   (francese) Tieni presente che la codifica `text_fasttext` non può gestire più di una lingua alla volta in una funzionalità. La funzionalità `node` seguente indica che la proprietà `description` francese di ogni nodo `Movie` deve essere trattata come una funzionalità `FastText`: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_fasttext", "language": "fr", "max_length": 1024 } ] } } ``` ### Definizione di una funzionalità `Sentence BERT` È possibile specificare una funzionalità `Sentence BERT` per una proprietà del nodo aggiungendo `"type": "text_sbert"` all'array `features`. Non è necessario specificare la lingua, poiché il metodo codifica automaticamente le funzionalità di testo utilizzando un modello linguistico multilingue. La funzionalità `node` seguente indica che la proprietà `description` di ogni nodo `Movie` deve essere trattata come una funzionalità `Sentence BERT`: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_sbert128", } ] } } ``` ### Definizione di una funzionalità `TF-IDF` È possibile specificare una funzionalità `TF-IDF` per una proprietà del nodo aggiungendo `"type": "text_tfidf"` all'array `features`. La funzionalità `node` seguente indica che la proprietà `bio` di ogni nodo `Person` deve essere trattata come una funzionalità `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 } ] } } ``` ### Definizione di una funzionalità `datetime` Il processo di esportazione deduce automaticamente le funzionalità `datetime` per le proprietà data. Tuttavia, per limitare l'uso di `datetime_parts` per una funzionalità `datetime` o ignorare una specifica di funzionalità affinché una proprietà che normalmente verrebbe trattata come una funzionalità `auto` venga trattata esplicitamente come una funzionalità `datetime`, puoi aggiungere l'elemento `"type": "datetime"` all'array features. La funzionalità `node` seguente indica che la proprietà `createdAt` di ogni nodo `Post` deve essere trattata come una funzionalità `datetime`: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Post", "property": "createdAt", "type": "datetime", "datetime_parts": ["month", "weekday", "hour"] } ] } } ``` ### Definizione di una funzionalità `category` Il processo di esportazione deduce automaticamente le funzionalità `auto` delle proprietà stringa e delle proprietà numeriche contenenti più valori. Per le proprietà numeriche contenenti valori singoli, deduce funzionalità `numerical`. Per le proprietà data deduce funzionalità `datetime`. Se desideri sovrascrivere la specifica di una funzionalità affinché una proprietà venga trattata come una funzionalità categoriale, aggiungi un elemento `"type": "category"` all'array features. Se la proprietà contiene più valori, includi un campo `separator`. Esempio: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Post", "property": "tag", "type": "category", "separator": "|" } ] } } ``` ### Definizione di una funzionalità `numerical` Il processo di esportazione deduce automaticamente le funzionalità `auto` delle proprietà stringa e delle proprietà numeriche contenenti più valori. Per le proprietà numeriche contenenti valori singoli, deduce funzionalità `numerical`. Per le proprietà data deduce funzionalità `datetime`. Se desideri sovrascrivere la specifica di una funzionalità affinché una proprietà venga trattata come una funzionalità `numerical`, aggiungi `"type": "numerical"` all'array features. Se la proprietà contiene più valori, includi un campo `separator`. Esempio: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Recording", "property": "duration", "type": "numerical", "separator": "," } ] } } ``` ### Definizione di una funzionalità `auto` Il processo di esportazione deduce automaticamente le funzionalità `auto` delle proprietà stringa e delle proprietà numeriche contenenti più valori. Per le proprietà numeriche contenenti valori singoli, deduce funzionalità `numerical`. Per le proprietà data deduce funzionalità `datetime`. Se desideri sovrascrivere la specifica di una funzionalità affinché una proprietà venga trattata come una funzionalità `auto`, aggiungi `"type": "auto"` all'array features. Se la proprietà contiene più valori, includi un campo `separator`. Esempio: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "User", "property": "role", "type": "auto", "separator": "," } ] } } ``` ## Esempi di grafi RDF con `additionalParams` ### Definizione di un coefficiente di divisione per la configurazione dell'addestramento dei modelli Nell'esempio seguente, il parametro `split_rate` imposta il coefficiente di divisione predefinito per l'addestramento dei modelli. Se non viene specificato alcun coefficiente di divisione predefinito, l'addestramento utilizza un valore di [0,9, 0,1, 0,0]. È possibile sovrascrivere il valore predefinito per ogni destinazione specificando un valore `split_rate` per ogni destinazione. Nell'esempio seguente il campo `default split_rate` indica che occorre usare un coefficiente di divisione di `[0.7,0.1,0.2]`, a meno che non venga sovrascritto per ogni singola destinazione:" ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "split_rate": [0.7,0.1,0.2], "targets": [ (...) ] } } ``` ### Definizione di un'attività di classificazione dei nodi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà del nodo contenente esempi etichettati ai fini dell'addestramento, aggiungi un elemento di classificazione dei nodi all'array `targets`, usando `"type" : "classification"`. Aggiungi un campo node per indicare il tipo di nodo dei nodi di destinazione. Aggiungi un campo `predicate` per definire i dati letterali da usare come funzionalità del nodo di destinazione del nodo di destinazione. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. Nell'esempio seguente la destinazione `node` indica che la proprietà `genre` di ogni nodo `Movie` deve essere trattata come un'etichetta della classe nodo. Il valore `split_rate` sovrascrive il coefficiente di divisione predefinito: ``` "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] } ] } } ``` ### Definizione di un'attività di regressione dei nodi per la configurazione dell'addestramento dei modelli Per indicare qual è la proprietà del nodo contenente le regressioni etichettate ai fini dell'addestramento, aggiungi un elemento di regressione dei nodi all'array targets usando `"type" : "regression"`. Aggiungi un campo `node` per indicare il tipo di nodo dei nodi di destinazione. Aggiungi un campo `predicate` per definire i dati letterali da usare come funzionalità del nodo di destinazione del nodo di destinazione. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. La destinazione `node` seguente indica che la proprietà `rating` di ogni nodo `Movie` deve essere trattata come un'etichetta di regressione del nodo. ``` "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] } ] } } ``` ### Definizione di un'attività di previsione dei collegamenti per archi particolari Per indicare gli archi da usare ai fini dell'addestramento delle previsioni dei collegamenti, aggiungi un elemento edge all'array targets usando `"type" : "link_prediction"`. Aggiungi i campi `subject`, `predicate` e `object` per specificare il tipo di arco. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. La destinazione `edge` seguente indica che è necessario usare gli archi `directed` che connettono `Directors` a `Movies` per la previsione dei collegamenti: ``` "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" } ] } } ``` ### Definizione di un'attività di previsione dei collegamenti per tutti gli archi Per indicare che è necessario usare tutti gli archi ai fini dell'addestramento delle previsioni dei collegamenti, aggiungi un elemento `edge` all'array targets usando `"type" : "link_prediction"`. Non aggiungere i campi `subject`, `predicate` o `object`. Aggiungi un campo `split_rate` per sovrascrivere il coefficiente di divisione predefinito. ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "type" : "link_prediction" } ] } } ``` # Elaborazione dei dati del grafo esportati da Neptune per l'addestramento La fase di elaborazione dei dati utilizza i dati del grafo di Neptune creati dal processo di esportazione e crea le informazioni utilizzate da [Deep Graph Library](https://www.dgl.ai/) (DGL) durante l'addestramento. Include l'esecuzione di varie mappature e trasformazioni dei dati: + Analisi di nodi e archi per creare i file di mappatura di grafo e ID richiesti da DGL. + Conversione delle proprietà dei nodi e degli archi nelle funzionalità di nodi e archi richieste da DGL. + Divisione dei dati in set di addestramento, convalida e test. ## Gestione della fase di elaborazione dei dati per Neptune ML Dopo aver esportato da Neptune i dati da utilizzare per l'addestramento dei modelli, puoi avviare un processo di elaborazione dati utilizzando un comando `curl` (o `awscurl`) come il seguente: ``` 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" }' ``` I dettagli su come utilizzare questo comando sono illustrati in [Comando dataprocessing](machine-learning-api-dataprocessing.md), insieme a informazioni su come recuperare lo stato di un processo in esecuzione, come arrestare un processo in esecuzione e come elencare tutti i processi in esecuzione. ## Elaborazione dei dati del grafo aggiornati per Neptune ML È inoltre possibile fornire un `previousDataProcessingJobId` all'API per garantire che il nuovo processo di elaborazione dei dati utilizzi lo stesso metodo di elaborazione di un processo precedente. Questo è necessario quando si desidera ottenere previsioni per i dati del grafo aggiornati in Neptune, riaddestrando il modello precedente sui nuovi dati o ricalcolando gli artefatti del modello sui nuovi dati. A tale scopo, puoi usare un comando `curl` (o `awscurl`) nel seguente modo: ``` 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)"}' ``` Imposta il valore del parametro `previousDataProcessingJobId` sull'ID processo del processo di elaborazione dati precedente corrispondente al modello addestrato. **Nota** Le eliminazioni dei nodi nel grafo aggiornato non sono attualmente supportate. Se i nodi sono stati rimossi in un grafo aggiornato, è necessario avviare un processo di elaborazione dei dati completamente nuovo anziché usare `previousDataProcessingJobId`. # Codifica delle funzionalità in Neptune ML I valori delle proprietà sono disponibili in formati e tipi di dati diversi. Per ottenere prestazioni ottimali nel machine learning, è essenziale convertire tali valori in codifiche numeriche note come *funzionalità*. Neptune ML esegue l'estrazione e la codifica delle funzionalità come parte dei passaggi di esportazione ed elaborazione dei dati, usando le tecniche di codifica delle funzionalità descritte qui. **Nota** Se prevedi di implementare una codifica delle funzionalità personalizzata nell'implementazione di un modello personalizzato, puoi disabilitare la codifica automatica delle funzionalità nella fase di pre-elaborazione dei dati selezionando `none` come tipo di codifica delle funzionalità. Non verrà quindi eseguita alcuna codifica delle funzionalità sulla proprietà del nodo o dell'arco specifica e i valori delle proprietà non elaborati verranno analizzati e salvati in un dizionario. La pre-elaborazione dei dati crea comunque il grafo DGL dal set di dati esportato, ma il grafo DGL creato non dispone delle funzionalità pre-elaborate per l'addestramento. Usa questa opzione solo se intendi eseguire una codifica personalizzata delle funzionalità come parte dell'addestramento personalizzato del modello. Per informazioni dettagliate, vedi [Modelli personalizzati in Neptune ML.](machine-learning-custom-models.md). ## Funzionalità categoriali in Neptune ML Una proprietà che può accettare uno o più valori distinti da un elenco fisso di valori possibili è una funzionalità categoriale. In Neptune ML le funzionalità categoriali vengono codificate mediante la [codifica one-hot.](https://en.wikipedia.org/wiki/One-hot) L'esempio seguente mostra in che modo viene applicata la codifica one-hot al nome della proprietà di diversi alimenti in base alla relativa categoria: ``` Food Veg. Meat Fruit Encoding --------- ---- ---- ----- -------- Apple 0 0 1 001 Chicken 0 1 0 010 Broccoli 1 0 0 100 ``` **Nota** Il numero massimo di categorie in ogni funzionalità categoriale è 100. Se una proprietà ha più di 100 categorie di valore, solo le 99 più comuni vengono inserite in categorie distinte, mentre le altre vengono incluse in una categoria speciale denominata `OTHER`. ## Funzionalità numeriche in Neptune ML Qualsiasi proprietà i cui valori sono numeri reali può essere codificata come funzionalità numerica in Neptune ML. Le funzionalità numeriche sono codificate utilizzando numeri a virgola mobile. È possibile specificare un metodo di normalizzazione dei dati da utilizzare per la codifica delle funzionalità numeriche, in questo modo: `"norm": "normalization technique"`. Sono supportate le seguenti tecniche di normalizzazione: + **"none"**: non normalizza i valori numerici durante la codifica. + **"min-max"**: normalizza ogni valore sottraendo da esso il valore minimo e poi dividendolo per la differenza tra il valore massimo e il valore minimo. + **"standard"**: normalizza ogni valore dividendolo per la somma di tutti i valori. ## Funzionalità numeriche per bucket in Neptune ML Invece di rappresentare una proprietà numeriche con numeri non elaborati, è possibile condensare i valori numerici in categorie. Ad esempio, è possibile suddividere l'età delle persone in categorie come bambini (0-20 anni), giovani adulti (20-40 anni), persone di mezza età (40-60 anni) e anziani (dai 60 anni in poi). Usando questi bucket numerici, si trasforma una proprietà numerica in una sorta di funzionalità categoriale. In Neptune ML per codificare una proprietà numerica come funzionalità numerica per bucket, devi specificare due elementi: + Un intervallo numerico nel formato ` "range": [a, b] `, dove `a` e `b` sono numeri interi. + Un numero di bucket nel formato ` "bucket_cnt": c `, dove `c` è il numero di bucket, anch'esso un numero intero. Neptune ML calcola quindi le dimensioni di ogni bucket come ` ( b - a ) / c ` e codifica ogni valore numerico come il numero dell'eventuale bucket in cui rientra. Qualsiasi valore inferiore a `a` viene considerato appartenente al primo bucket e qualsiasi valore superiore a `b` viene considerato appartenente all'ultimo bucket. Facoltativamente, puoi anche far rientrare i valori numerici in più di un bucket, specificando le dimensioni di una finestra scorrevole, come questa: ` "slide_window_size": s `, dove `s` è un numero. Neptune ML trasforma quindi ogni valore numerico `v` della proprietà in un intervallo da ` v - s/2 ` a ` v + s/2 ` e assegna il valore `v` a ogni bucket incluso nell'intervallo. Infine, è facoltativamente possibile specificare un modo per inserire i valori mancanti per le funzionalità numeriche e le funzionalità numeriche per bucket. A tale scopo, si usa ` "imputer": "imputation technique "`, dove la tecnica di imputazione è una tra `"mean"`, `"median"` o `"most-frequent"`. Se non si specifica un imputer, un valore mancante può causare l'interruzione dell'elaborazione. ## Codifica delle funzionalità di testo in Neptune ML Per il testo in formato libero, Neptune ML può utilizzare diversi modelli per convertire la sequenza di token in una stringa del valore della proprietà in un vettore di valori reali a dimensione fissa: + [`text_fasttext`](#machine-learning-fasttext-features): usa la codifica [fastText](https://fasttext.cc/). Si tratta della codifica consigliata per le funzionalità che utilizzano una e solo una delle cinque lingue supportate da fastText. + [`text_sbert`](#machine-learning-sbert-features): usa i modelli di codifica [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). Si tratta della codifica consigliata per il testo non supportato da `text_fasttext`. + [`text_word2vec`](#machine-learning-word2vec-features): usa gli algoritmi [Word2Vec](https://wikipedia.org/wiki/Word2vec) originariamente pubblicati da [Google](https://code.google.com/archive/p/word2vec/) per codificare il testo. Word2Vec supporta solo la lingua inglese. + [`text_tfidf`](#machine-learning-tfidf-features): usa un vettorizzatore TF-IDF ([Term Frequency—Inverse Document Frequency](https://wikipedia.org/wiki/Tf-idf)) per la codifica del testo. La codifica TF-IDF supporta funzionalità statistiche non supportate da altre codifiche. ### Codifica *fastText* dei valori delle proprietà di testo in Neptune ML Neptune ML può utilizzare i modelli [fastText](https://fasttext.cc/) per convertire i valori delle proprietà di testo in vettori di valori reali a dimensione fissa. Si tratta del metodo di codifica consigliato per i valori delle proprietà di testo in una delle cinque lingue supportate da fastText: + `en`   (inglese) + `zh`   (cinese) + `hi`   (hindi) + `es`   (spagnolo) + `fr`   (francese) Tieni presente che fastText non può gestire frasi contenenti parole in più di una lingua. Il metodo `text_fasttext` può facoltativamente usare un campo `max_length` che specifica il numero massimo di token nel valore di una proprietà di testo che verrà codificato, dopodiché la stringa viene troncata. In questo modo è possibile migliorare le prestazioni quando i valori delle proprietà di testo contengono stringhe lunghe, perché se non si specifica `max_length`, fastText codifica tutti i token indipendentemente dalla lunghezza della stringa. Questo esempio specifica che i titoli dei film in francese sono codificati utilizzando fastText: ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_fasttext"], "language": "fr", "max_length": 1024 } ] } ``` ### Codifica Sentence BERT (SBERT) delle funzionalità di testo in Neptune ML Neptune ML può convertire la sequenza di token in un valore della proprietà stringa in un vettore di valori reali a dimensione fissa utilizzando i modelli [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT). Neptune supporta due metodi SBERT: `text_sbert128`, che è il metodo predefinito se si specifica solo `text_sbert` e `text_sbert512`. La differenza tra i due sta nella lunghezza massima di una stringa di valori della proprietà di testo codificata. La codifica `text_sbert128` tronca le stringhe di testo dopo aver codificato 128 token, mentre `text_sbert512` tronca le stringhe di testo dopo aver codificato 512 token. Di conseguenza, l'utilizzo di `text_sbert512` richiede tempi di elaborazione superiori rispetto a `text_sbert128`. Entrambi i metodi sono più lenti di `text_fasttext`. La codifica SBERT è multilingue, quindi non è necessario specificare una lingua per il testo del valore della proprietà da codificare. SBERT supporta molte lingue e può codificare una frase che contiene più di una lingua. Se si codificano valori di proprietà contenenti testo in una o più lingue non supportate da fastText, SBERT è il metodo di codifica consigliato. L'esempio seguente specifica che i titoli dei film sono codificati come SBERT fino a un massimo di 128 token: ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_sbert128"] } ] } ``` ### Codifica Word2Vec delle funzionalità di testo in Neptune ML Neptune ML può codificare i valori delle proprietà stringa come funzionalità Word2Vec ([gli algoritmi Word2Vec](https://wikipedia.org/wiki/Word2vec) sono stati inizialmente pubblicati da [Google](https://code.google.com/archive/p/word2vec/)). Il metodo `text_word2vec` codifica i token in una stringa come vettore dense utilizzando uno dei [modelli addestrati da spaCy](https://spacy.io/models). Supporta solo la lingua inglese utilizzando il modello [en\$1core\$1web\$1lg](https://spacy.io/models/en#en_core_web_lg). L'esempio seguente specifica che i titoli dei film sono codificati con Word2Vec: ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_word2vec"], "language": "en_core_web_lg" } ] } ``` Nota che il campo della lingua è facoltativo, poiché il modello `en_core_web_lg` in lingua inglese è l'unico supportato da Neptune. ### Codifica TF-IDF delle funzionalità di testo in Neptune ML Neptune ML può codificare i valori delle proprietà di testo come funzionalità `text_tfidf`. Questa codifica converte la sequenza di parole nel testo in un vettore numerico utilizzando un vettorizzatore TF-IDF ([Term Frequency—Inverse Document Frequency](https://wikipedia.org/wiki/Tf-idf)), seguito da un'operazione di riduzione della dimensionalità. [TF-IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf) (Term Frequency—Inverse Document Frequency) è un valore numerico destinato a misurare l'importanza di una parola in un set di documenti. Viene calcolato dividendo il numero di volte in cui una parola compare in un determinato valore delle proprietà per il numero totale di tali valori delle proprietà in cui compare. Ad esempio, se la parola "kiss" compare due volte nel titolo di un determinato film (ad esempio, "kiss kiss bang bang") e "kiss" compare nel titolo di 4 film in tutto, allora il valore TF-IDF di "kiss" nel titolo "kiss kiss bang bang" sarà ` 2 / 4 `. Il vettore creato inizialmente ha ***d*** dimensioni, dove ***d*** è il numero di termini univoci in tutti i valori delle proprietà di quel tipo. L'operazione di riduzione della dimensionalità utilizza una proiezione sparse casuale per ridurre tale numero a un massimo di 100. Viene quindi generato il vocabolario di un grafo unendo tutte le funzionalità `text_tfidf` al suo interno. È possibile controllare il vettorizzatore TF-IDF in diversi modi: + **`max_features`**: usando il parametro `max_features` è possibile limitare il numero di termini nelle funzionalità `text_tfidf` a quelli più comuni. Ad esempio, se si imposta `max_features` su 100, vengono inclusi solo i primi 100 termini più utilizzati. Il valore predefinito per `max_features`, se non viene impostato esplicitamente, è 5.000. + **`min_df`**: usando il parametro `min_df` è possibile limitare il numero di termini nelle funzionalità `text_tfidf` a quelli con almeno una frequenza nel documento specificata. Se ad esempio si imposta `min_df` su 5, vengono utilizzati solo i termini che compaiono in almeno 5 valori delle proprietà diversi. Il valore predefinito per `min_df`, se non viene impostato esplicitamente, è 2. + **`ngram_range`**: il parametro `ngram_range` determina quali combinazioni di parole vengono trattate come termini. Se ad esempio si imposta `ngram_range` su `[2, 4]`, nel titolo "kiss kiss bang bang" verranno trovati i 6 termini seguenti: + *Termini di 2 parole*: "kiss kiss", "kiss bang" e "bang bang". + *Termini di 3 parole*: "kiss kiss bang" e "kiss bang bang". + *Termini di 4 parole*: "kiss kiss bang bang". L'impostazione predefinita per `ngram_range` è `[1, 1]`. ## Funzionalità datetime in Neptune ML Neptune ML può convertire parti dei valori della proprietà `datetime` in funzionalità categoriali codificandole come [array one-hot](https://en.wikipedia.org/wiki/One-hot). Usa il parametro `datetime_parts` per specificare una o più delle seguenti parti da codificare: `["year", "month", "weekday", "hour"]`. Se non imposti `datetime_parts`, per impostazione predefinita vengono codificate tutte e quattro le parti. Ad esempio, se l'intervallo di valori datetime comprende gli anni dal 2010 al 2012, le quattro parti della voce datetime `2011-04-22 01:16:34` sono le seguenti: + **year**: `[0, 1, 0]`. Poiché l'intervallo comprende solo 3 anni (2010, 2011 e 2012), l'array one-hot contiene tre voci, una per ogni anno. + **month**: `[0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0]`. Qui, l'array one-hot ha una voce per ogni mese dell'anno. + **weekday**: `[0, 0, 0, 0, 1, 0, 0]`. Lo standard ISO 8601 dichiara che il lunedì è il primo giorno della settimana e, poiché il 22 aprile 2011 era un venerdì, il valore one-hot del giorno della settimana nell'array si trova in quinta posizione. + **hour**: `[0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]`. L'ora è impostata sulla 1:00 in un array one-hot a 24 membri. Il giorno del mese, il minuto e il secondo non sono codificati in modo categoriale. Se l'intervallo `datetime` totale in questione include solo date comprese in un singolo anno, non viene codificato alcun array `year`. È possibile specificare una strategia di imputazione per inserire i valori `datetime` mancanti, utilizzando il parametro `imputer` e una delle strategie disponibili per le funzionalità numeriche. ## Codifica delle funzionalità auto in Neptune ML Anziché specificare manualmente i metodi di codifica delle funzionalità da utilizzare per le proprietà del grafo, puoi impostare `auto` come metodo di codifica delle funzionalità. Neptune ML tenta quindi di dedurre la migliore codifica delle funzionalità per ogni proprietà in base al tipo di dati sottostante. Ecco alcune delle euristiche utilizzate da Neptune ML per selezionare le codifiche di funzionalità appropriate: + Se la proprietà ha solo valori numerici e può essere convertita in tipi di dati numerici, Neptune ML generalmente la codifica come valore numerico. Tuttavia, se il numero di valori univoci per la proprietà è inferiore al 10% del numero totale di valori e la cardinalità di tali valori univoci è inferiore a 100, Neptune ML utilizza una codifica categoriale. + Se i valori delle proprietà possono essere convertiti in un tipo `datetime`, Neptune ML li codifica come funzionalità `datetime`. + Se i valori delle proprietà possono essere impostati su valori booleani (1/0 o True/False), Neptune ML utilizza la codifica delle categorie. + Se la proprietà è una stringa con valori univoci per più del 10% e numero medio di token per valore maggiore o uguale a 3, Neptune ML deduce che il tipo di proprietà è testo e rileva automaticamente la lingua utilizzata. Se la lingua rilevata è una di quelle supportate da [fastText](#machine-learning-fasttext-features), ovvero inglese, cinese, hindi, spagnolo e francese, Neptune ML utilizza `text_fasttext` per codificare il testo. Altrimenti, Neptune ML utilizza [`text_sbert`](#machine-learning-sbert-features) + Se la proprietà è una stringa non classificata come funzionalità di testo, Neptune ML presume che sia una funzionalità categoriale e utilizza la codifica delle categorie. + Se ogni nodo ha il proprio valore unico per una proprietà che viene dedotta come una funzionalità di categoria, Neptune ML elimina la proprietà dal grafo di addestramento perché probabilmente si tratta di un ID non informativo per l'apprendimento. + Se è noto che la proprietà contiene separatori di Neptune validi come punto e virgola (";"), Neptune ML può trattare la proprietà solo come `MultiNumerical` o `MultiCategorical`. + Neptune ML tenta innanzitutto di codificare i valori come funzionalità numerica. Se ha esito positivo, Neptune ML utilizza la codifica numerica per creare funzionalità vettoriali numeriche. + In caso contrario, Neptune ML codifica i valori come multi-categoriali. + Se Neptune ML non è in grado di dedurre il tipo di dati dei valori di una proprietà, MLdrops Neptune è la proprietà dal grafico di addestramento. # Modifica di un file di configurazione dei dati di addestramento Il processo di esportazione Neptune esporta i dati Neptune ML da un cluster Neptune DB in un bucket S3. Esporta nodi e archi separatamente in una cartella `nodes/` e in una cartella `edges/`. Crea inoltre un file di configurazione dei dati di addestramento JSON, denominato `training-data-configuration.json` per impostazione predefinita. Questo file contiene informazioni sullo schema del grafo, sui tipi delle relative funzionalità, sulle operazioni di trasformazione e normalizzazione delle funzionalità e sulla funzionalità di destinazione per un'attività di classificazione o regressione. In alcuni casi, potrebbe essere necessario modificare direttamente il file di configurazione. Uno di questi casi si verifica quando si vuole cambiare il modo in cui le funzionalità vengono elaborate o il modo in cui viene costruito il grafo, senza dover eseguire nuovamente l'esportazione ogni volta che si desidera modificare le specifiche per l'attività di machine learning da risolvere. **Modifica di un file di configurazione dei dati di addestramento** 1. **Scaricare il file nel computer locale.** A meno che non siano stati specificati uno o più processi denominati nel parametro `additionalParams/neptune_ml` passato al processo di esportazione, il file avrà il nome predefinito, ovvero `training-data-configuration.json`. Puoi usare un comando AWS CLI come questo per scaricare il file: ``` aws s3 cp \ s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json \ ./ ``` 1. **Modifica il file tramite un editor di testo.** 1. **Carica il file modificato.** Carica nuovamente il file modificato nella stessa posizione in Amazon S3 da cui lo hai scaricato, utilizzando un comando AWS CLI come questo: ``` aws s3 cp \ training-data-configuration.json \ s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json ``` # Esempio di file di configurazione dei dati di addestramento JSON Ecco un file di configurazione dei dati di addestramento di esempio che descrive un grafo per un'attività di classificazione dei nodi: ``` { "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" : [ ] ] } ``` # Struttura dei file di configurazione dei dati di addestramento JSON Il file di configurazione di addestramento fa riferimento ai file CSV salvati dal processo di esportazione nelle cartelle `nodes/` e `edges/`. In ogni file in `nodes/` sono archiviate informazioni sui nodi che hanno la stessa etichetta del nodo del grafo delle proprietà. Ogni colonna in un file dei nodi archivia l'ID del nodo o la proprietà del nodo. La prima riga del file contiene un'intestazione che specifica l'`~id` o il nome della proprietà per ogni colonna. In ogni file in `edges/` sono archiviate informazioni sui nodi che hanno la stessa etichetta dell'arco del grafo delle proprietà. Ogni colonna in un file dei nodi archivia l'ID del nodo di origine, l'ID del nodo di destinazione o la proprietà dell'arco. La prima riga del file contiene un'intestazione che specifica `~from`, `~to` o il nome della proprietà per ogni colonna. Il file di configurazione dei dati di addestramento contiene tre elementi di primo livello: ``` { "version" : "v2.0", "query_engine" : "gremlin", "graph" : [ ... ] } ``` + `version` (stringa): versione del file di configurazione utilizzata. + `query_engine` (stringa): il linguaggio di query utilizzato per esportare i dati del grafo. Attualmente è valido solo il linguaggio "gremlin". + `graph` (array JSON): elenca uno o più oggetti di configurazione che contengono i parametri del modello per ciascuno dei nodi e degli archi che verranno utilizzati. Gli oggetti di configurazione nell'array del grafo hanno la struttura descritta nella sezione successiva. ## Contenuto di un oggetto di configurazione elencato nell'array `graph` Un oggetto di configurazione nell'array `graph` può contenere tre nodi di primo livello: ``` { "edges" : [ ... ], "nodes" : [ ... ], "warnings" : [ ... ], } ``` + `edges` (array di oggetti JSON): ogni oggetto JSON specifica un set di parametri per definire come verrà trattato un arco del grafo durante l'elaborazione e l'addestramento del modello. Viene utilizzato solo con il motore Gremlin. + `nodes` (array di oggetti JSON): ogni oggetto JSON specifica un set di parametri per definire come verrà trattato un nodo del grafo durante l'elaborazione e l'addestramento del modello. Viene utilizzato solo con il motore Gremlin. + `warnings` (array di oggetti JSON): ogni oggetto contiene un avviso generato durante il processo di esportazione dei dati. ## Contenuto di un oggetto di configurazione arco elencato nell'array `edges` Un oggetto di configurazione arco elencato in un array `edges` può contenere i seguenti campi di primo livello: ``` { "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`**: stringa che specifica il percorso di un file CSV in cui sono archiviate le informazioni sugli archi con la stessa etichetta del grafo delle proprietà. La prima riga del file contiene una riga di intestazione con le etichette di colonna. Le prime due etichette di colonna sono `~from` e `~to`. Nella prima colonna (colonna `~from`) è archiviato l'ID del nodo iniziale dell'arco e nella seconda (colonna `~to`) è archiviato l'ID del nodo finale dell'arco. Le etichette delle colonne rimanenti nella riga di intestazione specificano, per ogni colonna rimanente, il nome della proprietà dell'arco i cui valori sono stati esportati in quella colonna. + **`separator`**: stringa contenente il delimitatore che separa le colonne nel file CSV. + **`source`**: array JSON contenente due stringhe che specificano il nodo iniziale dell'arco. La prima stringa contiene il nome dell'intestazione della colonna in cui è archiviato l'ID del nodo iniziale. La seconda stringa specifica il tipo di nodo. + **`relation`**: array JSON contenente due stringhe che specificano il tipo di relazione dell'arco. La prima stringa contiene il nome dell'intestazione della colonna in cui è archiviato il nome della relazione (`relname`). La seconda stringa contiene il prefisso per il nome della relazione (`prefixname`). Il tipo di relazione completo è costituito dalle due stringhe combinate con un trattino, in questo modo: `prefixname-relname`. Se la prima stringa è vuota, tutti gli archi hanno lo stesso tipo di relazione, ovvero la stringa `prefixname`. + **`dest`**: array JSON contenente due stringhe che specificano il nodo finale dell'arco. La prima stringa contiene il nome dell'intestazione della colonna in cui è archiviato l'ID del nodo finale. La seconda stringa specifica il tipo di nodo. + **`features`**: array JSON di oggetti funzionalità del valore della proprietà. Ogni oggetto funzionalità del valore della proprietà include i seguenti campi: + **feature**: array JSON di tre stringhe. La prima stringa contiene il nome dell'intestazione della colonna contenente il valore della proprietà. La seconda stringa contiene il nome della funzionalità. La terza stringa contiene il tipo di funzionalità. + **norm** (*facoltativo*): specifica un metodo di normalizzazione da applicare ai valori delle proprietà. + **`labels`**: array di oggetti JSON. Ogni oggetto definisce una funzionalità di destinazione degli archi e specifica le proporzioni degli archi che le fasi di addestramento e convalida devono accettare. Ogni oggetto include i seguenti campi: + **label**: array JSON di due stringhe. La prima stringa contiene il nome dell'intestazione della colonna contenente il valore della proprietà della funzionalità di destinazione. La seconda stringa specifica uno dei seguenti tipi di attività di destinazione: + `"classification"`: attività di classificazione degli archi. I valori delle proprietà forniti nella colonna identificata dalla prima stringa nell'array `label` vengono trattati come valori categoriali. Per un'attività di classificazione degli archi, la prima stringa nell'array `label` non può essere vuota. + `"regression"`: attività di regressione degli archi. I valori delle proprietà forniti nella colonna identificata dalla prima stringa nell'array `label` vengono trattati come valori numerici. Per un'attività di regressione degli archi, la prima stringa nell'array `label` non può essere vuota. + `"link_prediction"`: attività di previsione dei collegamenti. Non sono richiesti valori delle proprietà. Per un'attività di previsione dei collegamenti, la prima stringa nell'array `label` viene ignorata. + **`split_rate`**: array JSON contenente tre numeri compresi tra zero e uno che si sommano a uno e che rappresentano una stima delle proporzioni dei nodi che verranno utilizzati rispettivamente nelle fasi di addestramento, convalida e test. È possibile definire questo campo o `custom_split_filenames`, ma non entrambi. Vedi [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate). + **`custom_split_filenames`**: oggetto JSON che specifica i nomi dei file che definiscono le popolazioni di addestramento, convalida e test. È possibile definire questo campo o `split_rate`, ma non entrambi. Per ulteriori informazioni, consulta [train-validation-testproporzioni personalizzate](#machine-learning-custom-stages-splits). ## Contenuto di un oggetto di configurazione nodo elencato in un array `nodes` Un oggetto di configurazione nodo elencato in un array `nodes` può contenere i seguenti campi: ``` { "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`**: stringa che specifica il percorso di un file CSV in cui sono archiviate le informazioni sui nodi con la stessa etichetta del grafo delle proprietà. La prima riga del file contiene una riga di intestazione con le etichette di colonna. L'etichetta della prima colonna è `~id` e nella prima colonna (colonna `~id`) è archiviato l'ID del nodo. Le etichette delle colonne rimanenti nella riga di intestazione specificano, per ogni colonna rimanente, il nome della proprietà del nodo i cui valori sono stati esportati in quella colonna. + **`separator`**: stringa contenente il delimitatore che separa le colonne nel file CSV. + **`node`**: array JSON contenente due stringhe. La prima stringa contiene il nome dell'intestazione della colonna che memorizza il nodo. IDs La seconda stringa specifica il tipo di nodo nel grafo, che corrisponde a un'etichetta del grafo delle proprietà del nodo. + **`features`**: array JSON di oggetti funzionalità del nodo. Per informazioni, consulta [Contenuto di un oggetto feature elencato in un array `features` per un nodo o un arco](#machine-learning-graph-node-features-config). + **`labels`**: array JSON di oggetti etichetta del nodo. Per informazioni, consulta [Contenuto di un oggetto label elencato in un array `labels` del nodo](#machine-learning-graph-node-labels-config). ## Contenuto di un oggetto feature elencato in un array `features` per un nodo o un arco Un oggetto feature del nodo elencato in un array `features` può contenere i seguenti campi di primo livello: + **`feature`**: array JSON di tre stringhe. La prima stringa contiene il nome dell'intestazione della colonna contenente il valore della proprietà della funzionalità. La seconda stringa contiene il nome della funzionalità. La terza stringa contiene il tipo di funzionalità. I tipi di funzionalità validi sono elencati in [Valori possibili del campo di tipo per le funzionalità](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-feature-types). + **`norm`**: campo obbligatorio per le funzioni numeriche. Specifica un metodo di normalizzazione da utilizzare sui valori numerici. I valori validi sono `"none"`, `"min-max"` e "standard". Per informazioni dettagliate, vedi [Il campo della norma](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-norm). + **`language`**: il campo della lingua specifica la lingua utilizzata nei valori delle proprietà del testo. Il suo utilizzo dipende dal metodo di codifica del testo: + Per la codifica [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) questo campo è obbligatorio e deve specificare una delle seguenti lingue: + `en`   (inglese) + `zh`   (cinese) + `hi`   (hindi) + `es`   (spagnolo) + `fr`   (francese) Tuttavia, `text_fasttext` non può gestire più di una lingua alla volta. + Per la codifica [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) questo campo non viene utilizzato, poiché la codifica SBERT è multilingue. + Per la codifica [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) questo campo è facoltativo, poiché `text_word2vec` supporta solo la lingua inglese. Se presente, deve specificare il nome del modello linguistico inglese: ``` "language" : "en_core_web_lg" ``` + Per la codifica [`tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) questo campo non viene utilizzato. + **`max_length`**: questo campo è facoltativo per le funzionalità [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features), in quanto specifica il numero massimo di token in una funzionalità di testo di input che verranno codificati. Il testo immesso una volta raggiunto il valore `max_length` viene ignorato. Ad esempio, l'impostazione di max\$1length su 128 indica che tutti i token successivi al 128° in una sequenza di testo verranno ignorati. + **`separator`**: questo campo viene utilizzato facoltativamente con le funzionalità `category`, `numerical` e `auto`. Specifica un carattere che può essere utilizzato per suddividere il valore di una proprietà in più valori categoriali o valori numerici. Per informazioni, consulta [Il campo separatore](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-separator). + **`range`**: questo campo è obbligatorio per le funzionalità `bucket_numerical`. Specifica l'intervallo di valori numerici che devono essere suddivisi in bucket. Per informazioni, consulta [Il campo dell'intervallo](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-range). + **`bucket_cnt`**: questo campo è obbligatorio per le funzionalità `bucket_numerical`. Specifica il numero di bucket in cui deve essere suddiviso l'intervallo numerico definito dal parametro `range`. Per informazioni, consulta [Funzionalità numeriche per bucket in Neptune ML](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features). + **`slide_window_size`**: questo campo viene usato facoltativamente con le funzionalità `bucket_numerical` per assegnare valori a più di un bucket: Per informazioni, consulta [Il campo slide\$1window\$1size](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-slide_window_size). + **`imputer`**: questo campo viene utilizzato facoltativamente con le funzionalità `numerical`, `bucket_numerical` e `datetime` per fornire una tecnica di imputazione per inserire i valori mancanti. Le tecniche di imputazione supportate sono `"mean"`, `"median"` e `"most_frequent"`. Per informazioni, consulta [Il campo dell'imputer](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-imputer). + **`max_features`**: questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare il numero massimo di termini da codificare. Per informazioni, consulta [Il campo max\$1features](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-max_features). + **`min_df`**: questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare la frequenza minima nel documento dei termini da codificare. Per informazioni, consulta [Il campo min\$1df](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-min_df). + **`ngram_range`**: questo campo viene utilizzato facoltativamente dalle funzionalità `text_tfidf` per specificare le dimensioni delle sequenze di parole o token da considerare come potenziali termini individuali da codificare. Per informazioni, consulta [Il campo ngram\$1range](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-ngram_range). + **`datetime_parts`**: questo campo viene utilizzato facoltativamente dalle funzionalità `datetime` per specificare quali parti del valore datetime codificare in modo categoriale. Per informazioni, consulta [Il campo datetime\$1parts](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-datetime_parts). ## Contenuto di un oggetto label elencato in un array `labels` del nodo Un oggetto label elencato in un array `labels` del nodo definisce una funzionalità di destinazione del nodo e specifica le proporzioni dei nodi che verranno utilizzate nelle fasi di addestramento, convalida e test. Ogni oggetto può contenere i seguenti campi: ``` { "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`**: array JSON contenente due stringhe. La prima stringa contiene il nome dell'intestazione della colonna in cui sono archiviati i valori delle proprietà per la funzionalità. La seconda stringa specifica il tipo di attività di destinazione, che può essere: + `"classification"`: attività di classificazione dei nodi. I valori delle proprietà nella colonna specificata vengono utilizzati per creare una funzionalità categoriale. + `"regression"`: attività di regressione dei nodi. I valori delle proprietà nella colonna specificata vengono utilizzati per creare una funzionalità numerica. + **`split_rate`**: array JSON contenente tre numeri compresi tra zero e uno che si sommano a uno e che rappresentano una stima delle proporzioni dei nodi che verranno utilizzati rispettivamente nelle fasi di addestramento, convalida e test. Per informazioni, consulta [split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate). + **`custom_split_filenames`**: oggetto JSON che specifica i nomi dei file che definiscono le popolazioni di addestramento, convalida e test. È possibile definire questo campo o `split_rate`, ma non entrambi. Per ulteriori informazioni, consulta [train-validation-testproporzioni personalizzate](#machine-learning-custom-stages-splits). + **`separator`**: stringa contenente il delimitatore che separa i valori delle funzionalità categoriali per un'attività di classificazione. **Nota** Se non viene specificato alcun oggetto etichetta sia per gli archi che per i nodi, si presume automaticamente che si tratti di un'attività di previsione dei collegamenti e gli archi vengono divisi casualmente in 90% per l'addestramento e 10% per la convalida. ## train-validation-testproporzioni personalizzate Per impostazione predefinita, Neptune ML utilizza il parametro `split_rate` per dividere il grafo in modo casuale in popolazioni di addestramento, convalida e test utilizzando le proporzioni definite in questo parametro. Per avere un controllo più preciso sulle entità utilizzate in queste diverse popolazioni, è possibile creare file che le definiscono in modo esplicito, quindi [modificare il file di configurazione dei dati di addestramento](machine-learning-processing-training-config-file.md) per mappare questi file di indicizzazione alle popolazioni. Questa mappatura è specificata da un oggetto JSON per la chiave [`custom_split_filesnames`](#custom_split_filenames) nel file di configurazione dell'addestramento. Se viene utilizzata questa opzione, è obbligatorio specificare il nome del file per le chiavi `train` e `validation`, mentre è facoltativo per la chiave `test`. La formattazione di questi file deve corrispondere al [formato dei dati Gremlin](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-systemheaders). In particolare, per le attività a livello di nodo, ogni file deve contenere una colonna con l'`~id`intestazione che elenca il nodo IDs e per le attività a livello di bordo, i file devono specificare `~from` e indicare rispettivamente i nodi `~to` di origine e di destinazione dei bordi. Questi file devono essere collocati nella stessa posizione Amazon S3 dei dati esportati utilizzati per l'elaborazione dei dati (consulta: [`outputS3Path`](export-parameters.md#export-parameters-outputS3Path)). Per le attività di classificazione o regressione delle proprietà, questi file possono facoltativamente definire le etichette per l'attività di machine learning. In tal caso, i file devono avere una colonna delle proprietà con lo stesso nome di intestazione [definito nel file di configurazione dei dati di addestramento](#machine-learning-graph-node-labels-config). Se le etichette delle proprietà sono definite sia nei file dei nodi e degli archi esportati che nei file di divisione personalizzata, i file di divisione personalizzata avranno la priorità. # Addestramento di un modello con Neptune ML. Dopo aver esportato da Neptune i dati da utilizzare per l'addestramento dei modelli, puoi avviare un processo di elaborazione dei dati utilizzando un comando `curl` (o `awscurl`) come il seguente: ``` 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" }' ``` I dettagli su come utilizzare questo comando sono illustrati in [Comando modeltraining](machine-learning-api-modeltraining.md), insieme a informazioni su come recuperare lo stato di un processo in esecuzione, come arrestare un processo in esecuzione e come elencare tutti i processi in esecuzione. È inoltre possibile fornire un `previousModelTrainingJobId` per usare le informazioni provenienti dal processo di addestramento di un modello Neptune ML completato per accelerare la ricerca degli iperparametri in un nuovo processo di addestramento. Questo è utile durante il [riaddestramento del modello su nuovi dati del grafo](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-model-retraining), nonché per l'[addestramento incrementale sugli stessi dati del grafo](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental). Usa un comando come questo: ``` 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)" }' ``` Puoi addestrare l'implementazione di un modello personalizzato sull'infrastruttura di addestramento di Neptune ML specificando un oggetto `customModelTrainingParameters`, in questo modo: ``` 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)" } }' ``` Per ulteriori informazioni, ad esempio su come recuperare lo stato di un processo in esecuzione, su come arrestare un processo in esecuzione e su come elencare tutti i lavori in esecuzione, consulta [Comando modeltraining](machine-learning-api-modeltraining.md). Per ulteriori informazioni su come implementare e usare un modello personalizzato, consulta [Modelli personalizzati in Neptune ML.](machine-learning-custom-models.md). **Topics** + [Modelli e addestramento dei modelli in Amazon Neptune ML](machine-learning-models-and-training.md) + [Personalizzazione delle configurazioni degli iperparametri dei modelli in Neptune ML](machine-learning-customizing-hyperparams.md) + [Best practice per l'addestramento dei modelli](machine-learning-improve-model-performance.md) # Modelli e addestramento dei modelli in Amazon Neptune ML Neptune ML utilizza reti neurali a grafo (GNN) per creare modelli per le varie attività di machine learning. È stato dimostrato che le reti neurali grafiche ottengono state-of-the-art risultati per le attività di apprendimento automatico dei grafi e sono eccellenti nell'estrarre modelli informativi da dati strutturati a grafi. ## Reti neurali grafiche (GNNs) in Neptune ML Le reti neurali a grafo (GNNs) appartengono a una famiglia di reti neurali che calcolano le rappresentazioni dei nodi tenendo conto della struttura e delle caratteristiche dei nodi vicini. GNNs integrano altri metodi tradizionali di apprendimento automatico e di rete neurale che non sono adatti per i dati grafici. GNNs vengono utilizzati per risolvere attività di apprendimento automatico come la classificazione e la regressione dei nodi (previsione delle proprietà dei nodi), la classificazione e la regressione dei bordi (previsione delle proprietà degli spigoli) o la previsione dei link (previsione della connessione o meno di due nodi del grafico). In generale, l'utilizzo di una GNN per un'attività di machine learning prevede due fasi: + Una fase di codifica, in cui la GNN calcola un vettore d-dimensionale per ogni nodo del grafo. Questi vettori sono anche chiamati *rappresentazioni* o *incorporamenti*. + Una fase di decodifica, che effettua previsioni basate sulle rappresentazioni codificate. Per la classificazione e la regressione dei nodi, le rappresentazioni dei nodi vengono utilizzate direttamente per le attività di classificazione e regressione. Per la classificazione e la regressione degli archi, le rappresentazioni dei nodi incidenti su un arco vengono utilizzate come input per la classificazione o la regressione. Per la previsione dei collegamenti, viene calcolato un punteggio di probabilità degli archi utilizzando una coppia di rappresentazioni di nodi e una rappresentazione del tipo di arco. La [Deep Graph Library (DGL)](https://www.dgl.ai/) facilita la definizione e la formazione efficienti di queste attività. GNNs Diversi modelli di GNN sono unificati sotto la formulazione del passaggio dei messaggi. Da questo punto di vista, la rappresentazione di un nodo in un grafo viene calcolata utilizzando le rappresentazioni dei vicini del nodo (i messaggi), insieme alla rappresentazione iniziale del nodo. In Neptune ML la rappresentazione iniziale di un nodo deriva dalle funzionalità estratte dalle proprietà del nodo oppure è apprendibile e dipende dall'identità del nodo. Neptune ML consente inoltre di concatenare le funzionalità dei nodi e le rappresentazioni dei nodi apprendibili per fungere da rappresentazione del nodo originale. Per le varie attività di Neptune ML che coinvolgono grafi con proprietà dei nodi, viene usata la rete [Relational Graph Convolutional Network](https://arxiv.org/abs/1703.06103) (R-GCN) per eseguire la fase di codifica. La R-GCN è un'architettura GNN adatta per i grafi con più tipi di nodi e archi (noti come grafi eterogenei). La rete R-GCN è costituita da un numero fisso di livelli, impilati uno dopo l'altro. Ogni livello della rete R-GCN utilizza i relativi parametri del modello apprendibili per aggregare informazioni dal neighborhood a 1 hop di un nodo. Poiché i livelli successivi utilizzano le rappresentazioni di output del livello precedente come input, il raggio del neighborhood del grafo che influenza l'incorporamento finale di un nodo dipende dal numero di livelli (`num-layer`) della rete R-GCN. Questo significa ad esempio che una rete a 2 livelli utilizza le informazioni provenienti da nodi che si trovano a 2 hop di distanza. Per saperne di più GNNs, consulta [A Comprehensive Survey on Graph Neural](https://arxiv.org/abs/1901.00596) Networks. Per ulteriori informazioni sulla Deep Graph Library (DGL), visita la [pagina web](https://www.dgl.ai/) di DGL. Per un tutorial pratico sull'uso di DGL con GNNs, vedi [Apprendimento delle reti neurali grafiche](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library) con Deep Graph Library. ## Addestramento delle reti neurali a grafo Nel machine learning il processo che consente a un modello di apprendere come fare previsioni valide per un'attività è denominato addestramento del modello. Questa operazione viene in genere eseguita specificando un obiettivo particolare da ottimizzare e un algoritmo da utilizzare per eseguire tale ottimizzazione. Questo processo viene impiegato anche per addestrare una rete GNN ad apprendere rappresentazioni valide anche per l'attività a valle. Per tale attività viene creata una funzione obiettivo che viene ridotta al minimo durante l'addestramento del modello. Ad esempio, per la classificazione dei nodi, utilizziamo [CrossEntropyLoss](https://pytorch.org/docs/stable/generated/torch.nn.CrossEntropyLoss.html)come obiettivo, il che penalizza le classificazioni errate, mentre per la regressione dei nodi riduciamo al minimo. [MeanSquareError](https://pytorch.org/docs/stable/generated/torch.nn.MSELoss.html) L'obiettivo è in genere una funzione di perdita che accetta le previsioni del modello per un punto dati specifico e le confronta con il valore ground-truth per tale punto dati. Restituisce il valore di perdita, che mostra quanto siano lontane le previsioni del modello. L'obiettivo del processo di addestramento è ridurre al minimo le perdite e garantire che le previsioni dei modelli siano vicine al valore ground-truth. L'algoritmo di ottimizzazione utilizzato nel deep learning per il processo di addestramento è in genere una variante della discesa del gradiente. In Neptune ML, [utilizziamo](https://arxiv.org/pdf/1412.6980.pdf) Adam, un algoritmo per l'ottimizzazione basata su gradiente del primo ordine di funzioni obiettivo stocastiche basate su stime adattive di momenti di ordine inferiore. Sebbene il processo di addestramento del modello tenti di garantire che i parametri del modello appresi siano vicini ai minimi della funzione obiettivo, le prestazioni complessive di un modello dipendono anche dagli *iperparametri* del modello, che sono impostazioni del modello che non vengono apprese dall'algoritmo di addestramento. Ad esempio, la dimensionalità della rappresentazione del nodo appresa, `num-hidden`, è un iperparametro che influisce sulle prestazioni del modello. Pertanto, nel machine learning è comune eseguire l'ottimizzazione degli iperparametri per scegliere gli iperparametri adatti. Neptune ML utilizza SageMaker un processo di ottimizzazione degli iperparametri AI per avviare più istanze di addestramento dei modelli con diverse configurazioni di iperparametri per cercare di trovare il modello migliore per una serie di impostazioni di iperparametri. Consultare [Personalizzazione delle configurazioni degli iperparametri dei modelli in Neptune ML](machine-learning-customizing-hyperparams.md). ## Modelli di incorporamento del grafo della conoscenza in Neptune ML I Knowledge graphs (KGs) sono grafici che codificano informazioni su diverse entità (nodi) e le relative relazioni (bordi). In Neptune ML i modelli di incorporamento del grafo della conoscenza vengono applicati per impostazione predefinita per eseguire la previsione dei collegamenti quando il grafo non contiene proprietà dei nodi, ma solo relazioni con altri nodi. Tuttavia, anche i modelli R-GCN con incorporamenti apprendibili possono essere utilizzati per questi grafi specificando il tipo di modello `"rgcn"`, poiché i modelli di incorporamento dei grafi della conoscenza sono più semplici e progettati per essere efficaci per l'apprendimento di rappresentazioni per grafi della conoscenza su larga scala. I modelli di incorporamento dei grafi della conoscenza vengono usati in un'attività di previsione dei collegamenti per prevedere i nodi o le relazioni che completano una tripla `(h, r, t)`, dove `h` è il nodo di origine, `r` è il tipo di relazione e `t` è il nodo di destinazione. I modelli di incorporamento del grafo della conoscenza implementati in Neptune ML sono `distmult`, `transE` e `rotatE`. Per ulteriori informazioni sui modelli di incorporamento del grafo della conoscenza, consulta [DGL-KE](https://github.com/awslabs/dgl-ke). ## Addestramento di modelli personalizzati in Neptune ML. Neptune ML consente di definire e implementare modelli personalizzati, per scenari specifici. Per informazioni su come implementare un modello personalizzato e su come utilizzare l'infrastruttura di Neptune ML per addestrarlo, consulta [Modelli personalizzati in Neptune ML.](machine-learning-custom-models.md). # Personalizzazione delle configurazioni degli iperparametri dei modelli in Neptune ML Quando si avvia un processo di addestramento dei modelli Neptune ML, Neptune ML utilizza automaticamente le informazioni dedotte dal precedente processo di [elaborazione dei dati](machine-learning-on-graphs-processing.md). Utilizza le informazioni per generare intervalli di configurazione iperparametrici che vengono utilizzati per creare un [processo di ottimizzazione degli iperparametri SageMaker AI per addestrare](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-how-it-works.html) più modelli per l'attività. In questo modo, non è necessario specificare un lungo elenco di valori di iperparametri da usare per l'addestramento dei modelli. Gli intervalli e i valori predefiniti degli iperparametri del modello vengono invece selezionati in base al tipo di attività, al tipo di grafo e alle impostazioni del processo di ottimizzazione. Tuttavia, è anche possibile ignorare la configurazione degli iperparametri predefinita e specificare iperparametri personalizzati modificando un file di configurazione JSON generato dal processo di elaborazione dei dati. Utilizzando l'API [modelTraining](machine-learning-api-modeltraining.md) di Neptune ML, puoi controllare diverse impostazioni generali degli iperparametri del processo di ottimizzazione, come `maxHPONumberOfTrainingJobs`, `maxHPOParallelTrainingJobs` e `trainingInstanceType`. Per un controllo più granulare sugli iperparametri del modello, è possibile personalizzare il file `model-HPO-configuration.json` generato dal processo di elaborazione dei dati. Il file viene salvato nella posizione Amazon S3 specificata per l'output del processo di elaborazione. Puoi scaricare il file, modificarlo per sovrascrivere le configurazioni degli iperparametri predefinite e caricarlo nuovamente nella stessa posizione Amazon S3. Non modificare il nome del file e presta attenzione a seguire queste istruzioni durante la modifica. Per scaricare il file da S3 ``` aws s3 cp \ s3://(bucket name)/(path to output folder)/model-HPO-configuration.json \ ./ ``` Al termine della modifica, carica nuovamente il file nella posizione originale: ``` aws s3 cp \ model-HPO-configuration.json \ s3://(bucket name)/(path to output folder)/model-HPO-configuration.json ``` ## Struttura del file `model-HPO-configuration.json` Il file `model-HPO-configuration.json` specifica il modello da addestrare, il tipo di attività `task_type` di machine learning e gli iperparametri che devono essere variati o fissi per le varie esecuzioni di addestramento del modello. Gli iperparametri sono classificati come appartenenti a vari livelli che indicano la precedenza assegnata agli iperparametri quando viene richiamato il processo di ottimizzazione degli iperparametri: + Gli iperparametri di livello 1 hanno la precedenza più alta. Se imposti `maxHPONumberOfTrainingJobs` su un valore minore di 10, vengono ottimizzati solo gli iperparametri di livello 1 e gli altri assumono i valori predefiniti. + Gli iperparametri di livello 2 hanno una precedenza inferiore, quindi se sono presenti più di 10 ma meno di 50 processi di addestramento totali per un processo di ottimizzazione, vengono ottimizzati sia gli iperparametri di livello 1 che di livello 2. + Gli iperparametri di livello 3 vengono ottimizzati insieme a quelli di livello 1 e 2 solo se sono presenti più di 50 processi di addestramento totali. + Infine, gli iperparametri fissi non vengono mai ottimizzati e assumono sempre i valori predefiniti. ### Esempio di file `model-HPO-configuration.json` Di seguito è riportato un file `model-HPO-configuration.json` di esempio. ``` { "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 } ] } ] } ``` ### Elementi di un file `model-HPO-configuration.json` Il file contiene un oggetto JSON con un singolo array di primo livello denominato `models` che contiene un singolo oggetto configurazione del modello. Quando personalizzi il file, assicurati che l'array `models` contenga solo un oggetto configurazione del modello. Se il file contiene più di un oggetto configurazione del modello, il processo di ottimizzazione avrà esito negativo e verrà visualizzato un avviso. L'oggetto configurazione del modello contiene i seguenti elementi di primo livello: + **`model`** (*stringa*): tipo di modello da addestrare (**da non modificare**). I valori validi sono: + `"rgcn"`: impostazione predefinita per le attività di classificazione e regressione dei nodi e per le attività di previsione dei collegamenti eterogenee. + `"transe"`: impostazione predefinita per le attività di previsione dei collegamenti di incorporamento del grafo della conoscenza. + `"distmult"`: tipo di modello alternativo per le attività di previsione dei collegamenti di incorporamento del grafo della conoscenza. + `"rotate"`: tipo di modello alternativo per le attività di previsione dei collegamenti di incorporamento del grafo della conoscenza. In generale, è consigliabile non modificare direttamente il valore `model`, in quanto diversi tipi di modello hanno spesso iperparametri applicabili sostanzialmente diversi e ciò può causare un errore di analisi dopo l'avvio del processo di addestramento. Per modificare il tipo di modello, usa il parametro `modelName` nell'[API modelTraining](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job) anziché modificarlo nel file `model-HPO-configuration.json`. Un modo per modificare il tipo di modello e apportare modifiche granulari agli iperparametri consiste nel copiare il modello di configurazione del modello predefinito per il modello da usare e incollarlo nel file `model-HPO-configuration.json`. Esiste una cartella denominata `hpo-configuration-templates` nella stessa posizione Amazon S3 del file `model-HPO-configuration.json` se il tipo di attività dedotto supporta più modelli. Questa cartella contiene tutte le configurazioni di iperparametri predefinite per gli altri modelli applicabili all'attività. Ad esempio, per modificare le configurazioni del modello e degli iperparametri per un'attività di previsione dei collegamenti `KGE` dal modello predefinito `transe` a un modello `distmult`, è sufficiente incollare il contenuto del file `hpo-configuration-templates/distmult.json` nel file `model-HPO-configuration.json` e quindi modificare gli iperparametri in base alle esigenze. **Nota** Se imposti il parametro `modelName` nell'API `modelTraining` e modifichi il `model` e la specifica degli iperparametri nel file `model-HPO-configuration.json` e questi sono diversi, il valore `model` nel file `model-HPO-configuration.json` ha la precedenza e il valore `modelName` viene ignorato. + **`task_type`** (*stringa*): tipo di attività di machine learning dedotto o passato direttamente al processo di elaborazione dei dati (**da non modificare**). I valori validi sono: + `"node_class"` + `"node_regression"` + `"link_prediction"` Il processo di elaborazione dei dati deduce il tipo di attività esaminando il set di dati esportato e il file di configurazione del processo di apprendimento generato per verificare le proprietà del set di dati. Questo valore non deve essere modificato. Se si desidera addestrare un'attività diversa, è necessario [eseguire un nuovo processo di elaborazione dei dati](machine-learning-on-graphs-processing.md). Se il valore `task_type` non è quello previsto, è consigliabile verificare gli input del processo di elaborazione dati per assicurarsi che siano corretti. Sono inclusi i parametri nell'API `modelTraining` e il file di configurazione del processo di addestramento generato dal processo di esportazione dei dati. + **`eval_metric`** (*stringa*): la metrica di valutazione deve essere utilizzata per valutare le prestazioni del modello e per selezionare il modello con le migliori prestazioni tra le esecuzioni di ottimizzazione degli iperparametri. I valori validi sono: + `"acc"`: accuratezza della classificazione standard. Si tratta dell'impostazione predefinita per le attività di classificazione a etichetta singola, a meno che non vengano rilevate etichette sbilanciate durante l'elaborazione dei dati, nel qual caso l'impostazione predefinita è `"F1"`. + `"acc_topk"`: numero di volte in cui l'etichetta corretta compare tra le prime **`k`** previsioni. Puoi anche impostare il valore **`k`** passando `topk` come chiave aggiuntiva. + `"F1"`: [punteggio F1](https://en.wikipedia.org/wiki/F-score). + `"mse"`: [metrica dell'errore quadratico medio](https://en.wikipedia.org/wiki/Mean_squared_error), per le attività di regressione. + `"mrr"`: [metrica della classificazione reciproca media.](https://en.wikipedia.org/wiki/Mean_reciprocal_rank) + `"precision"`: precisione del modello, calcolata come rapporto tra veri positivi e positivi previsti: `= true-positives / (true-positives + false-positives)`. + `"recall"`: sensibilità del modello, calcolata come rapporto tra veri positivi e positivi effettivi: `= true-positives / (true-positives + false-negatives)`. + `"roc_auc"`: area sotto la [curva ROC](https://en.wikipedia.org/wiki/Receiver_operating_characteristic). Questa è l'impostazione predefinita per la classificazione multi-etichetta. Ad esempio, per modificare la metrica in `F1`, modifica il valore `eval_metric` come indicato di seguito: ``` " eval_metric": { "metric": "F1", }, ``` In alternativa, per modificare la metrica in un punteggio di accuratezza `topk`, dovrai modificare `eval_metric` come indicato di seguito: ``` "eval_metric": { "metric": "acc_topk", "topk": 2 }, ``` + **`eval_frequency`** (*oggetto*): specifica con quale frequenza durante l'addestramento devono essere verificate le prestazioni del modello sul set di convalida. In base alle prestazioni di convalida, è quindi possibile avviare l'arresto anticipato e salvare il modello migliore. L'oggetto `eval_frequency` contiene due elementi, ovvero `"type"` e `"value"`. Esempio: ``` "eval_frequency": { "type": "evaluate_every_pct", "value": 0.1 }, ``` I valori `type` validi sono: + **`evaluate_every_pct`**: specifica la percentuale di addestramento da completare per ogni valutazione. Per `evaluate_every_pct`, il campo `"value"` contiene un numero a virgola mobile compreso tra zero e uno che esprime tale percentuale. + **`evaluate_every_batch`**: specifica il numero di batch di addestramento da completare per ogni valutazione. Per `evaluate_every_batch`, il campo `"value"` contiene un numero intero che esprime il numero di batch. + **`evaluate_every_epoch`**: specifica il numero di epoche per valutazione, dove una nuova epoca inizia a mezzanotte. Per `evaluate_every_epoch`, il campo `"value"` contiene un numero intero che esprime il numero di epoche. L'impostazione predefinita per `eval_frequency` è: ``` "eval_frequency": { "type": "evaluate_every_epoch", "value": 1 }, ``` + **`1-tier-param`** (*obbligatorio*): array di iperparametri di livello 1. Se non si desidera ottimizzare alcun iperparametro, è possibile impostare questo parametro su un array vuoto. Ciò non influisce sul numero totale di processi di formazione avviati dal processo di ottimizzazione degli SageMaker iperparametri AI. Significa solo che tutti i processi di addestramento, se ne esistono più di 1 ma meno di 10, verranno eseguiti con lo stesso set di iperparametri. D'altra parte, per trattare tutti gli iperparametri ottimizzabili con uguale importanza, puoi includere tutti gli iperparametri in questo array. + **`2-tier-param`** (*obbligatorio*): array di iperparametri di livello 2. Questi parametri vengono ottimizzati solo se il valore di `maxHPONumberOfTrainingJobs` è maggiore di 10. In caso contrario, assumono i valori predefiniti. Se disponi di un budget di addestramento di almeno 10 processi di addestramento o se non desideri iperparametri di livello 2 per altri motivi, ma desideri ottimizzare tutti gli iperparametri ottimizzabili, puoi impostare questo parametro su un array vuoto. + **`3-tier-param`** (*obbligatorio*): array di iperparametri di livello 3. Questi parametri vengono ottimizzati solo se il valore di `maxHPONumberOfTrainingJobs` è maggiore di 50. In caso contrario, assumono i valori predefiniti. Se non si desiderano iperparametri di livello 3, è possibile impostare questo parametro su un array vuoto. + **`fixed-param`** (*obbligatorio*): array di iperparametri fissi che accettano solo i relativi valori predefiniti e non variano in processi di addestramento diversi. Per variare tutti gli iperparametri, puoi impostare questo parametro su un array vuoto e impostare il valore per `maxHPONumberOfTrainingJobs` su un numero sufficientemente elevato per variare tutti i livelli o impostare tutti gli iperparametri come di livello 1. L'oggetto JSON che rappresenta ogni iperparametro in `1-tier-param`, `2-tier-param`, `3-tier-param` e `fixed-param` contiene i seguenti elementi: + **`param`** (*stringa*): nome dell'iperparametro (**da non modificare**). Vedi l'[elenco dei nomi di iperparametri validi in Neptune ML](#machine-learning-hyperparams-list). + **`type`** (*stringa*): tipo dell'iperparametro (**da non modificare**). I tipi validi sono `bool`, `int` e `float`. + **`default`** (*stringa*): valore predefinito per l'iperparametro. È possibile impostare un nuovo valore predefinito. Gli iperparametri ottimizzabili possono contenere anche i seguenti elementi: + **`range`** (*array*): intervallo per un iperparametro ottimizzabile in modo continuo. Deve essere un array con due valori, ovvero il valore minimo e il valore massimo dell'intervallo (`[min, max]`). + **`options`** (*array*): opzioni per un iperparametro categoriale ottimizzabile. Questo array deve contenere tutte le opzioni da considerare: ``` "options" : [value1, value2, ... valuen] ``` + **`inc_strategy`** (*stringa*): tipo di modifica incrementale per gli intervalli di iperparametri ottimizzabili in modo continuo (**da non modificare**). I valori validi sono `log`, `linear` e `power2`. Si applica solo quando è impostata la chiave di intervallo. La modifica di questo elemento può determinare il mancato utilizzo dell'intero intervallo dell'iperparametro per l'ottimizzazione. + **`inc_val`** (*float*): quantità in base alla differiscono gli incrementi successivi per gli iperparametri ottimizzabili in modo continuo (**da non modificare**). Si applica solo quando è impostata la chiave di intervallo. La modifica di questo elemento può determinare il mancato utilizzo dell'intero intervallo dell'iperparametro per l'ottimizzazione. + **`node_strategy`** (*stringa*): indica che l'intervallo effettivo per questo iperparametro deve cambiare in base al numero di nodi nel grafo (**da non modificare**). I valori validi sono `"perM"` (per milione), `"per10M"` (per 10 milioni) e `"per100M"` (per 100 milioni). Invece di modificare questo valore, prova a modificare `range`. + **`edge_strategy`** (*stringa*): indica che l'intervallo effettivo per questo iperparametro deve cambiare in base al numero di archi nel grafo (**da non modificare**). I valori validi sono `"perM"` (per milione), `"per10M"` (per 10 milioni) e `"per100M"` (per 100 milioni). Invece di modificare questo valore, prova a modificare `range`. ### Elenco di tutti gli iperparametri in Neptune ML L'elenco seguente contiene tutti gli iperparametri che possono essere impostati ovunque in Neptune ML, per qualsiasi tipo di modello e attività. Poiché non sono tutti applicabili a ogni tipo di modello, è importante impostare nel file `model-HPO-configuration.json` solo gli iperparametri disponibili nel modello in uso. + **`batch-size`**: dimensioni del batch dei nodi di destinazione utilizzati in un unico passaggio in avanti. *Tipo*: `int`. L'impostazione di questo elemento su un valore molto elevato può causare problemi di memoria per l'addestramento sulle istanze GPU. + **`concat-node-embed`**: indica se ottenere o meno la rappresentazione iniziale di un nodo concatenando le relative funzionalità elaborate con incorporamenti iniziali del nodo apprendibili per aumentare l'espressività del modello. *Tipo*: `bool`. + **`dropout`**: probabilità di abbandono applicata ai livelli di abbandono. *Tipo*: `float`. + **`edge-num-hidden`**: dimensioni del livello nascosto o il numero di unità per il modulo della funzionalità arco. Usato solo quando `use-edge-features` è impostato su `True`. *Tipo*: float. + **`enable-early-stop`**: attiva/disattiva l'utilizzo della funzionalità di arresto anticipato. *Tipo*: `bool`. *Default*: `true` Usa questo parametro booleano per disattivare la funzionalità di arresto anticipato. + **`fanout`**: numero di neighbor da campionare per un nodo di destinazione durante il campionamento dei neighbor. *Tipo*: `int`. Questo valore è strettamente associato a `num-layers` e deve trovarsi sempre nello stesso livello di iperparametri. Questo perché puoi specificare un fanout per ogni potenziale livello GNN. Poiché questo iperparametro può causare ampie variazioni nelle prestazioni del modello, deve essere fisso o impostato come iperparametro di livello 2 o di livello 3. L'impostazione di questo elemento su un valore elevato può causare problemi di memoria per l'addestramento sulle istanze GPU. + **`gamma`**: valore del margine nella funzione di punteggio. *Tipo*: `float`. Si applica solo ai modelli di previsione dei collegamenti `KGE`. + **`l2norm`**: valore di decadimento del peso utilizzato nell'ottimizzatore che impone una penalità di normalizzazione L2 ai pesi. *Tipo*: `bool`. + **`layer-norm`**: indica se utilizzare la normalizzazione dei livelli per i modelli `rgcn`. *Tipo*: `bool`. + **`low-mem`**: indica se utilizzare un'implementazione a bassa memoria della funzione di passaggio dei messaggi di relazione a scapito della velocità. *Tipo*: `bool`. + **`lr`**: velocità di apprendimento. *Tipo*: `float`. Deve essere impostato come un iperparametro di primo livello. + **`neg-share`**: nella previsione dei collegamenti, indica se gli archi campionati positivi possono condividere campioni di archi negativi. *Tipo*: `bool`. + **`num-bases`**: numero di basi per la scomposizione delle basi in un modello `rgcn`. L'utilizzo di un valore `num-bases` inferiore al numero di tipi di archi nel grafo funge da regolarizzatore per il modello `rgcn`. *Tipo*: `int`. + **`num-epochs`**: numero di epoche di addestramento da eseguire. *Tipo*: `int`. Un'epoca è un passaggio di addestramento completo attraverso il grafo. + **`num-hidden`**: dimensioni del livello nascosto o numero di unità. *Tipo*: `int`. Questo elemento imposta anche le dimensioni dell'incorporamento iniziale per i nodi senza funzionalità. Impostarlo su un valore molto più grande senza ridurlo `batch-size` può causare out-of-memory problemi di formazione sull'istanza GPU. + **`num-layer`**: numero di livelli GNN nel modello. *Tipo*: `int`. Questo valore è strettamente associato al parametro fanout e deve essere posizionato dopo aver impostato il fanout nello stesso livello di iperparametri. Poiché questo iperparametro può causare ampie variazioni nelle prestazioni del modello, deve essere fisso o impostato come iperparametro di livello 2 o di livello 3. + **`num-negs`**: nella previsione dei collegamenti, il numero di campioni negativi per campione positivo. *Tipo*: `int`. + **`per-feat-name-embed`**: indica se incorporare ogni funzionalità trasformandola in modo indipendente prima di combinare le funzionalità. *Tipo*: `bool`. Se questo elemento è impostato su `true`, ogni funzionalità per nodo viene trasformata in modo indipendente in in dimensioni di dimensione fissa prima che tutte le funzionalità trasformate per il nodo vengano concatenate e ulteriormente trasformate nella dimensione `num_hidden`. Se questo elemento è impostato su `false`, le funzionalità vengono concatenate senza trasformazioni specifiche delle funzionalità. + **`regularization-coef`**: nella previsione dei collegamenti, il coefficiente di perdita di regolarizzazione. *Tipo*: `float`. + **`rel-part`**: indica se utilizzare la partizione di relazione per la previsione dei collegamenti `KGE`. *Tipo*: `bool`. + **`sparse-lr`**: velocità di apprendimento per gli incorporamenti di nodi apprendibili. *Tipo*: `float`. Gli incorporamenti iniziali dei nodi apprendibili vengono utilizzati per i nodi senza funzionalità o quando è impostato il parametro `concat-node-embed`. I parametri del livello di incorporamento dei nodi apprendibili sparse vengono addestrati utilizzando un ottimizzatore separato che può avere una velocità di apprendimento distinta. + **`use-class-weight`**: indica se applicare i pesi di classe per attività di classificazione non bilanciate. Se impostato su `true`, viene usato il numero di etichette per impostare un peso per ogni etichetta di classe. *Tipo*: `bool`. + **`use-edge-features`**: indica se utilizzare le funzionalità degli archi durante il passaggio dei messaggi. Se impostato su `true`, viene aggiunto un modulo di funzionalità degli archi personalizzato al livello RGCN per i tipi di archi che dispongono di funzionalità. *Tipo*: `bool`. + **`use-self-loop`**: indica se includere i cappi nell'addestramento di un modello `rgcn`. *Tipo*: `bool`. + **`window-for-early-stop`**: controlla il numero degli ultimi punteggi di convalida in base a cui calcolare la media per decidere se effettuare un arresto anticipato. Il valore predefinito è 3. type=int. Consulta anche [Arresto anticipato del processo di addestramento dei modelli in Neptune ML](machine-learning-improve-model-performance.md#machine-learning-model-training-early-stop). *Tipo*: `int`. *Default*: `3` Per informazioni, consulta . ## Personalizzazione degli iperparametri in Neptune ML Quando si modifica il file `model-HPO-configuration.json`, i tipi di modifiche più comuni sono i seguenti: + Modifica i valori and/or massimi minimi degli `range` iperparametri. + Impostare un iperparametro su un valore fisso spostandolo nella sezione `fixed-param` e impostando il relativo valore predefinito sul valore fisso che dovrà assumere. + Modificare la priorità di un iperparametro posizionandolo in un livello specifico, modificandone l'intervallo e assicurandosi che il valore predefinito sia impostato in modo appropriato. # Best practice per l'addestramento dei modelli Esistono diverse operazioni consigliate per migliorare le prestazioni dei modelli Neptune ML. ## Scelta della proprietà del nodo corretta Non tutte le proprietà del grafo sono significative o pertinenti per le attività di machine learning. Tutte le proprietà non pertinenti devono essere escluse durante l'esportazione dei dati. Ecco alcune best practice: + Rivolgiti a esperti del settore per valutare l'importanza delle funzionalità e la fattibilità del relativo utilizzo per le previsioni. + Rimuovi le funzionalità che ritieni ridondanti o irrilevanti per ridurre il rumore nei dati e le correlazioni non importanti. + Esegui iterazioni mentre costruisci il tuo modello. Modifica le funzionalità, le combinazioni di funzionalità e gli obiettivi di ottimizzazione man mano che procedi. La sezione relativa all'[elaborazione delle funzionalità](https://docs.aws.amazon.com/machine-learning/latest/dg/feature-processing.html) in Amazon Machine Learning Developer Guide fornisce linee guida aggiuntive per l'elaborazione delle funzionalità pertinenti per Neptune ML. ## Gestione degli outlier nei punti dati Un outlier è un punto dati che è significativamente diverso dai dati rimanenti. Gli outlier nei dati possono compromettere o fuorviare il processo di addestramento causando tempi di addestramento più lunghi o modelli meno accurati. A meno che non siano veramente importanti, è consigliabile eliminare gli outlier prima di esportare i dati. ## Rimozione di nodi e archi duplicati Nei grafi archiviati in Neptune possono essere presenti nodi o archi duplicati. Questi elementi ridondanti introdurranno rumore nell'addestramento dei modelli di machine learning. Elimina i nodi o gli archi duplicati prima di esportare i dati. ## Ottimizzazione della struttura del grafo Quando il grafo viene esportato, è possibile modificare la modalità di elaborazione delle funzionalità e la modalità di creazione del grafo, per migliorare le prestazioni del modello. Ecco alcune best practice: + Quando una proprietà dell'arco ha lo stesso significato di categorie di archi, in alcuni casi vale la pena trasformarla in tipi di archi. + La policy di normalizzazione predefinita utilizzata per una proprietà numerica è `min-max`, ma in alcuni casi altre policy di normalizzazione garantiscono un risultato migliore. È possibile pre-elaborare la proprietà e modificare la policy di normalizzazione come spiegato in [Elementi di un file `model-HPO-configuration.json`](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements). + Il processo di esportazione genera automaticamente i tipi di funzionalità in base ai tipi delle proprietà. Ad esempio, tratta le proprietà `String` come funzionalità categoriali e le proprietà `Float` e `Int` come funzionalità numeriche. Se necessario, è possibile modificare il tipo di funzionalità dopo l'esportazione (consulta [Elementi di un file `model-HPO-configuration.json`](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements)). ## Ottimizzazione degli intervalli e dei valori predefiniti degli iperparametri L'operazione di elaborazione dei dati deduce gli intervalli di configurazione degli iperparametri dal grafo. Se gli intervalli di iperparametri e i valori predefiniti del modello generati non sono adatti ai dati del grafo, puoi modificare il file di configurazione dell'ottimizzazione degli iperparametri per creare una strategia di ottimizzazione degli iperparametri personalizzata. Ecco alcune best practice: + Quando il grafo diventa grande, le dimensioni predefinite della dimensione nascosta potrebbero non essere sufficienti per contenere tutte le informazioni. Puoi modificare l'iperparametro `num-hidden` per controllare le dimensioni della dimensione nascosta. + Per i modelli di incorporamento del grafo della conoscenza, potrebbe essere necessario modificare il modello specifico usato in base alla struttura del grafo e al budget. `TrainsE`i modelli hanno difficoltà a gestire le relazioni one-to-many (1-N), many-to-one (N-1) e many-to-many (N-N). `DistMult`i modelli hanno difficoltà a gestire le relazioni simmetriche. `RotatE`è bravo a modellare tutti i tipi di relazioni ma è più costoso rispetto `TrainsE` e `DistMult` durante la formazione. + In alcuni casi, quando sono importanti sia l'identificazione dei nodi che le informazioni sulle funzionalità del nodo, è necessario usare ``concat-node-embed`` per indicare al modello Neptune ML di recuperare la rappresentazione iniziale di un nodo concatenando le sue funzionalità con gli incorporamenti iniziali. + Quando si ottengono prestazioni ragionevolmente buone su alcuni iperparametri, è possibile regolare lo spazio di ricerca degli iperparametri in base a tali risultati. ## Arresto anticipato del processo di addestramento dei modelli in Neptune ML L'arresto anticipato può ridurre in modo significativo il tempo di esecuzione dell'addestramento del modello e i costi associati senza compromettere le prestazioni del modello. Inoltre, impedisce l'overfitting del modello sui dati di addestramento. L'arresto anticipato dipende dalle misurazioni regolari delle prestazioni del set di convalida. Inizialmente, le prestazioni migliorano con il procedere dell'addestramento, ma quando si verifica l'overfitting, peggiora nuovamente. La funzionalità di arresto anticipato identifica il punto di overfitting del modello e arresta l'addestramento del modello in quel momento. Neptune ML monitora le chiamate alle metriche di convalida e confronta la metrica di convalida più recente con la media delle metriche di convalida delle ultime **`n`** valutazioni, dove **`n`** è un numero impostato utilizzando il parametro `window-for-early-stop`. Non appena la metrica di convalida è peggiore di quella media, Neptune ML arresta l'addestramento del modello e salva il miglior modello generato fino a quel momento. Puoi controllare l'arresto anticipato utilizzando i seguenti parametri: + **`window-for-early-stop`**: il valore di questo parametro è un numero intero che specifica il numero di punteggi di convalida recenti in base a cui calcolare la media per decidere se effettuare un arresto anticipato. Il valore predefinito è `3`. + **`enable-early-stop`**: usa questo parametro booleano per disattivare la funzionalità di arresto anticipato. Per impostazione predefinita, il suo valore è `true`. ## Arresto anticipato del processo di ottimizzazione degli iperparametri in Neptune ML La funzione di interruzione anticipata di Neptune ML interrompe anche i lavori di formazione che non funzionano bene rispetto ad altri lavori di formazione, utilizzando SageMaker la funzione di avvio a caldo AI HPO. Anche questa operazione consente di ridurre i costi e migliorare la qualità dell'ottimizzazione degli iperparametri. Per una descrizione del funzionamento, consulta [Esecuzione di un processo di ottimizzazione degli iperparametri con avvio a caldo](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-warm-start.html). L'avvio a caldo permette di trasferire le informazioni apprese dai processi di addestramento precedenti ai processi di addestramento successivi e offre due vantaggi distinti: + Innanzitutto, i risultati dei processi di ottimizzazione precedenti vengono utilizzati per indicare le combinazioni di iperparametri valide da cercare nel nuovo processo di ottimizzazione. + In secondo luogo, consente l'arresto anticipato per accedere a più esecuzioni del modello, riducendo così i tempi di ottimizzazione. Questa funzionalità è abilitata automaticamente in Neptune ML e consente di trovare un equilibrio tra il tempo di addestramento del modello e le prestazioni. Se sei soddisfatto delle prestazioni del modello corrente, puoi utilizzare tale modello. Altrimenti, se ne eseguono di più, HPOs avviate a caldo con i risultati delle esecuzioni precedenti, in modo da scoprire un modello migliore. ## Servizi di supporto professionali AWS offre servizi di supporto professionale per aiutarti a risolvere i problemi relativi all'apprendimento automatico sui progetti Neptune. Se rimani bloccato, contatta il [Supporto AWS](https://aws.amazon.com/premiumsupport/). # Utilizzo di un modello addestrato per generare nuovi artefatti del modello Utilizzando il comando di trasformazione dei modelli Neptune ML, puoi calcolare gli artefatti del modello come incorporamenti di nodi sui dati del grafo elaborati usando parametri del modello pre-addestrati. ## Trasformazione dei modelli per l'inferenza incrementale Nel [flusso di lavoro di inferenza incrementale del modello](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental), dopo aver esportato da Neptune i dati per l'addestramento, puoi avviare un processo di trasformazione del modello usando un comando curl (o awscurl) come il seguente: ``` 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/" }' ``` Puoi quindi passare l'ID di questo processo alla chiamata API di creazione degli endpoint per creare un nuovo endpoint o aggiornarne uno esistente con i nuovi artefatti del modello generati da questo processo. In questo modo, l'endpoint nuovo o aggiornato potrà fornire previsioni del modello per i dati del grafo aggiornati. ## Trasformazione dei modelli per qualsiasi processo di addestramento Puoi anche fornire un `trainingJobName` parametro per generare artefatti del modello per qualsiasi processo di formazione sull' SageMaker intelligenza artificiale lanciato durante l'addestramento del modello Neptune ML. Poiché un processo di formazione sul modello Neptune ML può potenzialmente avviare SageMaker molti lavori di formazione sull'intelligenza artificiale, ciò offre la flessibilità necessaria per creare un endpoint di inferenza basato su uno qualsiasi di questi lavori di formazione sull'intelligenza artificiale. SageMaker Per esempio: ``` 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 il processo di addestramento originale riguarda un modello personalizzato fornito dall'utente, è necessario includere un oggetto `customModelTransformParameters` quando si richiama una trasformazione del modello. Per ulteriori informazioni su come implementare e usare un modello personalizzato, consulta [Modelli personalizzati in Neptune ML.](machine-learning-custom-models.md). **Nota** Il `modeltransform` comando esegue sempre il modello Transform sul miglior processo di addestramento basato sull' SageMaker intelligenza artificiale per quel tipo di formazione. Per ulteriori informazioni sui processi di trasformazione dei modelli, consulta [Comando modeltransform](machine-learning-api-modeltransform.md). # Artefatti generati dall'addestramento dei modelli in Neptune ML Dopo l'addestramento del modello, Neptune ML utilizza i parametri del modello con le prestazioni di addestramento migliori per generare gli artefatti del modello necessari per avviare l'endpoint di inferenza e fornire previsioni del modello. Questi artefatti vengono impacchettati in base al processo di formazione e archiviati nella posizione di output Amazon S3 del miglior lavoro di formazione sull'intelligenza artificiale. SageMaker Le sezioni seguenti descrivono cosa è incluso negli artefatti del modello per le diverse attività e illustrano in che modo il comando di trasformazione del modello usa un modello addestrato preesistente per generare gli artefatti anche su nuovi dati del grafo. ## Artefatti generati per diverse attività Il contenuto degli artefatti del modello generati dal processo di addestramento dipende dall'attività di machine learning di destinazione: **** + **Classificazione e regressione dei nodi**: per la previsione delle proprietà dei nodi, gli artefatti includono i parametri del modello, gli incorporamenti dei nodi dal [codificatore GNN](machine-learning-models-and-training.md#machine-learning-gnns), le previsioni del modello per i nodi nel grafo di addestramento e alcuni file di configurazione per l'endpoint di inferenza. Nelle attività di classificazione e regressione dei nodi, le previsioni del modello vengono precalcolate per i nodi presenti durante l'addestramento per ridurre la latenza delle query. + **Classificazione e regressione degli archi**: per la previsione delle proprietà degli archi, gli artefatti includono anche i parametri del modello e gli incorporamenti dei nodi. I parametri del decodificatore del modello sono particolarmente importanti per l'inferenza, in quanto la classificazione degli archi o le previsioni di regressione degli archi vengono calcolate applicando il decodificatore del modello agli incorporamenti del vertice di origine e del vertice di destinazione di un arco. + **Previsione dei collegamenti**: per la previsione dei collegamenti, oltre agli artefatti generati per la previsione delle proprietà degli archi, anche il grafo DGL viene incluso come artefatto perché la previsione dei collegamenti richiede il grafo di addestramento per eseguire le previsioni. L'obiettivo della previsione dei collegamenti è prevedere i vertici di destinazione che probabilmente si combineranno con un vertice di origine per formare un arco di un tipo specifico nel grafo. A tale scopo, l'incorporamento dei nodi del vertice di origine e una rappresentazione appresa per il tipo di arco vengono combinati con gli incorporamenti dei nodi di tutti i possibili vertici di destinazione per generare un punteggio di probabilità degli archi per ciascuno dei vertici di destinazione. I punteggi vengono quindi ordinati per classificare i potenziali vertici di destinazione e restituire i migliori candidati. Per ogni tipo di attività, i pesi del modello di rete neurale a grafo (GNN) della libreria DGL vengono salvati nell'artefatto del modello. Questo consente a Neptune ML di calcolare nuovi output del modello man mano che il grafo cambia (inferenza *induttiva*), oltre a usare previsioni e incorporamenti precalcolati (inferenza *trasduttiva*) per ridurre la latenza. ## Generazione di nuovi artefatti del modello Gli artefatti del modello generati dopo l'addestramento del modello in Neptune ML sono direttamente collegati al processo di addestramento. Questo significa che gli incorporamenti e le previsioni precalcolati esistono solo per le entità presenti nel grafo di addestramento originale. Sebbene la modalità di inferenza induttiva per gli endpoint Neptune ML possa calcolare previsioni per nuove entità in tempo reale, potrebbe essere necessario generare previsioni in batch su nuove entità senza eseguire query su un endpoint. Per ottenere previsioni del modello in batch per le nuove entità che sono state aggiunte al grafo, è necessario ricalcolare i nuovi artefatti del modello per i nuovi dati del grafo. Questa operazione viene eseguita utilizzando il comando `modeltransform`. Puoi usare il comando `modeltransform` per ottenere solo previsioni in batch senza configurare un endpoint o per generare tutte le previsioni per poterle riscrivere nel grafo. Poiché l'addestramento del modello esegue implicitamente una trasformazione del modello alla fine del processo di addestramento, gli artefatti del modello vengono sempre ricalcolati da un processo di addestramento sui dati del grafo di addestramento. Tuttavia, il comando `modeltransform` può anche calcolare gli artefatti del modello su dati del grafi che non sono stati utilizzati per addestrare un modello. A tale scopo, i nuovi dati del grafo devono essere elaborati utilizzando le stesse codifiche di funzionalità dei dati del grafo originale e devono rispettare lo stesso schema del grafo. Per eseguire questa operazione è prima di tutto necessario creare un nuovo processo di elaborazione dei dati che sia un clone del processo di elaborazione dei dati eseguito sui dati del grafo di addestramento originale ed eseguirlo sui nuovi dati del grafo (consulta [Elaborazione dei dati del grafo aggiornati per Neptune ML](machine-learning-on-graphs-processing.md#machine-learning-on-graphs-processing-updated)). Quindi, occorre chiamare il comando `modeltransform` con l'ID `dataProcessingJobId` nuovo e l'ID `modelTrainingJobId` precedente per ricalcolare gli artefatti del modello sui dati del grafo aggiornati. Per la previsione delle proprietà dei nodi, gli incorporamenti e le previsioni dei nodi vengono ricalcolati sui nuovi dati del grafo, anche per i nodi presenti nel grafo di addestramento originale. Per la previsione delle proprietà degli archi e la previsione dei collegamenti, anche gli incorporamenti dei nodi vengono ricalcolati e sostituiscono allo stesso modo gli eventuali incorporamenti dei nodi esistenti. Per ricalcolare gli incorporamenti dei nodi, Neptune ML applica il codificatore GNN appreso dal precedente modello addestrato ai nodi dei nuovi dati del grafo con le nuove funzionalità. Per i nodi che non dispongono di funzionalità, vengono riutilizzate le rappresentazioni iniziali apprese durante l'addestramento del modello originale. Per i nuovi nodi che non dispongono di funzionalità e che non erano presenti nel grafo di addestramento originale, Neptune ML inizializza la loro rappresentazione come media delle rappresentazioni iniziali apprese dei nodi di quel tipo di nodo presenti nel grafo di addestramento originale. Questo approccio può causare un calo delle prestazioni nelle previsioni del modello se sono presenti molti nuovi nodi privi di funzionalità, poiché verranno tutti inizializzati in base all'incorporamento iniziale medio per quel tipo di nodo. Se il modello viene addestrato con `concat-node-embed` impostato su true, le rappresentazioni iniziali dei nodi vengono create concatenando le funzionalità dei nodi con la rappresentazione iniziale apprendibile. Pertanto, per il grafo aggiornato, la rappresentazione iniziale dei nuovi nodi utilizza anche gli incorporamenti iniziali medi dei nodi, concatenati con le nuove funzionalità dei nodi. Inoltre, le eliminazioni dei nodi non sono attualmente supportate. Se i nodi sono stati rimossi nel grafo aggiornato, è necessario riaddestrare il modello in base ai dati del grafo aggiornato. Il ricalcolo degli artefatti del modello riutilizza i parametri del modello appresi su un nuovo grafo e deve essere eseguito solo quando il nuovo grafo è molto simile a quello precedente. Se il nuovo grafo non è sufficientemente simile, è necessario riaddestrare il modello per ottenere prestazioni simili sui nuovi dati del grafo. Ciò che si intente per sufficientemente simile dipende dalla struttura dei dati del grafo, ma come regola generale è consigliabile riaddestrare il modello se i nuovi dati differiscono di oltre il 10-20% dai dati del grafo di addestramento originale. Per i grafi in cui tutti i nodi dispongono di funzionalità, si applica il limite superiore della soglia (differenza del 20%), ma per i grafi in cui molti nodi sono privi di funzionalità e i nuovi nodi aggiunti al grafo non hanno proprietà, il limite inferiore (differenza del 10%) potrebbe anche essere troppo alto. Per ulteriori informazioni sui processi di trasformazione dei modelli, consulta [Comando modeltransform](machine-learning-api-modeltransform.md). # Modelli personalizzati in Neptune ML. **Nota** Il supporto dei modelli personalizzati di Neptune ML si basa su una versione precedente di Python 3. [Per creare ed eseguire modelli GNN personalizzati con dipendenze, usa. up-to-date GraphStorm SageMaker](https://graphstorm.readthedocs.io/en/v0.3.1/cli/model-training-inference/distributed/sagemaker.html) L'[inferenza induttiva in tempo reale](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference) non è attualmente supportata per i modelli personalizzati. Neptune ML consente di definire le implementazioni di modelli personalizzati con Python. Puoi addestrare e implementare modelli personalizzati utilizzando l'infrastruttura di Neptune ML come avviene per i modelli predefiniti e utilizzarli per ottenere previsioni tramite query su grafo. Puoi iniziare a implementare un modello personalizzato in Python seguendo gli [esempi del kit di strumenti per Neptune ML](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/) e utilizzando i componenti del modello forniti nel kit di strumenti stesso. Nelle seguenti sezioni sono fornite informazioni dettagliate. **Contents** + [Panoramica dei modelli personalizzati in Neptune ML](machine-learning-custom-model-overview.md) + [Quando usare un modello personalizzato in Neptune ML](machine-learning-custom-model-overview.md#machine-learning-custom-models-when-to-use) + [Flusso di lavoro per lo sviluppo e l'utilizzo di un modello personalizzato in Neptune ML](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow) + [Sviluppo di modelli personalizzati in Neptune ML](machine-learning-custom-model-development.md) + [Sviluppo di script di addestramento dei modelli personalizzati in Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-training-script) + [Sviluppo di script di trasformazione dei modelli personalizzati in Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-transform-script) + [File `model-hpo-configuration.json` personalizzato in Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-hpo-configuration-file) + [Test locale dell'implementazione del modello personalizzato in Neptune ML](machine-learning-custom-model-development.md#machine-learning-custom-model-testing) # Panoramica dei modelli personalizzati in Neptune ML ## Quando usare un modello personalizzato in Neptune ML I modelli predefiniti di Neptune ML gestiscono tutte le attività standard supportate da Neptune ML, ma in alcuni casi potrebbe essere necessario un controllo più granulare sul modello per un'attività specifica o personalizzare il processo di addestramento del modello. Un modello personalizzato, ad esempio, è appropriato nelle seguenti situazioni: + È necessario eseguire la codifica delle funzionalità per le funzionalità di testo di modelli di testo molto grandi su istanze GPU. + Vuoi usare un modello di rete neurale a grafo (GNN) personalizzato sviluppato in Deep Graph Library (DGL). + Vuoi usare modelli tabulari o modelli di insieme per la classificazione e la regressione dei nodi. ## Flusso di lavoro per lo sviluppo e l'utilizzo di un modello personalizzato in Neptune ML Il supporto di modelli personalizzati in Neptune ML è progettato per integrarsi perfettamente nei flussi di lavoro Neptune ML esistenti. Il codice personalizzato viene eseguito nel modulo di origine sull'infrastruttura di Neptune ML per addestrare il modello. Proprio come nel caso di una modalità integrata, Neptune ML avvia automaticamente SageMaker un lavoro di ottimizzazione HyperParameter AI e seleziona il modello migliore in base alla metrica di valutazione. Utilizza quindi l'implementazione fornita nel modulo di origine per generare gli artefatti del modello da implementare. Le fasi di esportazione dei dati, configurazione di addestramento e pre-elaborazione dei dati sono le stesse sia per i modelli personalizzati che per quelli predefiniti. Dopo la pre-elaborazione dei dati è possibile sviluppare e testare l'implementazione del modello personalizzato in modo iterativo e interattivo con Python. Quando il modello è pronto per la produzione, puoi caricare il modulo Python risultante su Amazon S3 in questo modo: ``` aws s3 cp --recursive (source path to module) s3://(bucket name)/(destination path for your module) ``` Quindi, puoi utilizzare il normale flusso di lavoro dei dati [predefinito](machine-learning-overview.md#machine-learning-overview-starting-workflow) o [incrementale](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental) per implementare il modello in produzione, con alcune differenze. Per l'addestramento dei modelli con un modello personalizzato, è necessario fornire un oggetto JSON `customModelTrainingParameters` all'API di addestramento dei modelli Neptune ML per assicurarsi che venga usato il codice personalizzato. I campi nell'oggetto `customModelTrainingParameters` sono i seguenti: + **`sourceS3DirectoryPath`** (*obbligatorio*): percorso della posizione Amazon S3 in cui si trova il modulo Python che implementa il modello. Deve indicare una posizione Amazon S3 esistente valida che contenga almeno uno script di addestramento, uno script di trasformazione e un file `model-hpo-configuration.json`. + **`trainingEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che esegue l'addestramento del modello e accetta gli iperparametri come argomenti della riga di comando, inclusi gli iperparametri fissi. *Default*: `training.py` + **`transformEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che deve essere eseguito dopo aver identificato il modello migliore ottenuto dalla ricerca degli iperparametri, in modo da calcolare gli artefatti del modello necessari per l'implementazione del modello. Deve poter essere eseguito senza argomenti della riga di comando. *Default*: `transform.py` Esempio: ``` 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)" } }' ``` Allo stesso modo, per abilitare una trasformazione del modello personalizzata, è necessario fornire un oggetto JSON `customModelTransformParameters` all'API di trasformazione dei modelli Neptune ML, con valori dei campi compatibili con i parametri del modello salvati dal processo di addestramento. L'oggetto `customModelTransformParameters` contiene i seguenti campi: + **`sourceS3DirectoryPath`** (*obbligatorio*): percorso della posizione Amazon S3 in cui si trova il modulo Python che implementa il modello. Deve indicare una posizione Amazon S3 esistente valida che contenga almeno uno script di addestramento, uno script di trasformazione e un file `model-hpo-configuration.json`. + **`transformEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che deve essere eseguito dopo aver identificato il modello migliore ottenuto dalla ricerca degli iperparametri, in modo da calcolare gli artefatti del modello necessari per l'implementazione del modello. Deve poter essere eseguito senza argomenti della riga di comando. *Default*: `transform.py` Esempio: ``` 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)" } }' ``` # Sviluppo di modelli personalizzati in Neptune ML Un punto di partenza valido per lo sviluppo di modelli personalizzati è seguire gli [esempi del kit di strumenti per Neptune ML](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/introduction) per strutturare e scrivere il modulo di addestramento. Il kit di strumenti per Neptune ML implementa anche componenti modularizzati del modello ML a grafo nel [modelzoo](https://github.com/awslabs/neptuneml-toolkit/tree/main/src/neptuneml_toolkit/modelzoo) che puoi combinare e usare per creare un modello personalizzato. Inoltre, il kit di strumenti offre funzioni di utilità che consentono di generare gli artefatti necessari durante l'addestramento e la trasformazione dei modelli. Puoi importare questo pacchetto Python nella tua implementazione personalizzata. Tutte le funzioni o i moduli forniti nel kit di strumenti sono disponibili anche nell'ambiente di addestramento Neptune ML. Se il tuo modulo Python contiene dipendenze esterne aggiuntive, puoi includere queste dipendenze aggiuntive creando un file `requirements.txt` nella directory del modulo. I pacchetti elencati nel file `requirements.txt` verranno quindi installati prima dell'esecuzione dello script di addestramento. Come minimo, il modulo Python che implementa il modello personalizzato deve contenere quanto segue: + Un punto di ingresso dello script di addestramento + Un punto di ingresso dello script di trasformazione + Un file `model-hpo-configuration.json` ## Sviluppo di script di addestramento dei modelli personalizzati in Neptune ML Lo script di addestramento del modello personalizzato deve essere uno script Python eseguibile come l'esempio [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) del kit di strumenti per Neptune ML. Deve accettare nomi e valori di iperparametri come argomenti della riga di comando. Durante l'addestramento del modello, i nomi degli iperparametri vengono ottenuti dal file `model-hpo-configuration.json`. I valori degli iperparametri rientrano nell'intervallo di iperparametri validi se l'iperparametro è ottimizzabile oppure assumono il valore di iperparametro predefinito se non è ottimizzabile. Lo script di addestramento viene eseguito su un'istanza di formazione SageMaker AI utilizzando una sintassi come questa: ``` python3 (script entry point) --(1st parameter) (1st value) --(2nd parameter) (2nd value) (...) ``` Per tutte le attività, Neptune AutoTrainer ML invia diversi parametri richiesti allo script di addestramento oltre agli iperparametri specificati, e lo script deve essere in grado di gestire questi parametri aggiuntivi per funzionare correttamente. Questi parametri aggiuntivi obbligatori variano leggermente in base all'attività: **Per la classificazione o la regressione dei nodi** + **`task`**: tipo di attività utilizzato internamente da Neptune ML. Per la classificazione dei nodi è `node_class` e per la regressione dei nodi è `node_regression`. + **`model`**: nome del modello utilizzato internamente da Neptune ML, che in questo caso è `custom`. + **`name`**: nome dell'attività utilizzata internamente da Neptune ML, che in questo caso è `node_class-custom` per la classificazione dei nodi e `node_regression-custom` per la regressione dei nodi. + **`target_ntype`**: nome del tipo di nodo per la classificazione o la regressione. + **`property`**: nome della proprietà del nodo per la classificazione o la regressione. **Per la previsione dei collegamenti** + **`task`**: tipo di attività utilizzato internamente da Neptune ML. Per la previsione dei collegamenti è `link_predict`. + **`model`**: nome del modello utilizzato internamente da Neptune ML, che in questo caso è `custom`. + **`name`**: nome dell'attività utilizzata internamente da Neptune ML, che in questo caso è `link_predict-custom`. **Per la classificazione o la regressione degli archi** + **`task`**: tipo di attività utilizzato internamente da Neptune ML. Per la classificazione degli archi è `edge_class` e per la regressione degli archi è `edge_regression`. + **`model`**: nome del modello utilizzato internamente da Neptune ML, che in questo caso è `custom`. + **`name`**: nome dell'attività utilizzata internamente da Neptune ML, che in questo caso è `edge_class-custom` per la classificazione degli archi e `edge_regression-custom` per la regressione degli archi. + **`target_etype`**: nome del tipo di arco per la classificazione o la regressione. + **`property`**: nome della proprietà dell'arco per la classificazione o la regressione. Lo script deve salvare i parametri del modello e tutti gli altri artefatti necessari al termine dell'addestramento. È possibile utilizzare le funzioni di utilità del kit di strumenti per Neptune ML per determinare la posizione dei dati del grafo elaborati, la posizione in cui devono essere salvati i parametri del modello e quali dispositivi GPU sono disponibili sull'istanza di addestramento. Per esempi di utilizzo di queste funzioni di utilità, consulta lo script di addestramento di esempio [train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py). ## Sviluppo di script di trasformazione dei modelli personalizzati in Neptune ML Uno script di trasformazione consente di sfruttare il [flusso di lavoro incrementale](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental) di Neptune ML per l'inferenza del modello su grafi in evoluzione senza riaddestrare il modello. Anche se tutti gli artefatti necessari per l'implementazione del modello vengono generati dallo script di addestramento, è comunque necessario fornire uno script di trasformazione se si desidera generare modelli aggiornati senza riaddestrare il modello. **Nota** L'[inferenza induttiva in tempo reale](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference) non è attualmente supportata per i modelli personalizzati. Lo script di trasformazione del modello personalizzato deve essere uno script Python eseguibile come lo script di esempio [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) del kit di strumenti per Neptune ML. Poiché questo script viene richiamato durante l'addestramento del modello senza argomenti della riga di comando, tutti gli argomenti della riga di comando che lo script accetta devono avere valori predefiniti. Lo script viene eseguito su un'istanza di addestramento SageMaker AI con una sintassi come questa: ``` python3 (your transform script entry point) ``` Lo script di trasformazione necessita di numerose informazioni, ad esempio: + Posizione dei dati del grafo elaborati. + Posizione in cui vengono salvati i parametri del modello e in cui devono essere salvati i nuovi artefatti del modello. + Dispositivi disponibili sull'istanza. + Iperparametri che hanno generato il modello migliore. Questi input vengono ottenuti utilizzando le funzioni di utilità Neptune ML che lo script può chiamare. Consulta lo script [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) di esempio del kit di strumenti per esempi su come procedere. Lo script deve salvare gli incorporamenti dei nodi, le mappature degli ID dei nodi e gli eventuali altri artefatti necessari per l'implementazione del modello per ogni attività. Consulta la [documentazione degli artefatti del modello](machine-learning-model-artifacts.md) per ulteriori informazioni sugli artefatti del modello necessari per le diverse attività di Neptune ML. ## File `model-hpo-configuration.json` personalizzato in Neptune ML Il file `model-hpo-configuration.json` definisce gli iperparametri per il modello personalizzato. È nello stesso [formato](machine-learning-customizing-hyperparams.md) del file `model-hpo-configuration.json` usato con i modelli predefiniti di Neptune ML e ha la precedenza sulla versione generata automaticamente da Neptune ML e caricata nella posizione dei dati elaborati. Quando aggiungi un nuovo iperparametro al modello, devi anche aggiungere una voce per l'iperparametro in questo file in modo che l'iperparametro venga passato allo script di addestramento. È necessario fornire un intervallo per l'iperparametro se vuoi che sia ottimizzabile e devi impostarlo come parametro `tier-1`, `tier-2` o `tier-3`. L'iperparametro verrà ottimizzato se il numero totale di processi di addestramento configurati consente di ottimizzare gli iperparametri nel relativo livello. Per un parametro non ottimizzabile, è necessario fornire un valore predefinito e aggiungere l'iperparametro alla sezione `fixed-param` del file. Per un esempio di come eseguire questa operazione, consulta il [file `model-hpo-configuration.json` di esempio](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/model-hpo-configuration.json) del kit di strumenti. È inoltre necessario fornire la definizione della metrica che il job di SageMaker AI HyperParameter Optimization utilizzerà per valutare i modelli candidati formati. A tale scopo, aggiungi un oggetto JSON `eval_metric` al file `model-hpo-configuration.json` in questo modo: ``` "eval_metric": { "tuning_objective": { "MetricName": "(metric_name)", "Type": "Maximize" }, "metric_definitions": [ { "Name": "(metric_name)", "Regex": "(metric regular expression)" } ] }, ``` L'`metric_definitions`array nell'`eval_metric`oggetto elenca gli oggetti di definizione delle metriche per ogni metrica che desideri che l' SageMaker IA estragga dall'istanza di addestramento. Ogni oggetto definizione della metrica ha una chiave `Name` che consente di specificare un nome per la metrica, ad esempio "accuratezza", "F1" e così via. La chiave `Regex` permette di fornire una stringa di espressione regolare che corrisponde al modo in cui la metrica specifica viene stampata nei log di addestramento. Consulta la [pagina SageMaker AI HyperParameter Tuning](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-define-metrics.html) per maggiori dettagli su come definire le metriche. L'oggetto `tuning_objective` in `eval_metric` consente quindi di specificare quale metrica tra quelle in `metric_definitions` dovrà essere usata come metrica di valutazione che funge da metrica obiettivo per l'ottimizzazione degli iperparametri. Il valore di `MetricName` deve corrispondere al valore di `Name` a in una delle definizioni in `metric_definitions`. Il valore di `Type` dovrebbe essere «Massimizza» o «Minimizza» a seconda che la metrica debba essere interpretata come greater-is-better (ad esempio «precisione») o less-is-better (come "». mean-squared-error Gli errori in questa sezione del `model-hpo-configuration.json` file possono causare errori nel job dell'API di addestramento del modello Neptune ML, poiché SageMaker il job HyperParameter AI Tuning non sarà in grado di selezionare il modello migliore. ## Test locale dell'implementazione del modello personalizzato in Neptune ML Puoi usare l'ambiente Conda del kit di strumenti per Neptune ML per eseguire il codice in locale per il test e la convalida del modello. Se stai sviluppando in un'istanza notebook Neptune, l'ambiente Conda sarà preinstallato nell'istanza notebook Neptune. Se stai sviluppando in un'istanza diversa, devi seguire le [istruzioni di configurazione per l'ambiente locale](https://github.com/awslabs/neptuneml-toolkit#local-installation) nel kit di strumenti per Neptune ML. L'ambiente Conda riproduce accuratamente l'ambiente in cui verrà eseguito il modello quando chiami l'[API di addestramento dei modelli](machine-learning-api-modeltraining.md). Tutti gli script di addestramento e gli script di trasformazione di esempio consentono di passare un flag `--local` della riga di comando per eseguire gli script in un ambiente locale per facilitare il debug. Si tratta di una procedura valida durante lo sviluppo di un modello personalizzato perché consente di testare l'implementazione del modello in modo interattivo e iterativo. Durante l'addestramento del modello nell'ambiente di addestramento di produzione Neptune ML, questo parametro viene omesso. # Creazione di un endpoint di inferenza per l'esecuzione di query Un endpoint di inferenza consente di eseguire query su un modello specifico creato dal processo di addestramento del modello. L'endpoint si collega al modello con le migliori prestazioni di un tipo specifico che il processo di addestramento è riuscito a generare. L'endpoint può quindi accettare le query Gremlin di Neptune e restituire le previsioni di quel modello per gli input nelle query. Dopo aver creato l'endpoint di inferenza, questo rimane attivo finché non viene eliminato. ## Gestione degli endpoint di inferenza per Neptune ML Dopo aver completato l'addestramento del modello sui dati esportati da Neptune, puoi creare un endpoint di inferenza usando un comando `curl` (o `awscurl`) come il seguente: ``` 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)" }' ``` Puoi anche creare un endpoint di inferenza da un modello creato da un processo di trasformazione del modello completato, più o meno allo stesso modo: ``` 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)" }' ``` I dettagli su come usare questi comandi sono spiegati in [Comando endpoints](machine-learning-api-endpoints.md), insieme alle informazioni su come recuperare lo stato di un endpoint, come eliminare un endpoint e come elencare tutti gli endpoint di inferenza. # Query di inferenza in Neptune ML Per eseguire query sull'endpoint di inferenza Neptune ML è possibile usare Gremlin o SPARQL. L'[inferenza induttiva in tempo reale](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference), tuttavia, è attualmente supportata solo per le query Gremlin. # Query di inferenza Gremlin in Neptune ML Come descritto in [Funzionalità di Neptune ML](machine-learning.md#machine-learning-capabilities), Neptune ML supporta modelli di addestramento che possono eseguire i seguenti tipi di attività di inferenza: + **Classificazione dei nodi**: previsione della funzionalità categoriale di una proprietà del vertice. + **Regressione dei nodi**: previsione di una proprietà numerica di un vertice. + **Classificazione degli archi**: previsione della funzionalità categoriale di una proprietà dell'arco. + **Regressione degli archi**: previsione di una proprietà numerica di un arco. + **Previsione dei collegamenti**: previsione dei nodi di destinazione per un nodo di origine e un arco in uscita specifici oppure i nodi di origine per un nodo di destinazione e un arco in entrata specificati. [Possiamo illustrare queste diverse attività con esempi che utilizzano il [set di dati da MovieLens 100.000](https://grouplens.org/datasets/movielens/100k/) fornito da Research. GroupLens ](https://grouplens.org/datasets/movielens/) Questo set di dati è costituito da film, utenti e valutazioni dei film da parte degli utenti, da cui è stato creato un grafo delle proprietà come questo: ![\[Esempio di grafico delle proprietà del film utilizzando il set di dati da 100k MovieLens\]](http://docs.aws.amazon.com/it_it/neptune/latest/userguide/images/movie_property_graph_example.png) **Classificazione dei nodi**: nel set di dati precedente, `Genre` è un tipo di vertice collegato al tipo di vertice `Movie` tramite l'arco `included_in`. Tuttavia, se si modifica il set di dati per rendere `Genre` una funzionalità [categoriale](https://en.wikipedia.org/wiki/Categorical_variable) per il tipo di vertice `Movie`, il problema di dedurre `Genre` per i nuovi film aggiunti al grafo della conoscenza può essere risolto usando modelli di classificazione dei nodi. **Regressione dei nodi**: se si considera il tipo di vertice `Rating`, che ha proprietà come `timestamp` e `score`, il problema di dedurre il valore numerico `Score` per una valutazione `Rating` può essere risolto usando modelli di regressione dei nodi. **Classificazione dei bordi**: allo stesso modo, per un `Rated` bordo, se abbiamo una proprietà `Scale` che può avere uno dei valori,,`Love`,`Like`,, `Dislike` `Neutral``Hate`, allora il problema della deduzione `Scale` per l'`Rated`edge per nuovi movies/ratings può essere risolto utilizzando modelli di classificazione dei bordi. **Regressione degli archi**: allo stesso modo, se per lo stesso arco `Rated` è presente una proprietà `Score` che contiene un valore numerico per la valutazione, questo può essere dedotto usando modelli di regressione degli archi. **Previsione dei collegamenti**: nell'ambito della previsione dei collegamenti rientrano problemi come trovare i dieci utenti con le maggiori probabilità di valutare un determinato film o trovare i primi dieci film con le maggiori probabilità di essere valutati da un utente specifico. **Nota** Per i casi d'uso di Neptune ML, è disponibile un ampio set di notebook progettati per fornire informazioni pratiche su ogni caso d'uso. È possibile creare questi notebook insieme al cluster Neptune quando si utilizza il modello Neptune ML per creare un cluster [Neptune ML](machine-learning-quick-start.md). CloudFormation Questi notebook sono disponibili anche su [github](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning). **Topics** + [Predicati Neptune ML utilizzati nelle query di inferenza Gremlin](machine-learning-gremlin-inference-query-predicates.md) + [Query di classificazione dei nodi Gremlin in Neptune ML](machine-learning-gremlin-vertex-classification-queries.md) + [Query di regressione dei nodi Gremlin in Neptune ML](machine-learning-gremlin-vertex-regression-queries.md) + [Query di classificazione degli archi Gremlin in Neptune ML](machine-learning-gremlin-edge-classification-queries.md) + [Query di regressione degli archi Gremlin in Neptune ML](machine-learning-gremlin-edge-regression.md) + [Query di previsione dei collegamenti Gremlin che utilizzano modelli di previsione dei collegamenti in Neptune ML](machine-learning-gremlin-link-prediction-queries.md) + [Elenco delle eccezioni per le query di inferenza Gremlin in Neptune ML](machine-learning-gremlin-exceptions.md) # Predicati Neptune ML utilizzati nelle query di inferenza Gremlin ## `Neptune#ml.deterministic` Questo predicato è un'opzione per le query di inferenza induttiva, ovvero per le query che includono il predicato [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference). Quando si utilizza l'inferenza induttiva, il motore Neptune crea il sottografo appropriato per valutare il modello GNN addestrato e i requisiti di questo sottografo dipendono dai parametri del modello finale. In particolare, il parametro `num-layer` determina il numero di hop di attraversamento dai nodi o dagli archi di destinazione e il parametro `fanouts` specifica il numero di vicini da campionare in ogni hop (consulta [Parametri di ottimizzazione degli iperparametri](machine-learning-customizing-hyperparams.md)). Per impostazione predefinita, le query di inferenza induttiva vengono eseguite in modalità non deterministica, in cui Neptune crea il neighborhood in modo casuale. Quando si effettuano previsioni, questo normale campionamento casuale dei vicini genera talvolta previsioni diverse. Quando si include `Neptune#ml.deterministic` in una query di inferenza induttiva, il motore Neptune tenta di campionare i vicini in modo deterministico in modo che più invocazioni della stessa query restituiscano sempre gli stessi risultati. Tuttavia, non si può garantire che i risultati siano completamente deterministici, poiché le modifiche al grafo e agli artefatti sottostanti dei sistemi distribuiti possono comunque introdurre fluttuazioni. Includi il predicato `Neptune#ml.deterministic` in una query in questo modo: ``` .with("Neptune#ml.deterministic") ``` Se il predicato `Neptune#ml.deterministic` è incluso in una query che non include anche `Neptune#ml.inductiveInference`, viene semplicemente ignorato. ## `Neptune#ml.disableInductiveInferenceMetadataCache` Questo predicato è un'opzione per le query di inferenza induttiva, ovvero per le query che includono il predicato [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference). Per le query di inferenza induttiva, Neptune utilizza un file di metadati archiviato in Amazon S3 per decidere il numero di hop e il fanout durante la creazione del neighborhood Neptune normalmente memorizza nella cache i metadati di questo modello per evitare di recuperare ripetutamente il file da Amazon S3. La memorizzazione nella cache può essere disabilitata includendo il predicato `Neptune#ml.disableInductiveInferenceMetadataCache` nella query. Sebbene possa essere più lento per Neptune recuperare i metadati direttamente da Amazon S3, è utile SageMaker quando l'endpoint AI è stato aggiornato dopo la riqualificazione o la trasformazione e la cache è obsoleta. Includi il predicato `Neptune#ml.disableInductiveInferenceMetadataCache` in una query in questo modo: ``` .with("Neptune#ml.disableInductiveInferenceMetadataCache") ``` Ecco l'aspetto di una query di esempio in un notebook 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` Il predicato `Neptune#ml.endpoint` viene utilizzato in un passaggio `with()` per specificare l'endpoint di inferenza, se necessario: ``` .with("Neptune#ml.endpoint", "the model's SageMaker AI inference endpoint") ``` È possibile identificare l'endpoint in base all'`id` o al relativo URL. Esempio: ``` .with( "Neptune#ml.endpoint", "node-classification-movie-lens-endpoint" ) ``` O: ``` .with( "Neptune#ml.endpoint", "https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/node-classification-movie-lens-endpoint/invocations" ) ``` **Nota** Se [imposti il parametro `neptune_ml_endpoint`](machine-learning-cluster-setup.md#machine-learning-set-inference-endpoint-cluster-parameter) nel gruppo di parametri del cluster database Neptune DB sull'`id` o sull'URL dell'endpoint, non è necessario includere il predicato `Neptune#ml.endpoint` in ogni query. ## `Neptune#ml.iamRoleArn` `Neptune#ml.iamRoleArn`viene utilizzato in un `with()` passaggio per specificare l'ARN del ruolo IAM di esecuzione SageMaker AI, se necessario: ``` .with("Neptune#ml.iamRoleArn", "the ARN for the SageMaker AI execution IAM role") ``` Per informazioni su come creare il ruolo IAM per l'esecuzione dell' SageMaker IA, consulta[Crea un ruolo personalizzato NeptuneSageMaker IAMRole](machine-learning-manual-setup.md#ml-manual-setup-sm-role). **Nota** Se [imposti il `neptune_ml_iam_role` parametro](machine-learning-cluster-setup.md#machine-learning-enabling-create-param-group) nel gruppo di parametri del cluster Neptune DB sull'ARN del SageMaker tuo ruolo IAM di esecuzione AI, non è necessario includere `Neptune#ml.iamRoleArn` il predicato in ogni query. ## Neptune\$1ml.inductiveInference In Gremlin l'inferenza trasduttiva è abilitata per impostazione predefinita. Per creare una query di [inferenza induttiva in tempo reale](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference), includi il predicato `Neptune#ml.inductiveInference` in questo modo: ``` .with("Neptune#ml.inductiveInference") ``` Se il grafo è dinamico, l'inferenza induttiva è spesso la scelta migliore, ma se il grafo è statico, l'inferenza trasduttiva è più veloce ed efficiente. ## `Neptune#ml.limit` Il predicato `Neptune#ml.limit` limita facoltativamente il numero di risultati restituiti per ogni entità: ``` .with( "Neptune#ml.limit", 2 ) ``` Per impostazione predefinita, il limite è 1 e il numero massimo che è possibile impostare è 100. ## `Neptune#ml.threshold` Il predicato `Neptune#ml.threshold` stabilisce facoltativamente una soglia limite per i punteggi dei risultati: ``` .with( "Neptune#ml.threshold", 0.5D ) ``` Ciò consente di scartare tutti i risultati con punteggi inferiori alla soglia specificata. ## `Neptune#ml.classification` Il `Neptune#ml.classification` predicato è allegato alla `properties()` fase per stabilire che le proprietà devono essere recuperate dall'endpoint SageMaker AI del modello di classificazione dei nodi: ``` .properties( "property key of the node classification model" ).with( "Neptune#ml.classification" ) ``` ## `Neptune#ml.regression` Il `Neptune#ml.regression` predicato è allegato alla `properties()` fase per stabilire che le proprietà devono essere recuperate dall'endpoint SageMaker AI del modello di regressione dei nodi: ``` .properties( "property key of the node regression model" ).with( "Neptune#ml.regression" ) ``` ## `Neptune#ml.prediction` Il predicato `Neptune#ml.prediction` è collegato ai passaggi `in()` e `out()` per stabilire che si tratta di una query di previsione dei collegamenti: ``` .in("edge label of the link prediction model").with("Neptune#ml.prediction").hasLabel("target node label") ``` ## `Neptune#ml.score` Il predicato `Neptune#ml.score` viene usato nelle query di classificazione dei nodi o degli archi Gremlin per ottenere un punteggio di attendibilità di machine learning. Il predicato `Neptune#ml.score` deve essere passato insieme al predicato di query nel passaggio `properties()` per ottenere un punteggio di attendibilità di ML per le query di classificazione dei nodi o degli archi. È possibile trovare un esempio di classificazione dei nodi con [altri esempi di classificazione dei nodi](machine-learning-gremlin-vertex-classification-queries.md#machine-learning-gremlin-node-class-other-queries) e un esempio di classificazione degli archi nella [sezione relativa alla classificazione degli archi](machine-learning-gremlin-edge-classification-queries.md). # Query di classificazione dei nodi Gremlin in Neptune ML Per la classificazione dei nodi Gremlin in Neptune ML + Il modello viene addestrato su una proprietà dei vertici. Il set di valori univoci di questa proprietà è definito come un set di classi del nodo o semplicemente classi. + La classe del nodo o il valore della proprietà categoriale di un vertice può essere dedotto dal modello di classificazione dei nodi. Questo è utile quando questa proprietà non è già collegata al vertice. + Per recuperare una o più classi da un modello di classificazione dei nodi, è necessario utilizzare il passaggio `with()` con il predicato `Neptune#ml.classification` per configurare il passaggio `properties()`. Il formato di output è simile a quello previsto se si trattasse di proprietà dei vertici. **Nota** La classificazione dei nodi funziona solo con i valori delle proprietà stringa. Ciò significa che i valori delle proprietà numeriche come `0` o `1` non sono supportati, sebbene gli equivalenti stringa `"0"` e `"1"` lo siano. Allo stesso modo, i valori delle proprietà booleane `true` e `false` non sono supportati, ma `"true"` e `"false"` funzionano. Ecco una query di classificazione dei nodi di esempio: ``` 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") ``` L'output di questa query ha un aspetto simile al seguente: ``` ==>vp[genre->Action] ==>vp[genre->Crime] ==>vp[genre->Comedy] ``` Nella query precedente i passaggi `properties()` e `V()` vengono utilizzati nel modo seguente: Il passaggio `V()` contiene il set di vertici per cui recuperare le classi dal modello di classificazione dei nodi: ``` .V( "movie_1", "movie_2", "movie_3" ) ``` Il passaggio `properties()` contiene la chiave su cui è stato addestrato il modello e include `.with("Neptune#ml.classification")` per indicare che si tratta di una query di inferenza ML per la classificazione dei nodi. Attualmente non sono supportate più chiavi delle proprietà in un passaggio `properties().with("Neptune#ml.classification")`. Ad esempio, la query seguente restituisce un'eccezione: ``` 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") ``` Per il messaggio di errore specifico, consulta l'[elenco delle eccezioni di Neptune ML](machine-learning-gremlin-exceptions.md). È possibile usare un passaggio `properties().with("Neptune#ml.classification")` in combinazione con uno dei seguenti passaggi: + `value()` + `value().is()` + `hasValue()` + `has(value,"")` + `key()` + `key().is()` + `hasKey()` + `has(key,"")` + `path()` ## Altre query di classificazione dei nodi Se sia l'endpoint di inferenza che il ruolo IAM corrispondente sono stati salvati nel gruppo di parametri del cluster database, una query di classificazione dei nodi può essere semplice come questa: ``` g.V("movie_1", "movie_2", "movie_3").properties("genre").with("Neptune#ml.classification") ``` È possibile combinare proprietà e classi dei vertici in una query usando il passaggio `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") ) ``` Puoi anche creare una query illimitata come questa: ``` 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") ``` Puoi recuperare le classi dei nodi insieme ai vertici usando il passaggio `select()` insieme al passaggio `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") ``` Puoi anche filtrare in base alle classi di nodi, come illustrato in questi esempi: ``` 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")) ``` È possibile ottenere un punteggio di attendibilità di classificazione dei nodi usando il predicato `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") ``` E la risposta avrà un aspetto simile al seguente: ``` ==>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] ``` ## Utilizzo dell'inferenza induttiva in una query di classificazione dei nodi Si supponga di dover aggiungere un nuovo nodo a un grafo esistente in un notebook Jupyter, in questo modo: ``` %%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') ``` È quindi possibile usare una query di inferenza induttiva per ottenere un genere e un punteggio di attendibilità che riflettano il nuovo nodo: ``` %%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") ``` Se la query è stata eseguita più volte, tuttavia, i risultati restituiti potrebbero essere leggermente diversi: ``` # First time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.21365921] ``` Puoi decidere rendere deterministica la stessa query: ``` %%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") ``` In tal caso, i risultati sarebbero più o meno gli stessi ogni volta: ``` # First time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] ``` # Query di regressione dei nodi Gremlin in Neptune ML La regressione dei nodi è simile alla classificazione dei nodi, tranne per il fatto che il valore dedotto dal modello di regressione per ogni nodo è numerico. Per la regressione dei nodi è possibile usare le stesse query Gremlin usate per la classificazione dei nodi, con le seguenti differenze: + Ancora una volta, in Neptune ML i nodi fanno riferimento ai vertici. + Il passaggio `properties()` accetta il formato `properties().with("Neptune#ml.regression")` anziché `properties().with("Neptune#ml.classification")`. + I predicati `"Neptune#ml.limit`" e `"Neptune#ml.threshold"` non sono applicabili. + Quando si filtra in base al valore, è necessario specificare un valore numerico. Ecco una query di classificazione dei vertici di esempio: ``` 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") ``` È possibile filtrare in base al valore dedotto utilizzando un modello di regressione, come illustrato negli esempi seguenti: ``` 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)) ``` ## Utilizzo dell'inferenza induttiva in una query di regressione dei nodi Si supponga di dover aggiungere un nuovo nodo a un grafo esistente in un notebook Jupyter, in questo modo: ``` %%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') ``` È quindi possibile utilizzare una query di inferenza induttiva per ottenere una valutazione che tenga conto del nuovo nodo: ``` %%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") ``` Poiché la query è non deterministica, potrebbe restituire risultati leggermente diversi se la si esegue più volte, in base al neighborhood: ``` # First time ==>vp[rating->9.1] # Second time ==>vp[rating->8.9] ``` Se sono necessari risultati più coerenti, puoi rendere la query deterministica: ``` %%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") ``` Ora i risultati saranno più o meno gli stessi ogni volta: ``` # First time ==>vp[rating->9.1] # Second time ==>vp[rating->9.1] ``` # Query di classificazione degli archi Gremlin in Neptune ML Per la classificazione degli archi Gremlin in Neptune ML: + Il modello viene addestrato su una proprietà degli archi. Il set di valori univoci di questa proprietà è definito come un set di classi. + Il valore della classe o della proprietà categoriale di un arco può essere dedotto dal modello di classificazione degli archi, utile quando questa proprietà non è già collegata all'arco. + Per recuperare una o più classi da un modello di classificazione degli archi, è necessario utilizzare il passaggio `with()` con il predicato `"Neptune#ml.classification"` per configurare il passaggio `properties()`. Il formato di output è simile a quello previsto se si trattasse di proprietà degli archi. **Nota** La classificazione degli archi funziona solo con i valori delle proprietà stringa. Ciò significa che i valori delle proprietà numeriche come `0` o `1` non sono supportati, sebbene gli equivalenti stringa `"0"` e `"1"` lo siano. Allo stesso modo, i valori delle proprietà booleane `true` e `false` non sono supportati, ma `"true"` e `"false"` funzionano. Ecco un esempio di query di classificazione degli archi che richiede un punteggio di attendibilità usando il predicato `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") ``` E la risposta avrà un aspetto simile al seguente: ``` ==>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] ``` ## Sintassi di una query di classificazione degli archi Gremlin Per un grafo semplice in cui `User` è il nodo di testa e il nodo di coda e `Relationship` è l'arco che li collega, ecco un esempio di query di classificazione degli archi: ``` 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") ``` L'output di questa query ha un aspetto simile al seguente: ``` ==>p[knows_by->"Family"] ==>p[knows_by->"Friends"] ==>p[knows_by->"Colleagues"] ``` Nella query precedente i passaggi `properties()` e `E()` vengono utilizzati nel modo seguente: + Il passaggio `E()` contiene il set di archi per cui recuperare le classi dal modello di classificazione degli archi: ``` .E("relationship_1","relationship_2","relationship_3") ``` + Il passaggio `properties()` contiene la chiave su cui è stato addestrato il modello e include `.with("Neptune#ml.classification")` per indicare che si tratta di una query di inferenza ML per la classificazione degli archi. Attualmente non sono supportate più chiavi delle proprietà in un passaggio `properties().with("Neptune#ml.classification")`. Ad esempio, la query seguente restituisce un'eccezione: ``` 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") ``` Per i messaggi di errore specifici, consulta [Elenco delle eccezioni per le query di inferenza Gremlin in Neptune ML](machine-learning-gremlin-exceptions.md). È possibile usare un passaggio `properties().with("Neptune#ml.classification")` in combinazione con uno dei seguenti passaggi: + `value()` + `value().is()` + `hasValue()` + `has(value,"")` + `key()` + `key().is()` + `hasKey()` + `has(key,"")` + `path()` ## Utilizzo dell'inferenza induttiva in una query di classificazione degli archi Si supponga di dover aggiungere un nuovo arco a un grafo esistente in un notebook Jupyter, in questo modo: ``` %%gremlin g.V('1').as('fromV') .V('2').as('toV') .addE('eLabel1').from('fromV').to('toV').property(id, 'e101') ``` È quindi possibile utilizzare una query di inferenza induttiva per ottenere una valutazione che tenga conto del nuovo arco: ``` %%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") ``` Poiché la query è non deterministica, potrebbe restituire risultati leggermente diversi se la si esegue più volte, in base al neighborhood casuale: ``` # First time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.21365921] ``` Se sono necessari risultati più coerenti, puoi rendere la query deterministica: ``` %%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") ``` Ora i risultati saranno più o meno gli stessi ogni volta che si esegue la query: ``` # First time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] ``` # Query di regressione degli archi Gremlin in Neptune ML La regressione degli archi è simile alla classificazione degli archi, tranne per il fatto che il valore dedotto dal modello di machine learning è numerico. Per la regressione degli archi, Neptune ML supporta le stesse query utilizzate per la classificazione. Gli aspetti principali da notare sono: + È necessario usare il predicato ML `"Neptune#ml.regression"` per configurare il passaggio `properties()` per questo caso d'uso. + I predicati `"Neptune#ml.limit"` e `"Neptune#ml.threshold"` non sono applicabili in questo caso d'uso. + Per filtrare in base al valore, è necessario specificare il valore come numerico. ## Sintassi di una query di regressione degli archi Gremlin Per un grafo semplice in cui `User` è il nodo di testa, `Movie` è il nodo di coda e `Rated` è l'arco che li collega, ecco un esempio di query di regressione degli archi che trova il valore di valutazione numerico, qui denominato punteggio, per l'arco `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") ``` Puoi anche filtrare in base a un valore dedotto dal modello di regressione ML. Per gli archi `Rated` esistenti (da `User` a `Movie`) identificati da `"rating_1"`, `"rating_2"` e `"rating_3"`, dove la proprietà dell'arco `Score` sia presente per queste classificazioni, è possibile usare una query come la seguente per dedurre `Score` per gli archi in cui è maggiore o uguale 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)) ``` ## Utilizzo dell'inferenza induttiva in una query di regressione degli archi Si supponga di dover aggiungere un nuovo arco a un grafo esistente in un notebook Jupyter, in questo modo: ``` %%gremlin g.V('1').as('fromV') .V('2').as('toV') .addE('eLabel1').from('fromV').to('toV').property(id, 'e101') ``` È quindi possibile utilizzare una query di inferenza induttiva per ottenere un punteggio che tenga conto del nuovo arco: ``` %%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") ``` Poiché la query è non deterministica, potrebbe restituire risultati leggermente diversi se la si esegue più volte, in base al neighborhood casuale: ``` # First time ==>ep[score->96] # Second time ==>ep[score->91] ``` Se sono necessari risultati più coerenti, puoi rendere la query deterministica: ``` %%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") ``` Ora i risultati saranno più o meno gli stessi ogni volta che si esegue la query: ``` # First time ==>ep[score->96] # Second time ==>ep[score->96] ``` # Query di previsione dei collegamenti Gremlin che utilizzano modelli di previsione dei collegamenti in Neptune ML I modelli di previsione dei collegamenti possono risolvere problemi come i seguenti: + **Previsione del nodo di testa**: dati un vertice e un tipo di arco, quali sono i vertici da cui provengono i collegamenti di tale vertice? + **Previsione del nodo di coda**: dati un vertice e un tipo di arco, quali sono i vertici a cui si collega tale vertice? **Nota** La previsione degli archi non è ancora supportata in Neptune ML. Per gli esempi seguenti, si consideri un semplice grafo con i vertici `User` e `Movie` collegati dall'arco `Rated`. Ecco un esempio di query di previsione del nodo di testa, usata per prevedere i primi cinque utenti con le maggiori probabilità di valutare i film, `"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") ``` Eccone una simile per la previsione del nodo di coda, usata per prevedere i primi cinque film con le maggiori probabilità di essere valutati dall'utente `"user_1"`: ``` 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") ``` L'etichetta dell'arco e l'etichetta del vertice previsto sono obbligatorie. Se una delle due viene omessa, verrà generata un'eccezione. Ad esempio, la seguente query senza un'etichetta del vertice previsto genera un'eccezione: ``` 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") ``` Analogamente, la seguente query senza un'etichetta dell'arco genera un'eccezione: ``` 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") ``` Per i messaggi di errore specifici restituiti da queste eccezioni, consulta l'[elenco delle eccezioni di Neptune ML](machine-learning-gremlin-exceptions.md). ## Altre query di previsione dei collegamenti Puoi usare il passaggio `select()` con il passaggio `as(`) per generare i vertici previsti insieme ai vertici di input: ``` 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") ``` Puoi eseguire query illimitate, come queste: ``` 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") ``` ## Utilizzo dell'inferenza induttiva in una query di previsione dei collegamenti Si supponga di dover aggiungere un nuovo nodo a un grafo esistente in un notebook Jupyter, in questo modo: ``` %%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') ``` È quindi possibile utilizzare una query di inferenza induttiva per prevedere il nodo di testa, tenendo conto del nuovo nodo: ``` %%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") ``` Risultato: ``` ==>V[2] ``` Allo stesso modo, è possibile utilizzare una query di inferenza induttiva per prevedere il nodo di coda, tenendo conto del nuovo nodo: ``` %%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") ``` Risultato: ``` ==>V[1] ``` # Elenco delle eccezioni per le query di inferenza Gremlin in Neptune ML Questo è un elenco completo di eccezioni che possono verificarsi durante l'esecuzione di query di inferenza Neptune ML Gremlin. Queste eccezioni coprono una serie di problemi, dai problemi con il ruolo o l'endpoint IAM specificato, ai passaggi Gremlin non supportati e alle limitazioni sul numero di query di inferenza ML per query. Ogni voce include un messaggio dettagliato che descrive il problema. + **`BadRequestException`**: non è possibile caricare le credenziali per il ruolo fornito. *Messaggio*: `Unable to load credentials for role: the specified IAM Role ARN.` + **`BadRequestException`**— Il ruolo IAM specificato non è autorizzato a richiamare l'endpoint SageMaker AI. *Messaggio*: `User: the specified IAM Role ARN is not authorized to perform: sagemaker:InvokeEndpoint on resource: the specified endpoint.` + **`BadRequestException`**: l'endpoint specificato non esiste. *Messaggio*: `Endpoint the specified endpoint not found.` + **`InternalFailureException`**: non è possibile recuperare i metadati di inferenza induttiva in tempo reale di Neptune ML da Amazon S3. *Messaggio*: `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`**: Neptune ML non trova il file dei metadati per l'inferenza induttiva in tempo reale in Amazon S3. *Messaggio*: `Neptune ML cannot find the metadata file for Real-Time Inductive Inference in S3.` + **`InvalidParameterException`**: l'endpoint specificato non è valido dal punto di vista sintattico. *Messaggio*: `Invalid endpoint provided for external service query.` + **`InvalidParameterException`**— L' SageMaker esecuzione IAM Role ARN specificata non è sintatticamente valida. *Messaggio*: `Invalid IAM role ARN provided for external service query.` + **`InvalidParameterException`**: nel passaggio `properties()` di una query sono specificate più chiavi delle proprietà. *Messaggio*: `ML inference queries are currently supported for one property key.` + **`InvalidParameterException`**: in una query vengono specificate più etichette degli archi. *Messaggio*: `ML inference are currently supported only with one edge label.` + **`InvalidParameterException`**: in una query sono specificati più vincoli per le etichette dei vertici. *Messaggio*: `ML inference are currently supported only with one vertex label constraint.` + **`InvalidParameterException`**: nella stessa query sono presenti entrambi i predicati `Neptune#ml.classification` e `Neptune#ml.regression`. *Messaggio*: `Both regression and classification ML predicates cannot be specified in the query.` + **`InvalidParameterException`**: è stata specificata più di un'etichetta dell'arco nel passaggio `in()` o `out()` di una query di previsione dei collegamenti. *Messaggio*: `ML inference are currently supported only with one edge label.` + **`InvalidParameterException`**: è stata specificata più di una chiave delle proprietà con Neptune\$1ml.score. *Messaggio*: `Neptune ML inference queries are currently supported for one property key and one Neptune#ml.score property key.` + **`MissingParameterException`**: l'endpoint non è stato specificato nella query o come parametro del cluster database. *Messaggio*: `No endpoint provided for external service query.` + **``MissingParameterException**— Il ruolo IAM per l'esecuzione dell' SageMaker IA non è stato specificato nella query o come parametro del cluster DB. *Messaggio*: `No IAM role ARN provided for external service query.` + **`MissingParameterException`**: la chiave della proprietà non è presente nel passaggio `properties()` in una query. *Messaggio*: `Property key needs to be specified using properties() step for ML inference queries.` + **`MissingParameterException`**: non è stata specificata alcuna un'etichetta dell'arco nel passaggio `in()` o `out()` di una query di previsione dei collegamenti. *Messaggio*: `Edge label needs to be specified while using in() or out() step for ML inference queries.` + **`MissingParameterException`**: non è stata specificata alcuna chiave della proprietà con Neptune\$1ml.score. *Messaggio*: `Property key needs to be specified along with Neptune#ml.score property key while using the properties() step for Neptune ML inference queries.` + **`UnsupportedOperationException`**: in una query di previsione dei collegamenti è stato usato un passaggio `both()`. *Messaggio*: `ML inference queries are currently not supported with both() step.` + **`UnsupportedOperationException`**: non è stata specificata alcuna etichetta del vertice previsto nel passaggio `has()` con il passaggio `in()` o `out()` in una query di previsione dei collegamenti. *Messaggio*: `Predicted vertex label needs to be specified using has() step for ML inference queries.` + **`UnsupportedOperationException`**: le query di inferenza induttiva ML Gremlin non sono attualmente supportate con passaggi non ottimizzati. *Messaggio*: `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`**: le query di inferenza di Neptune ML non sono attualmente supportate all'interno di un passaggio `repeat`. *Messaggio*: `Neptune ML inference queries are currently not supported inside a repeat step.` + **`UnsupportedOperationException`**: attualmente non sono supportate più query di inferenza Neptune ML per ogni query Gremlin. *Messaggio*: `Neptune ML inference queries are currently supported only with one ML inference query per gremlin query.` # Query di inferenza SPARQL in Neptune ML Neptune ML mappa il grafo RDF in un grafo delle proprietà per modellare l'attività di machine learning. Attualmente supporta i seguenti casi d'uso: + **Classificazione degli oggetti**: prevede la funzionalità categoriale di un oggetto. + **Regressione degli oggetti**: prevede una proprietà numerica di un oggetto. + **Previsione dell'oggetto**: prevede un oggetto in base a un soggetto e a una relazione. + **Previsione del soggetto**: prevede un oggetto in base a un soggetto e a una relazione. **Nota** Neptune ML non supporta i casi d'uso di classificazione e regressione dei soggetti con SPARQL. # Predicati Neptune ML utilizzati nelle query di inferenza SPARQL Con l'inferenza SPARQL vengono usati i predicati seguenti: ## Predicato `neptune-ml:timeout` Specifica il timeout per la connessione al server remoto. Non deve essere confuso con il timeout della richiesta di query, che è il tempo massimo che il server può impiegare per soddisfare una richiesta. Tieni presente che se il timeout della query si verifica prima del timeout del servizio specificato dal predicato `neptune-ml:timeout`, viene annullata anche la connessione al servizio. ## Predicato `neptune-ml:outputClass` Il predicato `neptune-ml:outputClass` viene utilizzato solo per definire la classe dell'oggetto previsto per la previsione dell'oggetto o del soggetto previsto per la previsione del soggetto. ## Predicato `neptune-ml:outputScore` Il predicato `neptune-ml:outputScore` è un numero positivo che rappresenta la probabilità che l'output di un modello di machine learning sia corretto. ## Predicato `neptune-ml:modelType` Il predicato `neptune-ml:modelType` specifica il tipo di modello di machine learning da addestrare: + `OBJECT_CLASSIFICATION` + `OBJECT_REGRESSION` + `OBJECT_PREDICTION` + `SUBJECT_PREDICTION` ## Predicato `neptune-ml:input` Il `neptune-ml:input` predicato si riferisce all'elenco di quelli URIs usati come input per Neptune ML. ## Predicato `neptune-ml:output` Il predicato `neptune-ml:output` fa riferimento all'elenco dei set di associazione in cui Neptune ML restituisce risultati. ## Predicato `neptune-ml:predicate` Il predicato `neptune-ml:predicate` predicato viene usato in modo diverso a seconda dell'attività da eseguire: + Per la **previsione di oggetti o soggetti**: definisce il tipo di predicato (tipo di arco o relazione). + Per la **classificazione e la regressione degli oggetti**: definisce il valore letterale (proprietà) da prevedere. ## Predicato `neptune-ml:batchSize` `neptune-ml:batchSize` specifica le dimensioni di input per la chiamata al servizio remoto. # Esempi di classificazione degli oggetti SPARQL Per la classificazione degli oggetti SPARQL in Neptune ML, il modello viene addestrato su uno dei valori del predicato. È utile quando tale predicato non è già presente in un determinato soggetto. Con il modello di classificazione degli oggetti è possibile dedurre solo i valori dei predicati categoriali. La seguente query tenta di prevedere il valore del predicato per tutti gli input di 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 . } } ``` Questa query può essere personalizzata nel modo seguente: ``` 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 . } } ``` # Esempi di regressione degli oggetti SPARQL La regressione degli oggetti è simile alla classificazione degli oggetti, ad eccezione del valore numerico del predicato dedotto dal modello di regressione per ogni nodo. È possibile usare le stesse query SPARQL usate per la classificazione degli oggetti anche per la regressione degli oggetti, con l'eccezione che i predicati `the Neptune#ml.limit` e `Neptune#ml.threshold` non sono applicabili. La seguente query tenta di prevedere il valore del predicato per tutti gli input di 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 . } } ``` Questa query può essere personalizzata nel modo seguente: ``` 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 . } } ``` # Esempio di previsione degli oggetti SPARQL La *previsione degli oggetti* prevede il valore dell'oggetto per un determinato soggetto e predicato. La seguente query di previsione degli oggetti tenta di prevedere il tipo di film che piacerà all'input di tipo `foaf:Person`: ``` ?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 . } } ``` La query stessa può essere personalizzata come segue: ``` 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 . } } ``` # Esempio di previsione dei soggetti SPARQL La *previsione dei soggetti* prevede il valore del soggetto per un determinato predicato e oggetto. Ad esempio, la seguente query prevede chi (di tipo `foaf:User`) guarderà un determinato film: ``` 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 ; } } ``` # Elenco delle eccezioni per le query di inferenza SPARQL in Neptune ML **** + **`BadRequestException`**   –   *Messaggio*: `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`**   –   *Messaggio*: `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`**   –   *Messaggio*: `Invalid predicate (predicate name) provided for external service http://aws.amazon.com/neptune/vocab/v01/services/ml#inference query.` + **`BadRequestException`**   –   *Messaggio*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the predicate (predicate name) to be defined`. + **`BadRequestException`**   –   *Messaggio*: `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`**   –   *Messaggio*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the input (parameter name) to be a constant, found: (type)`. + **`BadRequestException`**   –   *Messaggio*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference is expected to return only 1 value`. + **`BadRequestException`**   –   *Messaggio*: `"The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference only allows StatementPatternNodes`. + **`BadRequestException`**   –   *Messaggio*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference does not allow the predicate (predicate name)`. + **`BadRequestException`**   –   *Messaggio*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference predicates cannot be variables, found: (type)`. + **`BadRequestException`**   –   *Messaggio*: `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)`. # Documentazione di riferimento per l'API di gestione Neptune ML **Contents** + [Comando dataprocessing](machine-learning-api-dataprocessing.md) + [Creazione un processo di elaborazione dei dati](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-create-job) + [Recupero dello stato del processo](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-get-job-status) + [Arresto di un processo](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-stop-job) + [Elenchi di processi](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-list-jobs) + [Comando modeltraining](machine-learning-api-modeltraining.md) + [Creazione di un processo di addestramento dei modelli](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job) + [Recupero dello stato del processo](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-get-job-status) + [Arresto di un processo](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-stop-job) + [Elenchi di processi](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-list-jobs) + [Comando modeltransform](machine-learning-api-modeltransform.md) + [Creazione di un processo di trasformazione dei modelli](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-create-job) + [Recupero dello stato del processo](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-get-job-status) + [Arresto di un processo](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-stop-job) + [Elenchi di processi](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-list-jobs) + [Comando endpoints](machine-learning-api-endpoints.md) + [Creazione di un endpoint di inferenza](machine-learning-api-endpoints.md#machine-learning-api-endpoints-create-job) + [Recupero dello stato dell'endpoint](machine-learning-api-endpoints.md#machine-learning-api-endpoints-get-endpoint-status) + [Eliminazione di un endpoint.](machine-learning-api-endpoints.md#machine-learning-api-endpoints-delete-endpoint) + [Elenco degli endpoint di inferenza](machine-learning-api-endpoints.md#machine-learning-api-endpoints-list-endpoints) + [Eccezioni](machine-learning-api-exceptions.md) # Elaborazione dei dati tramite il comando `dataprocessing` Si utilizza il comando `dataprocessing` in Neptune ML per creare un processo di elaborazione dei dati, controllarne lo stato, arrestarlo o elencare tutti i processi di elaborazione dei dati attivi. ## Creazione di un processo di elaborazione dei dati con il comando `dataprocessing` in Neptune ML Un tipico comando `dataprocessing` in Neptune ML per la creazione di un nuovo processo ha il seguente aspetto: ``` 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)" }' ``` Un comando per avviare una rielaborazione incrementale ha il seguente aspetto: ``` 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)" }' ``` **Parametri per il comando `dataprocessing` per la creazione del processo** + **`id`** (*facoltativo*): identificatore univoco per il nuovo processo. *Tipo:* stringa. *Impostazione predefinita*: un UUID generato automaticamente. + **`previousDataProcessingJobId`** (*facoltativo*): ID del processo di elaborazione dei dati completato che è stato eseguito su una versione precedente dei dati. *Tipo:* stringa. *Impostazione predefinita*: *none*. *Nota*: usa questo parametro per l'elaborazione incrementale dei dati, per aggiornare il modello in caso di modifica dei dati del grafo (ma non quando i dati sono stati eliminati). + **`inputDataS3Location`**— (*Obbligatorio*) L'URI della posizione Amazon S3 in cui desideri che l' SageMaker IA scarichi i dati necessari per eseguire il processo di elaborazione dei dati. *Tipo:* stringa. + **`processedDataS3Location`**— (*Obbligatorio*) L'URI della posizione Amazon S3 in cui desideri che l' SageMaker IA salvi i risultati di un processo di elaborazione dati. *Tipo:* stringa. + **`sagemakerIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM per l'esecuzione dell' SageMaker IA. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'Amazon Resource Name (ARN) di un ruolo IAM che l' SageMaker IA può assumere per eseguire attività per tuo conto. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`processingInstanceType`** (*facoltativo*): tipo di istanza ML utilizzata durante l'elaborazione dei dati. La sua memoria deve essere sufficientemente grande da contenere il set di dati elaborato. *Tipo:* stringa. *Impostazione predefinita*: tipo `ml.r5` più piccolo, la cui memoria è dieci volte più grande delle dimensioni dei dati dei grafi esportati su disco. *Nota*: Neptune ML può selezionare automaticamente il tipo di istanza. Per informazioni, consulta [Selezione di un'istanza per l'elaborazione dei dati](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size). + **`processingInstanceVolumeSizeInGB`** (*facoltativo*): dimensioni del volume del disco dell'istanza di elaborazione. Sia i dati di input che i dati elaborati vengono archiviati su disco, quindi le dimensioni del volume devono essere sufficientemente grandi da contenere entrambi i set di dati. *Tipo*: numero intero. *Default*: `0` *Nota*: se non è specificato o se è pari a 0, Neptune ML sceglie automaticamente le dimensioni del volume in base a quelle dei dati. + **`processingTimeOutInSeconds`** (*facoltativo*): timeout in secondi per il processo di elaborazione dei dati. *Tipo*: numero intero. *Impostazione predefinita*: `86,400` (7 giorni) + **`modelType`** (*facoltativo*): uno dei due tipi di modello attualmente supportati da Neptune ML: modelli a grafo eterogenei (`heterogeneous`) e grafo della conoscenza (`kge`). *Tipo:* stringa. *Impostazione predefinita*: *none*. *Nota*: se non è specificato, Neptune ML sceglie automaticamente il tipo di modello in base ai dati. + **`configFileName`** (*facoltativo*): file di specifica dei dati che descrive come caricare i dati dei grafi esportati per l'addestramento. Il file viene generato automaticamente dal kit di strumenti di esportazione Neptune. *Tipo:* stringa. *Default*: `training-data-configuration.json` + **`subnets`**— (*Facoltativo*) Le sottoreti IDs del VPC di Neptune. *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`securityGroupIds`**— (*Facoltativo*) Il gruppo di sicurezza VPC. IDs *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`volumeEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata da SageMaker AI per crittografare i dati sul volume di archiviazione collegato alle istanze di calcolo ML che eseguono il processo di elaborazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. + **`enableInterContainerTrafficEncryption`** (*facoltativo*): abilita o disabilita la crittografia del traffico tra container nei processi di addestramento o di ottimizzazione degli iperparametri. *Tipo*: booleano. *Impostazione predefinita*: *True*. **Nota** Il parametro `enableInterContainerTrafficEncryption` è disponibile solo nel [rilascio del motore 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md). + **`s3OutputEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata dall' SageMaker IA per crittografare l'output del processo di formazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. ## Recupero dello stato di un processo di elaborazione dei dati con il comando `dataprocessing` in Neptune ML Un comando `dataprocessing` di esempio in Neptune ML per lo stato di un processo ha il seguente aspetto: ``` curl -s \ "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)" \ | python -m json.tool ``` **Parametri per il comando `dataprocessing` per lo stato del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di elaborazione dei dati. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. ## Arresto di un processo di elaborazione dei dati con il comando `dataprocessing` in Neptune ML Un comando `dataprocessing` di esempio in Neptune ML per l'arresto di un processo ha il seguente aspetto: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)" ``` Oppure questo: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)?clean=true" ``` **Parametri per il comando `dataprocessing` per l'arresto del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di elaborazione dei dati. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`clean`** (*facoltativo*): questo flag specifica che tutti gli artefatti Amazon S3 devono essere eliminati quando il processo viene arrestato. *Tipo*: Boolean *Default*: `FALSE` ## Elenco dei processi di elaborazione dei dati attivi con il comando `dataprocessing` in Neptune ML. Un comando `dataprocessing` di esempio in Neptune ML per l'elenco dei processi attivi ha il seguente aspetto: ``` curl -s "https://(your Neptune endpoint)/ml/dataprocessing" ``` Oppure questo: ``` curl -s "https://(your Neptune endpoint)/ml/dataprocessing?maxItems=3" ``` **Parametri per il comando `dataprocessing` per l'elenco dei processi** + **`maxItems`** (*facoltativo*): numero massimo di elementi da restituire. *Tipo*: numero intero. *Default*: `10` *Valore massimo consentito*: `1024`. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. # Addestramento dei modelli con il comando `modeltraining` È possibile utilizzare il comando `modeltraining` in Neptune ML per creare un processo di addestramento dei modelli, controllarne lo stato, arrestarlo o elencare tutti i processi di addestramento dei modelli attivi. ## Creazione di un processo di addestramento dei modelli con il comando `modeltraining` in Neptune ML Un comando `modeltraining` in Neptune ML per la creazione di un processo completamente nuovo ha il seguente aspetto: ``` 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" }' ``` Un comando `modeltraining` in Neptune ML per la creazione di un processo di aggiornamento per l'addestramento dei modelli incrementale ha il seguente aspetto: ``` 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)", }' ``` Un comando `modeltraining` in Neptune ML per la creazione di un nuovo processo con l'implementazione di un modello personalizzato fornita dall'utente ha il seguente aspetto: ``` 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)" } }' ``` **Parametri per il comando `modeltraining` per la creazione del processo** + **`id`** (*facoltativo*): identificatore univoco per il nuovo processo. *Tipo:* stringa. *Impostazione predefinita*: un UUID generato automaticamente. + **`dataProcessingJobId`** (*obbligatorio*): ID del processo di elaborazione dei dati completato che ha creato i dati per l'addestramento. *Tipo:* stringa. + **`trainModelS3Location`** (*obbligatorio*): posizione in Amazon S3 in cui devono essere archiviati gli artefatti del modello. *Tipo:* stringa. + **`previousModelTrainingJobId`** (*facoltativo*): ID del processo di addestramento del modello completato che si desidera aggiornare in modo incrementale in base ai dati aggiornati. *Tipo:* stringa. *Impostazione predefinita*: *none*. + **`sagemakerIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM per l'esecuzione dell' SageMaker IA. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`modelName`** (*facoltativo*): tipo di modello per l'addestramento. Per impostazione predefinita, il modello di machine learning è basato automaticamente sul `modelType` utilizzato nell'elaborazione dei dati, ma qui è possibile specificare un tipo di modello diverso. *Tipo:* stringa. *Impostazione predefinita*: `rgcn` per i grafi eterogenei e `kge` per i grafi della conoscenza. *Valori validi*: per i grafi eterogenei: `rgcn`. Per i grafi `kge`: `transe`, `distmult` o `rotate`. Per l'implementazione di un modello personalizzato: `custom`. + **`baseProcessingInstanceType`** (*facoltativo*): tipo di istanza ML utilizzata nella preparazione e nella gestione dell'addestramento dei modelli ML. *Tipo:* stringa. *Nota*: si tratta di un'istanza CPU scelta in base ai requisiti di memoria per l'elaborazione dei dati e del modello di addestramento. Per informazioni, consulta [Selezione di un'istanza per l'addestramento e la trasformazione del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size). + **`trainingInstanceType`** (*facoltativo*): tipo di istanza ML utilizzato per l'addestramento del modello. Tutti i modelli Neptune ML supportano l'addestramento su CPU, GPU e multiGPU. *Tipo:* stringa. *Default*: `ml.p3.2xlarge` *Nota*: la scelta del tipo di istanza corretto per l'addestramento dipende dal tipo di attività, dalle dimensioni del grafo e dal budget. Per informazioni, consulta [Selezione di un'istanza per l'addestramento e la trasformazione del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size). + **`trainingInstanceVolumeSizeInGB`** (*facoltativo*): dimensioni del volume del disco dell'istanza di addestramento. Sia i dati di input che il modello di output vengono archiviati su disco, quindi le dimensioni del volume devono essere sufficientemente grandi da contenere entrambi i set di dati. *Tipo*: numero intero. *Default*: `0` *Nota*: se non è specificato o è pari a 0, Neptune ML seleziona le dimensioni del volume del disco in base alla raccomandazione generata nella fase di elaborazione dati. Per informazioni, consulta [Selezione di un'istanza per l'addestramento e la trasformazione del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size). + **`trainingTimeOutInSeconds`** (*facoltativo*): timeout in secondi per il processo di addestramento. *Tipo*: numero intero. *Impostazione predefinita*: `86,400` (7 giorni) + **`maxHPONumberOfTrainingJobs`**: numero totale massimo di processi di addestramento da avviare per il processo di ottimizzazione degli iperparametri. *Tipo*: numero intero. *Default*: `2` *Nota*: Neptune ML ottimizza automaticamente gli iperparametri del modello di machine learning. Per ottenere un modello che funzioni correttamente, utilizza almeno 10 processi (in altre parole, imposta `maxHPONumberOfTrainingJobs` su 10). In generale, maggiore è il numero di esecuzioni di ottimizzazione, migliori sono i risultati. + **`maxHPOParallelTrainingJobs`**: Numero massimo di processi di addestramento paralleli da avviare per il processo di ottimizzazione degli iperparametri. *Tipo*: numero intero. *Default*: `2` *Nota*: il numero di processi paralleli che è possibile eseguire è limitato dalle risorse disponibili sull'istanza di addestramento. + **`subnets`**— (*Facoltativo*) Le sottoreti IDs del VPC di Neptune. *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`securityGroupIds`**— (*Facoltativo*) Il gruppo di sicurezza VPC. IDs *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`volumeEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata da SageMaker AI per crittografare i dati sul volume di archiviazione collegato alle istanze di calcolo ML che eseguono il processo di formazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. + **`s3OutputEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata dall' SageMaker IA per crittografare l'output del processo di elaborazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. + **`enableInterContainerTrafficEncryption`** (*facoltativo*): abilita o disabilita la crittografia del traffico tra container nei processi di addestramento o di ottimizzazione degli iperparametri. *Tipo*: booleano. *Impostazione predefinita*: *True*. **Nota** Il parametro `enableInterContainerTrafficEncryption` è disponibile solo nel [rilascio del motore 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md). + **`enableManagedSpotTraining`** (*facoltativo*): ottimizza il costo per l'addestramento dei modelli di machine learning utilizzando le istanze spot di Amazon Elastic Compute Cloud. Per ulteriori informazioni, consulta [Managed Spot Training in Amazon SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/model-managed-spot-training.html). *Tipo*: Boolean *Impostazione predefinita*: *False*. + **`customModelTrainingParameters`** (*facoltativo*): configurazione per l'addestramento di modelli personalizzati. Si tratta di un oggetto JSON con i campi seguenti: + **`sourceS3DirectoryPath`** (*obbligatorio*): percorso della posizione Amazon S3 in cui si trova il modulo Python che implementa il modello. Deve indicare una posizione Amazon S3 esistente valida che contenga almeno uno script di addestramento, uno script di trasformazione e un file `model-hpo-configuration.json`. + **`trainingEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che esegue l'addestramento del modello e accetta gli iperparametri come argomenti della riga di comando, inclusi gli iperparametri fissi. *Default*: `training.py` + **`transformEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che deve essere eseguito dopo aver identificato il modello migliore ottenuto dalla ricerca degli iperparametri, in modo da calcolare gli artefatti del modello necessari per l'implementazione del modello. Deve poter essere eseguito senza argomenti della riga di comando. *Default*: `transform.py` + **`maxWaitTime`** (*facoltativo*): tempo massimo di attesa, in secondi, quando si esegue l'addestramento dei modelli utilizzando istanze spot. Deve essere maggiore di `trainingTimeOutInSeconds`. *Tipo*: numero intero. ## Recupero dello stato di un processo di addestramento dei modelli con il comando `modeltraining` in Neptune ML Un comando `modeltraining` di esempio in Neptune ML per lo stato di un processo ha il seguente aspetto: ``` curl -s \ "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)" \ | python -m json.tool ``` **Parametri per il comando `modeltraining` per lo stato del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di addestramento dei modelli. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. ## Arresto di un processo di addestramento dei modelli con il comando `modeltraining` in Neptune ML Un comando `modeltraining` di esempio in Neptune ML per l'arresto di un processo ha il seguente aspetto: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)" ``` Oppure questo: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)?clean=true" ``` **Parametri per il comando `modeltraining` per l'arresto del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di addestramento dei modelli. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`clean`** (*facoltativo*): questo flag specifica che tutti gli artefatti Amazon S3 devono essere eliminati quando il processo viene arrestato. *Tipo*: Boolean *Default*: `FALSE` ## Elenco dei processi di addestramento dei modelli attivi con il comando `modeltraining` in Neptune ML Un comando `modeltraining` di esempio in Neptune ML per l'elenco dei processi attivi ha il seguente aspetto: ``` curl -s "https://(your Neptune endpoint)/ml/modeltraining" | python -m json.tool ``` Oppure questo: ``` curl -s "https://(your Neptune endpoint)/ml/modeltraining?maxItems=3" | python -m json.tool ``` **Parametri per il comando `modeltraining` per l'elenco dei processi** + **`maxItems`** (*facoltativo*): numero massimo di elementi da restituire. *Tipo*: numero intero. *Default*: `10` *Valore massimo consentito*: `1024`. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. # Trasformazione dei modelli con il comando `modeltransform` È possibile utilizzare il comando `modeltransform` in Neptune ML per creare un processo di trasformazione dei modelli, controllarne lo stato, arrestarlo o elencare tutti i processi di trasformazione dei modelli attivi. ## Creazione di un processo di trasformazione dei modelli con il comando `modeltransform` in Neptune ML Un comando `modeltransform` in Neptune ML per la creazione di un processo di trasformazione incrementale senza riaddestramento dei modelli ha il seguente aspetto: ``` 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" }' ``` Un comando Neptune `modeltransform` ML per creare un lavoro da un lavoro di formazione AI SageMaker completato ha il seguente aspetto: ``` 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" : "" }' ``` Un comando `modeltransform` in Neptune ML per la creazione di un processo che usa l'implementazione di un modello personalizzato ha il seguente aspetto: ``` 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)" } }' ``` **Parametri per il comando `modeltransform` per la creazione del processo** + **`id`** (*facoltativo*): identificatore univoco per il nuovo processo. *Tipo:* stringa. *Impostazione predefinita*: un UUID generato automaticamente. + **`dataProcessingJobId`**: ID di un processo di elaborazione dei dati completato. *Tipo:* stringa. *Nota*: è necessario includere sia `dataProcessingJobId` che `mlModelTrainingJobId`, o `trainingJobName`. + **`mlModelTrainingJobId`**: ID di un processo di addestramento del modello completato. *Tipo:* stringa. *Nota*: è necessario includere sia `dataProcessingJobId` che `mlModelTrainingJobId`, o `trainingJobName`. + **`trainingJobName`**— Il nome di un lavoro di formazione sull' SageMaker intelligenza artificiale completato. *Tipo:* stringa. *Nota*: è necessario includere entrambi i parametri `dataProcessingJobId` e `mlModelTrainingJobId` oppure il parametro `trainingJobName`. + **`sagemakerIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM per l'esecuzione dell' SageMaker IA. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`customModelTransformParameters `** (*facoltativo*): informazioni di configurazione per una trasformazione del modello mediante un modello personalizzato. L'oggetto `customModelTransformParameters` contiene i seguenti campi, che devono avere valori compatibili con i parametri del modello salvati durante il processo di addestramento: + **`sourceS3DirectoryPath`** (*obbligatorio*): percorso della posizione Amazon S3 in cui si trova il modulo Python che implementa il modello. Deve indicare una posizione Amazon S3 esistente valida che contenga almeno uno script di addestramento, uno script di trasformazione e un file `model-hpo-configuration.json`. + **`transformEntryPointScript`** (*facoltativo*): nome del punto di ingresso nel modulo di uno script che deve essere eseguito dopo aver identificato il modello migliore ottenuto dalla ricerca degli iperparametri, in modo da calcolare gli artefatti del modello necessari per l'implementazione del modello. Deve poter essere eseguito senza argomenti della riga di comando. *Default*: `transform.py` + **`baseProcessingInstanceType`** (*facoltativo*): tipo di istanza ML utilizzata nella preparazione e nella gestione dell'addestramento dei modelli ML. *Tipo:* stringa. *Nota*: si tratta di un'istanza CPU scelta in base ai requisiti di memoria per l'elaborazione dei dati e del modello di trasformazione. Per informazioni, consulta [Selezione di un'istanza per l'addestramento e la trasformazione del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size). + **`baseProcessingInstanceVolumeSizeInGB`** (*facoltativo*): dimensioni del volume del disco dell'istanza di addestramento. Sia i dati di input che il modello di output vengono archiviati su disco, quindi le dimensioni del volume devono essere sufficientemente grandi da contenere entrambi i set di dati. *Tipo*: numero intero. *Default*: `0` *Nota*: se non è specificato o è pari a 0, Neptune ML seleziona le dimensioni del volume del disco in base alla raccomandazione generata nella fase di elaborazione dati. Per informazioni, consulta [Selezione di un'istanza per l'addestramento e la trasformazione del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size). + **`subnets`**— (*Facoltativo*) Le sottoreti IDs del VPC di Neptune. *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`securityGroupIds`**— (*Facoltativo*) Il gruppo di sicurezza VPC. IDs *Tipo*: elenco di stringhe. *Impostazione predefinita*: *none*. + **`volumeEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata da SageMaker AI per crittografare i dati sul volume di archiviazione collegato alle istanze di calcolo ML che eseguono il processo di trasformazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. + **`enableInterContainerTrafficEncryption`** (*facoltativo*): abilita o disabilita la crittografia del traffico tra container nei processi di addestramento o di ottimizzazione degli iperparametri. *Tipo*: booleano. *Impostazione predefinita*: *True*. **Nota** Il parametro `enableInterContainerTrafficEncryption` è disponibile solo nel [rilascio del motore 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md). + **`s3OutputEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata dall' SageMaker IA per crittografare l'output del processo di elaborazione. *Tipo:* stringa. *Impostazione predefinita*: *none*. ## Recupero dello stato di un processo di trasformazione dei modelli con il comando `modeltransform` in Neptune ML Un comando `modeltransform` di esempio in Neptune ML per lo stato di un processo ha il seguente aspetto: ``` curl -s \ "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)" \ | python -m json.tool ``` **Parametri per il comando `modeltransform` per lo stato del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di trasformazione dei modelli. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. ## Arresto di un processo di trasformazione dei modelli con il comando `modeltransform` in Neptune ML Un comando `modeltransform` di esempio in Neptune ML per l'arresto di un processo ha il seguente aspetto: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)" ``` Oppure questo: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)?clean=true" ``` **Parametri per il comando `modeltransform` per l'arresto del processo** + **`id`** (*obbligatorio*): identificatore univoco del processo di trasformazione dei modelli. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`clean`** (*facoltativo*): questo flag specifica che tutti gli artefatti Amazon S3 devono essere eliminati quando il processo viene arrestato. *Tipo*: Boolean *Default*: `FALSE` ## Elenco dei processi di trasformazione dei modelli attivi con il comando `modeltransform` in Neptune ML Un comando `modeltransform` di esempio in Neptune ML per l'elenco dei processi attivi ha il seguente aspetto: ``` curl -s "https://(your Neptune endpoint)/ml/modeltransform" | python -m json.tool ``` Oppure questo: ``` curl -s "https://(your Neptune endpoint)/ml/modeltransform?maxItems=3" | python -m json.tool ``` **Parametri per il comando `modeltransform` per l'elenco dei processi** + **`maxItems`** (*facoltativo*): numero massimo di elementi da restituire. *Tipo*: numero intero. *Default*: `10` *Valore massimo consentito*: `1024`. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. # Gestione degli endpoint di inferenza mediante il comando `endpoints` Si utilizza il comando `endpoints` in Neptune ML per creare un endpoint di inferenza, controllarne lo stato, eliminarlo o elencare gli endpoint di inferenza esistenti. ## Creazione di un endpoint di inferenza con il comando `endpoints` in Neptune ML Un comando `endpoints` in Neptune ML per la creazione di un endpoint di inferenza da un modello creato da un processo di addestramento ha il seguente aspetto: ``` 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)" }' ``` Un comando `endpoints` in Neptune ML per l'aggiornamento di un endpoint di inferenza esistente da un modello creato da un processo di addestramento ha il seguente aspetto: ``` 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)" }' ``` Un comando `endpoints` in Neptune ML per la creazione di un endpoint di inferenza da un modello creato da un processo di trasformazione dei modelli ha il seguente aspetto: ``` 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)" }' ``` Un comando `endpoints` in Neptune ML per l'aggiornamento di un endpoint di inferenza esistente da un modello creato da un processo di trasformazione dei modelli ha il seguente aspetto: ``` 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)" }' ``` **Parametri per il comando `endpoints` per la creazione di endpoint di inferenza** + **`id`** (*facoltativo*): identificatore univoco per il nuovo endpoint di inferenza. *Tipo:* stringa. *Impostazione predefinita*: nome con timestamp generato automaticamente. + **`mlModelTrainingJobId`**: ID del processo di addestramento dei modelli completato che ha creato il modello a cui punterà l'endpoint di inferenza. *Tipo:* stringa. *Nota*: è necessario specificare `mlModelTrainingJobId` o `mlModelTransformJobId`. + **`mlModelTransformJobId`**: ID del processo di trasformazione dei modelli completato. *Tipo:* stringa. *Nota*: è necessario specificare `mlModelTrainingJobId` o `mlModelTransformJobId`. + **`update`** (*facoltativo*): se presente, questo parametro indica che si tratta di una richiesta di aggiornamento. *Tipo*: Boolean *Default*: `false` *Nota*: è necessario specificare `mlModelTrainingJobId` o `mlModelTransformJobId`. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso di Neptune alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`modelName`** (*facoltativo*): tipo di modello per l'addestramento. Per impostazione predefinita, il modello di machine learning è basato automaticamente sul `modelType` utilizzato nell'elaborazione dei dati, ma qui è possibile specificare un tipo di modello diverso. *Tipo:* stringa. *Impostazione predefinita*: `rgcn` per i grafi eterogenei e `kge` per i grafi della conoscenza. *Valori validi*: per i grafi eterogenei: `rgcn`. Per i grafi della conoscenza: `kge`, `transe`, `distmult` o `rotate`. + **`instanceType`** (*facoltativo*): tipo di istanza ML utilizzata per l'elaborazione online. *Tipo:* stringa. *Default*: `ml.m5.xlarge` *Nota*: la scelta dell'istanza ML per un endpoint di inferenza dipende dal tipo di attività, dalle dimensioni del grafo e dal budget. Per informazioni, consulta [Selezione di un'istanza per un endpoint di inferenza](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size). + **`instanceCount`** (*facoltativo*): numero minimo di istanze Amazon EC2 da implementare su un endpoint ai fini della previsione. *Tipo*: numero intero. *Default*: `1` + **`volumeEncryptionKMSKey`**— (*Facoltativo*) La chiave AWS Key Management Service (AWS KMS) utilizzata da SageMaker AI per crittografare i dati sul volume di storage collegato alle istanze di calcolo ML che eseguono gli endpoint. *Tipo:* stringa. *Impostazione predefinita*: *none*. ## Recupero dello stato di un endpoint di inferenza con il comando `endpoints` in Neptune ML Un comando `endpoints` di esempio in Neptune ML per lo stato di un endpoint dell'istanza ha il seguente aspetto: ``` curl -s \ "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)" \ | python -m json.tool ``` **Parametri per il comando `endpoints` per lo stato dell'endpoint dell'istanza** + **`id`** (*obbligatorio*): identificatore univoco dell'endpoint di inferenza. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso di Neptune alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. ## Eliminazione di un endpoint dell'istanza con il comando `endpoints` in Neptune ML Un comando `endpoints` di esempio in Neptune ML per l'eliminazione di un endpoint dell'istanza ha il seguente aspetto: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)" ``` Oppure questo: ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)?clean=true" ``` **Parametri per il comando `endpoints` per l'eliminazione di un endpoint di inferenza** + **`id`** (*obbligatorio*): identificatore univoco dell'endpoint di inferenza. *Tipo:* stringa. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso di Neptune alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. + **`clean`** (*facoltativo*): indica che devono essere eliminati anche tutti gli artefatti relativi a questo endpoint. *Tipo*: Boolean *Default*: `FALSE` ## Elenco degli endpoint di inferenza con il comando `endpoints` in Neptune ML Un comando `endpoints` in Neptune ML per l'elenco degli endpoint di inferenza ha il seguente aspetto: ``` curl -s "https://(your Neptune endpoint)/ml/endpoints" \ | python -m json.tool ``` Oppure questo: ``` curl -s "https://(your Neptune endpoint)/ml/endpoints?maxItems=3" \ | python -m json.tool ``` **Parametri per il comando `dataprocessing` per l'elenco degli endpoint di inferenza** + **`maxItems`** (*facoltativo*): numero massimo di elementi da restituire. *Tipo*: numero intero. *Default*: `10` *Valore massimo consentito*: `1024`. + **`neptuneIamRoleArn`**— (*Facoltativo*) L'ARN di un ruolo IAM che fornisce a Neptune l'accesso di Neptune alle risorse AI e SageMaker Amazon S3. *Tipo:* stringa. *Nota*: deve essere elencato nel gruppo di parametri del cluster database o si verificherà un errore. # Errori ed eccezioni dell'API di gestione Neptune ML Tutte le eccezioni dell'API di gestione Neptune ML restituiscono un codice HTTP 400. Dopo aver ricevuto una di queste eccezioni, è consigliabile non ripetere il comando che ha generato l'eccezione. **** + **`MissingParameterException`**   –   Messaggio di errore: `Required credentials are missing. Please add IAM role to the cluster or pass as a parameter to this request.` + **`InvalidParameterException`**   –   Messaggi di errore: + `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`**   –   Messaggi di errore: + `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.` # Limiti di Neptune ML + I tipi di inferenza attualmente supportati sono: classificazione dei nodi, regressione dei nodi, classificazione degli archi, regressione degli archi e la previsione dei collegamenti (consulta [Funzionalità di Neptune ML](machine-learning.md#machine-learning-capabilities)). + Le dimensioni massime del grafo supportate da Neptune ML dipendono dalla quantità di memoria e di spazio di archiviazione richiesti durante la [preparazione dei dati](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size), l'[addestramento del modello](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size) e l'[inferenza](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size). + La dimensione massima di memoria di un'istanza di elaborazione dati SageMaker AI è di 768 GB. Di conseguenza, la fase di elaborazione dei dati ha esito negativo se richiede più di 768 GB di memoria. + La dimensione massima di memoria di un'istanza di addestramento SageMaker AI è di 732 GB. Di conseguenza, la fase di addestramento ha esito negativo se richiede più di 732 GB di memoria. + La dimensione massima di un payload di inferenza per un endpoint SageMaker AI è di 6 MiB. Di conseguenza, l'inferenza induttiva ha esito negativo se il payload del sottografo supera questo limite. + Neptune ML è attualmente disponibile solo nelle regioni in cui Neptune e gli altri servizi da cui dipende (come Amazon API AWS Lambda Gateway e Amazon AI) sono tutti supportati. SageMaker Esistono differenze tra la regione Cina (Pechino) e la regione Cina (Ningxia) in merito all'utilizzo predefinito dell'autenticazione IAM, come [spiegato qui](https://docs.amazonaws.cn/en_us/aws/latest/userguide/api-gateway.html#feature-diff), oltre ad altre differenze. + Gli endpoint di inferenza per la previsione dei collegamenti avviati da Neptune ML al momento possono solo prevedere i collegamenti possibili con i nodi presenti nel grafo durante l'addestramento. Ad esempio, si consideri un grafo con i vertici `User` e `Movie` e gli archi `Rated`. Utilizzando un modello di raccomandazione di previsione dei collegamenti Neptune ML, è possibile aggiungere un nuovo utente al grafo affinché il modello preveda i film per tale utente, ma il modello può raccomandare solo i film presenti al momento dell'addestramento del modello. Sebbene l'incorporamento del nodo `User` venga calcolato in tempo reale utilizzando il relativo sottografo locale e il modello GNN e possa quindi cambiare nel tempo in base alle valutazioni dei film da parte degli utenti, per la raccomandazione finale viene confrontato con gli incorporamenti di film statici e precalcolati. + I modelli di incorporamento del grafo della conoscenza supportati da Neptune ML funzionano solo per le attività di previsione dei collegamenti e le rappresentazioni sono specifiche per i vertici e i tipi di archi presenti nel grafo durante l'addestramento. Ciò significa che tutti i vertici e i tipi di archi a cui viene fatto riferimento in una query di inferenza dovevano essere presenti nel grafo durante l'addestramento. Non è possibile eseguire previsioni per nuovi tipi di archi o vertici senza riaddestrare il modello. ## SageMaker Limitazioni delle risorse AI A seconda delle tue attività e dell'utilizzo delle risorse nel tempo, potresti ricevere messaggi di errore che indicano che [hai superato la tua quota](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html) ([ResourceLimitExceeded](https://repost.aws/knowledge-center/sagemaker-resource-limit-exceeded-error)). E se devi aumentare le tue risorse SageMaker AI, segui i passaggi della procedura Richiedi un aumento della quota di servizio in questa pagina per [richiedere un aumento della quota di servizio per SageMaker le risorse](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html#service-limit-increase-request-procedure) in questa pagina per richiedere un aumento della quota a AWS Support. SageMaker I nomi delle risorse AI corrispondono alle fasi di Neptune ML come segue: + L' SageMaker intelligenza artificiale `ProcessingJob` viene utilizzata dai lavori di elaborazione dati, formazione dei modelli e trasformazione dei modelli di Neptune. + L' SageMaker intelligenza artificiale `HyperParameterTuningJob` viene utilizzata dai lavori di formazione del modello Neptune. + L' SageMaker intelligenza artificiale `TrainingJob` viene utilizzata dai lavori di formazione del modello Neptune. + L' SageMaker intelligenza artificiale `Endpoint` viene utilizzata dagli endpoint di inferenza di Neptune.