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

# Sviluppo di modelli personalizzati in Neptune ML
<a name="machine-learning-custom-model-development"></a>

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
<a name="machine-learning-custom-model-training-script"></a>

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
<a name="machine-learning-custom-model-transform-script"></a>

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
<a name="machine-learning-custom-model-hpo-configuration-file"></a>

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
<a name="machine-learning-custom-model-testing"></a>

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.