diff --git a/docs/source/it/_toctree.yml b/docs/source/it/_toctree.yml index 0ccc97bf3c..e59de8c6bd 100644 --- a/docs/source/it/_toctree.yml +++ b/docs/source/it/_toctree.yml @@ -21,10 +21,14 @@ title: Condividere un modello title: Esercitazione - sections: + - local: create_a_model + title: Crea un'architettura personalizzata - local: run_scripts title: Addestramento con script - local: multilingual title: Modelli multilingua per l'inferenza + - local: serialization + title: Esporta modelli Transformers - sections: - local: debugging title: Debugging diff --git a/docs/source/it/create_a_model.mdx b/docs/source/it/create_a_model.mdx new file mode 100644 index 0000000000..6e11f3f1d0 --- /dev/null +++ b/docs/source/it/create_a_model.mdx @@ -0,0 +1,357 @@ + + +# Crea un'architettura personalizzata + +Una [`AutoClass`](model_doc/auto) deduce automaticamente il modello dell'architettura e scarica la configurazione e i pesi pre-allenati. Generalmente, noi consigliamo di usare un `AutoClass` per produrre un codice indipendente dal checkpoint. Ma gli utenti che desiderano un controllo maggiore su parametri specifici del modello possono creare un modello 🤗 Transformers personalizzato da poche classi base. Questo potrebbe essere particolarmente utile per qualunque persona sia interessata nel studiare, allenare o sperimentare con un modello 🤗 Transformers. In questa guida, approfondisci la creazione di un modello personalizzato senza `AutoClass`. Impara come: + +- Caricare e personalizzare una configurazione del modello. +- Creare un'architettura modello. +- Creare un tokenizer lento e veloce per il testo. +- Creare un estrattore di caratteristiche per attività riguardanti audio o immagini. +- Creare un processore per attività multimodali. + +## Configurazione + +Una [configurazione](main_classes/configuration) si riferisce agli attributi specifici di un modello. Ogni configurazione del modello ha attributi diversi; per esempio, tutti i modelli npl hanno questi attributi in comune `hidden_size`, `num_attention_heads`, `num_hidden_layers` e `vocab_size`. Questi attributi specificano il numero di attention heads o strati nascosti con cui costruire un modello. + +Dai un'occhiata più da vicino a [DistilBERT](model_doc/distilbert) accedendo a [`DistilBertConfig`] per ispezionare i suoi attributi: + +```py +>>> from transformers import DistilBertConfig + +>>> config = DistilBertConfig() +>>> print(config) +DistilBertConfig { + "activation": "gelu", + "attention_dropout": 0.1, + "dim": 768, + "dropout": 0.1, + "hidden_dim": 3072, + "initializer_range": 0.02, + "max_position_embeddings": 512, + "model_type": "distilbert", + "n_heads": 12, + "n_layers": 6, + "pad_token_id": 0, + "qa_dropout": 0.1, + "seq_classif_dropout": 0.2, + "sinusoidal_pos_embds": false, + "transformers_version": "4.16.2", + "vocab_size": 30522 +} +``` + +[`DistilBertConfig`] mostra tutti gli attributi predefiniti usati per costruire una base [`DistilBertModel`]. Tutti gli attributi sono personalizzabili, creando uno spazio per sperimentare. Per esempio, puoi configurare un modello predefinito per: + +- Provare un funzione di attivazione diversa con il parametro `activation`. +- Utilizzare tasso di drop out più elevato per le probalità di attention con il parametro `attention_dropout`. + +```py +>>> my_config = DistilBertConfig(activation="relu", attention_dropout=0.4) +>>> print(my_config) +DistilBertConfig { + "activation": "relu", + "attention_dropout": 0.4, + "dim": 768, + "dropout": 0.1, + "hidden_dim": 3072, + "initializer_range": 0.02, + "max_position_embeddings": 512, + "model_type": "distilbert", + "n_heads": 12, + "n_layers": 6, + "pad_token_id": 0, + "qa_dropout": 0.1, + "seq_classif_dropout": 0.2, + "sinusoidal_pos_embds": false, + "transformers_version": "4.16.2", + "vocab_size": 30522 +} +``` + +Nella funzione [`~PretrainedConfig.from_pretrained`] possono essere modificati gli attributi del modello pre-allenato: + +```py +>>> my_config = DistilBertConfig.from_pretrained("distilbert-base-uncased", activation="relu", attention_dropout=0.4) +``` + +Quando la configurazione del modello ti soddisfa, la puoi salvare con [`~PretrainedConfig.save_pretrained`]. Il file della tua configurazione è memorizzato come file JSON nella save directory specificata: + +```py +>>> my_config.save_pretrained(save_directory="./your_model_save_path") +``` + +Per riutilizzare la configurazione del file, caricalo con [`~PretrainedConfig.from_pretrained`]: + +```py +>>> my_config = DistilBertConfig.from_pretrained("./your_model_save_path/my_config.json") +``` + + + +Puoi anche salvare il file di configurazione come dizionario oppure come la differenza tra gli attributi della tua configurazione personalizzata e gli attributi della configurazione predefinita! Guarda la documentazione [configuration](main_classes/configuration) per più dettagli. + + + +## Modello + +Il prossimo passo e di creare [modello](main_classes/models). Il modello - vagamente riferito anche come architettura - definisce cosa ogni strato deve fare e quali operazioni stanno succedendo. Attributi come `num_hidden_layers` provenienti dalla configurazione sono usati per definire l'architettura. Ogni modello condivide la classe base [`PreTrainedModel`] e alcuni metodi comuni come il ridimensionamento degli input embeddings e la soppressione delle self-attention heads . Inoltre, tutti i modelli sono la sottoclasse di [`torch.nn.Module`](https://pytorch.org/docs/stable/generated/torch.nn.Module.html), [`tf.keras.Model`](https://www.tensorflow.org/api_docs/python/tf/keras/Model) o [`flax.linen.Module`](https://flax.readthedocs.io/en/latest/flax.linen.html#module). Cio significa che i modelli sono compatibili con l'uso di ciascun di framework. + + + +Carica gli attributi della tua configurazione personalizzata nel modello: + +```py +>>> from transformers import DistilBertModel + +>>> my_config = DistilBertConfig.from_pretrained("./your_model_save_path/my_config.json") +>>> model = DistilBertModel(my_config) +``` + +Questo crea modelli con valori casuali invece di pesi pre-allenati. Non sarai in grado di usare questo modello per niente di utile finché non lo alleni. L'allenamento è un processo costoso e che richiede tempo . Generalmente è meglio usare un modello pre-allenato per ottenere risultati migliori velocemente, utilizzando solo una frazione delle risorse neccesarie per l'allenamento. + +Crea un modello pre-allenato con [`~PreTrainedModel.from_pretrained`]: + +```py +>>> model = DistilBertModel.from_pretrained("distilbert-base-uncased") +``` + +Quando carichi pesi pre-allenati, la configurazione del modello predefinito è automaticamente caricata se il modello è fornito da 🤗 Transformers. Tuttavia, puoi ancora sostituire gli attributi - alcuni o tutti - di configurazione del modello predefinito con i tuoi se lo desideri: + +```py +>>> model = DistilBertModel.from_pretrained("distilbert-base-uncased", config=my_config) +``` + + +Carica gli attributi di configurazione personalizzati nel modello: + +```py +>>> from transformers import TFDistilBertModel + +>>> my_config = DistilBertConfig.from_pretrained("./your_model_save_path/my_config.json") +>>> tf_model = TFDistilBertModel(my_config) +``` + + +Questo crea modelli con valori casuali invece di pesi pre-allenati. Non sarai in grado di usare questo modello per niente di utile finché non lo alleni. L'allenamento è un processo costoso e che richiede tempo . Generalmente è meglio usare un modello pre-allenato per ottenere risultati migliori velocemente, utilizzando solo una frazione delle risorse neccesarie per l'allenamento. + +Crea un modello pre-allenoto con [`~TFPreTrainedModel.from_pretrained`]: + +```py +>>> tf_model = TFDistilBertModel.from_pretrained("distilbert-base-uncased") +``` + +Quando carichi pesi pre-allenati, la configurazione del modello predefinito è automaticamente caricato se il modello è fornito da 🤗 Transformers. Tuttavia, puoi ancora sostituire gli attributi - alcuni o tutti - di configurazione del modello predefinito con i tuoi se lo desideri: + +```py +>>> tf_model = TFDistilBertModel.from_pretrained("distilbert-base-uncased", config=my_config) +``` + + + + +### Model head + +A questo punto, hai un modello DistilBERT base i cui output sono gli *hidden states* (in italiano stati nascosti). Gli stati nascosti sono passati come input a un model head per produrre l'output finale. 🤗 Transformers fornisce un model head diverso per ogni attività fintanto che il modello supporta l'attività (i.e., non puoi usare DistilBERT per un attività sequence-to-sequence come la traduzione). + + + +Per esempio, [`DistilBertForSequenceClassification`] è un modello DistilBERT base con una testa di classificazione per sequenze. La sequenza di classificazione head è uno strato lineare sopra gli output ragruppati. + +```py +>>> from transformers import DistilBertForSequenceClassification + +>>> model = DistilBertForSequenceClassification.from_pretrained("distilbert-base-uncased") +``` + +Riutilizza facilmente questo checkpoint per un'altra attività passando ad un model head differente. Per un attività di risposta alle domande, utilizzerai il model head [`DistilBertForQuestionAnswering`]. La head per compiti di question answering è simile alla classificazione di sequenza head tranne per il fatto che è uno strato lineare sopra l'output degli stati nascosti (hidden states in inglese) + +```py +>>> from transformers import DistilBertForQuestionAnswering + +>>> model = DistilBertForQuestionAnswering.from_pretrained("distilbert-base-uncased") +``` + + +Per esempio, [`TFDistilBertForSequenceClassification`] è un modello DistilBERT base con classificazione di sequenza head. La classificazione di sequenza head è uno strato lineare sopra gli output raggruppati. + +```py +>>> from transformers import TFDistilBertForSequenceClassification + +>>> tf_model = TFDistilBertForSequenceClassification.from_pretrained("distilbert-base-uncased") +``` + +Riutilizza facilmente questo checkpoint per un altra attività passando ad un modello head diverso. Per un attività di risposta alle domande, utilizzerai il model head [`TFDistilBertForQuestionAnswering`]. Il head di risposta alle domande è simile alla sequenza di classificazione head tranne per il fatto che è uno strato lineare sopra l'output degli stati nascosti (hidden states in inglese) + +```py +>>> from transformers import TFDistilBertForQuestionAnswering + +>>> tf_model = TFDistilBertForQuestionAnswering.from_pretrained("distilbert-base-uncased") +``` + + + +## Tokenizer + +L'ultima classe base di cui hai bisogno prima di utilizzare un modello per i dati testuali è un [tokenizer](main_classes/tokenizer) per convertire il testo grezzo in tensori. Ci sono due tipi di tokenizer che puoi usare con 🤗 Transformers: + +- [`PreTrainedTokenizer`]: un'implementazione Python di un tokenizer. +- [`PreTrainedTokenizerFast`]: un tokenizer dalla nostra libreria [🤗 Tokenizer](https://huggingface.co/docs/tokenizers/python/latest/) basata su Rust. Questo tipo di tokenizer è significativamente più veloce, specialmente durante la batch tokenization, grazie alla sua implementazione Rust. Il tokenizer veloce offre anche metodi aggiuntivi come *offset mapping* che associa i token alle loro parole o caratteri originali. + +Entrambi i tokenizer supportano metodi comuni come la codifica e la decodifica, l'aggiunta di nuovi token e la gestione di token speciali. + + + +Non tutti i modelli supportano un tokenizer veloce. Dai un'occhiata a questo [tabella](index#supported-frameworks) per verificare se un modello ha il supporto per tokenizer veloce. + + + +Se hai addestrato il tuo tokenizer, puoi crearne uno dal tuo file *vocabolario*: + +```py +>>> from transformers import DistilBertTokenizer + +>>> my_tokenizer = DistilBertTokenizer(vocab_file="my_vocab_file.txt", do_lower_case=False, padding_side="left") +``` + +È importante ricordare che il vocabolario di un tokenizer personalizzato sarà diverso dal vocabolario generato dal tokenizer di un modello preallenato. È necessario utilizzare il vocabolario di un modello preallenato se si utilizza un modello preallenato, altrimenti gli input non avranno senso. Crea un tokenizer con il vocabolario di un modello preallenato con la classe [`DistilBertTokenizer`]: + +```py +>>> from transformers import DistilBertTokenizer + +>>> slow_tokenizer = DistilBertTokenizer.from_pretrained("distilbert-base-uncased") +``` + +Crea un tokenizer veloce con la classe [`DistilBertTokenizerFast`]: + +```py +>>> from transformers import DistilBertTokenizerFast + +>>> fast_tokenizer = DistilBertTokenizerFast.from_pretrained("distilbert-base-uncased") +``` + + + +Per l'impostazione predefinita, [`AutoTokenizer`] proverà a caricare un tokenizer veloce. Puoi disabilitare questo comportamento impostando `use_fast=False` in `from_pretrained`. + + + +## Estrattore Di Feature + +Un estrattore di caratteristiche (feature in inglese) elabora input audio o immagini. Eredita dalla classe [`~feature_extraction_utils.FeatureExtractionMixin`] base e può anche ereditare dalla classe [`ImageFeatureExtractionMixin`] per l'elaborazione delle caratteristiche dell'immagine o dalla classe [`SequenceFeatureExtractor`] per l'elaborazione degli input audio. + +A seconda che tu stia lavorando a un'attività audio o visiva, crea un estrattore di caratteristiche associato al modello che stai utilizzando. Ad esempio, crea un [`ViTFeatureExtractor`] predefinito se stai usando [ViT](model_doc/vit) per la classificazione delle immagini: + +```py +>>> from transformers import ViTFeatureExtractor + +>>> vit_extractor = ViTFeatureExtractor() +>>> print(vit_extractor) +ViTFeatureExtractor { + "do_normalize": true, + "do_resize": true, + "feature_extractor_type": "ViTFeatureExtractor", + "image_mean": [ + 0.5, + 0.5, + 0.5 + ], + "image_std": [ + 0.5, + 0.5, + 0.5 + ], + "resample": 2, + "size": 224 +} +``` + + + +Se non stai cercando alcuna personalizzazione, usa il metodo `from_pretrained` per caricare i parametri di default dell'estrattore di caratteristiche di un modello. + + + +Modifica uno qualsiasi dei parametri [`ViTFeatureExtractor`] per creare il tuo estrattore di caratteristiche personalizzato: + +```py +>>> from transformers import ViTFeatureExtractor + +>>> my_vit_extractor = ViTFeatureExtractor(resample="PIL.Image.BOX", do_normalize=False, image_mean=[0.3, 0.3, 0.3]) +>>> print(my_vit_extractor) +ViTFeatureExtractor { + "do_normalize": false, + "do_resize": true, + "feature_extractor_type": "ViTFeatureExtractor", + "image_mean": [ + 0.3, + 0.3, + 0.3 + ], + "image_std": [ + 0.5, + 0.5, + 0.5 + ], + "resample": "PIL.Image.BOX", + "size": 224 +} +``` + +Per gli input audio, puoi creare un [`Wav2Vec2FeatureExtractor`] e personalizzare i parametri in modo simile: + +```py +>>> from transformers import Wav2Vec2FeatureExtractor + +>>> w2v2_extractor = Wav2Vec2FeatureExtractor() +>>> print(w2v2_extractor) +Wav2Vec2FeatureExtractor { + "do_normalize": true, + "feature_extractor_type": "Wav2Vec2FeatureExtractor", + "feature_size": 1, + "padding_side": "right", + "padding_value": 0.0, + "return_attention_mask": false, + "sampling_rate": 16000 +} +``` + +## Processore + +Per modelli che supportano attività multimodali, 🤗 Transformers offre una classe di processore che racchiude comodamente un estrattore di caratteristiche e un tokenizer in un unico oggetto. Ad esempio, utilizziamo [`Wav2Vec2Processor`] per un'attività di riconoscimento vocale automatico (ASR). ASR trascrive l'audio in testo, quindi avrai bisogno di un estrattore di caratteristiche e di un tokenizer. + +Crea un estrattore di feature per gestire gli input audio: + +```py +>>> from transformers import Wav2Vec2FeatureExtractor + +>>> feature_extractor = Wav2Vec2FeatureExtractor(padding_value=1.0, do_normalize=True) +``` + +Crea un tokenizer per gestire gli input di testo: + +```py +>>> from transformers import Wav2Vec2CTCTokenizer + +>>> tokenizer = Wav2Vec2CTCTokenizer(vocab_file="my_vocab_file.txt") +``` + +Combinare l'estrattore di caratteristiche e il tokenizer in [`Wav2Vec2Processor`]: + +```py +>>> from transformers import Wav2Vec2Processor + +>>> processor = Wav2Vec2Processor(feature_extractor=feature_extractor, tokenizer=tokenizer) +``` + +Con due classi di base - configurazione e modello - e una classe di preelaborazione aggiuntiva (tokenizer, estrattore di caratteristiche o processore), puoi creare qualsiasi modello supportato da 🤗 Transformers. Ognuna di queste classi base è configurabile, consentendoti di utilizzare gli attributi specifici che desideri. È possibile impostare facilmente un modello per l'addestramento o modificare un modello preallenato esistente per la messa a punto. \ No newline at end of file diff --git a/docs/source/it/serialization.mdx b/docs/source/it/serialization.mdx new file mode 100644 index 0000000000..9190e22e44 --- /dev/null +++ b/docs/source/it/serialization.mdx @@ -0,0 +1,673 @@ + + +# Esporta modelli 🤗 Transformers + +Se devi implementare 🤗 modelli Transformers in ambienti di produzione, noi +consigliamo di esportarli in un formato serializzato che può essere caricato ed eseguito +su runtime e hardware specializzati. In questa guida ti mostreremo come farlo +esporta 🤗 Modelli Transformers in due formati ampiamente utilizzati: ONNX e TorchScript. + +Una volta esportato, un modello può essere ottimizato per l'inferenza tramite tecniche come +la quantizzazione e soppressione. Se sei interessato a ottimizzare i tuoi modelli per l'esecuzione +con la massima efficienza, dai un'occhiata a [🤗 Optimum +library](https://github.com/huggingface/optimum). + +## ONNX + +Il progetto [ONNX (Open Neural Network eXchange)](http://onnx.ai) Il progetto onnx è un open +standard che definisce un insieme comune di operatori e un formato di file comune a +rappresentano modelli di deep learning in un'ampia varietà di framework, tra cui +PyTorch e TensorFlow. Quando un modello viene esportato nel formato ONNX, questi +operatori sono usati per costruire un grafico computazionale (often called an +_intermediate representation_) che rappresenta il flusso di dati attraverso la +rete neurale. + +Esponendo un grafico con operatori e tipi di dati standardizzati, ONNX rende +più facile passare da un framework all'altro. Ad esempio, un modello allenato in PyTorch può +essere esportato in formato ONNX e quindi importato in TensorFlow (e viceversa). + +🤗 Transformers fornisce un pacchetto `transformers.onnx` che ti consente di +convertire i checkpoint del modello in un grafico ONNX sfruttando gli oggetti di configurazione. +Questi oggetti di configurazione sono già pronti per una serie di architetture di modelli, +e sono progettati per essere facilmente estensibili ad altre architetture. + +Le configurazioni pronte includono le seguenti architetture: + + + +- ALBERT +- BART +- BEiT +- BERT +- BigBird +- BigBird-Pegasus +- Blenderbot +- BlenderbotSmall +- CamemBERT +- ConvBERT +- Data2VecText +- Data2VecVision +- DeiT +- DistilBERT +- ELECTRA +- FlauBERT +- GPT Neo +- GPT-J +- I-BERT +- LayoutLM +- M2M100 +- Marian +- mBART +- MobileBERT +- OpenAI GPT-2 +- Perceiver +- PLBart +- RoBERTa +- RoFormer +- SqueezeBERT +- T5 +- ViT +- XLM +- XLM-RoBERTa +- XLM-RoBERTa-XL + +Nelle prossime due sezioni, ti mostreremo come: + +* Esporta un modello supportato usando il pacchetto `transformers.onnx`. +* Esporta un modello personalizzato per un'architettura non supportata. + +### Esportazione di un modello in ONNX + +Per esportare un modello 🤗 Transformers in ONNX, dovrai prima installarne alcune +dipendenze extra: + +```bash +pip install transformers[onnx] +``` + +Il pacchetto `transformers.onnx` può essere usato come modulo Python: + +```bash +python -m transformers.onnx --help + +usage: Hugging Face Transformers ONNX exporter [-h] -m MODEL [--feature {causal-lm, ...}] [--opset OPSET] [--atol ATOL] output + +positional arguments: + output Path indicating where to store generated ONNX model. + +optional arguments: + -h, --help show this help message and exit + -m MODEL, --model MODEL + Model ID on huggingface.co or path on disk to load model from. + --feature {causal-lm, ...} + The type of features to export the model with. + --opset OPSET ONNX opset version to export the model with. + --atol ATOL Absolute difference tolerence when validating the model. +``` + +L'esportazione di un checkpoint utilizzando una configurazione già pronta può essere eseguita come segue: + +```bash +python -m transformers.onnx --model=distilbert-base-uncased onnx/ +``` + +che dovrebbe mostrare i seguenti log: + +```bash +Validating ONNX model... + -[✓] ONNX model output names match reference model ({'last_hidden_state'}) + - Validating ONNX Model output "last_hidden_state": + -[✓] (2, 8, 768) matches (2, 8, 768) + -[✓] all values close (atol: 1e-05) +All good, model saved at: onnx/model.onnx +``` + +Questo esporta un grafico ONNX del checkpoint definito dall'argomento `--model`. +In questo esempio è `distilbert-base-uncased`, ma può essere qualsiasi checkpoint +Hugging Face Hub o uno memorizzato localmente. + +Il file risultante `model.onnx` può quindi essere eseguito su uno dei [tanti +acceleratori](https://onnx.ai/supported-tools.html#deployModel) che supportano il +lo standard ONNX. Ad esempio, possiamo caricare ed eseguire il modello con [ONNX +Runtime](https://onnxruntime.ai/) come segue: + +```python +>>> from transformers import AutoTokenizer +>>> from onnxruntime import InferenceSession + +>>> tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased") +>>> session = InferenceSession("onnx/model.onnx") +>>> # ONNX Runtime expects NumPy arrays as input +>>> inputs = tokenizer("Using DistilBERT with ONNX Runtime!", return_tensors="np") +>>> outputs = session.run(output_names=["last_hidden_state"], input_feed=dict(inputs)) +``` + +I nomi di output richiesti (cioè `["last_hidden_state"]`) possono essere ottenuti +dando un'occhiata alla configurazione ONNX di ogni modello. Ad esempio, per +DistilBERT abbiamo: + +```python +>>> from transformers.models.distilbert import DistilBertConfig, DistilBertOnnxConfig + +>>> config = DistilBertConfig() +>>> onnx_config = DistilBertOnnxConfig(config) +>>> print(list(onnx_config.outputs.keys())) +["last_hidden_state"] +``` + +Il processo è identico per i checkpoint TensorFlow sull'hub. Ad esempio, noi +possiamo esportare un checkpoint TensorFlow puro da [Keras +organizzazione](https://huggingface.co/keras-io) come segue: + +```bash +python -m transformers.onnx --model=keras-io/transformers-qa onnx/ +``` + +Per esportare un modello memorizzato localmente, devi disporre dei pesi del modello +e file tokenizer memorizzati in una directory. Ad esempio, possiamo caricare e salvare un +checkpoint come segue: + + + +```python +>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification + +>>> # Load tokenizer and PyTorch weights form the Hub +>>> tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased") +>>> pt_model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased") +>>> # Save to disk +>>> tokenizer.save_pretrained("local-pt-checkpoint") +>>> pt_model.save_pretrained("local-pt-checkpoint") +``` + +Una volta salvato il checkpoint, possiamo esportarlo su ONNX puntando l'argomento `--model` +del pacchetto `transformers.onnx` nella directory desiderata: + +```bash +python -m transformers.onnx --model=local-pt-checkpoint onnx/ +``` + + +```python +>>> from transformers import AutoTokenizer, TFAutoModelForSequenceClassification + +>>> # Load tokenizer and TensorFlow weights from the Hub +>>> tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased") +>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased") +>>> # Save to disk +>>> tokenizer.save_pretrained("local-tf-checkpoint") +>>> tf_model.save_pretrained("local-tf-checkpoint") +``` + +Once the checkpoint is saved, we can export it to ONNX by pointing the `--model` +argument of the `transformers.onnx` package to the desired directory: + +```bash +python -m transformers.onnx --model=local-tf-checkpoint onnx/ +``` + + + +### Selezione delle caratteristiche per diverse topologie di modello + +Ogni configurazione già pronta viene fornita con una serie di _caratteristiche_ che ti consentono di +esportare modelli per diversi tipi di topologie o attività. Come mostrato nella tabella +di seguito, ogni caratteristica è associata a una diversa Auto Class: + +| Caratteristica | Auto Class | +| ------------------------------------ | ------------------------------------ | +| `causal-lm`, `causal-lm-with-past` | `AutoModelForCausalLM` | +| `default`, `default-with-past` | `AutoModel` | +| `masked-lm` | `AutoModelForMaskedLM` | +| `question-answering` | `AutoModelForQuestionAnswering` | +| `seq2seq-lm`, `seq2seq-lm-with-past` | `AutoModelForSeq2SeqLM` | +| `sequence-classification` | `AutoModelForSequenceClassification` | +| `token-classification` | `AutoModelForTokenClassification` | + +Per ciascuna configurazione, puoi trovare l'elenco delle funzionalità supportate tramite il +`FeaturesManager`. Ad esempio, per DistilBERT abbiamo: + +```python +>>> from transformers.onnx.features import FeaturesManager + +>>> distilbert_features = list(FeaturesManager.get_supported_features_for_model_type("distilbert").keys()) +>>> print(distilbert_features) +["default", "masked-lm", "causal-lm", "sequence-classification", "token-classification", "question-answering"] +``` + +Puoi quindi passare una di queste funzionalità all'argomento `--feature` nel +pacchetto `transformers.onnx`. Ad esempio, per esportare un modello di classificazione del testo +possiamo scegliere un modello ottimizzato dall'Hub ed eseguire: + +```bash +python -m transformers.onnx --model=distilbert-base-uncased-finetuned-sst-2-english \ + --feature=sequence-classification onnx/ +``` + +che visualizzerà i seguenti registri: + +```bash +Validating ONNX model... + -[✓] ONNX model output names match reference model ({'logits'}) + - Validating ONNX Model output "logits": + -[✓] (2, 2) matches (2, 2) + -[✓] all values close (atol: 1e-05) +All good, model saved at: onnx/model.onnx +``` + +Puoi notare che in questo caso, i nomi di output del modello ottimizzato sono +`logits` invece di `last_hidden_state` che abbiamo visto con il +checkpoint `distilbert-base-uncased` precedente. Questo è previsto dal +modello ottimizato visto che ha una testa di e. + + + +Le caratteristiche che hanno un suffisso `wtih-past` (ad es. `causal-lm-with-past`) +corrispondono a topologie di modello con stati nascosti precalcolati (chiave e valori +nei blocchi di attenzione) che possono essere utilizzati per la decodifica autoregressiva veloce. + + + + +### Esportazione di un modello per un'architettura non supportata + +Se desideri esportare un modello la cui architettura non è nativamente supportata dalla +libreria, ci sono tre passaggi principali da seguire: + +1. Implementare una configurazione ONNX personalizzata. +2. Esportare il modello in ONNX. +3. Convalidare gli output di PyTorch e dei modelli esportati. + +In questa sezione, vedremo come DistilBERT è stato implementato per mostrare cosa è +coinvolto in ogni passaggio. + +#### Implementazione di una configurazione ONNX personalizzata + +Iniziamo con l'oggetto di configurazione ONNX. Forniamo tre classi +astratte da cui ereditare, a seconda del tipo di archittettura +del modello che desideri esportare: + +* I modelli basati su encoder ereditano da [`~onnx.config.OnnxConfig`] +* I modelli basati su decoder ereditano da [`~onnx.config.OnnxConfigWithPast`] +* I modelli encoder-decoder ereditano da[`~onnx.config.OnnxSeq2SeqConfigWithPast`] + + + +Un buon modo per implementare una configurazione ONNX personalizzata è guardare l'implementazione +esistente nel file `configuration_.py` di un'architettura simile. + + + +Poiché DistilBERT è un modello basato su encoder, la sua configurazione eredita da +`OnnxConfig`: + +```python +>>> from typing import Mapping, OrderedDict +>>> from transformers.onnx import OnnxConfig + + +>>> class DistilBertOnnxConfig(OnnxConfig): +... @property +... def inputs(self) -> Mapping[str, Mapping[int, str]]: +... return OrderedDict( +... [ +... ("input_ids", {0: "batch", 1: "sequence"}), +... ("attention_mask", {0: "batch", 1: "sequence"}), +... ] +... ) +``` + +Ogni oggetto di configurazione deve implementare la proprietà `inputs` e restituire una +mappatura, dove ogni chiave corrisponde a un input previsto e ogni valore +indica l'asse di quell'input. Per DistilBERT, possiamo vedere che sono richiesti +due input: `input_ids` e `attention_mask`. Questi inputs hanno la stessa forma di +`(batch_size, sequence_length)` per questo motivo vediamo gli stessi assi usati nella +configurazione. + + + +Puoi notare che la proprietà `inputs` per `DistilBertOnnxConfig` restituisce un +`OrdinatoDict`. Ciò garantisce che gli input corrispondano alla loro posizione +relativa all'interno del metodo `PreTrainedModel.forward()` durante il tracciamento del grafico. +Raccomandiamo di usare un `OrderedDict` per le proprietà `inputs` e `outputs` +quando si implementano configurazioni ONNX personalizzate. + + + +Dopo aver implementato una configurazione ONNX, è possibile istanziarla +fornendo alla configurazione del modello base come segue: + +```python +>>> from transformers import AutoConfig + +>>> config = AutoConfig.from_pretrained("distilbert-base-uncased") +>>> onnx_config = DistilBertOnnxConfig(config) +``` + +L'oggetto risultante ha diverse proprietà utili. Ad esempio è possibile visualizzare il +Set operatore ONNX che verrà utilizzato durante l'esportazione: + +```python +>>> print(onnx_config.default_onnx_opset) +11 +``` + +È inoltre possibile visualizzare gli output associati al modello come segue: + +```python +>>> print(onnx_config.outputs) +OrderedDict([("last_hidden_state", {0: "batch", 1: "sequence"})]) +``` + +Puoi notare che la proprietà degli output segue la stessa struttura degli input; esso +restituisce un `OrderedDict` di output con nome e le loro forme. La struttura di output +è legato alla scelta della funzione con cui viene inizializzata la configurazione. +Per impostazione predefinita, la configurazione ONNX viene inizializzata con la funzione 'predefinita' +che corrisponde all'esportazione di un modello caricato con la classe `AutoModel`. Se tu +desideri esportare una topologia di modello diversa, è sufficiente fornire una funzionalità diversa a +l'argomento `task` quando inizializzi la configurazione ONNX. Ad esempio, se +volevamo esportare DistilBERT con una testa di classificazione per sequenze, potremmo +usare: + +```python +>>> from transformers import AutoConfig + +>>> config = AutoConfig.from_pretrained("distilbert-base-uncased") +>>> onnx_config_for_seq_clf = DistilBertOnnxConfig(config, task="sequence-classification") +>>> print(onnx_config_for_seq_clf.outputs) +OrderedDict([('logits', {0: 'batch'})]) +``` + + + +Tutte le proprietà e i metodi di base associati a [`~onnx.config.OnnxConfig`] e le +altre classi di configurazione possono essere sovrascritte se necessario. Guarda +[`BartOnnxConfig`] per un esempio avanzato. + + + +#### Esportazione del modello + +Una volta implementata la configurazione ONNX, il passaggio successivo consiste nell'esportare il +modello. Qui possiamo usare la funzione `export()` fornita dal +pacchetto `transformers.onnx`. Questa funzione prevede la configurazione ONNX, insieme +con il modello base e il tokenizer e il percorso per salvare il file esportato: + +```python +>>> from pathlib import Path +>>> from transformers.onnx import export +>>> from transformers import AutoTokenizer, AutoModel + +>>> onnx_path = Path("model.onnx") +>>> model_ckpt = "distilbert-base-uncased" +>>> base_model = AutoModel.from_pretrained(model_ckpt) +>>> tokenizer = AutoTokenizer.from_pretrained(model_ckpt) + +>>> onnx_inputs, onnx_outputs = export(tokenizer, base_model, onnx_config, onnx_config.default_onnx_opset, onnx_path) +``` + +Gli `onnx_inputs` e `onnx_outputs` restituiti dalla funzione `export()` sono +liste di chiavi definite nelle proprietà di `input` e `output` della +configurazione. Una volta esportato il modello, puoi verificare che il modello sia ben +formato come segue: + +```python +>>> import onnx + +>>> onnx_model = onnx.load("model.onnx") +>>> onnx.checker.check_model(onnx_model) +``` + + + +Se il tuo modello è più largo di 2 GB, vedrai che molti file aggiuntivi sono +creati durante l'esportazione. Questo è _previsto_ perché ONNX utilizza [Protocol +Buffer](https://developers.google.com/protocol-buffers/) per memorizzare il modello e +questi hanno un limite di dimensione 2 GB. Vedi la [Documentazione +ONNX](https://github.com/onnx/onnx/blob/master/docs/ExternalData.md) +per istruzioni su come caricare modelli con dati esterni. + + + +#### Convalida degli output del modello + +Il passaggio finale consiste nel convalidare gli output dal modello di base e quello esportato +corrispondere entro una soglia di tolleranza assoluta. Qui possiamo usare la +Funzione `validate_model_outputs()` fornita dal pacchetto `transformers.onnx` +come segue: + +```python +>>> from transformers.onnx import validate_model_outputs + +>>> validate_model_outputs( +... onnx_config, tokenizer, base_model, onnx_path, onnx_outputs, onnx_config.atol_for_validation +... ) +``` + +Questa funzione usa il metodo `OnnxConfig.generate_dummy_inputs()` per generare +input per il modello di base e quello esportato e la tolleranza assoluta può essere +definita nella configurazione. Generalmente troviamo una corrispondenza numerica nell'intervallo da 1e-6 +a 1e-4, anche se è probabile che qualsiasi cosa inferiore a 1e-3 vada bene. + +### Contribuire con una nuova configurazione a 🤗 Transformers + +Stiamo cercando di espandere l'insieme di configurazioni già pronte e di accettare +contributi della community! Se vuoi contribuire con la tua aggiunta +nella libreria, dovrai: + +* Implementare la configurazione ONNX nella corrispondente `configuration file +_.py` +* Includere l'architettura del modello e le funzioni corrispondenti in [`~onnx.features.FeatureManager`] +* Aggiungere la tua architettura del modello ai test in `test_onnx_v2.py` + +Scopri come stato contribuito la configurazione per [IBERT] +(https://github.com/huggingface/transformers/pull/14868/files) per +avere un'idea di cosa è coinvolto. + +## TorchScript + + + +Questo è l'inizio dei nostri esperimenti con TorchScript e stiamo ancora esplorando le sue capacità con +modelli con variable-input-size. È una nostra priorità e approfondiremo le nostre analisi nelle prossime versioni, +con più esempi di codici, un'implementazione più flessibile e benchmark che confrontano i codici basati su Python con quelli compilati con +TorchScript. + + + +Secondo la documentazione di Pytorch: "TorchScript è un modo per creare modelli serializzabili e ottimizzabili da codice +Pytorch". I due moduli di Pytorch [JIT e TRACE](https://pytorch.org/docs/stable/jit.html) consentono allo sviluppatore di esportare +il loro modello da riutilizzare in altri programmi, come i programmi C++ orientati all'efficienza. + +Abbiamo fornito un'interfaccia che consente l'esportazione di modelli 🤗 Transformers in TorchScript in modo che possano essere riutilizzati +in un ambiente diverso rispetto a un programma Python basato su Pytorch. Qui spieghiamo come esportare e utilizzare i nostri modelli utilizzando +TorchScript. + +Esportare un modello richiede due cose: + +- Un passaggio in avanti con input fittizzi. +- Istanziazione del modello con flag `torchscript`. + +Queste necessità implicano diverse cose a cui gli sviluppatori dovrebbero prestare attenzione. Questi dettagli mostrati sotto. + +### Flag TorchScript e pesi legati + +Questo flag è necessario perché la maggior parte dei modelli linguistici in questo repository hanno pesi legati tra il loro +strato "Embedding" e lo strato "Decoding". TorchScript non consente l'esportazione di modelli che hanno pesi +legati, quindi è necessario prima slegare e clonare i pesi. + +Ciò implica che i modelli istanziati con il flag `torchscript` hanno il loro strato `Embedding` e strato `Decoding` +separato, il che significa che non dovrebbero essere addestrati in futuro. L'allenamento de-sincronizza i due +strati, portando a risultati inaspettati. + +Questo non è il caso per i modelli che non hanno una testa del modello linguistico, poiché quelli non hanno pesi legati. Questi modelli +può essere esportato in sicurezza senza il flag `torchscript`. + +### Input fittizi e standard lengths + +Gli input fittizzi sono usati per fare un modello passaggio in avanti . Mentre i valori degli input si propagano attraverso i strati, +Pytorch tiene traccia delle diverse operazioni eseguite su ciascun tensore. Queste operazioni registrate vengono quindi utilizzate per +creare la "traccia" del modello. + +La traccia viene creata relativamente alle dimensioni degli input. È quindi vincolato dalle dimensioni dell'input +fittizio e non funzionerà per altre lunghezze di sequenza o dimensioni batch. Quando si proverà con una dimensione diversa, ci sarà errore +come: + +`La dimensione espansa del tensore (3) deve corrispondere alla dimensione esistente (7) nella dimensione non singleton 2` + +will be raised. Si consiglia pertanto di tracciare il modello con una dimensione di input fittizia grande almeno quanto il più grande +input che verrà fornito al modello durante l'inferenza. È possibile eseguire il padding per riempire i valori mancanti. Il modello +sarà tracciato con una grande dimensione di input, tuttavia, anche le dimensioni della diverse matrici saranno grandi, +risultando in più calcoli. + +Si raccomanda di prestare attenzione al numero totale di operazioni eseguite su ciascun input e di seguire da vicino le prestazioni +durante l'esportazione di modelli di sequenza-lunghezza variabili. + +### Usare TorchSscript in Python + +Di seguito è riportato un esempio, che mostra come salvare, caricare modelli e come utilizzare la traccia per l'inferenza. + +#### Salvare un modello + +Questo frammento di codice mostra come usare TorchScript per esportare un `BertModel`. Qui il `BertModel` è istanziato secondo +una classe `BertConfig` e quindi salvato su disco con il nome del file `traced_bert.pt` + +```python +from transformers import BertModel, BertTokenizer, BertConfig +import torch + +enc = BertTokenizer.from_pretrained("bert-base-uncased") + +# Tokenizing input text +text = "[CLS] Who was Jim Henson ? [SEP] Jim Henson was a puppeteer [SEP]" +tokenized_text = enc.tokenize(text) + +# Masking one of the input tokens +masked_index = 8 +tokenized_text[masked_index] = "[MASK]" +indexed_tokens = enc.convert_tokens_to_ids(tokenized_text) +segments_ids = [0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1] + +# Creating a dummy input +tokens_tensor = torch.tensor([indexed_tokens]) +segments_tensors = torch.tensor([segments_ids]) +dummy_input = [tokens_tensor, segments_tensors] + +# Initializing the model with the torchscript flag +# Flag set to True even though it is not necessary as this model does not have an LM Head. +config = BertConfig( + vocab_size_or_config_json_file=32000, + hidden_size=768, + num_hidden_layers=12, + num_attention_heads=12, + intermediate_size=3072, + torchscript=True, +) + +# Instantiating the model +model = BertModel(config) + +# The model needs to be in evaluation mode +model.eval() + +# If you are instantiating the model with *from_pretrained* you can also easily set the TorchScript flag +model = BertModel.from_pretrained("bert-base-uncased", torchscript=True) + +# Creating the trace +traced_model = torch.jit.trace(model, [tokens_tensor, segments_tensors]) +torch.jit.save(traced_model, "traced_bert.pt") +``` + +#### Caricare un modello + +Questo frammento di codice mostra come caricare il `BertModel` che era stato precedentemente salvato su disco con il nome `traced_bert.pt`. +Stiamo riutilizzando il `dummy_input` precedentemente inizializzato. + +```python +loaded_model = torch.jit.load("traced_bert.pt") +loaded_model.eval() + +all_encoder_layers, pooled_output = loaded_model(*dummy_input) +``` + +#### Utilizzare un modello tracciato per l'inferenza + +Usare il modello tracciato per l'inferenza è semplice come usare il suo metodo dunder `__call__`: + +```python +traced_model(tokens_tensor, segments_tensors) +``` + +###Implementare modelli HuggingFace TorchScript su AWS utilizzando Neuron SDK + +AWS ha introdotto [Amazon EC2 Inf1](https://aws.amazon.com/ec2/instance-types/inf1/) +famiglia di istanze per l'inferenza di machine learning a basso costo e ad alte prestazioni nel cloud. +Le istanze Inf1 sono alimentate dal chip AWS Inferentia, un acceleratore hardware personalizzato, +specializzato in carichi di lavoro di inferenza di deep learning. +[AWS Neuron](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/#) +è l'SDK per Inferentia che supporta il tracciamento e l'ottimizzazione dei modelli transformers per +distribuzione su Inf1. L'SDK Neuron fornisce: + + +1. API di facile utilizzo con una riga di modifica del codice per tracciare e ottimizzare un modello TorchScript per l'inferenza nel cloud. +2. Ottimizzazioni delle prestazioni pronte all'uso per [miglioramento dei costi-prestazioni](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/neuron-guide/benchmark/>) +3. Supporto per i modelli di trasformatori HuggingFace costruiti con [PyTorch](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/src/examples/pytorch/bert_tutorial/tutorial_pretrained_bert.html) + o [TensorFlow](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/src/examples/tensorflow/huggingface_bert/huggingface_bert.html). + +#### Implicazioni + +Modelli Transformers basati su architettura [BERT (Bidirectional Encoder Representations from Transformers)](https://huggingface.co/docs/transformers/main/model_doc/bert), +o sue varianti come [distilBERT](https://huggingface.co/docs/transformers/main/model_doc/distilbert) +e [roBERTa](https://huggingface.co/docs/transformers/main/model_doc/roberta) +funzioneranno meglio su Inf1 per attività non generative come la question answering estrattive, +Classificazione della sequenza, Classificazione dei token. In alternativa, generazione di testo +le attività possono essere adattate per essere eseguite su Inf1, secondo questo [tutorial AWS Neuron MarianMT](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/src/examples/pytorch/transformers-marianmt.html). +Ulteriori informazioni sui modelli che possono essere convertiti fuori dagli schemi su Inferentia possono essere +trovati nella [sezione Model Architecture Fit della documentazione Neuron](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/neuron-guide/models/models-inferentia.html#models-inferentia). + +#### Dipendenze + +L'utilizzo di AWS Neuron per convertire i modelli richiede le seguenti dipendenze e l'ambiente: + +* A [Neuron SDK environment](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/neuron-guide/neuron-frameworks/pytorch-neuron/index.html#installation-guide), + which comes pre-configured on [AWS Deep Learning AMI](https://docs.aws.amazon.com/dlami/latest/devguide/tutorial-inferentia-launching.html). + +#### Convertire un modello per AWS Neuron + +Usando lo stesso script come in [Usando TorchScipt in Python](https://huggingface.co/docs/transformers/main/en/serialization#using-torchscript-in-python) +per tracciare un "BertModel", importi l'estensione del framework `torch.neuron` per accedere +i componenti di Neuron SDK tramite un'API Python. + +```python +from transformers import BertModel, BertTokenizer, BertConfig +import torch +import torch.neuron +``` +E modificare solo la riga di codice di traccia + +Da: + +```python +torch.jit.trace(model, [tokens_tensor, segments_tensors]) +``` + +A: + +```python +torch.neuron.trace(model, [token_tensor, segments_tensors]) +``` + +Questa modifica consente a Neuron SDK di tracciare il modello e ottimizzarlo per l'esecuzione nelle istanze Inf1. + +Per ulteriori informazioni sulle funzionalità, gli strumenti, i tutorial di esempi e gli ultimi aggiornamenti di AWS Neuron SDK, +consultare la [documentazione AWS NeuronSDK](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/index.html). \ No newline at end of file