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