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à. # 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.